# Orders (v1)

> GET /v1/orders/{address} and GET /v1/orders/by-id/{orderId}. Track v1 orders from created to filled or refunded.

> API v1 is deprecated. It stays supported, but new integrations should use the [Khalani API](/). See [Migrate to v2](/v1/migrate/).

## Orders for an address

```text
GET /v1/orders/{address}
```

Returns a wallet's orders, newest first, one page at a time.

### Path parameters

| Parameter | Description |
|---|---|
| `address` | The wallet: an EVM, Solana, TRON, Bitcoin, CKB or Stellar address. Wallet orders are listed under the depositing address. Deposit-address orders are listed under their refund address. Passing an order id here returns `400` with a hint to use `?orderIds=` instead. |

### Query parameters

| Parameter | Type | Description |
|---|---|---|
| `fromChainId` | integer | Only orders from this source chain. |
| `toChainId` | integer | Only orders to this destination chain. |
| `limit` | integer | Orders per page, 1 to 20. Default 10. |
| `cursor` | integer | The `cursor` from the previous page. It is an offset, at most 1000: narrow the filters to reach older orders. |
| `orderIds` | string | Only these orders. Comma-separated, repeated (`?orderIds=a&orderIds=b`), or a JSON array. Accepts both id formats below. |
| `txHashSearch` | string | A deposit, fill or refund transaction hash, with or without `0x`. Hex only, at most 66 characters. |

The list merges two kinds of order:

- **Wallet orders**, created by `PUT /v1/deposit/submit`. Their ids are `c` and 24 lowercase letters or digits, such as `cm2x8k3n70001qz5v9w4r6t2y`.
- **Deposit-address orders**, created by a `TRANSFER` build on the native route. Their ids are 32 hex characters. Their `author` is the refund address.

### Example

```bash
# The latest orders of a wallet
curl "https://api.hyperstream.dev/v1/orders/0x5b38da6a701c568545dcfcb03fcb875f56beddc4"

# Arbitrum to Base only, five per page
curl "https://api.hyperstream.dev/v1/orders/0x5b38da6a701c568545dcfcb03fcb875f56beddc4?fromChainId=42161&toChainId=8453&limit=5"

# Two specific orders
curl "https://api.hyperstream.dev/v1/orders/0x5b38da6a701c568545dcfcb03fcb875f56beddc4?orderIds=cm2x8k3n70001qz5v9w4r6t2y,cm2x8k3n70002ab7c9d1e3f5g"
```

### Response

```json
{
  "data": [
    {
      "id": "cm2x8k3n70001qz5v9w4r6t2y",
      "type": "native-filler",
      "quoteId": "3f6c2a1e-8b4d-4e7a-9c15-2d0b7e9a4f61",
      "routeId": "Hyperstream",
      "fromChainId": 42161,
      "fromToken": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
      "toChainId": 8453,
      "toToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "srcAmount": "10000000",
      "destAmount": "9993000",
      "status": "filled",
      "author": "0x5b38da6a701c568545dcfcb03fcb875f56beddc4",
      "recipient": null,
      "refundTo": null,
      "fillerAddress": null,
      "depositTxHash": "0x4e9a2c71d0b35f8e6a1c9d27b4f08e35a6c1d92e7b04f3a85c6d1e29f7b30a4c",
      "externalOrderId": null,
      "createdAt": "2026-10-19T12:00:00.000Z",
      "updatedAt": "2026-10-19T12:00:41.000Z",
      "tradeType": "EXACT_INPUT",
      "stepsCompleted": ["created", "deposited", "published", "filled"],
      "transactions": {
        "deposit": { "timestamp": "2026-10-19T12:00:04.000Z", "txHash": "0x4e9a…0a4c", "chainId": 42161 },
        "fill": { "timestamp": "2026-10-19T12:00:39.000Z", "txHash": "0x81c3…5d2e", "chainId": 8453, "amount": "9993000" }
      },
      "timestamps": { "createdAt": "2026-10-19T12:00:00.000Z", "publishedAt": "2026-10-19T12:00:20.000Z" },
      "providerStatus": { "provider": "hyperstream", "nativeStatus": "filled" },
      "fromTokenMeta": { "symbol": "USDC", "decimals": 6, "logoURI": "https://api.hyperstream.dev/v1/tokens/icon/fe4f9d5f34ef4ebeb5d80e1f5ff63dcaf5a0d5495f4adf206e4c3011d1f5c57d.svg" },
      "toTokenMeta": { "symbol": "USDC", "decimals": 6, "logoURI": "https://api.hyperstream.dev/v1/tokens/icon/fe4f9d5f34ef4ebeb5d80e1f5ff63dcaf5a0d5495f4adf206e4c3011d1f5c57d.svg" }
    }
  ],
  "cursor": 10
}
```

| Field | Type | Description |
|---|---|---|
| `data` | array | Orders, newest first. |
| `cursor` | integer | Pass it as `cursor` for the next page. Absent on the last page. |

### Errors

| Status | `name` | When |
|---|---|---|
| `400` | `ValidationException` | A malformed address or parameter, an order id in the path, or `cursor` above 1000. |

## One order

```text
GET /v1/orders/by-id/{orderId}
```

Returns one wallet order, in the same shape as an entry of `data` above.

| Parameter | Description |
|---|---|
| `orderId` | A wallet order id: `c` and 24 lowercase letters or digits, as returned by the submit. |

```bash
curl "https://api.hyperstream.dev/v1/orders/by-id/cm2x8k3n70001qz5v9w4r6t2y"
```

This route serves wallet orders only. Look up a deposit-address order (32 hex characters) with `GET /v1/orders/{refundTo}?orderIds={orderId}`.

| Status | Body | When |
|---|---|---|
| `400` | `ValidationException`, `Invalid orderId format` | The id is not `c` and 24 lowercase letters or digits. |
| `404` | Plain text `Order not found` | No wallet order has this id. Not JSON. |

## The order object

| Field | Type | Description |
|---|---|---|
| `id` | string | The order id. |
| `type` | string | The route type: `native-filler`, `liquidity-router` or `external-intent-router`. |
| `quoteId` | string | The quote the order came from. |
| `routeId` | string | The route: `Hyperstream`, `HyperstreamUTXO`, `Across`, `DeBridge` or `Glacis`. |
| `fromChainId` | integer | Source chain id. |
| `fromToken` | string or null | Source token address. |
| `toChainId` | integer | Destination chain id. |
| `toToken` | string or null | Destination token address. |
| `srcAmount` | string | Source amount, in base units. |
| `destAmount` | string | Destination amount as quoted, in base units. The fill transaction's `amount` is what arrived. |
| `status` | string | See [Statuses](#statuses). |
| `author` | string | The depositing wallet. For a deposit-address order, the refund address. |
| `recipient` | string or null | The recipient. `null` means none was set and none could be read from the intent; it does not mean "same as author". |
| `refundTo` | string or null | The refund address, when one was set. |
| `fillerAddress` | string or null | The `filler` sent with the quote, if any. |
| `depositTxHash` | string or null | The deposit's hash. |
| `externalOrderId` | string or null | The external route's own order id, when it has one. |
| `createdAt`, `updatedAt` | string | ISO 8601 timestamps. |
| `tradeType` | string | `EXACT_INPUT` or `EXACT_OUTPUT`. |
| `stepsCompleted` | string[] | Progress steps reached. See [Statuses](#statuses). |
| `transactions` | object | `deposit`, `fill` and `refund`, each optional: `{ timestamp, txHash, chainId, amount? }`. |
| `timestamps` | object | `createdAt`, and optionally `publishedAt` and `failedAt`. |
| `providerStatus` | object | Optional. The route's own status: `{ provider, nativeStatus, substatus?, metadata? }`. `nativeStatus` is the provider's raw value; do not build logic on it. |
| `fromTokenMeta`, `toTokenMeta` | object or null | `{ symbol, decimals, logoURI }`, or `null` when unknown. |

## Statuses

`status` takes one of seven values. Build your logic on these only.

| Status | Meaning | Final? |
|---|---|---|
| `created` | The order exists; the route has not reported deposit progress yet. | No |
| `deposited` | The route reports deposit progress. Source-chain confirmation depends on the route. | No |
| `published` | The order is visible to fillers. | No |
| `filled` | The user received the output on the destination chain. | Yes |
| `refund_pending` | Native route only. The intent was cancelled or expired; waiting for the cross-chain refund message to be delivered. | No |
| `refunded` | The deposit was returned on the source chain. | Yes |
| `failed` | The order cannot complete. | Yes |

Poll every 5 to 10 seconds until the status is `filled`, `refunded` or `failed`. Show `refund_pending` as a refund on its way, not as a failure.

`deposited` is not a finality guarantee. On `HyperstreamUTXO`, both submitted deposits and deposits awaiting confirmation map to it. If you need to know that a Bitcoin or TRON deposit is confirmed, check the source transaction and its confirmation evidence on that chain; the normalized status alone is insufficient.

`stepsCompleted` usually grows `["created"]`, `["created", "deposited"]`, `["created", "deposited", "published"]`, then adds `"filled"`. Treat it as a hint. A route can skip a step (deBridge can go from `deposited` to `filled`), and on a refunded or failed order it can be shorter than how far the order really got. To see what happened, read `status`, `transactions` and `timestamps`.