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.

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

On error, only the error object is populated:

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

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

ErrorCode

Value	Typical status
INTERNAL_ERROR	500
BAD_REQUEST	400
NOT_FOUND	404
CONFLICT	409
VALIDATION_ERROR	422
UNAUTHORIZED	401
FORBIDDEN	403
RATE_LIMITED	429
SERVICE_UNAVAILABLE	503
QUOTE_UNAVAILABLE	422
UPSTREAM_ERROR	502
BELOW_MIN_TRADE_SIZE	422
COMPLIANCE_BLOCKED	422
FEE_NOT_ENABLED	403
FEE_WALLETS_REQUIRED	400
FEE_UNSUPPORTED_LANE	400
FEE_UNAVAILABLE	503
FEE_NOTHING_TO_CLAIM	409
FEE_BELOW_MINIMUM	409

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.

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

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.

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

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

Field	Type	Description
fromChainId	string	Source chain ID.
toChainId	string	Destination chain ID.
fromToken	string	Source token.
toToken	string	Destination token.
fromAmount	string	Amount sold, smallest unit.
toAmount	string	On-chain order.askTokenAmount — the swap output threshold the solver must meet to fill the order; used to construct orderRequests[].askTokenAmount. NOT what the receiver gets when the outbound bridge charges a protocol fee — see finalAmount.
finalAmount	string	What the receiver gets: toAmount minus the outbound CCTP fast-track maxFee. <= toAmount (equal for LayerZero outbound / CCTP slow-track). Always populated.
bridge	string	Bridge provider for the route (e.g. Circle).
feeBps	integer	Route protocol fee in basis points (CCTP fast-track fee for Circle lanes; 0 for LayerZero). Metadata only — NOT subtracted from toAmount; the actual fee is the gap between toAmount and finalAmount.
inboundProtocolFee	string	CCTP fast-track maxFee debited from the input before pricing: the inbound bridge delivers fromAmount − inboundProtocolFee. "0" for LayerZero bids, local bids, slow-track lanes.
estimatedDuration	integer	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.
recommendedDeadline	string	Suggested value for orderRequests[0].deadline: a unix timestamp in seconds (decimal string), equal to the quote time plus recommendedDeadlineSeconds. Derived from this lane's estimatedDuration: 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 sender, orderRequests[].deadline comes back "0" and you set it; with one, orderRequests[0].deadline is already the deadline txData signs for. A shorter deadline risks the order expiring before it can be filled: the fill then reverts ZDLite__OrderExpired, the order ends fill_failed, and the owner calls cancel to recover the funds. Absent when the gateway has no recommendation.
recommendedDeadlineSeconds	integer	recommendedDeadline as a span in seconds from the moment of the quote. Absent together with it.
lifespanSeconds	integer	Quote validity in seconds, from the winning provider's signed expiry (floored at 0). 0 when the provider does not sign an expiry or the quote has lapsed. The on-chain fill threshold itself does not expire.
swapTimeSeconds	integer	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). 0 when block-time data is unavailable.
route	Route	The route this quote priced.
gasCostSource	string	LayerZero inbound native fee in wei; 0 for CCTP. Pass as msg.value.
gasCostDest	string	LayerZero outbound native fee in wei; 0 for CCTP.
swapCost	string	Gas hint from the winning liquidity provider (decimal string; empty when not provided).
provider	string	Masked liquidity-provider label — always "zerodelta" on a successful swap quote; omitted on direct-bridge quotes.
orderRequests	OrderRequest[]	Pre-built argument array for submitOrder. One element normally, two when isChained.
isDirect	boolean	Direct-bridge quote (same token, different chains): no swap, no solver fill, not cancellable; provider and the top-level cancel coordinates are omitted.
isChained	boolean	Two-leg quote: orderRequests carries two elements and settlement spans two execution chains.
escrowAddress	string	Source-chain escrow address (present when owner is supplied).
executionChainId	string	Chain ID where settlement executes and where cancel runs (present when owner is supplied; omitted on direct quotes).
executionEscrowAddress	string	Escrow address on the execution chain.
complianceStatus	string	SCREENED or UNSCREENED.
compliance	Compliance	Full screening decision; present only when the gate is configured and an owner was supplied.
txData	EvmTransaction[] or SolanaTransaction[]	Present only when the request named a sender. 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 approve when the escrow's allowance from sender 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 submit. Solana: a returning wallet's single-leg order is one submit; a first order is setup then submit; a chained order adds one write 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.

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

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

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.

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

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.

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

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

Field	Type	Description
chainId	string	Chain ID (serialized as a string).
name	string	Internal name (e.g. arbitrum).
displayName	string	Human label (e.g. Arbitrum One).
explorerUrl	string	Block explorer base URL.
nativeCurrency	string	Native currency symbol.
isTestnet	boolean	Testnet flag.
isEnabled	boolean	Whether the chain is enabled.
isExecutionChain	boolean	True when this is a configured execution chain.
isChainedDestination	boolean	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.
contracts	object	Contract addresses for this chain (string → address).
escrowContract	string	Escrow contract address.
rolesContract	string	Roles contract address.
providerIds	integer[]	Provider IDs available on this chain.
slug	string	Chain slug.
createdAt / updatedAt	string	RFC 3339 timestamps.

Token

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

Route

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

Solver

Field	Type	Description
id	string (uuid)	Solver ID.
chainId	integer	Chain the solver operates on.
chainName	string	Resolved chain name.
address	string	0x-prefixed EVM address.
name	string	Solver name.
operator	string	Operator name.
operatorType	string	internal or third-party.
description	string	Optional description.
website	string	Optional website.
contact	string	Optional contact.
isActive	boolean	Whether the solver is active.
createdBy	string	Creator.
createdAt / updatedAt	string	RFC 3339 timestamps.

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.