> For the complete documentation index, see [llms.txt](https://docs.glacislabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.glacislabs.com/zero-delta/integration-guide/api/models.md).

# Models

Schema reference for the ZeroDelta read API: envelope, error codes, status vocabulary, compliance decision, quote and order shapes, and the tracked transaction with its chained-journey fields.

Schema reference for the ZeroDelta read API. For the endpoints that return these shapes, see the API reference.

### Envelope

Every `/api/v1/*` response uses this wrapper. `data` carries the result (an object or array); `error` is present only on failure; `meta` and `paging` appear on list responses.

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>data</code></td><td>object or array</td><td>The resource payload.</td></tr><tr><td><code>error.code</code></td><td>ErrorCode</td><td>Machine-readable error code.</td></tr><tr><td><code>error.message</code></td><td>string</td><td>Human-readable message.</td></tr><tr><td><code>error.fieldErrors[]</code></td><td>array</td><td>Per-field errors, each <code>{ field, message }</code>.</td></tr><tr><td><code>error.reasons[]</code></td><td>array</td><td>Machine-readable decision reason codes, populated on <code>COMPLIANCE_BLOCKED</code> per the server's disclosure policy (<code>POLICY_GUARD_REASON_DISCLOSURE</code>).</td></tr><tr><td><code>meta.page</code></td><td>integer</td><td>Current page.</td></tr><tr><td><code>meta.perPage</code></td><td>integer</td><td>Items per page.</td></tr><tr><td><code>meta.totalCount</code></td><td>integer</td><td>Total matching items.</td></tr><tr><td><code>paging.self</code></td><td>string</td><td>URL of the current page.</td></tr><tr><td><code>paging.next</code></td><td>string or null</td><td>URL of the next page, or null.</td></tr><tr><td><code>paging.prev</code></td><td>string or null</td><td>URL of the previous page, or null.</td></tr></tbody></table>

On error, only the `error` object is populated:

```json
{ "error": { "code": "UNAUTHORIZED", "message": "missing or invalid API key" } }
```

Branch on `error.code` (machine-readable), not on `error.message`.

### ErrorCode

<table data-search="false"><thead><tr><th>Value</th><th>Typical status</th></tr></thead><tbody><tr><td><code>INTERNAL_ERROR</code></td><td>500</td></tr><tr><td><code>BAD_REQUEST</code></td><td>400</td></tr><tr><td><code>NOT_FOUND</code></td><td>404</td></tr><tr><td><code>CONFLICT</code></td><td>409</td></tr><tr><td><code>VALIDATION_ERROR</code></td><td>422</td></tr><tr><td><code>UNAUTHORIZED</code></td><td>401</td></tr><tr><td><code>FORBIDDEN</code></td><td>403</td></tr><tr><td><code>RATE_LIMITED</code></td><td>429</td></tr><tr><td><code>SERVICE_UNAVAILABLE</code></td><td>503</td></tr><tr><td><code>QUOTE_UNAVAILABLE</code></td><td>422</td></tr><tr><td><code>BRIDGE_RATE_LIMITED</code></td><td>422</td></tr><tr><td><code>ROUTE_UNHEALTHY</code></td><td>422</td></tr><tr><td><code>UPSTREAM_ERROR</code></td><td>502</td></tr><tr><td><code>BELOW_MIN_TRADE_SIZE</code></td><td>422</td></tr><tr><td><code>COMPLIANCE_BLOCKED</code></td><td>422</td></tr><tr><td><code>WALLETS_REQUIRED</code></td><td>400</td></tr><tr><td><code>FEE_NOT_ENABLED</code></td><td>403</td></tr><tr><td><code>FEE_WALLETS_REQUIRED</code></td><td>400</td></tr><tr><td><code>FEE_UNSUPPORTED_LANE</code></td><td>400</td></tr><tr><td><code>FEE_UNAVAILABLE</code></td><td>503</td></tr><tr><td><code>FEE_NOTHING_TO_CLAIM</code></td><td>409</td></tr><tr><td><code>FEE_BELOW_MINIMUM</code></td><td>409</td></tr></tbody></table>

### TrackingStatus

Lifecycle status of a tracked cross-chain transaction. Returned as a lowercase string (not the on-chain `OrderStatus` enum — see the Smart Contract Reference). When polling, treat any value outside the non-terminal set as terminal so a newly added status cannot trap your loop.

<table data-search="false"><thead><tr><th>Status</th><th>Terminal?</th><th>Meaning</th></tr></thead><tbody><tr><td><code>pending</code></td><td>no</td><td>Submitted; awaiting arrival on the execution chain.</td></tr><tr><td><code>in_progress</code></td><td>no</td><td>Arrived on the execution chain; awaiting fill.</td></tr><tr><td><code>outbound_bridging</code></td><td>no</td><td>Filled; bridging out to the destination chain.</td></tr><tr><td><code>cancel_pending</code></td><td>no</td><td>User pre-cancelled; awaiting arrival to claim.</td></tr><tr><td><code>awaiting_claim</code></td><td>no</td><td>Arrived after a pre-cancel; user can claim funds.</td></tr><tr><td><code>continuing</code></td><td>no</td><td>A chained journey's leg 1 landed and the connector is parked on the destination escrow, awaiting leg 2. Appears on <code>journeyStatus</code>.</td></tr><tr><td><code>delivered</code></td><td>yes</td><td>Success — receiver got the asset.</td></tr><tr><td><code>expired</code></td><td>yes</td><td>Deadline elapsed in transit (claim required).</td></tr><tr><td><code>cancelled</code></td><td>yes</td><td>Order cancelled; funds returned.</td></tr><tr><td><code>fill_failed</code></td><td>yes</td><td>Solver gave up before filling.</td></tr><tr><td><code>delivery_failed</code></td><td>yes</td><td>Outbound bridge permanently failed.</td></tr><tr><td><code>failed</code></td><td>yes</td><td>Generic unrecoverable failure.</td></tr></tbody></table>

Happy path: `pending → in_progress → outbound_bridging → delivered`.

> **`status` is per-order; `journeyStatus` is per-journey.** On a chained (two-leg) order — which is what a tokenized-asset purchase is — the parent's `status` reads `delivered` as soon as leg 1 lands, because that leg genuinely finished. The value is parked mid-journey, not in the receiver's wallet, and `journeyStatus` reads `continuing` for that whole window. Put completion checks on `journeyStatus`, falling back to `status` when it is absent (it is absent on non-chained orders).

### Compliance

The complete compliance-engine decision surfaced on a quote — the result of screening the owner (and receiver, when supplied) before deposit instructions are returned. Benign decision metadata is always present. The risk and sanctions signals (`riskCategories`, `flaggedCategories`, `blockingCategories`, `reasons`) are disclosure-gated by the server's `POLICY_GUARD_REASON_DISCLOSURE` setting (`all` | `policy` | `none`) to avoid tipping off, so they may be omitted even when the upstream engine populated them.

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>status</code></td><td>string</td><td><code>SCREENED</code> when the wallet pair was checked and approved; <code>UNSCREENED</code> when no <code>owner</code> was supplied. Always present.</td></tr><tr><td><code>decision</code></td><td>string</td><td>Engine verdict: <code>ALLOW</code>, <code>DENY</code>, <code>REVIEW</code> or <code>REMEDIATE</code>. A successful quote is only ever returned for <code>ALLOW</code>. There is no <code>BLOCK</code> value — a client branching on one would treat every refusal as an allow.</td></tr><tr><td><code>screenedWallets[]</code></td><td>string[]</td><td>The addresses screened — <code>owner</code>, plus the receiver when supplied.</td></tr><tr><td><code>sourceJurisdiction</code></td><td>string</td><td>Jurisdiction resolved for the owner (e.g. <code>EU</code>, <code>US_EX_NY</code>).</td></tr><tr><td><code>appliedPolicyIds[]</code> / <code>appliedPolicyNames[]</code></td><td>string[]</td><td>The policies the decision was evaluated against.</td></tr><tr><td><code>appliedLegislation[]</code></td><td>string[]</td><td>In-scope legislation overlays applied (e.g. <code>["MICA_EU"]</code>).</td></tr><tr><td><code>riskCategories[]</code></td><td>string[]</td><td>Risk categories detected. Disclosure-gated.</td></tr><tr><td><code>flaggedCategories[]</code></td><td>string[]</td><td>Non-blocking flagged categories. Disclosure-gated.</td></tr><tr><td><code>blockingCategories[]</code></td><td>string[]</td><td>Categories that would block. Disclosure-gated.</td></tr><tr><td><code>reasons[]</code></td><td>string[]</td><td>Machine-readable decision reason codes. Disclosure-gated.</td></tr><tr><td><code>policyVersion</code></td><td>string</td><td>Content-addressed version of the composed policy used.</td></tr><tr><td><code>checkId</code></td><td>string</td><td>Unique id for this compliance check (audit-trail anchor).</td></tr><tr><td><code>expiresAt</code></td><td>string</td><td>When this decision stops being valid (RFC 3339).</td></tr></tbody></table>

### QuoteRequest

| Field                 | Type   | Required | Description                                                                                                                                                                                                                                                                                                                    |
| --------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `fromChainId`         | string | yes      | Source chain ID (string or number accepted).                                                                                                                                                                                                                                                                                   |
| `toChainId`           | string | yes      | Destination chain ID.                                                                                                                                                                                                                                                                                                          |
| `fromToken`           | string | yes      | Source token symbol or contract address.                                                                                                                                                                                                                                                                                       |
| `toToken`             | string | yes      | Destination token symbol or address.                                                                                                                                                                                                                                                                                           |
| `fromAmount`          | string | yes      | Amount to sell, in smallest unit.                                                                                                                                                                                                                                                                                              |
| `owner`               | string | no       | Order owner address; when set, the response includes `escrowAddress` and `executionChainId`.                                                                                                                                                                                                                                   |
| `destinationReceiver` | string | no       | Recipient wallet; screened alongside `owner` when present.                                                                                                                                                                                                                                                                     |
| `sender`              | string | no       | The wallet that pays for and signs the order: a hex address on an EVM source, a base58 public key on a Solana source (`fromChainId` `1151111081099710`). When set, the response carries `txData` and `owner` and `destinationReceiver` become required. `503` when the gateway cannot build transactions for the source chain. |
| `deadline`            | string | no       | Only with `sender`. The order's deadline that `txData` signs for, in unix seconds (decimal string). Absent: the quote's `recommendedDeadline`. `"0"`: no deadline. A past value is a `400`.                                                                                                                                    |

### Quote

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>fromChainId</code></td><td>string</td><td>Source chain ID.</td></tr><tr><td><code>toChainId</code></td><td>string</td><td>Destination chain ID.</td></tr><tr><td><code>fromToken</code></td><td>string</td><td>Source token.</td></tr><tr><td><code>toToken</code></td><td>string</td><td>Destination token.</td></tr><tr><td><code>fromAmount</code></td><td>string</td><td>Amount sold, smallest unit.</td></tr><tr><td><code>toAmount</code></td><td>string</td><td>On-chain <code>order.askTokenAmount</code> — the swap output threshold the solver must meet to fill the order; used to construct <code>orderRequests[].askTokenAmount</code>. NOT what the receiver gets when the outbound bridge charges a protocol fee — see <code>finalAmount</code>.</td></tr><tr><td><code>finalAmount</code></td><td>string</td><td>What the receiver gets: <code>toAmount</code> minus the outbound CCTP fast-track maxFee. <code>&#x3C;= toAmount</code> (equal for LayerZero outbound / CCTP slow-track). Always populated.</td></tr><tr><td><code>bridge</code></td><td>string</td><td>Bridge provider for the route (e.g. <code>Circle</code>).</td></tr><tr><td><code>feeBps</code></td><td>integer</td><td>Route protocol fee in basis points (CCTP fast-track fee for Circle lanes; <code>0</code> for LayerZero). Metadata only — NOT subtracted from <code>toAmount</code>; the actual fee is the gap between <code>toAmount</code> and <code>finalAmount</code>.</td></tr><tr><td><code>inboundProtocolFee</code></td><td>string</td><td>CCTP fast-track maxFee debited from the input before pricing: the inbound bridge delivers <code>fromAmount − inboundProtocolFee</code>. <code>"0"</code> for LayerZero bids, local bids, slow-track lanes.</td></tr><tr><td><code>estimatedDuration</code></td><td>integer</td><td>End-to-end transfer time in seconds: inbound bridge finality + execution-chain swap window + outbound bridge finality, plus a per-leg fill-latency buffer for tx inclusion.</td></tr><tr><td><code>recommendedDeadline</code></td><td>string</td><td>Suggested value for <code>orderRequests[0].deadline</code>: a unix timestamp in seconds (decimal string), equal to the quote time plus <code>recommendedDeadlineSeconds</code>. Derived from this lane's <code>estimatedDuration</code>: the estimate plus one hour, never below one hour and never above 24 hours (a 30-minute lane gets 1h30, a two-hour lane 3h). Advisory — without a <code>sender</code>, <code>orderRequests[].deadline</code> comes back <code>"0"</code> and you set it; with one, <code>orderRequests[0].deadline</code> is already the deadline <code>txData</code> signs for. A shorter deadline risks the order expiring before it can be filled: the fill then reverts <code>ZDLite__OrderExpired</code>, the order ends <code>fill_failed</code>, and the owner calls <code>cancel</code> to recover the funds. Absent when the gateway has no recommendation.</td></tr><tr><td><code>recommendedDeadlineSeconds</code></td><td>integer</td><td><code>recommendedDeadline</code> as a span in seconds from the moment of the quote. Absent together with it.</td></tr><tr><td><code>lifespanSeconds</code></td><td>integer</td><td>Quote validity in seconds, from the winning provider's signed expiry (floored at 0). <code>0</code> when the provider does not sign an expiry or the quote has lapsed. The on-chain fill threshold itself does not expire.</td></tr><tr><td><code>swapTimeSeconds</code></td><td>integer</td><td>Estimated time for the on-chain swap to settle on the execution chain — one block of the execution chain (average block time, differs per chain). <code>0</code> when block-time data is unavailable.</td></tr><tr><td><code>route</code></td><td>Route</td><td>The route this quote priced.</td></tr><tr><td><code>gasCostSource</code></td><td>string</td><td>LayerZero inbound native fee in wei; <code>0</code> for CCTP. Pass as <code>msg.value</code>.</td></tr><tr><td><code>gasCostDest</code></td><td>string</td><td>LayerZero outbound native fee in wei; <code>0</code> for CCTP.</td></tr><tr><td><code>swapCost</code></td><td>string</td><td>Gas hint from the winning liquidity provider (decimal string; empty when not provided).</td></tr><tr><td><code>provider</code></td><td>string</td><td>Masked liquidity-provider label — always <code>"zerodelta"</code> on a successful swap quote; omitted on direct-bridge quotes.</td></tr><tr><td><code>orderRequests</code></td><td>OrderRequest[]</td><td>Pre-built argument array for <code>submitOrder</code>. One element normally, two when <code>isChained</code>.</td></tr><tr><td><code>isDirect</code></td><td>boolean</td><td>Direct-bridge quote (same token, different chains): no swap, no solver fill, not cancellable; <code>provider</code> and the top-level cancel coordinates are omitted.</td></tr><tr><td><code>isChained</code></td><td>boolean</td><td>Two-leg quote: <code>orderRequests</code> carries two elements and settlement spans two execution chains.</td></tr><tr><td><code>escrowAddress</code></td><td>string</td><td>Source-chain escrow address (present when <code>owner</code> is supplied).</td></tr><tr><td><code>executionChainId</code></td><td>string</td><td>Chain ID where settlement executes and where <code>cancel</code> runs (present when <code>owner</code> is supplied; omitted on direct quotes).</td></tr><tr><td><code>executionEscrowAddress</code></td><td>string</td><td>Escrow address on the execution chain.</td></tr><tr><td><code>complianceStatus</code></td><td>string</td><td><code>SCREENED</code> or <code>UNSCREENED</code>.</td></tr><tr><td><code>compliance</code></td><td>Compliance</td><td>Full screening decision; present only when the gate is configured and an <code>owner</code> was supplied.</td></tr><tr><td><code>txData</code></td><td>EvmTransaction[] or SolanaTransaction[]</td><td>Present only when the request named a <code>sender</code>. The unsigned transactions the order needs, in send order: send each one and wait for it to confirm before sending the next. The entries follow the source chain's family. EVM: an <code>approve</code> when the escrow's allowance from <code>sender</code> on the bid token is below the bid (two, a zero-amount reset first, for a token that refuses to overwrite a stale allowance), then <code>submit</code>. Solana: a returning wallet's single-leg order is one <code>submit</code>; a first order is <code>setup</code> then <code>submit</code>; a chained order adds one <code>write</code> per 700-byte piece of its route. Never re-send stored transactions after a failure or an expiry — request a new quote; the gateway reads the wallet's state on every build and returns only what is still to do.</td></tr></tbody></table>

**`partnerId`.** `partnerId` is present on every quote that carries `feeRecipients` (see Integrator fees below), and on certain other quotes depending on your API key; on a fee quote it is always the string form. It is either a `0x`-prefixed 32-byte hex string bound to the quoted order and both wallets, or `{ "error": "..." }` when `owner` or `destinationReceiver` was omitted from a quote without `feeRecipients`. In the latter case, request a new quote naming both wallets before submission. Pass a string marker verbatim to `submitOrder`; for a quote without `partnerId`, use `bytes32(0)`. Direct-bridge quotes (`isDirect: true`) never carry it. Changing a marked order's wallets or amounts invalidates its marker.

### OrderRequest

Pre-built Solidity `OrderRequest` struct, one element of the array `submitOrder()` takes. `owner` and `destinationReceiver` come back filled with the wallets the quote request named, or `null` when it named none — make sure both are set on **every** element with real, non-zero addresses before calling the contract (see the Integration Guide).

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>owner</code></td><td>string or null</td><td>The request's <code>owner</code>, or <code>null</code> — fill with the user's wallet address.</td></tr><tr><td><code>bidToken</code></td><td>string</td><td>Resolved source token contract address.</td></tr><tr><td><code>bidTokenAmount</code></td><td>string</td><td>Amount in smallest unit. On <code>orderRequests[1]</code> of a chained quote this is an estimate the contract overwrites with actual receipts.</td></tr><tr><td><code>askToken</code></td><td>string</td><td>Resolved destination token contract address (passed on-chain as <code>bytes</code>; a 20-byte hex string for EVM).</td></tr><tr><td><code>askTokenAmount</code></td><td>string</td><td>On-chain fill threshold — the swap output the solver must meet to fill the order. Always equals <code>Quote.toAmount</code>. NOT what the destination receiver gets when the outbound bridge charges a protocol fee — see <code>Quote.finalAmount</code>.</td></tr><tr><td><code>destinationReceiver</code></td><td>string or null</td><td>Filled from the request's <code>destinationReceiver</code>, or <code>null</code> — fill with the recipient address (20 bytes for EVM; the contract rejects any width other than 20 or 32).</td></tr><tr><td><code>destinationChainId</code></td><td>string</td><td>Target chain ID.</td></tr><tr><td><code>executionChainId</code></td><td>string</td><td>Chain this order clears on. Always populated; the contract rejects <code>0</code> and any chain outside its allowlist.</td></tr><tr><td><code>deadline</code></td><td>string</td><td>Unix seconds; <code>"0"</code> means no deadline. Returned as <code>"0"</code> — set it before calling <code>submitOrder</code>; <code>Quote.recommendedDeadline</code> is the suggested value for this lane. When the request named a <code>sender</code>, <code>orderRequests[0].deadline</code> is already the deadline <code>txData</code> signs for.</td></tr></tbody></table>

### EvmTransaction

One entry of `Quote.txData` on an EVM source: a call for the `sender` wallet to send on `chainId`. Gas is the wallet's to estimate. Decode `data` against the escrow ABI and compare it with the quote before signing.

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>actionType</code></td><td>string</td><td><code>approve</code> — ERC-20 <code>approve(escrow, amount)</code> on the bid token; a zero-amount one comes first when the token refuses to overwrite a stale allowance. <code>submit</code> — <code>submitOrder(requests, partnerId)</code> on the escrow, with every leg of the quote in the calldata.</td></tr><tr><td><code>chainId</code></td><td>string</td><td>The source chain, decimal.</td></tr><tr><td><code>to</code></td><td>string</td><td>The contract called — the bid token, or the escrow.</td></tr><tr><td><code>data</code></td><td>string</td><td>The calldata, <code>0x</code>-hex.</td></tr><tr><td><code>value</code></td><td>string</td><td><code>msg.value</code> in wei, decimal. On the <code>submit</code> of a LayerZero lane, the source messaging fee (<code>gasCostSource</code>) plus 15% headroom; <code>"0"</code> otherwise.</td></tr></tbody></table>

### SolanaTransaction

One entry of `Quote.txData` on a Solana source: an unsigned, serialized transaction. The `sender` wallet is the fee payer and the first signer on every one. You may replace the recent blockhash before signing; nothing else in the message depends on it.

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>actionType</code></td><td>string</td><td><code>setup</code> — the wallet's profile and its first empty route buffer, in one transaction (a wallet's first order, or a first buffer left unfinished). <code>buffer</code> — a new empty route buffer, when the first one cannot serve. <code>write</code> — one piece of a chained route into the order's buffer; the last piece seals it. <code>submit</code> — the order itself, always alone.</td></tr><tr><td><code>instructions</code></td><td>string[]</td><td>The program instructions inside, in order, by IDL name (for example <code>["create_profile", "initialize_buffer_data", "finalize_buffer_data"]</code>).</td></tr><tr><td><code>transaction</code></td><td>string</td><td>Base64 serialized transaction (<code>VersionedTransaction.deserialize</code> in web3.js), every signature slot empty.</td></tr><tr><td><code>blockhash</code></td><td>string</td><td>The recent blockhash the message was compiled with.</td></tr><tr><td><code>lastValidBlockHeight</code></td><td>integer</td><td>The last block height at which that blockhash is valid.</td></tr><tr><td><code>buildData</code></td><td>object</td><td>On the <code>submit</code> transaction only: <code>salt</code> (32 random bytes, <code>0x</code>-hex, new on every build) and <code>messageSentEventData</code> (a base58 public key).</td></tr></tbody></table>

**The `submit` transaction has a second signer.** CCTP creates its `message_sent_event_data` account inside the order instruction, so that account signs for its own creation. Its keypair is derived, never sent: `seed = sha256(sender public key bytes ‖ salt bytes)`, then an ed25519 keypair from that seed (`Keypair.fromSeed(seed)` in web3.js). Check that its public key equals `buildData.messageSentEventData`, then sign the transaction with it and with the wallet, in either order, after any blockhash change.

### Integrator fees

The shapes behind `feeRecipients` on a quote and the Fees endpoints (see the API reference).

> ⚠️ **`chainId` has two types here.** It is a **string** in `RecipientFees`, like every chain id in a quote, and an **integer** in `FeePayoutTarget` and `FeePayout`. Parse each where it appears.

> **Money is an exact decimal string.** `amountUsd` carries up to 18 decimal places. Never parse it as a float.

**The fee arithmetic**, so you can reproduce `recipientFees` from a quote:

* `gross` is the ask before the fee: `toAmount + recipientFees.amount`.
* `fee = floor(gross × totalCentibps ÷ 1,000,000)`. When the output leaves the execution chain over LayerZero, the fee is floored again to the bridge's 6-decimal grid.
* Each recipient's share is `floor(fee × feeCentibps ÷ totalCentibps)`, with the rounding remainder going to the **first** recipient, so the shares always sum to `amount`.

#### FeeRecipient

One entry of `QuoteRequest.feeRecipients` (1–8 entries, each `recipient` unique, total `feeCentibps` at most 100,000 = 10%).

| Field         | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recipient`   | string  | The address owed this share. An EVM address: `0x` plus 40 hex digits, not the zero address; all-lowercase or all-uppercase is accepted as written, mixed case must carry a valid EIP-55 checksum, and the response echoes it checksummed. Or a Solana address: base58 that decodes to 32 bytes, not `11111111111111111111111111111111`, kept **verbatim** (base58 case is significant). The echoed form is the one balances and payout claims use. |
| `feeCentibps` | integer | This recipient's fee in centibps of the output (100 = 1 bps), 1 to 100,000.                                                                                                                                                                                                                                                                                                                                                                        |

#### RecipientFees

`Quote.recipientFees`, present only when the request carried `feeRecipients`: the fee taken off this quote. Amounts are raw units of the output token **on the execution chain**, the same scale as `toAmount`.

| Field           | Type    | Description                                                                                |
| --------------- | ------- | ------------------------------------------------------------------------------------------ |
| `totalCentibps` | integer | Sum of the recipients' `feeCentibps`.                                                      |
| `amount`        | string  | The whole fee, raw units.                                                                  |
| `chainId`       | string  | The execution chain. **A string**, unlike `chainId` in the payout shapes.                  |
| `token`         | string  | The output token's address on the execution chain.                                         |
| `decimals`      | integer | That token's decimals.                                                                     |
| `recipients[]`  | array   | One `{ recipient, feeCentibps, amount }` per requested recipient; amounts sum to `amount`. |

#### FeeBalance

| Field       | Type               | Description                                                                                                        |
| ----------- | ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `recipient` | string             | EVM, EIP-55 checksummed, or Solana, base58 verbatim.                                                               |
| `amountUsd` | string             | Unclaimed fees in US dollars, each valued at its fill block's market price. Exact decimal string, up to 18 places. |
| `fills`     | integer            | Fills that contributed since the last claim.                                                                       |
| `updatedAt` | string (date-time) | RFC 3339 timestamp.                                                                                                |

#### FeeBalancesListing

| Field      | Type          | Description                                                                                               |
| ---------- | ------------- | --------------------------------------------------------------------------------------------------------- |
| `rows`     | FeeBalance\[] | One row per recipient this key has paid.                                                                  |
| `measured` | boolean       | `false` (with no rows) when the balances could not be read right now. It never means "nothing collected". |

#### FeePayoutClaim

| Field          | Type               | Description                                                                                                  |
| -------------- | ------------------ | ------------------------------------------------------------------------------------------------------------ |
| `recipients[]` | FeePayoutTarget\[] | 1 to 100. A recipient appears once per claim (an EVM address regardless of case; a Solana address verbatim). |

#### FeePayoutTarget

| Field       | Type    | Description                                                                                                                                                                                                 |
| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recipient` | string  | The recipient whose balance is claimed, and the address the payout is sent to: a Solana address when `chainId` is Solana, an EVM address on every other chain.                                              |
| `chainId`   | integer | The chain the USDC payout is sent on. **An integer.** One of `1`, `10`, `130`, `137`, `143`, `146`, `196`, `1329`, `1672`, `8453`, `9745`, `42161`, `43114`, `57073`, `98866`, `1151111081099710` (Solana). |

#### FeePayout

| Field         | Type               | Description                                                                             |
| ------------- | ------------------ | --------------------------------------------------------------------------------------- |
| `id`          | string (uuid)      | Payout request ID.                                                                      |
| `keyId`       | string             | The claiming API key's fee attribution id (16 hex characters).                          |
| `recipient`   | string             | EVM, EIP-55 checksummed, or Solana, base58 verbatim.                                    |
| `chainId`     | integer            | The chain the payout is sent on, as named in the claim. Always present. **An integer.** |
| `amountUsd`   | string             | The whole balance claimed, in US dollars. Exact decimal string.                         |
| `fills`       | integer            | Fills the claimed balance came from.                                                    |
| `status`      | string             | `pending` or `completed`.                                                               |
| `requestedAt` | string (date-time) | When the claim was made.                                                                |
| `completedAt` | string (date-time) | When the payout was sent. Absent while `pending`.                                       |

### Chain

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>chainId</code></td><td>string</td><td>Chain ID (serialized as a string).</td></tr><tr><td><code>name</code></td><td>string</td><td>Internal name (e.g. <code>arbitrum</code>).</td></tr><tr><td><code>displayName</code></td><td>string</td><td>Human label (e.g. <code>Arbitrum One</code>).</td></tr><tr><td><code>explorerUrl</code></td><td>string</td><td>Block explorer base URL.</td></tr><tr><td><code>nativeCurrency</code></td><td>string</td><td>Native currency symbol.</td></tr><tr><td><code>isTestnet</code></td><td>boolean</td><td>Testnet flag.</td></tr><tr><td><code>isEnabled</code></td><td>boolean</td><td>Whether the chain is enabled.</td></tr><tr><td><code>isExecutionChain</code></td><td>boolean</td><td>True when this is a configured execution chain.</td></tr><tr><td><code>isChainedDestination</code></td><td>boolean</td><td>True when a chained (two-leg) order may terminate on this chain — leg 2 swaps the connector into the ask here, so an ask token the escrow owns no bridge adapter for is still deliverable. Absent when chained quoting is off.</td></tr><tr><td><code>contracts</code></td><td>object</td><td>Contract addresses for this chain (string → address).</td></tr><tr><td><code>escrowContract</code></td><td>string</td><td>Escrow contract address.</td></tr><tr><td><code>rolesContract</code></td><td>string</td><td>Roles contract address.</td></tr><tr><td><code>providerIds</code></td><td>integer[]</td><td>Provider IDs available on this chain.</td></tr><tr><td><code>slug</code></td><td>string</td><td>Chain slug.</td></tr><tr><td><code>createdAt</code> / <code>updatedAt</code></td><td>string</td><td>RFC 3339 timestamps.</td></tr></tbody></table>

### Token

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td>Token ID.</td></tr><tr><td><code>symbol</code></td><td>string</td><td>Symbol (e.g. <code>USDC</code>).</td></tr><tr><td><code>name</code></td><td>string</td><td>Token name.</td></tr><tr><td><code>chainId</code></td><td>string</td><td>Chain ID.</td></tr><tr><td><code>chainName</code></td><td>string</td><td>Chain name.</td></tr><tr><td><code>address</code></td><td>string</td><td>Contract address on this chain.</td></tr><tr><td><code>decimals</code></td><td>integer</td><td>Token decimals.</td></tr><tr><td><code>logoUrl</code></td><td>string</td><td>Logo URL.</td></tr><tr><td><code>isEnabled</code></td><td>boolean</td><td>Whether the token is enabled.</td></tr><tr><td><code>isChainedDestination</code></td><td>boolean</td><td>True only when this exact token deployment is allowlisted for a chained destination-local swap.</td></tr><tr><td><code>isSellSource</code></td><td>boolean</td><td>True only when this exact token deployment is allowlisted as a quote's bid (sell) token.</td></tr><tr><td><code>implAddress</code></td><td>string</td><td>Per-chain implementation address (e.g. OFT impl).</td></tr><tr><td><code>bridge</code></td><td>string</td><td>Bridge provider (e.g. <code>Circle</code>, <code>LayerZero</code>).</td></tr><tr><td><code>standard</code></td><td>string</td><td>Token standard (e.g. <code>CCTPV2</code>, <code>LayerZeroV2OFT</code>).</td></tr><tr><td><code>facet</code></td><td>string</td><td>Diamond facet name.</td></tr><tr><td><code>homeChainId</code></td><td>string</td><td>Home chain ID of the canonical token.</td></tr><tr><td><code>homeTokenAddress</code></td><td>string</td><td>Canonical token address on the home chain.</td></tr><tr><td><code>gmpParameters</code></td><td>string</td><td>GMP-encoded parameters for this token (hex).</td></tr><tr><td><code>routes</code></td><td>Route[]</td><td>Enabled outbound routes from this token.</td></tr></tbody></table>

### Route

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td>Route ID.</td></tr><tr><td><code>tokenId</code></td><td>string</td><td>Token ID.</td></tr><tr><td><code>tokenName</code></td><td>string</td><td>Token name.</td></tr><tr><td><code>fromChainId</code> / <code>fromChainName</code></td><td>string</td><td>Source chain.</td></tr><tr><td><code>toChainId</code> / <code>toChainName</code></td><td>string</td><td>Destination chain.</td></tr><tr><td><code>fromAddress</code> / <code>toAddress</code></td><td>string</td><td>Source / destination token addresses.</td></tr><tr><td><code>homeChainId</code></td><td>string</td><td>Home chain ID of the canonical token.</td></tr><tr><td><code>homeTokenAddress</code></td><td>string</td><td>Canonical token address on the home chain.</td></tr><tr><td><code>decimals</code></td><td>integer</td><td>Token decimals.</td></tr><tr><td><code>bridge</code></td><td>string</td><td>Bridge provider.</td></tr><tr><td><code>adapter</code></td><td>string</td><td>Bridge adapter address.</td></tr><tr><td><code>standard</code></td><td>string</td><td>Token standard (e.g. <code>CCTPV2</code>).</td></tr><tr><td><code>facet</code></td><td>string</td><td>Diamond facet name.</td></tr><tr><td><code>estimatedDuration</code></td><td>integer</td><td>Estimated settlement time, seconds.</td></tr><tr><td><code>minAmount</code> / <code>maxAmount</code></td><td>string</td><td>Route amount bounds. <strong>Advisory only</strong> — <code>maxAmount</code> is serialized but enforced nowhere, so do not rely on it as a limit; the quote engine declines an order it cannot price.</td></tr><tr><td><code>feeBps</code></td><td>integer</td><td>Route protocol fee in basis points.</td></tr><tr><td><code>isQuotable</code></td><td>boolean</td><td>Present only when the route-health prober measured this exact lane broken and enforcement is on (<code>false</code>). <strong>Absent means not measured and must be treated as quotable</strong> — only an explicit <code>false</code> demotes a lane.</td></tr><tr><td><code>isEnabled</code></td><td>boolean</td><td>Whether the route is enabled.</td></tr></tbody></table>

### Solver

<table data-search="false"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string (uuid)</td><td>Solver ID.</td></tr><tr><td><code>chainId</code></td><td>integer</td><td>Chain the solver operates on.</td></tr><tr><td><code>chainName</code></td><td>string</td><td>Resolved chain name.</td></tr><tr><td><code>address</code></td><td>string</td><td>0x-prefixed EVM address.</td></tr><tr><td><code>name</code></td><td>string</td><td>Solver name.</td></tr><tr><td><code>operator</code></td><td>string</td><td>Operator name.</td></tr><tr><td><code>operatorType</code></td><td>string</td><td><code>internal</code> or <code>third-party</code>.</td></tr><tr><td><code>description</code></td><td>string</td><td>Optional description.</td></tr><tr><td><code>website</code></td><td>string</td><td>Optional website.</td></tr><tr><td><code>contact</code></td><td>string</td><td>Optional contact.</td></tr><tr><td><code>isActive</code></td><td>boolean</td><td>Whether the solver is active.</td></tr><tr><td><code>createdBy</code></td><td>string</td><td>Creator.</td></tr><tr><td><code>createdAt</code> / <code>updatedAt</code></td><td>string</td><td>RFC 3339 timestamps.</td></tr></tbody></table>

### ChainSolvers

Per-chain group in the `/solvers` response.

| Field       | Type      | Description            |
| ----------- | --------- | ---------------------- |
| `chainId`   | integer   | Chain ID.              |
| `chainName` | string    | Chain name.            |
| `solvers`   | Solver\[] | Solvers on this chain. |

### ProtocolState

| Field              | Type    | Description                                   |
| ------------------ | ------- | --------------------------------------------- |
| `chainId`          | string  | Chain ID.                                     |
| `executionChainId` | string  | Configured execution chain.                   |
| `isPaused`         | boolean | Whether the protocol is paused on this chain. |
| `updatedAt`        | string  | RFC 3339 timestamp.                           |