> ## 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.

# Transit API Reference

> REST API reference for cross-chain Transit order submission.

## Base URL

```
Base URL: https://api.paxoslabs.com
```

All Transit endpoints are public and do not require authentication.

## Response Format

The `/v1/transit/orders/quote` endpoint accepts a `responseFormat` query parameter:

| `responseFormat`      | `data` (hex) | `abi` / `functionName` / `args` | Use when                                                |
| --------------------- | ------------ | ------------------------------- | ------------------------------------------------------- |
| `encoded` *(default)* | Yes          | No                              | Signer consumes raw `data` (`eth_sendTransaction`, HSM) |
| `full`                | Yes          | Yes                             | Debugging; need raw + decoded views                     |
| `structured`          | No           | Yes                             | Encode locally (viem `encodeFunctionData`)              |

***

## Order Quote

`GET /v1/transit/orders/quote`

Returns everything needed to submit a `submitOrder` transaction on-chain: the TransitStation address, ABI-encoded calldata, and ETH value for cross-chain messaging.

### Request Parameters

| Parameter               | Type                   | Required    | Description                                                                                                   |
| ----------------------- | ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
| `userAddress`           | hex string             | Yes         | Wallet address receiving the want asset on the destination chain                                              |
| `offerAmount`           | decimal string         | Yes         | Amount of offer asset in base units. Minimum \$35 USD equivalent.                                             |
| `offerAsset`            | hex string             | Yes         | Token contract address on source chain (debited)                                                              |
| `wantAsset`             | hex string             | Yes         | Token contract address on destination chain (credited)                                                        |
| `sourceChainId`         | integer                | Yes         | EVM chain ID of source chain (where tx is submitted)                                                          |
| `destinationChainId`    | integer                | Yes         | EVM chain ID of destination chain                                                                             |
| `permitSignature`       | hex string (130 chars) | Conditional | EIP-2612 permit signature. Required if `permitDeadline` is provided.                                          |
| `permitDeadline`        | integer                | Conditional | Unix timestamp. Required if `permitSignature` is provided.                                                    |
| `integratorFee`         | decimal string         | Conditional | Fee in offer-asset base units. Required if `integratorFeeReceiver` is provided.                               |
| `integratorFeeReceiver` | hex string             | Conditional | Address to receive integrator fee. Required if `integratorFee` is provided.                                   |
| `distributorCode`       | hex string (64 chars)  | Optional    | 32-byte code tagging order source (emitted on-chain). Defaults to organization's configured distributor code. |
| `responseFormat`        | enum                   | Optional    | `encoded` (default), `full`, or `structured`                                                                  |

### Response

```json theme={null}
{
  "transaction": {
    "to": "0x...",
    "data": "0x...",
    "value": "1500000000000000",
    "abi": [],
    "functionName": "submitOrder",
    "args": []
  },
  "amountOut": "49990000",
  "protocolFee": "10000",
  "integratorFee": "0",
  "totalFees": "10000",
  "estimatedLatencyMs": 300000
}
```

| Field                      | Description                                                                     |
| -------------------------- | ------------------------------------------------------------------------------- |
| `transaction.to`           | TransitStation contract address on source chain                                 |
| `transaction.data`         | ABI-encoded calldata (present when `responseFormat` is `encoded` or `full`)     |
| `transaction.value`        | ETH value to send (decimal string, wei). Covers cross-chain messaging fee.      |
| `transaction.abi`          | Solidity ABI fragment (present when `responseFormat` is `full` or `structured`) |
| `transaction.functionName` | `submitOrder` or `submitOrderWithPermit`                                        |
| `transaction.args`         | Positional arguments (BigInt values as decimal strings)                         |
| `amountOut`                | Net credit in want-asset base units after fees                                  |
| `protocolFee`              | Protocol fee in offer-asset base units                                          |
| `integratorFee`            | Integrator fee in offer-asset base units (`"0"` when none)                      |
| `totalFees`                | Sum of `protocolFee` + `integratorFee`                                          |
| `estimatedLatencyMs`       | Estimated delivery time in milliseconds (undefined if no SLA data)              |

### On-Chain Structs

The `args` array contains the Quote struct and signature:

```solidity theme={null}
struct Route {
  uint32 destEID;
  address offerAsset;
  address wantAsset;
}

struct Quote {
  Route route;
  uint256 offerAmount;
  address receiver;
  uint256 protocolFee;
  uint256 integratorFee;
  address integratorFeeReceiver;
  bytes32 distributorCode;
  uint256 deadline;
  bytes32 salt;
}

function submitOrder(Quote quote, bytes signature) payable returns (bytes32 uuid)

function submitOrderWithPermit(
  Quote quote,
  bytes signature,
  uint256 permitDeadline,
  uint8 v,
  bytes32 r,
  bytes32 s
) payable returns (bytes32 uuid)
```

### Example

```bash theme={null}
curl "https://api.paxoslabs.com/v1/transit/orders/quote?\
userAddress=0x1234567890abcdef1234567890abcdef12345678&\
offerAmount=50000000&\
offerAsset=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&\
wantAsset=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913&\
sourceChainId=1&\
destinationChainId=4663" \
```

### Code Example (viem)

```ts theme={null}
import { createWalletClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const BASE = 'https://api.paxoslabs.com'

// 1. Fetch quote calldata
const url = new URL(`${BASE}/v1/transit/orders/quote`)
url.searchParams.set('userAddress', account.address)
url.searchParams.set('offerAmount', '50000000') // $50 USDC
url.searchParams.set('offerAsset', USDC_ETH)
url.searchParams.set('wantAsset', USDG_RH)
url.searchParams.set('sourceChainId', '1')
url.searchParams.set('destinationChainId', '4663')

const { transaction: tx } = await fetch(url).then((r) => r.json())

// 2. Submit order (value covers messaging fee)
await walletClient.sendTransaction({
  to: tx.to as `0x${string}`,
  data: tx.data as `0x${string}`,
  value: BigInt(tx.value),
  chain: mainnet,
  account,
})
```

***

## Routes

`GET /v1/transit/routes`

Lists available Transit routes for the caller's organization.

### Request Parameters

| Parameter | Type   | Required | Description                                                                                       |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `filter`  | string | Optional | AIP-160 filter expression. Keys: `sourceChainId`, `destinationChainId`, `offerAsset`, `wantAsset` |

### Response

```json theme={null}
{
  "routes": [
    {
      "sourceChainId": 1,
      "destinationChainId": 4663,
      "destinationChainEID": 40451,
      "offerAsset": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "wantAsset": "0x...",
      "minOrderSize": "35000000",
      "tokenMetadataMap": {
        "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48": {
          "chain_id": "1",
          "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "name": "USD Coin",
          "symbol": "USDC",
          "decimals": "6",
          "token_standard": "ERC20"
        }
      }
    }
  ]
}
```

| Field                 | Description                                  |
| --------------------- | -------------------------------------------- |
| `sourceChainId`       | EVM chain ID of source chain                 |
| `destinationChainId`  | EVM chain ID of destination chain            |
| `destinationChainEID` | Endpoint ID of destination chain             |
| `offerAsset`          | Token address on source chain                |
| `wantAsset`           | Token address on destination chain           |
| `minOrderSize`        | Minimum order size in offer-asset base units |
| `tokenMetadataMap`    | Token metadata keyed by lowercase address    |

***

## Get Order

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

Returns indexer-backed status and details for a single Transit order.

### Path Parameters

| Parameter | Type                  | Description                                    |
| --------- | --------------------- | ---------------------------------------------- |
| `orderId` | hex string (64 chars) | 32-byte order ID (from `OrderSubmitted` event) |

### Response

```json theme={null}
{
  "order": {
    "id": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "offerAsset": "0x...",
    "wantAsset": "0x...",
    "amountDue": "50000000",
    "remainingAmountDue": "0",
    "offerAmount": "50000000",
    "receiver": "0x...",
    "distributorCode": "0x0000...0000",
    "destinationChainId": 4663,
    "sourceChainId": 1,
    "receiveTime": 1234567890,
    "status": "PROCESSED",
    "user": "0x...",
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-01T00:05:00Z",
    "tokenMetadata": {},
    "orderExecuteds": [
      {
        "id": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "amount": "50000000",
        "remaining": "0",
        "timestamp": 1234567890,
        "txHash": "0x...",
        "chainId": 4663
      }
    ]
  }
}
```

### Order Status Values

| Status           | Meaning                                     |
| ---------------- | ------------------------------------------- |
| `PENDING_BRIDGE` | Order submitted, awaiting bridge processing |
| `PROCESSING`     | Order is being processed                    |
| `PROCESSED`      | Order fulfilled                             |
| `REMOVED`        | Order removed                               |

***

## List Orders

`GET /v1/transit/orders`

Returns a paginated list of orders for a user address.

### Request Parameters

| Parameter     | Type       | Required | Description                                                                                             |
| ------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `userAddress` | hex string | Yes      | User wallet address to filter by                                                                        |
| `pageSize`    | integer    | Optional | Results per page (default: 10, max: 100)                                                                |
| `pageToken`   | string     | Optional | Opaque cursor for next page                                                                             |
| `filter`      | string     | Optional | AIP-160 filter expression. Keys: `offerAsset`, `wantAsset`, `sourceChain`, `destinationChain`, `status` |

### Response

```json theme={null}
{
  "orders": [],
  "nextPageToken": "opaque-cursor"
}
```

***

## Error Handling

```json theme={null}
{
  "error": {
    "code": 400,
    "message": "Order amount is below the minimum of $35",
    "status": "INVALID_ARGUMENT"
  }
}
```

| HTTP | `error.status`     | Action                                    |
| ---- | ------------------ | ----------------------------------------- |
| 400  | `INVALID_ARGUMENT` | Fix request (e.g., increase offer amount) |
| 404  | `NOT_FOUND`        | Order or route not found                  |
| 503  | `INTERNAL`         | Retry with exponential backoff            |

***

## Common Errors

| Issue                                                | Error                  | Fix                                                |
| ---------------------------------------------------- | ---------------------- | -------------------------------------------------- |
| Offer amount below \$35 USD                          | `400 INVALID_ARGUMENT` | Increase offer amount                              |
| Missing `permitDeadline` with `permitSignature`      | `400 INVALID_ARGUMENT` | Provide both or neither                            |
| Missing `integratorFeeReceiver` with `integratorFee` | `400 INVALID_ARGUMENT` | Provide both or neither                            |
| Invalid `distributorCode` length                     | `400 INVALID_ARGUMENT` | Must be 32 bytes (0x + 64 hex chars)               |
| Insufficient ETH for `value`                         | On-chain revert        | Ensure wallet has ETH to cover `transaction.value` |
| Route not available                                  | `404 NOT_FOUND`        | Check `/v1/transit/routes` for available pairs     |

***

## Supported Chains

| Chain    | ID   |
| -------- | ---- |
| Ethereum | 1    |
| RH Chain | 4663 |