> ## Documentation Index
> Fetch the complete documentation index at: https://developers.paxoslabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Tracking

> Monitor Transit order status and view execution history.

After submitting an order, use these endpoints to track fulfillment progress and view execution details.

## Get Single Order

`GET /v1/transit/orders/:orderId`

Retrieve status and details for a specific order.

### Parameters

| Parameter | Type          | Description                                         |
| --------- | ------------- | --------------------------------------------------- |
| `orderId` | string (path) | Order ID (hex hash) from the `OrderSubmitted` event |

### Example Request

```bash theme={null}
curl "https://api.paxoslabs.com/v1/transit/orders/0x2680b1256a66f8e762a64b2dda813a071356530715f0084d38f0c67cd8a2068f" \
```

### Response

```json theme={null}
{
  "order": {
    "id": "0x2680b1256a66f8e762a64b2dda813a071356530715f0084d38f0c67cd8a2068f",
    "offerAsset": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "wantAsset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "amountDue": "49750000",
    "remainingAmountDue": "0",
    "offerAmount": "50000000",
    "receiver": "0x1234567890abcdef1234567890abcdef12345678",
    "distributorCode": null,
    "destinationChainId": 4663,
    "sourceChainId": 1,
    "receiveTime": 1735689600,
    "status": "PROCESSED",
    "user": "0x1234567890abcdef1234567890abcdef12345678",
    "createdAt": "2026-01-21T15:04:05Z",
    "updatedAt": "2026-01-21T15:09:05Z",
    "tokenMetadata": {},
    "orderExecuteds": [
      {
        "id": "4663_71768178_6",
        "amount": "49750000",
        "remaining": "0",
        "timestamp": 1735689600,
        "txHash": "0xbf747f3281c538b42c6e7730007867d1bf6107ea33722b860c05be61e8b9bc57",
        "chainId": 4663
      }
    ]
  }
}
```

## Order Status Values

| Status           | Description                          |
| ---------------- | ------------------------------------ |
| `PENDING_BRIDGE` | Order submitted, awaiting processing |
| `PROCESSING`     | Order is being fulfilled             |
| `PROCESSED`      | Order complete — funds delivered     |
| `REMOVED`        | Order removed from the queue         |

## List Orders

`GET /v1/transit/orders`

Retrieve a paginated list of orders for a user address.

### Parameters

| Parameter     | Type       | Required | Description                              |
| ------------- | ---------- | -------- | ---------------------------------------- |
| `userAddress` | hex string | Yes      | Wallet address to filter by              |
| `pageSize`    | integer    | No       | Results per page (default: 10, max: 100) |
| `pageToken`   | string     | No       | Cursor for next page                     |
| `filter`      | string     | No       | AIP-160 filter expression                |

### Filter Keys

| Key                | Type       | Description                    |
| ------------------ | ---------- | ------------------------------ |
| `offerAsset`       | hex string | Filter by offer token address  |
| `wantAsset`        | hex string | Filter by want token address   |
| `sourceChain`      | integer    | Filter by source chain ID      |
| `destinationChain` | integer    | Filter by destination chain ID |
| `status`           | enum       | Filter by order status         |

### Example Request

```bash theme={null}
curl "https://api.paxoslabs.com/v1/transit/orders?\
userAddress=0x1234567890abcdef1234567890abcdef12345678" \
```

With filtering:

```bash theme={null}
curl "https://api.paxoslabs.com/v1/transit/orders?\
userAddress=0x1234...&\
filter=status%3DPROCESSED" \
```

### Response

```json theme={null}
{
  "orders": [
    {
      "id": "0x2680b1256a66f8e762a64b2dda813a071356530715f0084d38f0c67cd8a2068f",
      "status": "PROCESSED",
      ...
    }
  ],
  "nextPageToken": "eyJvZmZzZXQiOjI1fQ=="
}
```

## Polling for Completion

Poll the single-order endpoint until `status` reaches a terminal state (`PROCESSED` or `REMOVED`).

```ts theme={null}
async function waitForOrder(orderId: string): Promise<Order> {
  const url = `https://api.paxoslabs.com/v1/transit/orders/${orderId}`

  while (true) {
    const { order } = await fetch(url).then((r) => r.json())

    if (order.status === 'PROCESSED' || order.status === 'REMOVED') {
      return order
    }

    await new Promise((r) => setTimeout(r, 10_000)) // 10s interval
  }
}
```

## Response Fields

| Field                | Type           | Description                                        |
| -------------------- | -------------- | -------------------------------------------------- |
| `id`                 | string         | Order ID (hex hash from on-chain event)            |
| `offerAsset`         | string         | Token sent (source chain)                          |
| `wantAsset`          | string         | Token received (destination chain)                 |
| `amountDue`          | string         | Initial amount owed (want-asset base units)        |
| `remainingAmountDue` | string         | Outstanding amount (decreases with partial fills)  |
| `offerAmount`        | string         | Amount sent by user (offer-asset base units)       |
| `receiver`           | string         | Address receiving funds                            |
| `distributorCode`    | string \| null | 32-byte hex tracking code, or null if not provided |
| `destinationChainId` | number         | Destination chain EVM ID                           |
| `sourceChainId`      | number         | Source chain EVM ID                                |
| `receiveTime`        | number         | Unix timestamp when order was indexed              |
| `status`             | string         | Current order status                               |
| `user`               | string         | Address that submitted the order                   |
| `createdAt`          | string         | ISO 8601 creation time                             |
| `updatedAt`          | string         | ISO 8601 last update time                          |
| `tokenMetadata`      | object         | Token metadata for offer and want assets           |
| `orderExecuteds`     | array          | Execution history with amounts and tx hashes       |

## Error Responses

| HTTP  | Cause           | Action          |
| ----- | --------------- | --------------- |
| `404` | Order not found | Verify order ID |