# Models Reference for the public swap request and response shapes used by the B2B API Gateway. This page intentionally stays compact. The Swagger UI models list is the exhaustive schema inventory and remains the authoritative source for every field and union member. ## Common ### ApiMeta Present on successful responses. | Field | Type | Description | | ----------- | ------ | ---------------------- | | `requestId` | string | Request correlation ID | | `timestamp` | string | ISO 8601 timestamp | ### ApiError Structured error body. | Field | Type | Description | | --------------- | ------- | --------------------------- | | `error.code` | string | Stable error code | | `error.message` | string | Human-readable explanation | | `error.details` | object | Optional structured context | | `meta` | ApiMeta | Request metadata | *** ## Quote And Permit ### QuoteRequest | Field | Type | Required | Description | | --------------------------------------------- | ------- | -------- | ---------------------------------- | | `fromChain` | string | Yes | Source chain identifier | | `toChain` | string | Yes | Destination chain identifier | | `tokenIn` | string | Yes | Input token identifier | | `tokenOut` | string | Yes | Output token identifier | | `amount` | string | Yes | Human amount string | | `network` | string | No | `mainnet` or `testnet` | | `slippageBps` | integer | No | Quote-time slippage hint | | `recipient` | string | No | Recipient address | | `tokenRefFromOverride` / `tokenRefToOverride` | string | No | Explicit token-reference overrides | ### QuoteRouteSummary | Field | Type | Description | | -------------------------- | --------- | --------------------------------------------------------------------------- | | `routeId` | string | Route identifier used in `POST /swap/build` | | `provider` | string | Convenience alias when the route resolves to a single public provider label | | `providers` | string\[] | Ordered provider list across the route steps | | `bridgeProvider` | string | Bridge provider when the route includes a bridge step | | `family` | enum | Route family when available | | `stepCount` | integer | Number of execution legs represented by the route | | `expectedAmountOut` | string | Expected output amount | | `estimatedDurationSeconds` | integer | Estimated completion time | | `warnings` | string\[] | Optional route warnings | For same-chain routes, `provider` is often enough. For cross-chain or other multi-step routes, prefer `providers`, `bridgeProvider`, and `stepCount`. ### QuoteResponse | Field | Type | Description | | ------------------ | -------------------- | ------------------------------------------------------------------- | | `data.quoteId` | string | Quote identifier | | `data.expiresAtMs` | integer | Quote expiry timestamp | | `data.routes` | QuoteRouteSummary\[] | Available route summaries; may be empty when no viable route exists | | `meta` | ApiMeta | Request metadata | *** ## Swap ### SwapBuildRequest | Field | Type | Required | Description | | -------------------------------------------------------- | ------- | -------- | ---------------------------------- | | `quoteId` | string | Yes | Quote identifier | | `routeId` | string | Yes | Route identifier from the quote | | `recipient` | string | No | Recipient address | | `userAddress` | string | No | Wallet owner address | | `permitType` | enum | No | `eip2612`, `permit2`, or `approve` | | `permitDeadline` | integer | No | Permit deadline | | `permitSignature` / `permitSignatureCompact` / `permit2` | object | No | Optional permit artifacts | | `waitForTxRequestMs` | integer | No | Bounded wait before async fallback | ### WalletSigningStep | Field | Type | Description | | --------- | ------- | ----------------------------- | | `current` | integer | Current signing step number | | `total` | integer | Total number of signing steps | ### WalletSigningEnvelope | Field | Type | Description | | ---------------- | ------------------------- | ----------------------------------------- | | `step` | WalletSigningStep or null | Current step descriptor | | `expiresAtMs` | integer or null | Current payload expiry | | `readyAtMs` | integer or null | Time when payload is expected to be ready | | `payload` | union | Chain-family-specific signing payload | | `executionHints` | object | Optional gas and execution hints | | `clientHints` | object | Optional wallet UX hints | `WalletSigningPayload` is a union across EVM, Solana, Bitcoin, and Cosmos payload shapes. Use Swagger Models for the exact family-specific fields. ### WalletSwapSigningReadyResponse | Field | Type | Description | | ----------------- | --------------------- | ---------------------- | | `data.swapId` | string | Swap identifier | | `data.mode` | string | `sync` | | `data.nextAction` | string | `sign` | | `data.signing` | WalletSigningEnvelope | Ready-to-sign envelope | ### WalletSwapSigningAsyncResponse | Field | Type | Description | | ------------------ | --------------------- | -------------------------- | | `data.swapId` | string | Swap identifier | | `data.mode` | string | `async` | | `data.nextAction` | string | `poll` | | `data.pollAfterMs` | integer | Suggested polling interval | | `data.signing` | WalletSigningEnvelope | Pending signing envelope | ### WalletSignedArtifactRequest | Field | Type | Required | Description | | ------- | ------ | -------- | ------------------------------------ | | `rawTx` | string | Yes | Externally signed artifact to submit | *** ## Discovery ### Chain | Field | Type | Description | | ------ | ------ | ------------------------- | | `id` | string | Chain identifier | | `name` | string | Human-readable chain name | ### Token | Field | Type | Description | | ---------- | ------- | ------------------------------------ | | `chain` | string | Chain identifier | | `symbol` | string | Canonical token symbol | | `name` | string | Human-readable token name | | `address` | string | EVM contract address when applicable | | `decimals` | integer | Token decimals | | `mint` | string | Solana mint address when applicable | | `logoUrl` | string | Token logo URL when available | ### Pair | Field | Type | Description | | ----------- | ------ | ---------------------------- | | `fromChain` | string | Source chain identifier | | `toChain` | string | Destination chain identifier | | `tokenIn` | string | Input token symbol | | `tokenOut` | string | Output token symbol | ### Response wrappers | Schema | Fields | | ---------------- | ------------------------------------------------- | | `ChainsResponse` | `data.chains`, `meta` | | `TokensResponse` | `data.tokens`, optional `data.nextCursor`, `meta` | | `PairsResponse` | `data.pairs`, optional `data.nextCursor`, `meta` | *** ## Limit Orders ### LimitOrderPublicRequest Public create and replace requests mirror `QuoteRequest` and add limit-order terms: | Field | Type | Required | Description | | ------------------------------------------------------- | --------------- | -------- | --------------------------------------- | | `fromChain`, `toChain`, `tokenIn`, `tokenOut`, `amount` | mixed | Yes | Same core quote inputs as `POST /quote` | | `minAmountOut` | string | Yes | Minimum output threshold | | `timeInForce` | enum | No | `GTC`, `GTD`, `IOC`, or `FOK` | | `expiresAtMs` | integer | No | Absolute expiry | | `expireAfterMs` | integer | No | Relative expiry | | `network`, `slippageBps`, `recipient` | mixed | No | Optional quote-style helpers | | `route`, `routeKey` | object / string | No | Optional route metadata | ### Limit-order responses | Schema | Fields | | --------------------------- | ---------------------------------------------------------------------------------------------------- | | `LimitOrderCreateResponse` | `limitOrderId`, `status`, `expiresAtMs`, `minAmountOut` | | `LimitOrderReplaceResponse` | `limitOrderId`, `status`, `expiresAtMs`, `minAmountOut`, `replacesLimitOrderId` | | `LimitOrderCancelResponse` | `limitOrderId`, `status` | | `LimitOrderRow` | `limitOrderId`, `status`, `timeInForce`, `createdAtMs`, `updatedAtMs`, `expiresAtMs`, `minAmountOut` | | `LimitOrdersListResponse` | `data.limitOrders`, `meta` | *** ## Status ### TransactionStatusResponse | Field | Type | Description | | -------------------- | ------- | ------------------------------------- | | `data.txHash` | string | Transaction hash | | `data.chain` | string | Chain identifier | | `data.status` | enum | `pending`, `confirmed`, or `failed` | | `data.confirmedAtMs` | integer | Confirmation timestamp when available | | `data.error` | string | Failure reason when available | | `meta` | ApiMeta | Request metadata | *** {% embed url="" %} Zert API — Schemas {% endembed %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.zert.com/models.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.