# Overview

Make digital assets make sense. [**Glacis Labs**](https://glacislabs.com/) builds the cross-chain infrastructure that moves digital assets at institutional scale. Our products share one foundation and one goal: settlement that holds when real size is on the line. ### Products * **ZeroDelta** — *flagship, latest.* The clearing house for RWAs. Match institutional orderflow and settle any stablecoin into any other, across any chain, with firm, zero-slippage execution at scale. **Start here if you're integrating.** [Full docs ↗](/zero-delta/why-zerodelta) * **Airlift** — *in production.* A universal token registry for cross-chain token standards (OFT, NTT, CCT, xERC20, and more) — integrate any burn-and-mint token through one API. [Full docs ↗](https://docs.glacislabs.com/airlift/why-airlift) * **Glacis Core** — *the foundation.* A router and firewall for cross-chain messages: build cross-chain apps independent of any single GMP, with quorum-based security. [Full docs ↗](https://docs.glacislabs.com/glacis-core/why-glacis) ### How they fit together Glacis Core carries the messages and enforces the security model. Airlift moves the tokens. ZeroDelta clears and settles on top of both — its architecture is, literally, "built on Glacis Core messaging and Glacis Airlift token transfers." ```javascript ZeroDelta flagship · clears & settles (RWAs, stablecoins) │ builds on ├── Airlift interchain token transfers (Circle CCTP, LayerZero OFT) └── Glacis Core secure cross-chain messaging / GMP + security Glacis Labs — the lab that builds and owns all three. ``` ### Start here * **Integrate ZeroDelta** → [Product Overview](/zero-delta/why-zerodelta) · [Architecture ](/zero-delta/architecture)· [Integration Guide](/zero-delta/integration-guide) * **Move a token cross-chain (Airlift)** → [Airlift overview](/airlift/why-airlift) * **Build on the messaging layer (Glacis Core)** → [Glacis Core overview](/glacis-core/why-glacis) * **Partner or co-design** → [contact the Glacis Labs team](https://t.me/glacisofficial) # Why ZeroDelta? The clearing house for RWAs. ZeroDelta matches institutional RWA orderflow, delivering compliant, zero-slippage execution for capital moving at scale. * **Neutral by design.** No token, no preferred routes. One request, one firm settlement that holds at size. The clearing house works for the market, not against it. * **Proven operator.** Built by [Glacis Labs](https://www.glacislabs.com/), the team behind Airlift, our universal interchain token-bridging product. * **Audited.** Smart contracts audited by Halborn and Sherlock; all important findings addressed. Over 1B already cleared. * **Built on tier-1 infrastructure.** Circle CCTP V2 and LayerZero V2 OFT underneath, not an untested bridge of our own. * **Non-custodial.** Funds move only through audited contracts under conditions the contracts enforce. *** ### Moving a billion dollars should mean moving a billion dollars The emergence of digital assets has hyper-fragmented liquidity across dozens of chains, dozens of stablecoins, and a fast-growing universe of tokenized real-world assets (RWAs). For institutions moving real size, execution means severe slippage, endless integrations, and broken compliance. DeFi is simply not built for institutional scale. Today ZeroDelta clears stablecoins and tokenized assets across 9 chains, and the architecture is built to extend the same clearing model to any tokenized asset. We clear multi-chain orderflow as a single venue, and unlike an aggregator our pricing improves with size rather than decaying against pool depth. **Live today:** eight bridged assets — USDC, USDT, USDe, USDtb, AUSD, PYUSD, USDG and XAUT — clearing across 9 chains with firm quotes, plus a substantially larger **ask-only** set that can be bought but not bridged (delivered on the order's execution chain). **Chained two-leg orders, which is what a tokenized-asset purchase is, are live in production.** Query `GET /api/v1/routes` for the authoritative live set; the Integration Guide carries the coverage matrix. **Direction (roadmap, not live):** chains and issuers at scale, compliance at the protocol layer, and an open solver network. The sections below mark which is which. Because the biggest players don't need a dollar to equal a dollar. They need a billion to equal a billion. *** ### A clearing house, not an aggregator

This is the distinction that defines the category. An aggregator routes and quotes. It searches existing pools for the best path and hands the trade back to the same fragmented liquidity everyone else is drawing on. Its per-order economics flatten as it scales, because every order still pays the spread on the venue it lands in. A clearing house clears orderflow centrally and commits to a firm price before the user signs. That is why ZeroDelta wins the trades that break an aggregator: execution gets cheaper and tighter with size rather than worse, and the price you are quoted is the price you settle, held at size. Concretely: a small order on an aggregator pays the spread on whatever venue it lands in, and that cost holds or worsens as the order grows. A large order cleared through ZeroDelta is priced as a single firm quote, so the marginal cost of size falls instead of rising. We do not disclose how the matching is computed. What matters for an integrator is the behavior: a single firm quote, held to settlement, that improves rather than degrades as the order grows. *** ### One integration, one settlement, any supported asset and chain ZeroDelta abstracts the entire fragmented surface of chains, bridges, and issuers behind a single interface. You send one request and get one firm settlement that holds at size, regardless of how many venues, bridges, and issuers sit underneath it. Today it clears stablecoins and tokenized assets across 9 chains; the architecture is built to scale to hundreds of assets, issuers, and chains (direction, not current scale). * **One integration, complete coverage.** Any supported asset, any supported chain, through a single interface. No bilateral integration per route. * **Firm quotes.** The price you are quoted is the price you settle, with no quote-versus-execution drift; the solver must fill at or above the quoted threshold on-chain. * **Deterministic delivery.** Every order has one traceable lifecycle from submission to settlement, with a canonical on-chain record on the order's execution chain that is publicly verifiable. * **Honest about depth.** An order larger than the depth currently available for a route is declined at quote rather than filled at a worse price. *** ### Compliance, moving to the protocol layer Institutional flow needs rails whose compliance posture matches the assets moving across them. ZeroDelta is designed to move compliance into the protocol layer instead of leaving it to bespoke integrations. Today, access is permissioned in practice: integrators are onboarded and KYB'd by the Glacis team, and asset eligibility is controlled at the contract layer. Wallet screening runs at quote time and again at fill time, so a pair that becomes blocked after quoting is still stopped before settlement. These protocol-layer capabilities are rolling out as the clearing layer matures: * **Permissioned by default.** * **Protocol-enforced issuer rules.** * **Travel-rule support built in.** The goal is a settlement layer for compliance-forward issuers and the integrators that serve them, one that fits the regulatory era they actually operate in rather than one they have to retrofit. *** ### Built for RWAs. Overkill for stablecoins. Tokenized real-world assets are where fragmentation hurts most: NAV-locked windows, multi-jurisdiction compliance, asset-class diversity, counterparty permissioning, and audit-traceable lifecycles all compound at once. ZeroDelta is built to clear that — and clears it today: a tokenized-asset purchase settles as a chained two-leg order, live in production, where leg 1 moves the user's stablecoin to the execution chain and leg 2 swaps it into the asset and delivers it. The same clearing house also settles stablecoins across 9 chains, which is the simplest case it handles. Whether you are moving stablecoins or tokenized assets, the distribution, convertibility, and coverage are the same single integration. *** ### Built for | Partner | What ZeroDelta enables | | ------------------------------- | --------------------------------------------------------------------------------------------- | | **Wallets and exchanges** | Complete asset coverage for users without building or maintaining bidirectional integrations. | | **Stablecoin and RWA issuers** | Distribution and convertibility across every supported chain through a single integration. | | **Funds and payment platforms** | Large trades and cross-border settlement executed without slippage. | | **Treasury and OTC desks** | Audit-traceable rebalancing with firm quotes at institutional size. | *** ### The ambition ZeroDelta is not a point solution for one swap on one route. The goal is to fix the way digital assets move: clearing any supported asset into any other, at scale, with compliance moving into the protocol layer and a price that holds. Stablecoins and the first tokenized assets today; the full RWA frontier next. If your team is moving stablecoins, FX, or tokenized assets at institutional size, the technical deep-dive and partner co-design conversations are available under NDA. *** ### Talk to us * **Integrate** → [Integration Guide](/zero-delta/integration-guide) * **Partner with us** → [Glacis integrations team](https://t.me/+CXFgMhEqkE85N2Nh) * **Technical deep-dive** → under NDA # Architecture ### Three components | Component | Who runs it | What it does | | --------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Users / integrators** | You and your users | Submit orders on-chain and receive the delivered asset. An integrator can submit on a user's behalf. | | **Escrow contracts** | Audited contracts deployed on every supported chain | Hold the user's asset between submission and settlement, and enforce the user's declared terms: destination, minimum output, deadline. The contract is permissionless to call; which assets are eligible is gated at the contract layer (`isSupportedToken`). | | **Clearing and settlement** | Operated by Glacis today; opens over time | Matches incoming orderflow, settles the difference, and delivers the destination asset. | Orders clear on an **execution chain**. Because an asset of a given ticker is treated as equivalent across chains through canonical cross-chain transfer (CCTP burn-and-mint for USDC, LayerZero OFT for USDT, USDe and the other OFT stables), ZeroDelta can match and settle wherever the equivalent asset lives and deliver wherever the user wants it. The execution chain is chosen **per order** — every order carries an `executionChainId` that the escrow validates against its allowlist, and the API elects it for you (Ethereum is the default; Base, Arbitrum and Plume are also allowed in the current deployment). **Most orders are cross-asset.** An order moves one stablecoin into a *different* stablecoin (for example USDC → USDT); the assets are not interchangeable, so a price has to be set. That price is the firm quote: you request it from the API and submit against it, you do not price the leg yourself. The response carries `askTokenAmount` (the on-chain fill threshold the solver must meet) and `finalAmount` (the expected delivery to the receiver). **Same-ticker moves across chains** (for example USDC → USDC) are quoted too, as a **direct bridge**: `isDirect: true`, no swap and no solver fill, the funds leave in the submit transaction itself, and the transfer is **not cancellable**. Only a same token on the *same* chain is rejected, with **`400 BAD_REQUEST`** — a malformed pair rather than a pricing failure, so it does not join the `422` family the other quote refusals belong to. There is nothing to bridge or swap. How a swap price is matched is out of scope here; what matters for integration is that the quoted price is the price the order settles at. *** ### How an order clears ```mermaid flowchart LR U[User / Integrator] -->|1. quote| API[ZeroDelta API] U -->|2. approve + submitOrder| ESC[Source-chain escrow
holds order until filled or cancelled] ESC -->|3. forward order to execution chain| HUB[Execution-chain escrow
order routing + fulfillment] HUB -->|4. orders picked up| SOLV[Glacis-approved solvers] SOLV -->|source liquidity| LP[Liquidity providers
various sources, best rate] SOLV -->|5. deliver| R[Receiver on destination chain] HUB -.->|status events| API API -.->|poll status| U U -.->|user cancels, then reclaims| HUB ``` *Cross-chain legs move over ZeroDelta's own CCTP V2 and LayerZero V2 OFT bridge adapters; Glacis Core provides the GMP status layer.* The dashed cancel path is user-initiated recovery: if an order cannot be settled, the user (or an integrator on their behalf) cancels and reclaims the locked funds on the execution chain. Nothing auto-refunds; the escrow never returns funds on its own. Recovery runs on the order's execution chain — the one named in the quote's `executionChainId` — so it incurs that chain's gas regardless of which chain the order originated on. Which function to call depends on whether the order has arrived yet (`cancel` post-arrival, `claimCancellation` pre-arrival), and a relayer can submit the owner's signed cancel with `cancelFor` — see Cancellation for the decision and Trust model. 1. **Quote.** You request a firm quote from the API for a `(fromChain, fromToken) → (toChain, toToken, amount)` pair. The quote carries `lifespanSeconds` — its price-validity window, from the winning provider's signed expiry (`0` when the provider does not sign one, or the quote has lapsed). Treat a quote as short-lived: refetch when `lifespanSeconds` elapses, or periodically (about every 10 seconds) to keep pricing current. The on-chain fill threshold itself does not expire. 2. **Approve and submit.** The user approves the asset to the source-chain escrow (standard ERC-20 `approve`), then calls `submitOrder`. The escrow pulls the asset and locks it. `submitOrder` is the only Zero-Delta-specific call; the preceding approve is a standard ERC-20 transaction. 3. **Settle.** The order is filled on the execution chain at or above the user's declared minimum output (`askTokenAmount`); the escrow verifies the fill meets that floor before releasing funds. Underneath, the source and destination legs move over Circle CCTP V2 (USDC) and LayerZero V2 OFT (USDT, USDe and the other OFT stables). 4. **Deliver.** The destination asset is delivered to the chosen receiver on the destination chain. On-chain, the order status moves `Pending → Filled` on the happy path, or `Cancelled` if the user cancels (the `OrderStatus` enum). The **read API uses a different, lowercase status vocabulary** (`pending` / `in_progress` / `outbound_bridging` / `delivered`, plus `continuing` and the terminal failure states) — so if you poll the API, compare against its values, not the enum names. You track status either by polling the read API by source transaction hash, or on-chain by `orderId` via `getOrder` / `orderStatuses`; the Reference lists the full status set and the Integration Guide shows a correct poller. > **A chained order has two statuses, and only one of them answers "is the user done?"** A chained (two-leg) order — which is what every RWA purchase is — exposes a per-order `status` and a journey-scoped `journeyStatus`. When leg 1 lands, `status` reads `delivered`: that leg genuinely finished. But the value is parked on the destination escrow awaiting leg 2, not in the receiver's wallet, and `journeyStatus` reads `continuing` for that entire window. Completion checks belong on `journeyStatus`, with `status` as the fallback for non-chained orders. *** ### The front end is deliberately standard There is nothing proprietary to learn on the front end. The deposit pattern is the same **ERC-20 approve + escrow-lock** that many on-chain protocols use: ```jsx // data is the quote response; see the Integration Guide for the runnable version. // Exact-amount approve assumes a non-fee-on-transfer token (true for the current stablecoin set). await erc20.approve(data.escrowAddress, data.orderRequests[0].bidTokenAmount); // The quote returns owner/destinationReceiver as null on every element; set both to // non-zero addresses first, or submitOrder reverts (ZDLite__ZeroAddress). const requests = data.orderRequests.map((request) => ({ ...request, owner, destinationReceiver })); // submitOrder takes the ARRAY plus a partnerId (attribution only — pass the zero value). // value covers the bridge messaging fee in the source chain's native token (gasCostSource); // it is 0 for a USDC/CCTP source. See the Integration Guide for buffer and revert behavior. await escrow.submitOrder(requests, PARTNER_ID, { value: data.gasCostSource }); ``` The user signs an approval and one `submitOrder` transaction. Everything after that, matching, settlement, and delivery, is handled by the protocol and ZeroDelta's infrastructure. *** ### What you can rely on * **Firm quotes.** The price you are quoted is the price the order settles at. No quote-versus-execution drift. * **A declared floor.** The escrow enforces the user's destination, minimum output, and deadline. An order that cannot meet the declared minimum does not settle. * **Settlement that holds at size.** Pricing improves with order size rather than decaying against pool depth. An order larger than the depth currently available for a route is declined at quote (`422`) rather than filled at a worse price. * **A traceable lifecycle.** Every order carries a deterministic ID (`orderId`) and an on-chain record; the canonical record resolves on the order's execution chain once it bridges, and the read API mirrors it keyed by source transaction hash. *** ### Built on the Glacis Labs stack * **Glacis Core** — secure cross-chain messaging / GMP abstraction; the Glacis Labs foundation. ZeroDelta uses it for **cross-chain message status**, which is what drives the tracked-transaction lifecycle. See Glacis Core. * **ZeroDelta's own bridge adapters** — the cross-chain token legs themselves move through adapters that ship with the ZeroDelta contracts (`CctpV2BridgeAdapter` for USDC, `LayerZeroOFTAdapter` for the OFT stables), not through a separate transfer product. * **Circle CCTP V2** (USDC; burn-and-mint, native 1:1) and **LayerZero V2 OFT** (USDT, USDe and the other OFT stables) — the bridge rails underneath, which govern each cross-chain leg and its timing. * **Glacis Airlift** is a sibling Glacis Labs product for interchain token transfers. ZeroDelta does **not** route its cross-chain legs through it. See Airlift. *** ### Trust model * **Non-custodial.** User funds move only through audited contracts under conditions the contracts enforce. **ZeroDelta** never holds user balances in an account it controls. * **Recoverable, but user-initiated.** If an order cannot be settled, the user cancels and reclaims funds on the execution chain. Recovery is not automatic. Direct-bridge transfers are the exception: they complete in the submit transaction and have nothing to recover. > **Operational default worth a risk-committee note:** with `deadline = 0` (the default, no expiry), an unfilled order sits `Pending` indefinitely and **nothing auto-refunds** — funds are recovered only by an explicit user-initiated cancel on the execution chain. For unattended or automated flows, set a real `deadline` so every order has a defined failure point. * **Upgradeable contracts.** The contracts are currently upgradeable under administrative roles held by Glacis; this is disclosed as an operational risk in the Integration Guide. We intend to move admin roles toward multisig control, with progressive decentralization of governance as a forward direction. * **Audited.** Smart contracts audited by Halborn and Sherlock; all important findings addressed. # Integration Guide Integrate the clearing house. One quote, one contract call. Guide for engineering teams integrating ZeroDelta. Today the clearing house settles stablecoins across 9 chains; this is the surface you integrate now. A base integration is four calls (quote, approve, `submitOrder`, poll) with no proprietary SDK to learn. The same four calls clear stablecoins today and tokenized assets as coverage expands. Pre-req reading: Product Overview and Architecture. ### Jump to reference {% columns %} {% column %} #### API Quote routes, check status, and read supported coverage. {% endcolumn %} {% column %} #### Smart Contracts See `submitOrder`, cancellation, and on-chain behavior. {% endcolumn %} {% endcolumns %} #### Before you start > The on-chain contracts and API use the internal name **ZDLite** (you will see it in error codes like `ZDLite__UnsupportedToken` and in the `ZDLITE_ABI` package); **ZeroDelta** is the product. The two names refer to the same thing. > **Addresses in this guide are the `prod` deployment.** ZeroDelta runs two deployments — `prod` (production) and `dev` (pre-production) — and every contract address rotates between them, so `dev` shares none of these addresses. Use the base URL, API key, and deployment you were given at onboarding, and read addresses from `GET /api/v1/chains` for that environment rather than hardcoding them. These come from the Glacis team during onboarding, not from this doc. Line them up first: * **API key** (`x-apikey` header) and the **base URL** for your environment (`dev` or `prod`). * The **ABI/OpenAPI package** (`ZDLITE_ABI`, full request/response schemas). * The **environment scope** your key is granted (mainnet small-amount and/or an onboarding-provisioned `dev` environment; see Testing without mainnet funds). * Confirmed **chain IDs, token addresses, and fee model** for your routes (the live `/chains`, `/tokens`, `/routes` endpoints are canonical).
### What ZeroDelta is, and isn't **Is:** * Single-call cross-chain stablecoin clearing. * Audited contracts on every supported chain. * A quote-and-submit interface with deterministic order tracking. **Isn't:** * A bridge for arbitrary ERC-20s (supported tokens only). * An atomic same-block swap (settlement spans cross-chain bridge windows). * A public/permissionless solver network (today). * A replacement for general-purpose bridges.
### Quick start A minimal integration is four steps: **quote → approve → `submitOrder` → poll status.** You interact with one smart-contract function (`submitOrder`) on the source chain and the ZeroDelta API for quoting and tracking. Base URL and an API key are provided during onboarding (see Operational details). > **Three things to know before you write the submit code.** `submitOrder` takes an **array** of order requests plus a `partnerId` — pass the quote's `orderRequests` through unchanged and `bytes32(0)` for the id unless the Glacis team issued you one. It is a state-changing transaction, so `orderId` is **not** returned to your off-chain call; you parse it from the `OrderSubmitted` event (shown in step 2). And `msg.value` must carry the bridge fee from the quote (`gasCostSource`), denominated in the **source chain's native token** (see step 2 for buffer and revert behavior). {% stepper %} {% step %} ### 1. Request a quote Refetch the quote roughly every 10 seconds in any live interface to keep pricing current. ```jsx const response = await fetch(`${ZD_API_ENDPOINT}/api/v1/quote`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'x-apikey': ZD_API_KEY, }, body: JSON.stringify({ fromChainId: '130', // Unichain toChainId: '42161', // Arbitrum fromToken: 'USDC', toToken: 'USDT', fromAmount: '1000000000000', // 1,000,000 USDC (6 decimals) owner: await signer.getAddress(), // optional: when set, the response includes escrowAddress + executionChainId destinationReceiver: RECIPIENT_ADDRESS, // optional: screened alongside owner }), }); // Surface documented HTTP errors (400/401/422/429/502) before touching the body. if (!response.ok) { const body = await response.text(); throw new Error(`Quote failed: HTTP ${response.status} ${body}`); } const { data } = await response.json(); ``` The `/quote` request requires `{ fromChainId, toChainId, fromToken, toToken, fromAmount }` and accepts optional `owner` and `destinationReceiver` — both are used for compliance screening, and passing `owner` makes the response include the source `escrowAddress` and `executionChainId` (used in the approve + submit steps). The response also carries `finalAmount` (what the receiver gets on the destination chain), fee and ETA fields, and the prepared `orderRequests` array. A full annotated response is shown under Quote example. > **You must set `owner` and `destinationReceiver` on every element of `orderRequests` before submitting.** Passing them in the quote request screens the wallets; it does **not** populate the prepared structs, which always come back with both fields `null`. Fill both client-side with real, non-zero addresses before calling `submitOrder`; the contract reverts with `ZDLite__ZeroAddress` on a zero `owner` or `destinationReceiver` (see step 2). > **Two quote shapes worth branching on.** `isDirect: true` is a same-token direct bridge — no swap, no solver fill, and **not cancellable**, so suppress cancel affordances. `isChained: true` returns **two** elements in `orderRequests` (leg 1's output funds leg 2); fill owner and receiver on both. > {% endstep %} {% step %} ### Approve and submit `submitOrder` pulls the bid token from the caller, so the user approves the escrow first (standard ERC-20 approve). `msg.value` must cover the bridge adapter's native messaging fee, returned in the quote as `gasCostSource`. **On `msg.value` / `gasCostSource`:** * **Unit.** `gasCostSource` is the **source chain's native messaging fee** in wei, not the asset being moved. Always pass `{ value: gasCostSource }` from the quote. * **Per rail.** `gasCostSource` is **`0` for CCTP-source orders (USDC)** and **nonzero for LayerZero-source orders (USDT/USDe and the other OFT stables)**. The worked example below is a USDC source, so its `gasCostSource` is `0`; a USDT or USDe source returns a real native fee. * **Buffer (LayerZero-source only).** When `gasCostSource` is nonzero, send it as quoted or slightly above; because the messaging fee can move between quote and inclusion, a small buffer (for example +10-20%) reduces the chance of an underpayment revert on volatile-gas chains. The escrow passes `msg.sender` as the LayerZero `refundAddress`, so the OFT refunds the unused excess to the caller. **Do not carry this buffer onto a CCTP (USDC) order:** CCTP-source orders quote `gasCostSource: 0`, the CCTP adapter's refund-address parameter is unused, and any native value you attach to a USDC lane is **stranded in the contract** rather than refunded. * **Underpayment.** If `msg.value` is below what the bridge adapter requires, `submitOrder` reverts and no order is created. There is no `ZDLite__` error for this case: the revert comes from the bridge adapter itself and is **adapter-specific** (CCTP vs LayerZero), so do not match it by a `ZDLite__` name. Send `gasCostSource` (plus the buffer above) to avoid it. * **Overpayment.** Send `gasCostSource` as quoted (plus the small buffer above) and avoid large overpayments. ```jsx // Exact-amount approve assumes a non-fee-on-transfer token (true for the current stablecoin set). // If a fee-on-transfer asset is ever onboarded, approve the gross amount or use an allowance buffer. await erc20.approve(escrowAddress, data.orderRequests[0].bidTokenAmount); // ZDLITE_ABI: from the ABI/OpenAPI package provided at onboarding (see Reference). const escrow = new Contract(escrowAddress, ZDLITE_ABI, signer); // data.orderRequests is the prepared ARRAY from the quote — submitOrder takes it as-is. // Set owner and destinationReceiver on EVERY element: the contract reverts on a zero owner // OR a zero destinationReceiver (ZDLite__ZeroAddress), and the quote returns them null. const owner = await signer.getAddress(); // the address that will own the order (non-zero) const requests = data.orderRequests.map((request) => ({ ...request, owner, destinationReceiver: RECIPIENT_ADDRESS, // who receives the asset on the destination chain (non-zero) })); // partnerId is attribution metadata only; pass the zero value unless Glacis issued you one. const PARTNER_ID = '0x' + '00'.repeat(32); const tx = await escrow.submitOrder(requests, PARTNER_ID, { value: data.gasCostSource }); const receipt = await tx.wait(); // orderId is not returned to off-chain callers from a normal send. Parse it from the // OrderSubmitted event in the receipt. OrderSubmitted carries BOTH the indexed orderId and the // full Order tuple — persist the whole tuple: it is the exact struct the cancel path needs, and // before the order arrives on its execution chain it is the ONLY place to get it (see Cancellation). // orderId is also the key for on-chain reads. // A DIRECT bridge (quote.isDirect) emits OrderDirectBridged INSTEAD, stores no order, // and is terminal at submit — there is no fill and nothing to cancel. let orderId; let order; for (const log of receipt.logs) { try { const parsed = escrow.interface.parseLog(log); if (parsed && (parsed.name === 'OrderSubmitted' || parsed.name === 'OrderDirectBridged')) { orderId = parsed.args.orderId; order = parsed.args.order; // full Order tuple — persist it, you need it to cancel break; } } catch (_) { /* not an escrow event; skip */ } } // viem equivalent: decodeEventLog({ abi: ZDLITE_ABI, ...log }) and match eventName. ``` > **The ask side is `bytes` on-chain.** `askToken` and `destinationReceiver` are chain-agnostic byte strings, so a non-EVM destination can be expressed. For EVM destinations you pass the plain 20-byte address — exactly the `0x`-prefixed hex string the API returns — and ethers/viem encode it correctly. Any width other than 20 or 32 bytes reverts with `ZDLite__UnsupportedReceiver`. > `OrderRequest.owner` does not have to equal `msg.sender`. An integrator can submit on a user's behalf: pull the bid token from the user through your own flow, then submit with `owner` set to the user's address. Set both `owner` and `destinationReceiver` to the correct, non-zero addresses before you submit — the contract reverts (`ZDLite__ZeroAddress`) if either is the zero address. > {% endstep %} {% step %} ### Track status Poll the read API by source transaction hash (about every 10 seconds) until the order reaches a terminal state. Immediately after broadcast, before the source tx is mined and indexed, the API has not seen the hash yet and returns `404`. Treat `404` as "not indexed yet" and keep polling; start with a short initial backoff (about 5–10 seconds) to let the source tx mine and the indexer catch up. ```jsx // The read API returns a LOWERCASE status string, NOT the on-chain enum names. // Poll while the status is non-terminal; treat anything else as terminal so a newly // added status can never trap the loop. This is the full, code-verified non-terminal set. const NON_TERMINAL_STATUSES = new Set([ 'pending', 'in_progress', 'outbound_bridging', 'cancel_pending', 'awaiting_claim', 'continuing', ]); async function pollUntilDone(txHash) { while (true) { const res = await fetch( `${ZD_API_ENDPOINT}/api/v1/transactions/${txHash}`, { headers: { 'x-apikey': ZD_API_KEY } }, ); if (res.status === 404) { // Not indexed yet (tx not mined / indexer catching up). Back off and retry. await new Promise((r) => setTimeout(r, 10_000)); continue; } if (res.status === 429) { // Honor the Retry-After header (seconds) on rate limit, then retry. const wait = (Number(res.headers.get('Retry-After')) || 10) * 1000; await new Promise((r) => setTimeout(r, wait)); continue; } if (!res.ok) { throw new Error(`Status poll failed: HTTP ${res.status} ${await res.text()}`); } const { data } = await res.json(); // Terminal once the JOURNEY status leaves the non-terminal set (delivered = success; // failed / expired = failure). // // Read journeyStatus, NOT status. On a chained order (an RWA buy is one) the parent's // `status` flips to 'delivered' as soon as LEG 1 lands — but the funds are parked mid- // journey, not in the user's wallet. journeyStatus reads 'continuing' for exactly that // window. Branching on `status` alone reports "done" on every in-flight chained order. // journeyStatus is absent on non-chained orders, so fall back to status. const effectiveStatus = data.journeyStatus ?? data.status; if (!NON_TERMINAL_STATUSES.has(effectiveStatus)) return data; await new Promise((r) => setTimeout(r, 10_000)); } } ``` **Status vocabulary — read this before you write the terminal check.** The read API returns a **lowercase** status string, not the on-chain enum names (`Filled` / `Cancelled`); comparing `status === 'Filled'` never matches. The full, code-verified set: | Status | Terminal? | | ------------------- | ----------------- | | `pending` | no | | `in_progress` | no | | `outbound_bridging` | no | | `cancel_pending` | no | | `awaiting_claim` | no | | `continuing` | no | | `delivered` | **yes** (success) | | `expired` | **yes** | | `cancelled` | **yes** | | `fill_failed` | **yes** | | `delivery_failed` | **yes** | | `failed` | **yes** | Happy path: `pending → in_progress → outbound_bridging → delivered` (`outbound_bridging` appears only when the destination chain differs from the execution chain). The poller above stops only on a terminal status, so a newly added status can never trap the loop. > **`status` is per-order; `journeyStatus` is per-journey. Branch on `journeyStatus`.** A chained order (`isChained: true`, and every RWA buy) settles in two legs. When leg 1 lands, the parent order's `status` is genuinely `delivered` — that leg *is* done — but the value is parked on the destination chain waiting for leg 2, not in the receiver's wallet. `journeyStatus` reads `continuing` for that whole window and only reaches a terminal value when the last leg settles. Treat `continuing` as **non-terminal** and prefer `journeyStatus` over `status` in any completion check, or you will report success on every chained order still in flight. A response looks like: ```json { "data": { "txHash": "0x...", "status": "in_progress", "journeyStatus": "in_progress", "sourceChainId": "130", "destChainId": "42161", "currentStep": "arrived", "completedSteps": 2, "totalSteps": 4, "steps": [ { "stepName": "submitted", "stepStatus": "completed" }, { "stepName": "arrived", "stepStatus": "completed" }, { "stepName": "filled", "stepStatus": "pending" }, { "stepName": "delivered", "stepStatus": "pending" } ] } } ``` * `status` is the lowercase lifecycle string in the table above, scoped to **this order**. `journeyStatus` is the same vocabulary scoped to the **whole journey** across chained legs — it is the field to branch on for completion (see the warning above). `delivered` is the success terminal. Keep polling while the status is in the non-terminal set; stop on any terminal status. `currentStep` and the `steps[]` array (`stepName` ∈ `submitted` / `arrived` / `filled` / `delivered`, `stepStatus` ∈ `completed` / `pending` / `failed` / `recovered`) give finer-grained progress. * The API is keyed by **source transaction hash** (`txHash`), not by `orderId`. Persist your source tx hash for API status polling; persist `orderId` (read from the `OrderSubmitted` event) for the on-chain cancel/read path. * **`id` is not `orderId`.** The tracked transaction's `id` is a deployment-scoped uid (for example `"rwa:0x52b1…"`), unique across redeployments; `orderId` is the raw on-chain id. The escrow's cancel/claim calls take `orderId` — passing `id` there reverts. * A batch submit can create more than one order under one tx hash — `GET /api/v1/transactions/{txHash}/orders` returns the full set. The API is keyed by source transaction hash. The same lifecycle can be read on-chain by `orderId`: `getOrder(orderId)` returns the full `Order` struct, and `orderStatuses(orderId)` returns the on-chain status enum (`Pending` / `Filled` / `Cancelled` — a different vocabulary from the API string; see the Reference). To obtain `orderId` from a submit, read it from the `OrderSubmitted` event in the transaction receipt. {% endstep %} {% endstepper %} ### Supported coverage The core bid stablecoins are USDC, USDT and USDe, with USDtb, AUSD, PYUSD and USDG also bridge-configured. Additional tokens are **ask-only** — they can be bought but not bridged, so they are delivered on the chain the order executes on (`destinationChainId` must equal `executionChainId` for those). **Per-(chain, token) availability is not uniform** — not every token is enabled on every chain. Query `GET /api/v1/tokens` for the live per-cell set and `GET /api/v1/route-health` for which lanes between those cells actually work, before you build a route picker — the full flow is in [Discover what you can trade](/zero-delta/integration-guide/discover-what-you-can-trade). **Bridge rail by token** (the same regardless of chain): | Token | Rail | | ------------------------------------ | ------------------------------------------ | | USDC | Circle CCTP V2 (burn-and-mint, native 1:1) | | USDT, USDe, USDtb, AUSD, PYUSD, USDG | LayerZero V2 OFT | | Ask-only tokens | none — delivered on the execution chain | **Chains and IDs** (code-verified against the `prod` deployment manifest; confirm against the live `/chains` API): | Chain | Chain ID | Role | | -------- | -------- | ----------------------------------- | | Ethereum | 1 | Connected & default execution chain | | Optimism | 10 | Connected | | Arbitrum | 42161 | Connected & allowed execution chain | | Base | 8453 | Connected & allowed execution chain | | Ink | 57073 | Connected | | Unichain | 130 | Connected | | Plasma | 9745 | Connected | | Sonic | 146 | Connected | | Plume | 98866 | Connected & allowed execution chain | The `dev` deployment spans the same nine chains with the same execution-chain allowlist; only the contract addresses differ. > **Execution chain is per order, not global.** Each order carries an `executionChainId` that the escrow validates against its allowlist — Ethereum (1), Base (8453), Arbitrum (42161), Plume (98866). The API elects it for you and returns it on every element of `orderRequests`, plus as the top-level `executionChainId` / `executionEscrowAddress` you cancel against. > **Do not assume every (chain × token) cell is enabled, or that an enabled cell is a tradeable lane.** Token coverage differs by chain, and a cell being enabled says nothing about whether a lane between two cells can be filled. `GET /api/v1/tokens` returns the live cells; `GET /api/v1/route-health` returns the measured verdict for each lane between them. Gate your UI on those two. A quote for an unsupported cell returns `422` / `ZDLite__UnsupportedToken` on submit. **`GET /api/v1/routes` is not the trade catalogue** — it is the bridge-rail table, one row per token per chain pair, and a `Route` carries a single `tokenId` with no destination-token field, so it cannot express a trade between two different tokens at all. See [Discover what you can trade](/zero-delta/integration-guide/discover-what-you-can-trade). Per-(chain, token) contract addresses are returned by `GET /api/v1/tokens`; treat that endpoint as the canonical source rather than hardcoding addresses. A representative `/tokens` response is shown under API reference. New chains, tokens, and routes are onboarded on partner request. Always treat `GET /api/v1/chains`, `/tokens` and `/route-health` as the live source of truth for what is currently enabled and tradeable.
### Smart contract interface The escrow contract is deployed on every supported chain. On source chains it handles `submitOrder` and bridging to the order's execution chain. Integrators only need `submitOrder` on the source chain; full interface is in the Reference. #### `submitOrder` ```solidity function submitOrder( OrderRequest[] calldata requests, bytes32 partnerId ) external payable returns (bytes32 orderId, Order memory order); ``` Transfers `requests[0].bidToken` from the caller, bridges it to that request's execution chain, and emits `OrderSubmitted`. If the source chain is already the execution chain, the order is stored directly without bridging. The function is `payable`; always include `{ value: gasCostSource }` from the quote. Off-chain callers read `orderId` from the `OrderSubmitted` event (or an `eth_call` simulation); a normal send does not return values to the caller. * **`requests`** is length 1 for a normal order, or 2 for a **chained** order where request 0's swap output funds request 1. Pass the quote's `orderRequests` through unchanged. * **`partnerId`** is attribution metadata only — no on-chain logic reads it. Pass `bytes32(0)` unless the Glacis team issued you an id; a non-zero value emits `PartnerOrder(partnerId)`. **Requirements:** * Caller must approve `requests[0].bidToken` to the escrow before calling. * `msg.value` must cover the bridge adapter's native messaging fee. * `bidToken` and `askToken` must be registered/supported on their respective chains. * A bridge adapter must exist for the `(bidToken, executionChainId)` pair. * `executionChainId` must be non-zero and in the escrow's allowlist. * `destinationReceiver` must be 20 or 32 bytes — exactly 20 when the destination chain is the order's execution chain. * `deadline` must be `0` (no expiry) or a future timestamp. * The contract must not be paused. **Same-token direct bridge.** When a single request's ask token is the same asset as its bid token on the destination chain, `submitOrder` bridges straight to `destinationReceiver`, stores no order state, and emits `OrderDirectBridged` **instead of** `OrderSubmitted`. Such a transfer never arrives, never fills, and **cannot be cancelled**; `askTokenAmount` acts as a minimum-delivered floor. The quote flags these with `isDirect: true`. See Reference for the `OrderRequest` / `Order` structs, events, and error codes. #### Cancellation If an order cannot be filled (for example, the market moves beyond the quoted minimum), the user reclaims funds on the order's execution chain: * `cancel(Order)` — direct cancel by the order owner; funds are released immediately once the order has arrived. * `claimCancellation(Order)` — withdraw funds for an order cancelled before it arrived, once it lands. * `cancelFor(Order, signature)` — the same cancel, authorized off-chain by the owner and relayed by anyone (the owner pays no gas). **Which to call:** check the status `steps` (step 3). If the `arrived` step is `completed`, use `cancel`. If you cancelled while the order was still pre-arrival, call `claimCancellation` once it lands. > **Persist the `Order` tuple at submit — pre-arrival, it is the only copy that exists.** Every cancel function takes the full populated `Order` struct. `getOrder(orderId)` on the execution-chain escrow only returns it **after the order has bridged and arrived**; call it earlier and it returns a zeroed struct. Passing that zeroed struct to `cancel()` derives `keccak256(0, 0, 0)` — an id that belongs to no one — and the call reverts with `ZDLite__UnauthorizedCaller`, which reads like a permissions bug and is not one. Pre-arrival is exactly when users most want out, so capture the `Order` tuple from the `OrderSubmitted` event at submit time (step 2) and keep it. Read it back with `getOrder` only as a post-arrival fallback. **Gasless cancel (`cancelFor`).** The owner signs an EIP-712 message and a relayer submits it: * Domain: `name = "ZDLiteEscrow"`, `version = "1"`, `chainId` = the execution chain, `verifyingContract` = that chain's escrow. The contract's `domainSeparator()` view returns the same value for verification. * Typed struct: `Cancel(address owner,uint64 orderNonce,uint64 sourceChainId)` — the identity triple that derives `orderId`. * Replay protection is the order's one-way status machine, not a separate nonce: once the cancel lands the status is no longer `Pending`/`Nonexistent`, so replaying the signature reverts. Contract wallets (EIP-1271) are supported. **Chained orders** park their intermediate funds on the destination chain instead of paying out. If the follow-up leg cannot proceed, the owner calls `claimChain(prevOrderId)` on that chain's escrow to recover the parked funds; `continueChain(prevOrderId)` is permissionless and pushes the chain forward. Cancel functions take the full populated `Order` struct, which the contract assigns at submit (it sets `nonce` and `sourceChainId`). You already have this struct from the `OrderSubmitted` event (it carries the full `Order` tuple), so persist it at submit time; otherwise — **and only once the order has arrived** — read it back from the **execution chain**, where the canonical record lives after the order bridges. Query the execution-chain escrow, not the source-chain one: ```jsx // The order's execution chain and escrow come from the quote (or the tracked transaction): // data.executionChainId / data.executionEscrowAddress // In the prod deployment the escrow is 0x5e25c8ABc19b88d6A7Ab0D805C77A34987a68b40 on every // chain — but that address is deployment-specific, so read it from GET /api/v1/chains for // your environment rather than hardcoding it. const execProvider = new JsonRpcProvider(EXECUTION_CHAIN_RPC_URL); const execSigner = wallet.connect(execProvider); // signer with gas on that chain const execEscrow = new Contract(data.executionEscrowAddress, ZDLITE_ABI, execSigner); // PREFERRED: use the Order tuple you persisted from the OrderSubmitted event at submit time. // It is valid immediately, including before the order arrives on the execution chain. let order = persistedOrderTuple; // from step 2 // FALLBACK, POST-ARRIVAL ONLY: read it back on the execution chain. // Before arrival this returns a ZEROED struct; cancel(order) would then derive // keccak256(0,0,0) and revert with ZDLite__UnauthorizedCaller. Guard on arrival first. if (!order) { order = await execEscrow.getOrder(orderId); if (order.owner === ZeroAddress) { throw new Error('Order has not arrived on the execution chain yet — ' + 'use the Order tuple from the OrderSubmitted event.'); } } // Cancel and reclaim (cancel post-arrival, or claimCancellation for a pre-arrival cancel). await execEscrow.cancel(order); ``` `getOrder(orderId)` is a view on the **execution-chain** escrow; it returns the canonical `Order` (see the Reference) **once the order has arrived**. Calling it on a source-chain instance returns `Nonexistent` after the order bridges, so switch your provider first. Because `nonce` and `sourceChainId` are contract-assigned, do not reconstruct the struct by hand; persist it from the event, or read it back after arrival.\
### Solver model Solvers are operated by Glacis today, vetted and approved to fill orders. Liquidity on the other side is sourced from vetted private market makers under Glacis operation. There is nothing for an integrator to run or operate; you submit orders and the network fills them. An open, third-party solver network is on the roadmap. If you want to run a solver as an independent party, contact the Glacis team.
### Risk model ZeroDelta's contracts have been audited by Halborn and Sherlock. The operational risks an integrator should be aware of: | Risk | Detail | Mitigation / forward path | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Upgradeable contracts | The contracts are currently upgradeable under admin roles held by Glacis (a disclosed operational risk). Compromise of admin keys could put escrowed funds at risk. | We intend to move admin roles toward multisig control, with progressive decentralization of governance as a forward direction. | | Quote drift | Quotes are estimates; if the market moves significantly mid-flight, a solver may be unable to fill at the quoted minimum. | The order stays `Pending`; the user cancels and reclaims funds on the execution chain. | | Bridge / relayer dependence | Cross-chain settlement relies on third-party messaging infrastructure (Circle CCTP for USDC, LayerZero for the OFT stables). Outages can delay a cross-chain leg. | These are widely used, production cross-chain providers; a stuck leg completes once the provider recovers. | | Token-level pauses | A stablecoin or its bridge implementation with pause features can halt a transfer mid-flight. | Limited to assets with such features; surfaced in transaction status. | ### FAQ **Do I need to run a solver or hold inventory?** No. You quote and submit; the Glacis-operated solver network fills. **Can I submit on behalf of my users?** Yes. Set `OrderRequest.owner` to the user's address and submit from your own contract or wallet (`msg.sender` need not equal `owner`). **What happens if the order can't be filled?** It stays `Pending`; nothing auto-refunds. The user (or you on their behalf) calls `cancel` and reclaims funds on the execution chain. With `deadline = 0` (the default) there is no expiry; set a `deadline` for unattended flows so an order has a defined failure point. See Cancellation. **Is it atomic / instant?** No. Settlement spans cross-chain bridge windows. The quote's `estimatedDuration` (seconds) is the expected time for that route; actual finality depends on the chains and assets involved and is bounded by the underlying bridge (Circle CCTP V2 for USDC, LayerZero V2 OFT for the OFT stables). ZeroDelta optimizes for certainty at size, not sub-minute UX. **Which stablecoins and chains are supported?** USDC, USDT and USDe are the core set (with USDtb, AUSD, PYUSD and USDG also bridged, plus a set of ask-only tokens) across 9 chains today; query `/chains`, `/tokens` and `/route-health` for the live set. **How long does integration take?** The surface is small: four calls (quote, approve, `submitOrder`, poll) and no proprietary SDK to learn, so once you have the prerequisites (see Before you start) the build is short. The gating step is onboarding (key, base URL, ABI package, environment scope), not the code. **Can I get more chains/tokens/routes?** Yes, on request. Contact the Glacis team.
### Operational details * **Environments:** two deployments, `dev` (pre-production) and `prod` (production), each with its own base URL and API key, provided on onboarding. They are independent on-chain deployments: the addresses in this guide are **`prod`**, and `dev` uses a different address for every contract. A key is valid against one environment only. See Testing without mainnet funds. * **Auth & rate limits:** `x-apikey` header; per-key rate limits apply to pricing endpoints. See Errors and limits for `429` / `Retry-After` and retry guidance. * **Versioning:** additive within `/api/v1/`; breaking changes ship under a new version with advance notice (see Auth and environments). * **Support & incidents:** support and status channels provided on onboarding.
### Audit Halborn and Sherlock have audited the ZeroDelta (ZDLite) smart contracts. All important findings have been addressed. The reports are available on request.
### Roadmap Next-version capabilities include deeper network settlement that tightens pricing as orderflow grows, an open solver network, RWA support, and the partner capabilities described in the Product Overview. The internal technical reference is available under NDA. To start an integration or discuss your use case, contact the Glacis team. # Discover What You Can Trade The tradeable surface is a cross product narrowed by live measurement, not a list of routes. Four calls, one copy-paste function, and the three filtering mistakes to design out. Build your route picker from what the clearing house can actually settle right now. Four calls, one function to copy, and the three mistakes that otherwise reach production. ### Three questions, three endpoints ZeroDelta's tradeable surface is **not a list of routes**. It is a cross product — any enabled token on any connected chain, to any enabled token on any connected chain — narrowed by live measurement. Three endpoints answer three different questions, and conflating them is the root of most integration problems. | Question | Endpoint | Answers | | --------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | | What exists? | `GET /api/v1/chains`, `GET /api/v1/tokens` | The chains we are connected to and the tokens enabled on each. Their cross product is your candidate surface. | | What works? | `GET /api/v1/route-health` | One measured row per lane, from a prober that actually quotes each pair. This narrows the candidates. | | What fills right now? | `POST /api/v1/quote` | The authoritative answer for one trade, at one size, at this moment. | > **`/api/v1/routes` is not the trade catalogue.** It is the bridge-rail table: one row per token per chain pair, describing how that *one* token moves — its bridge, adapter, standard and facet. A `Route` carries a single `tokenId` and no destination-token field, so it cannot express a trade between two different tokens at all, and it covers only the tokens that are bridge-configured. Read it to understand a rail; never to build a picker. ### 1. Authenticate Every endpoint requires a key, sent as a request header. There is no public surface — an unauthenticated request returns `401 UNAUTHORIZED` with `missing API key`, including for `/chains`. ``` X-API-Key: your-api-key ``` Every `/api/v1/*` response uses the same envelope: `data` on success, plus `meta` and `paging` on list endpoints, and `error` carrying a `code` and `message` on failure. On an error there is **no `data` key at all** — check the status before reading it, as the sample below does. ### 2. Read the chains `GET /api/v1/chains`. Each entry carries `chainId`, `escrowContract`, `isExecutionChain` and the contract set. You need the escrow address later to submit and to cancel, so treat this endpoint as canonical rather than hardcoding addresses. ### 3. Read the tokens `GET /api/v1/tokens`. One row per *(token, chain)* cell, with `address`, `decimals`, `isEnabled` and the rail metadata. These cells are your candidate surface. > **Page this endpoint.** The default page size is 100 and the catalogue is larger, so a single bare call returns a **truncated** list and nothing in the response body looks wrong. `meta.totalCount` is the real number — compare it against what you received, and page with `limit` (max 500) and `offset` until they match. A picker built from the first page silently omits whole tokens. ### 4. Read the measured health, and filter `GET /api/v1/route-health?scope=all`. One row per lane the prober has an opinion about. The top level carries `summary` with the live counts, `measuredAt`, and `nextSweepDueAt`. This endpoint is not paginated — it returns `data` only, with no `meta` or `paging`. > **`scope` has exactly two behaviours, and only one of them is spelled.** `scope=all` returns every measured lane. **Any other value — including omitting the parameter entirely, and including `scope=healthy` — returns the unhealthy subset**, and the response echoes `"scope": "unhealthy"` whatever you asked for. Always send `scope=all` when you want the full picture, and read the echoed `scope` back rather than assuming your value was honoured. ```json { "mode": "enforce", "scope": "all", "summary": { "healthy": 128, "degraded": 3, "broken": 11, "unknown": 6, "total": 148 }, "measuredAt": "2026-09-11T08:06:23Z", "lastSweepAt": "2026-09-11T08:06:23Z", "nextSweepDueAt": "2026-09-11T08:21:23Z", "lanes": [ { "laneKey": "10:0x01bf...071 then 10:0x0b2c...f85", "route": "USDT@10 to USDC@10", "status": "healthy", "par": 0.9994, "lastProbedAt": "2026-09-11T08:06:23Z", "lastOkAt": "2026-09-11T08:06:23Z" } ] } ``` Shape only — the values above are illustrative, not a census. Read `summary` from your own call for the live counts. A lane that is not healthy also carries `kind`, and usually a human-readable `message`; broken lanes add `consecutiveFailures` and `firstFailedAt`. | Field | Meaning | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `laneKey` | Stable identifier. Source `chainId:address`, then a greater-than sign, then destination `chainId:address`, both addresses lowercased. Key on this. | | `route` | Human-readable label. Display only. | | `status` | `healthy`, `degraded`, `broken` or `unknown`. | | `kind` | Why the lane is not healthy. Absent on healthy lanes. See the table below. | | `message` | The upstream reason, when there is one worth surfacing. | | `par` | The ratio the prober last measured for this lane. | | `lastProbedAt` / `lastOkAt` | When the lane was last measured, and last measured working. | ### What to do with each `kind` This table is the whole decision. `kind` tells you *why* a lane is not offerable, and each reason has a different correct response. | `kind` | What it means | Do | | --------------------- | ------------------------------------------------------------------------------ | -------------------- | | *absent* | Measured and working. The healthy majority carry no `kind` at all. | Offer | | `firewalled` | Disabled by ZeroDelta operations; it will not quote. Not a transient failure. | Hide, do not retry | | `not-fillable` | The lane prices cleanly but cannot actually be filled at the measured size. | Hide | | `lane-gap` | No bridge wiring exists for this token pair. | Hide | | `bridge-throttled` | The token's bridge path is rate-limited to zero upstream. Temporary. | Hide, retry later | | `persistent-upstream` | Liquidity providers unavailable for this pair. Temporary. | Hide, retry later | | `vault-closed` | An RWA vault is not accepting deposits. `message` carries the upstream reason. | Hide, explain | | `value-floor` | No acceptable price at the probed size. Size-dependent, not structural. | Offer with a warning | ### Three mistakes to design out > **Page `/tokens`, or your catalogue is quietly incomplete.** This is the failure that hides best: the default page is 100 cells, the response is well-formed, and the tokens you never received simply never appear in your picker. Read `meta.totalCount` and page until you match it. > **Filter on `kind`, never on `status`.** The two are not interchangeable, and the overlap is exactly where integrations break. A firewalled lane's status is `unknown`, **not** `broken` — the prober skips it rather than measuring it — so "hide broken, show the rest" puts every disabled lane back into your picker, where it will be refused the moment a user selects it. In the other direction, `not-fillable` appears under both `degraded` and `broken`. Build your allow and deny sets from `kind`. > **Key on `laneKey`, never on a symbol pair.** A symbol does not identify a cell: most symbols exist on several chains at once, so "USDC to AUSD" names many different lanes with different verdicts. `laneKey` pins both ends to a chain and an address. Symbol casing is a second reason to avoid them — it is not uniform across the catalogue (`USDe`, `USDtb`, and the `n`- and `de`-prefixed tokenized assets are not upper-case), so an exact comparison against a hardcoded upper-case symbol misses them. ### Copy this Everything above, as the function most integrations end up writing anyway. ```jsx // Lanes that should never reach a user. 'value-floor' is deliberately absent: // it is a size problem, not a broken lane. const HIDE = new Set([ 'firewalled', 'not-fillable', 'lane-gap', 'bridge-throttled', 'persistent-upstream', 'vault-closed', ]); const cell = (t) => t.chainId + ':' + t.address.toLowerCase(); const laneKey = (from, to) => cell(from) + '>' + cell(to); const sameCell = (from, to) => cell(from) === cell(to); // On failure the envelope carries 'error', not 'data'. Check the status first, or a bad // key surfaces as "data is not iterable" three frames away from the cause. These endpoints // are rate limited per key, so honour 429 and its Retry-After header. async function get(base, path, headers) { for (let attempt = 0; ; attempt++) { const res = await fetch(base + path, { headers }); if (res.status === 429 && attempt < 5) { const retryAfter = Number(res.headers.get('Retry-After')) || 1; await new Promise((r) => setTimeout(r, retryAfter * 1000 * (attempt + 1))); continue; } const body = await res.json(); if (!res.ok) { const err = (body && body.error) || {}; throw new Error(path + ' failed: HTTP ' + res.status + ' ' + err.code + ' ' + err.message); } return body; } } // List endpoints page at 100 by default, and a truncated page is indistinguishable from a // complete one. Page until the rows you hold match meta.totalCount. async function pageAll(base, path, headers) { const out = []; for (let offset = 0; ; offset += 500) { const body = await get(base, path + '?limit=500&offset=' + offset, headers); out.push(...body.data); if (body.data.length === 0) return out; const total = body.meta && body.meta.totalCount; if (total != null ? out.length >= total : body.data.length < 500) return out; } } export async function loadCatalogue(base, apiKey) { const headers = { 'X-API-Key': apiKey, Accept: 'application/json' }; const [tokens, health] = await Promise.all([ pageAll(base, '/api/v1/tokens', headers), get(base, '/api/v1/route-health?scope=all', headers), ]); const hidden = new Map(); for (const lane of health.data.lanes) { if (HIDE.has(lane.kind)) hidden.set(lane.laneKey, lane.message || lane.kind); } return { // Every (token, chain) cell you may offer. cells: tokens.filter((t) => t.isEnabled), // Refresh when the next sweep is due, not on a timer of your own. refreshAt: health.data.nextSweepDueAt, canTrade: (from, to) => !sameCell(from, to) && !hidden.has(laneKey(from, to)), whyNot: (from, to) => hidden.get(laneKey(from, to)), }; } ``` `canTrade` and `whyNot` take two cells from `cells`, not symbols. `base` is the environment base URL you were given at onboarding — a `dev` key is not valid against `prod`. > **One pair is never tradeable and needs no measurement.** The same token on the same chain is rejected with `400 BAD_REQUEST` — there is nothing to bridge or swap. That is what `sameCell` guards. The same token across *different* chains is fine: it is quoted as a direct bridge (`isDirect: true`), with no liquidity-provider swap and no solver fill, and it is not cancellable once submitted. ### Health narrows the menu; the quote decides the trade Use `/route-health` to decide what appears in your interface, and `/quote` to decide whether a specific trade proceeds. They are not redundant, and the quote is not a substitute for the health filter. > **A served quote is not proof a lane can be filled.** `/quote` refuses the cases it can see at pricing time: a closed vault, a throttled bridge, a disabled lane, a lane measured broken while enforcement is on. It cannot refuse what it cannot see — a `degraded` lane marked `not-fillable` prices cleanly and still fails to fill. If you skip the health filter and rely on the quote alone, you will publish lanes that quote and never settle. The reverse also holds. Health is measured at a probe size, seconds to minutes ago; the quote is priced for *your* size, now. A lane that passes the filter can still return `422` — `BELOW_MIN_TRADE_SIZE`, `COMPLIANCE_BLOCKED`, or no acceptable price at your amount. Surface the error rather than treating it as a catalogue bug. ### Refreshing * **The health data moves continuously.** The prober re-measures lanes all the time, so `summary`, `measuredAt` and individual verdicts change between two calls seconds apart. Treat every read as a snapshot, not as a stable list. * `nextSweepDueAt` is a sensible poll interval — roughly how long until the next full pass lands. Refreshing much faster than that mostly re-reads the same verdicts. * `/chains` and `/tokens` change on onboarding, not on a schedule. Cache them for hours. * `mode` tells you whether measurement is being enforced. Under `enforce`, lanes measured broken are already withheld from quoting, so your filter and the gateway agree. Once you know what you can offer, continue with [Request a quote](/zero-delta/integration-guide). Field-level reference for every endpoint above is in the [API reference](/zero-delta/integration-guide/api). # API Complete reference for the ZeroDelta read API: quoting, transaction tracking, and chain/token/route/solver/protocol discovery. For an integration walkthrough see the Integration Guide. ### Conventions * **Auth.** Most endpoints require an API key in the `x-apikey` request header (an `Authorization: Bearer ` form is also accepted, and `x-api-key` works as an alias). The health probes are public. The base URL and your API key are provided during onboarding (separate `dev` and `prod` hosts); they are not published here. * **Environments.** Two deployments are live: **`prod`** (production) and **`dev`** (pre-production). Each is a separate on-chain deployment on the same nine mainnet chains — the escrow, roles and bridge-adapter addresses differ between them, and a key issued for one environment is not valid against the other. Read the contract addresses for your environment from `GET /api/v1/chains` against your own base URL; never hardcode them or copy them between environments. * **Versioning.** Paths are namespaced under `/api/v1/`. Changes within `v1` are additive; breaking changes ship under a new version. * **Roles.** Keys are `viewer` (all `/api/v1/*` read and quote endpoints) or `admin`. The admin role additionally reaches an operator-only management surface that is not part of the integration contract and is not documented here. * **Envelope.** Every `/api/v1/*` response is wrapped in a standard envelope: the resource lives under `data`, errors under `error`, and list responses carry `meta` and `paging`. The examples below show the `data` payload; assume the envelope around it. See Models. * **Amounts.** Token amounts are strings in the token's smallest unit (e.g. `"1000000"` = 1 USDC at 6 decimals). Chain IDs are serialized as strings in responses. Native fees are wei strings. * **Pagination.** List endpoints accept `limit` (max 500; default 50 for transactions, 100 elsewhere) and `offset` (default 0). ⚠️ A bare call therefore returns only the **first page**, and a truncated list is indistinguishable from a complete one unless you check `meta.totalCount` against the number of rows you received. > **Schemas live on their own pages.** Models covers the envelope, error codes, the status vocabulary, the compliance decision, and the quote/order shapes. Transaction Models covers the tracked transaction, its steps, and the chained-journey fields. ### Endpoints at a glance

Method	Path	Purpose
`POST`	`/api/v1/quote`	Cross-chain swap quote
`GET`	`/api/v1/transactions`	List tracked transactions
`GET`	`/api/v1/transactions/{txHash}`	One transaction, with steps
`GET`	`/api/v1/transactions/{txHash}/orders`	Batch orders in single transaction
`GET`	`/api/v1/transactions/{txHash}/gmp`	On-demand GMP status enrichment
`GET`	`/api/v1/transactions/stats`	Aggregated transaction statistics
`GET`	`/api/v1/chains`	List supported chains
`GET`	`/api/v1/chains/{chainId}`	One chain
`GET`	`/api/v1/tokens`	List supported tokens
`GET`	`/api/v1/tokens/{tokenId}`	One token by ID
`GET`	`/api/v1/tokens/lookup`	One token by address + chain
`GET`	`/api/v1/tokens/configs`	Token bridge configuration documents
`GET`	`/api/v1/prices`	Cached USD prices by symbol
`GET`	`/api/v1/routes`	List bridge rails (not the trade catalogue)
`GET`	`/api/v1/routes/{routeId}`	One route
`GET`	`/api/v1/route-health`	Measured lane health — build your picker from this
`GET`	`/api/v1/protocols`	List supported GMP protocols
`GET`	`/api/v1/solvers`	Solvers grouped by chain
`GET`	`/api/v1/solvers/{chainId}`	Solvers on one chain
`GET`	`/api/v1/rwa/*`	Tokenized real-world-asset vaults (5 routes)
`GET`	`/api/v1/stakeflow/*`	Stakeflow points and commitments (7 routes)
`GET`	`/health`	Liveness probe (no auth)
`GET`	`/health/ready`	Readiness probe (no auth)
`GET`	`/metrics`	Prometheus metrics (no auth)

*** ### Quotes #### `POST /api/v1/quote` > **Wallet screening.** ZeroDelta screens wallets at two points. (1) **At quote time** — when you supply `owner` (and optionally `destinationReceiver`), both are screened by the compliance engine *before* a quote is returned; a blocked pair receives no quote or deposit instructions (`422 COMPLIANCE_BLOCKED`). (2) **At execution time** — the solver re-screens the pair through its pre-fill compliance gate *before filling* the order, so a pair that becomes blocked after quoting is still stopped before settlement. When `owner` is omitted the quote returns `complianceStatus: UNSCREENED` and the execution-time gate remains the enforcement point. Calculates a firm cross-chain swap quote between two supported tokens. The quote is computed in-process: the engine races every configured liquidity provider in parallel, picks the best output, adds LayerZero/CCTP fees and a bridge-time estimate, and returns a prepared `orderRequests` array ready for `submitOrder`. The response carries a masked `provider` label (the specific market maker is not disclosed). This endpoint is per-key rate limited; max request body 1 MB. **Same-token pairs.** A same-token pair across two different chains is quoted as a **direct bridge** (`isDirect: true`) when the token's mesh connects those chains: no liquidity-provider swap and no solver fill — `submitOrder` bridges straight to the receiver, `toAmount == finalAmount` is a minimum-delivered floor, and the resulting transfer is **not cancellable**. Only a same token on the *same* chain is rejected (`400 BAD_REQUEST`), since there is nothing to bridge or swap. **Minimum trade size.** Orders below the per-pair floor are refused with `422 BELOW_MIN_TRADE_SIZE`, and `error.fieldErrors` carries a `fromAmount` entry with the exact minimum. The global floor is **$0.02**; USDe pairs carry a higher floor of **$0.11**. > **A served quote is not proof a lane can be filled.** The quote gate refuses what it can see at pricing time — a closed vault, a throttled bridge, a firewalled lane, a lane measured broken while enforcement is on. It cannot refuse what it cannot see: a lane the prober marks `degraded` / `not-fillable` prices cleanly and still fails to fill. Filter your catalogue with `GET /api/v1/route-health` rather than relying on the quote alone. **Request body** (QuoteRequest): | Field | Required | Description | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `fromChainId` | yes | Source chain ID (string or number). | | `toChainId` | yes | Destination chain ID. | | `fromToken` | yes | Source token symbol or contract address. | | `toToken` | yes | Destination token symbol or contract address. | | `fromAmount` | yes | Amount to sell, in the source token's smallest unit. | | `owner` | no | Order owner address. When provided, the response also populates `escrowAddress` and `executionChainId`. | | `destinationReceiver` | no | Recipient wallet; screened alongside `owner` when present. | Both `owner` and `destinationReceiver` are optional inputs used for compliance screening. The returned `orderRequests[]` still come back with `owner` and `destinationReceiver` as `null` regardless — fill both client-side before submitting (see the Integration Guide). ```json { "fromChainId": "130", "toChainId": "42161", "fromToken": "USDC", "toToken": "USDT", "fromAmount": "1000000000000" } ``` **Response** (`200`, `data` is a Quote; illustrative values):

{
  "data": {
    "fromChainId": "130",
    "toChainId": "42161",
    "fromToken": "USDC",
    "toToken": "USDT",
    "fromAmount": "1000000000000",
    "toAmount": "999850000000",
    "finalAmount": "999850000000",
    "bridge": "Circle",
    "feeBps": 0,
    "estimatedDuration": 600,
    "lifespanSeconds": 30,
    "swapTimeSeconds": 12,
    "gasCostSource": "0",
    "gasCostDest": "0",
    "swapCost": "",
    "inboundProtocolFee": "0",
    "provider": "zerodelta",
    "route": { "...": "see Route" },
    "orderRequests": [
      {
        "owner": null,
        "bidToken": "0x078D782b760474a361dDA0AF3839290b0EF57AD6",
        "bidTokenAmount": "1000000000000",
        "askToken": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
        "askTokenAmount": "999850000000",
        "destinationReceiver": null,
        "destinationChainId": "42161",
        "executionChainId": "1",
        "deadline": "0"
      }
    ],
    "complianceStatus": "SCREENED",
      "compliance": {
      "status": "SCREENED",
      "decision": "ALLOW",
      "screenedWallets": [
        "0x1111111111111111111111111111111111111111",
        "0x2222222222222222222222222222222222222222"
      ],
      "sourceJurisdiction": "US_EX_NY",
      "appliedPolicyIds": ["pol_01H..."],
      "appliedPolicyNames": ["Default OFAC + Jurisdiction"],
      "appliedLegislation": ["MICA_EU"],
      "riskCategories": [],
      "flaggedCategories": [],
      "blockingCategories": [],
      "reasons": [],
      "policyVersion": "2026-07-01",
      "checkId": "chk_01H...",
      "expiresAt": "2026-07-14T12:30:00Z"
    }
  }
}

When `owner` is supplied in the request, the response additionally includes `escrowAddress`, `executionChainId`, and `executionEscrowAddress`. > **`compliance.decision` is `ALLOW` / `DENY` / `REVIEW` / `REMEDIATE`.** There is no `BLOCK` value — a client branching on one would treat every refusal as an allow. A successful quote is only ever returned for `ALLOW`. See Models. **Order-request semantics:** * `orderRequests` is an **array** — it is the exact argument `submitOrder` takes. One element for a normal or direct quote; **two** for a chained quote (`isChained: true`), where element 0's swap output funds element 1. Pass the whole array through unchanged, filling `owner` and `destinationReceiver` on **every** element. * `orderRequests[].executionChainId` is the chain the order clears on. It is always populated — including on direct quotes, where the contract validates it before short-circuiting — and the contract reverts on `0`. * On a chained quote, `orderRequests[1].bidTokenAmount` is an estimate the contract overwrites with actual receipts, and `orderRequests[1].deadline` is `"0"` by design (it is re-validated at continuation time). **Fee and amount semantics:** * `toAmount` is the on-chain `order.askTokenAmount` — the swap output threshold the solver must meet to fill the order, used to construct `orderRequests[].askTokenAmount`. It is not what the destination receiver gets when the outbound bridge charges a protocol fee — see `finalAmount`. * `finalAmount` is what the destination receiver actually gets: `toAmount` minus the outbound bridge protocol fee (CCTP fast-track maxFee). It equals `toAmount` for LayerZero outbound and CCTP slow-track outbound, and is otherwise slightly lower. `finalAmount <= toAmount` always; always populated. * `inboundProtocolFee` is the CCTP fast-track maxFee debited from the **input** before pricing: the inbound bridge delivers `fromAmount − inboundProtocolFee` to the execution chain and `toAmount` is quoted from that. `"0"` for LayerZero bids, local bids, and slow-track lanes. * `feeBps` is the route protocol fee in basis points (CCTP fast-track fee for Circle lanes; `0` for LayerZero). Metadata only — it is **not** subtracted from `toAmount`. The actual fee shows up as the gap between `toAmount` and `finalAmount`. * `estimatedDuration` is the end-to-end transfer time in seconds, composed of inbound bridge finality + execution-chain swap window + outbound bridge finality, plus a per-leg fill-latency buffer that covers tx inclusion on each hop. CCTP legs use fast vs standard finality depending on the deployed adapter's slow-track setting. * `lifespanSeconds` is how long the quote stays valid, in seconds, derived from the winning provider's signed expiry (expiry minus generation time, floored at 0). It is `0` when the provider does not sign an expiry or the quote has already lapsed. The on-chain fill threshold itself does **not** expire — this is the provider's price-validity window. * `swapTimeSeconds` is the estimated time for the on-chain swap to settle on the execution chain. The swap executes in a single transaction, so this is one block of the execution chain (its average block time, which differs per chain); `0` when block-time data is unavailable. * `gasCostSource` / `gasCostDest` are LayerZero native messaging fees in wei (inbound and outbound respectively), and are `0` for CCTP (USDC). Pass `gasCostSource` as `msg.value` on `submitOrder`. * `swapCost` is a gas hint from the winning liquidity provider (decimal string; empty when the provider does not return one). * `provider` is a masked liquidity-provider label, always `"zerodelta"` on a successful swap quote — the specific market maker the engine routes through is not disclosed. Omitted on direct-bridge quotes (there is no provider). * `isDirect` marks a direct-bridge quote (same token, different chains): no swap, no solver fill, not cancellable, and the top-level `executionChainId` / `executionEscrowAddress` cancel coordinates are omitted. * `isChained` marks a two-leg quote: `orderRequests` carries two elements and settlement spans two execution chains. **Errors:**


Status	`error.code`	Cause
`400`	`BAD_REQUEST`	Malformed body, missing required field, non-positive `fromAmount`, or the same token on the same chain (`fromToken` == `toToken` with `fromChainId` == `toChainId`).
`401`	`UNAUTHORIZED`	Missing or invalid API key.
`422`	`BELOW_MIN_TRADE_SIZE`	Bid amount is under the per-pair minimum ($0.02 global, $0.11 for USDe pairs). `error.fieldErrors` carries a `fromAmount` entry with the exact minimum.
`422`	`QUOTE_UNAVAILABLE`	No registered route for the requested (token, source chain, destination chain) — e.g. the token is not enabled on that chain.
`422`	`VALIDATION_ERROR`	Semantic validation failure, with per-field details.
`422`	`COMPLIANCE_BLOCKED`	Supplied `owner`/`destinationReceiver` pair failed screening; no quote or deposit instructions returned. The error `reasons[]` array is populated per the disclosure policy.
`429`	`RATE_LIMITED`	Rate limit exceeded; a `Retry-After` header (seconds) is returned.
`502`	`UPSTREAM_ERROR`	The quoting engine could not produce a quote (all liquidity providers failed, or bridge-fee estimation failed). Transient; retry with backoff.
`503`	`SERVICE_UNAVAILABLE`	Compliance engine unreachable while screening — the quote gate fails closed (only when `owner` is supplied and the gate is configured).

*** ### Transactions #### `GET /api/v1/transactions` Lists tracked cross-chain transactions, most recent first. Returns an array of TrackedTransaction (without the per-transaction `steps` array — fetch a single transaction for steps). **Query parameters:**

Parameter	Description
`status`	Filter by TrackingStatus.
`protocol`	Filter by GMP protocol (e.g. `layerzero`).
`chainId`	Matches source or destination chain.
`fromChainId`	Filter by source chain.
`toChainId`	Filter by destination chain.
`txHash`	Filter by transaction hash (list filter, not the path lookup).
`wallet`	Filter by wallet address.
`includeChainedLegs`	Surface the second leg of a chained order as its own row. Default `false`; see the note below.
`createdAfter` / `createdBefore`	RFC 3339 time-window bounds.
`sortBy`	`created_at` (default) or `updated_at`.
`sortOrder`	`desc` (default) or `asc`.
`limit` / `offset`	Pagination (default limit 50, max 500).

> **`includeChainedLegs` defaults to `false`, and that default is deliberate.** A chained child is half of one user intent, so listing it beside its parent shows a single purchase as two transactions — one of which the user never submitted and cannot cancel. By default the parent carries it in `legs[]` instead, and the fold is **applied in SQL**, so `meta.totalCount`, pagination and `/transactions/stats` all agree with the rows you get back. Set it to `true` only when you specifically want per-leg rows, and expect your order counts to change. **Errors:** `400 BAD_REQUEST`, `401 UNAUTHORIZED`. #### `GET /api/v1/transactions/{txHash}` Returns one TrackedTransaction keyed by **source transaction hash**, including the `steps` array. This is the endpoint the status poller calls (see the Integration Guide). Before the source tx is mined and indexed, this returns `404` — treat that as "not indexed yet" and keep polling. **Path parameter:** `txHash` — the source-chain submit transaction hash. > **`id` is not `orderId`.** The tracked transaction's `id` is a deployment-scoped uid (for example `"rwa:0x52b1…"`) because raw order ids are not unique across redeployments — a redeployed escrow restarts the nonce. The escrow's `cancel` / `claimCancellation` / `getOrder` calls take `orderId`; passing `id` there reverts. **Errors:** `401 UNAUTHORIZED`, `404 NOT_FOUND`. #### `GET /api/v1/transactions/{txHash}/orders` Returns **all** orders sharing a submit transaction hash, most-recent first. A single submit tx can create more than one order (a batch); the single-object `GET /api/v1/transactions/{txHash}` collapses to the most-recent, while this returns the full set — each enriched identically to the single GET. Requires an API key. **Path parameter:** `txHash` — the source-chain submit transaction hash. **Response (200):** `data` = array of `TrackedTransaction` (each with its `steps`). **Errors:** `401 UNAUTHORIZED`, `404 NOT_FOUND`. #### `GET /api/v1/transactions/{txHash}/gmp` On-demand GMP status enrichment for one transaction. Declared in the published spec; in deployed environments it may additionally be IP-restricted to internal services, so treat access as environment-dependent rather than guaranteed by your key. **Errors:** `401 UNAUTHORIZED`, `404 NOT_FOUND`. #### `GET /api/v1/transactions/stats` Returns aggregated statistics over the transactions matching the filters. The `data` payload is a TransactionStats object. **Query parameters:** `status`, `protocol`, `chainId` (matches source **or** destination chain), `fromChainId`, `toChainId`, `wallet`, `createdAfter`, `createdBefore` (same semantics as the list endpoint). ```json { "data": { "total": 1234, "byStatus": { "delivered": 1100, "in_progress": 30 }, "byProtocol": { "layerzero": 800, "cctp": 434 }, "avgDeliveryMs": 412000.0, "bySourceChain": { "1": 600, "42161": 300 }, "byDestChain": { "42161": 500, "8453": 200 } } } ``` **Errors:** `401 UNAUTHORIZED`. *** ### Chains #### `GET /api/v1/chains` Lists supported chains. Returns an array of Chain. Each chain is enriched at response time with its contract addresses and execution-chain flag. This is the canonical source for the escrow, roles and adapter addresses **of the environment your key belongs to** — `dev` and `prod` return different addresses for the same chain. **Query parameters:** `enabledOnly` (string; set to `false` to include disabled chains, default `true`), `limit`, `offset`. **Errors:** `401 UNAUTHORIZED`. #### `GET /api/v1/chains/{chainId}` Returns one Chain. **Path parameter:** `chainId` (integer). **Errors:** `401 UNAUTHORIZED`, `404 NOT_FOUND`. *** ### Tokens #### `GET /api/v1/tokens` Lists supported tokens as per-chain rows. Returns an array of Token, each enriched with bridge metadata and its enabled outbound `routes`. This is the canonical source for per-(chain, token) contract addresses — do not hardcode them. Together with `GET /api/v1/route-health` it is what you build a route picker from. > ⚠️ **Page this endpoint.** The default page is 100 rows and the catalogue is larger, so a bare call returns a **truncated** list that looks entirely healthy. Compare `meta.totalCount` against the rows you received and page with `limit` (max 500) and `offset` until they match — otherwise your picker silently omits whole tokens. **Query parameters:** `chainId`, `symbol` (e.g. `USDC`), `isEnabled` (string; `false` includes disabled tokens, default `true`), `limit`, `offset`. ```json { "data": [ { "symbol": "USDC", "chainId": "42161", "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "decimals": 6 }, { "symbol": "USDT", "chainId": "42161", "address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "decimals": 6 } ] } ``` **Errors:** `401 UNAUTHORIZED`. #### `GET /api/v1/tokens/{tokenId}` Returns one Token by its ID. **Path parameter:** `tokenId` (string). **Errors:** `401 UNAUTHORIZED`, `404 NOT_FOUND`. #### `GET /api/v1/tokens/lookup` Resolves a single Token by contract address and chain. **Query parameters (both required):** `address`, `chainId`. **Errors:** `400 BAD_REQUEST`, `401 UNAUTHORIZED`, `404 NOT_FOUND`. #### `GET /api/v1/tokens/configs` Returns the per-symbol token bridge configs (loaded from the token config directory), as an array of typed `TokenConfig` objects — one per token, sorted by `name`. `contracts` is keyed by chain ID. Useful for discovering bridge/standard metadata across chains in one call. ```json { "data": [ { "name": "USD Coin", "bridge": "Circle", "facet": "CCTPV2", "standard": "CCTPV2", "homeChainId": "1", "logoUrl": "https://...", "contracts": { "42161": { "impl": "0x…", "token": "0x…", "name": "USD Coin", "symbol": "USDC", "chainName": "arbitrum", "decimals": 6, "gmpParameters": "0x…" } } } ] } ``` **Errors:** `401 UNAUTHORIZED`. #### `GET /api/v1/prices` Returns cached USD prices for the supported market and tokenized-asset symbols. The snapshot is cached and refreshed with stale-while-revalidate, so this is cheap to poll. **Query parameter:** `symbols` — comma-separated token or native-currency symbols (max 100); omit for the full catalogue. ```json { "data": { "prices": { "USDC": 1.0, "XAUT": 2412.35 }, "fetchedAt": "2026-04-13T12:00:00Z", "stale": false, "ageSeconds": 42, "fallbackSymbols": [], "unavailableSymbols": [], "unsupportedSymbols": [] } } ``` `fallbackSymbols` lists USD-pegged assets priced at the explicit $1 fallback because no live observation was available. **Errors:** `400 BAD_REQUEST`, `401 UNAUTHORIZED`. *** ### Routes and lane health #### `GET /api/v1/routes` Lists the **bridge rails**. Returns an array of Route. A route describes how **one** token moves between two chains — its bridge, adapter, standard, facet, fee and duration metadata. > **This is not the trade catalogue.** A `Route` carries a single `tokenId` and no destination-token field, so it cannot express a trade between two different tokens, and it only covers the tokens that are bridge-configured. Build a route picker from `GET /api/v1/tokens` (the cells that exist) filtered by `GET /api/v1/route-health` (the lanes that work). See Discover what you can trade in the Integration Guide. **Query parameters:**

Parameter	Description
`fromChainId`	Filter by source chain.
`toChainId`	Filter by destination chain.
`token`	Filter by token symbol, token name, token ID, or source/destination token address.
`tokenId`	Filter by token ID.
`bridge`	Filter by bridge provider (e.g. `layerzero`, `Circle`).
`isEnabled`	String; `false` includes disabled routes, default `true`.
`limit` / `offset`	Pagination.

**Errors:** `401 UNAUTHORIZED`. #### `GET /api/v1/routes/{routeId}` Returns one Route. **Path parameter:** `routeId` (string). **Errors:** `401 UNAUTHORIZED`, `404 NOT_FOUND`. #### `GET /api/v1/route-health` Measured lane health from the route-health prober, which re-quotes every catalogued lane on a sweep and records the verdict. **This is the endpoint a route picker is built from** — see Discover what you can trade in the Integration Guide for the full flow. It also feeds `Route.isQuotable`: a lane the prober measured broken is demoted only when enforcement is on, and an **absent** `isQuotable` means "not measured", which must be treated as quotable. > **`scope` has exactly two behaviours.** `scope=all` returns every measured lane. **Any other value — including omitting the parameter, and including `scope=healthy` — returns the unhealthy subset**, and the response echoes `"scope": "unhealthy"` whatever you sent. Send `scope=all` when you want the full picture, and read the echoed `scope` back rather than assuming your value was honoured. **Response:** `data` carries `mode` (whether measured-broken lanes are currently being withheld from quoting), `scope`, a `summary` of lane counts by status, the sweep timestamps `lastSweepAt` / `nextSweepDueAt` / `measuredAt`, and the `lanes` array. The prober re-measures continuously, so counts and verdicts move between two calls seconds apart — treat every read as a snapshot.

Lane field	Description
`laneKey`	Stable identifier: source `chainId:address`, a greater-than sign, then destination `chainId:address`, both addresses lowercased. Key on this, not on symbols.
`route`	Human-readable label. Display only.
`status`	`healthy`, `degraded`, `broken` or `unknown`.
`kind`	Why the lane is not healthy. Absent on healthy lanes.
`message`	The upstream reason, when there is one worth surfacing.
`par`	The ratio the prober last measured for this lane.
`consecutiveFailures` / `firstFailedAt`	Present on broken lanes.
`lastProbedAt` / `lastOkAt`	When the lane was last measured, and last measured working.

**`kind` values, and what to do with each:** | `kind` | Meaning | Do | | --------------------- | ----------------------------------------------------------------------- | -------------------- | | `firewalled` | Disabled by ZeroDelta operations. It will not quote. | Hide, do not retry | | `not-fillable` | Prices cleanly but cannot actually be filled at the measured size. | Hide | | `lane-gap` | No bridge wiring exists for this token pair. | Hide | | `bridge-throttled` | The token's bridge path is rate-limited to zero upstream. Temporary. | Hide, retry later | | `persistent-upstream` | Liquidity providers unavailable for this pair. Temporary. | Hide, retry later | | `vault-closed` | An RWA vault is not accepting deposits; `message` carries the reason. | Hide, explain | | `value-floor` | No acceptable price at the probed size. Size-dependent, not structural. | Offer with a warning | > **Filter on `kind`, not on `status`.** The two are not interchangeable. A firewalled lane's `status` is `unknown`, **not** `broken` — the prober skips it rather than measuring it — so a filter that only hides `broken` keeps every disabled lane in your picker. In the other direction, `not-fillable` appears under both `degraded` and `broken`. **Errors:** `401 UNAUTHORIZED`. *** ### Protocols #### `GET /api/v1/protocols` Lists the supported cross-chain messaging (GMP) protocols and their per-chain state. The `data` payload has `protocols` (a string array) and `states` (an array of ProtocolState). ```json { "data": { "protocols": ["cctp", "layerzero"], "states": [ { "chainId": "1", "executionChainId": "1", "isPaused": false, "updatedAt": "2026-04-13T12:00:00Z" } ] } } ``` **Errors:** `401 UNAUTHORIZED`. *** ### Solvers A solver is a wallet authorized to fill orders on a given chain. These endpoints expose the public solver registry (read-only). #### `GET /api/v1/solvers` Returns active solvers grouped by chain, as an array of ChainSolvers. **Query parameter:** `enabledOnly` (boolean; set to `false` to include soft-deleted rows, default `true`). **Errors:** `401 UNAUTHORIZED`. #### `GET /api/v1/solvers/{chainId}` Returns one ChainSolvers group for a single chain. Returns `404` for chain IDs not in the chain registry. **Path parameter:** `chainId` (integer). **Query parameter:** `enabledOnly` (boolean, default `true`). **Errors:** `400 BAD_REQUEST`, `401 UNAUTHORIZED`, `404 NOT_FOUND`. *** ### Tokenized assets (RWA) Read-only views over the tokenized real-world-asset vaults ZeroDelta can clear into. Declared in the published spec; full response schemas ship in the OpenAPI package. | Method + path | Purpose | Query | | ---------------------------------------- | ----------------------------------------- | ------------------------- | | `GET /api/v1/rwa/vaults` | List tokenized RWA vaults | `status` | | `GET /api/v1/rwa/vaults/{slug}` | One vault by slug | — | | `GET /api/v1/rwa/vaults/{slug}/history` | Daily price, APY and TVL series | — | | `GET /api/v1/rwa/vaults/{slug}/activity` | Deposits and redemptions for one vault | `cursor`, `days`, `limit` | | `GET /api/v1/rwa/icons/{file}` | Vault icon, proxied from the upstream CMS | — | **Errors:** `400 BAD_REQUEST`, `401 UNAUTHORIZED`, `404 NOT_FOUND` (per route; the icon proxy needs no key). *** ### Stakeflow Points and commitment views. Declared in the published spec; full response schemas ship in the OpenAPI package. | Method + path | Purpose | Query | | ---------------------------------------- | ---------------------------------------------------- | ---------------------------- | | `GET /api/v1/stakeflow/leaderboard` | Ranked wallet totals (restricted — can return `403`) | `wallet` | | `GET /api/v1/stakeflow/points/{address}` | A wallet's points position | — | | `GET /api/v1/stakeflow/rates` | Published earn rate per committable token | — | | `GET /api/v1/stakeflow/commitments` | A wallet's commitments, active and revoked | `wallet` | | `GET /api/v1/stakeflow/balance` | One wallet's live balance of a committable token | `wallet`, `token`, `chainId` | | `GET /api/v1/stakeflow/capacity` | How much of one token a wallet could revoke | `wallet`, `token` | | `GET /api/v1/stakeflow/revoke-preview` | What a specific revocation would cost | `wallet`, `token`, `amount` | **Errors:** `400 BAD_REQUEST`, `401 UNAUTHORIZED`, and `403` on the leaderboard. *** ### Health and metrics #### `GET /health` Liveness probe. Always returns `200`. No auth. ```json { "status": "ok", "time": "2026-04-13T12:00:00Z" } ``` #### `GET /health/ready` Readiness probe. Probes downstream dependencies in parallel; only the database pools are critical. Returns `503` when a critical DB check fails, otherwise `200` — with `status: degraded` when a non-critical dependency is down. No auth. ```json { "status": "ok", "time": "2026-04-13T12:00:00Z", "checks": { "database": { "status": "ok", "critical": true, "latencyMs": 3 }, "read_database": { "status": "ok", "critical": true, "latencyMs": 4 }, "cache": { "status": "ok", "critical": true } }, "providers": { "a1b2c3d4e5f6": { "status": "ok", "critical": false, "latencyMs": 40, "ageSeconds": 5 }, "9c0d1e2f3a4b": { "status": "ok", "critical": false } }, "failures": [] } ``` > * `status` is `ok` or `degraded`. > * `checks` holds infrastructure dependencies under generic role labels (`database`, `read_database`, `cache`). > * `providers` holds third-party / internal-service dependencies under **opaque hashed keys** — the specific vendor is never disclosed. > * Each entry has `status` (`ok | unavailable | stub | not_configured`), a `critical` flag, and optional `latencyMs` / `ageSeconds`. Per-check error detail is intentionally omitted. > * `failures` lists the masked keys of non-ok checks (omitted when empty). #### `GET /metrics` Prometheus-format metrics. No auth; optionally IP-whitelisted per environment. *** ### Authentication and rate limits * **Auth.** Send your key in the `x-apikey` header on every `/api/v1/*` request (`x-api-key` is accepted as an alias, as is `Authorization: Bearer `). The base URL and key are provided during onboarding (separate `dev` and `prod` hosts). A missing or invalid key returns `401 UNAUTHORIZED`. The health and metrics probes need no key. * **Environments.** `dev` and `prod` are independent deployments with independent contract addresses and independent keys — a `dev` key returns `401` against `prod`. Point each build at one environment's base URL and read its addresses from `GET /api/v1/chains`. * **Rate limits.** A **global per-IP** limit of roughly **100 requests/second with a burst allowance of 200** applies to every route. A tighter **per-key** limit of roughly **50 requests/second, burst 100** applies to the pricing endpoints, `/api/v1/quote` above all. These are the deployed defaults; your key's exact limit is set at onboarding. On `429 RATE_LIMITED` the API returns a `Retry-After` header — in the current implementation it is always the literal value `1` (seconds), so treat it as a floor and add your own backoff rather than assuming it grows. If you run many concurrent sessions refetching quotes, tell the Glacis team your expected `/quote` rate so your key is sized for it. * **A note for generated clients.** The published OpenAPI spec does not declare a `429` response on any path, so a client generated from it will have no rate-limit branch even though every endpoint is rate limited. Handle `429` explicitly. # 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: ```json { "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

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

### OrderRequest Pre-built Solidity `OrderRequest` struct, one element of the array `submitOrder()` takes. `owner` and `destinationReceiver` come back `null` — the frontend must fill both on **every** element with real, non-zero addresses before calling the contract (see the Integration Guide).

Field	Type	Description
`owner`	string or null	`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	`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.

### 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. | # Transaction Models The tracked transaction and its steps, including the chained-journey fields that describe a two-leg order as one user intent. The shapes returned by the `/transactions` endpoints. For the other schemas, see Models. ### TrackedTransaction Key fields (a single-transaction GET additionally returns the `steps` array):

Field	Type	Description
`id`	string	Deployment-scoped uid (for example `"rwa:0x52b1…"`), unique across redeployments. This is not `orderId` — see below.
`orderId`	string	The raw on-chain order id. This is what the escrow's `cancel` / `claimCancellation` / `getOrder` calls take; passing `id` there reverts. Returned by the API but not yet declared in the published OpenAPI spec, so a generated client may not surface it.
`txHash`	string	Source transaction hash (the lookup key).
`protocol`	string[]	GMP protocol(s) involved.
`sourceChainId` / `destChainId`	string	Source / destination chain IDs.
`wallet`	string	Order owner wallet.
`status`	TrackingStatus	Lifecycle status of this order. For a chained order see `journeyStatus`.
`claimable`	boolean	True iff `claimCancellation()` on the execution-chain escrow would succeed right now (status is `awaiting_claim` or `expired`).
`fromTokenAddress` / `fromTokenSymbol` / `fromTokenDecimals`	—	Source token metadata.
`fromTokenAmount` / `fromTokenRawAmount`	string	Human-readable / raw source amount.
`toTokenAddress` / `toTokenSymbol` / `toTokenDecimals`	—	Destination token metadata. On a chained leg 1 this is the internal connector, not what the user bought — see the `finalToToken*` fields.
`toTokenAmount` / `toTokenRawAmount`	string	Human-readable / raw destination amount.
`completedSteps` / `totalSteps`	integer	Step progress.
`currentStep`	string	Current step name.
`submittedAt` / `arrivedAt` / `filledAt` / `deliveredAt` / `failedAt`	string or null	Lifecycle timestamps.
`failedReason` / `failedStep`	string	Failure detail.
`steps`	TransactionStep[]	Step entries (single-transaction GET only).
`sourceExplorerLink` / `destinationExplorerLink`	string	Explorer links.
`destinationTx`	string	Destination transaction hash.
`gmpStatus` / `gmpMessageId`	string	GMP status / message ID.
`orderNonce`	string	Per-source-chain order nonce (decimal string); part of the identity triple that derives `orderId`.
`destinationReceiver`	string	Receiver of the ask token on the destination chain.
`orderDeadline`	string	Order deadline (unix seconds, decimal string); `"0"` means none.
`executionChainId`	string	Chain where the escrow lives (where `cancel` / `claimCancellation` are called).
`executionEscrowAddress`	string	Escrow proxy address on the execution chain.
`createdAt` / `updatedAt`	string	RFC 3339 timestamps.

#### Chained-journey fields A chained (two-leg) order is the shape used when the asset being bought exists only on the chained destination chain — an RWA vault share on Plume, for example. It is **one user intent settled as two orders**, and these fields describe the journey rather than the individual leg.

Field	Type	Description
`isDirect`	boolean	True for a direct-bridged transfer (`OrderDirectBridged`): a same-token order bridged straight to the destination at submit time — no solver fill, no execution-chain round-trip, and not cancellable.
`isChained`	boolean	True for either leg of a chained order. On leg 1 the `toToken*` fields describe the internal connector, not the asset the user bought.
`chainedParentOrderId`	string	Order ID of leg 1, present only on the child. Rows carrying it are excluded from `GET /transactions` unless `includeChainedLegs=true`.
`chainedChildOrderId`	string	Order ID of leg 2, once `continueChain` has created it. Absent during the park window between leg 1's fill and leg 2's creation.
`journeyStatus`	TrackingStatus	Status of the user's intent, which for a chained order is not the status of any one leg: leg 1 reaching `delivered` means the connector was parked on the destination escrow, not that the user received anything. Reads `continuing` for that window. Branch completion checks on this field, falling back to `status` when it is absent.
`journeyStartedAt`	string	When leg 1 was submitted — the start of the whole journey.
`journeyCompletedAt`	string or null	When the final leg delivered. Null until the journey actually completes. It means the user got their asset at this time, not that movement stopped.
`legs[]`	TransactionLeg[]	The whole journey, index 0 being this order. Present only on a chained parent and omitted entirely for a single-leg order, so the single-leg response shape is unchanged.
`finalToTokenAddress`	string	The destination the user actually asked for, as opposed to the internal connector in `toToken*`. Correct from the moment of submit, including before leg 2 exists — leg 2's ask is ABI-encoded into `Order.nextOrders` on-chain at submit.
`finalToTokenSymbol` / `finalToTokenDecimals`	—	Metadata for the asset the user actually bought.
`finalToTokenAmount` / `finalToTokenRawAmount`	string	Human-readable / on-chain raw amount of that asset.
`finalDestChainId`	string	The chain the user's asset actually lands on. On a chained order this is not `destChainId` of leg 1.
`deliveryEvidence`	string	Qualifies a `delivered` status; absent for any order not claiming delivery. `observed` means the delivery was seen — a solver-confirmed outbound row, a same-chain direct transfer, or a fill that was itself the delivery. `presumed` means it was inferred.
`sourceEventMissing`	boolean	The source-chain submit event was never indexed, so the row was reconstructed. Returned by the API but not yet declared in the published OpenAPI spec.

> **A chained order spans three chains, and the execution chain is neither end.** Leg 1 is a same-symbol cross-chain move of the bid asset (a USDC to USDC hop is correct, not a bug) onto the execution chain; leg 2 swaps that connector into the ask and delivers it. A destination that looks wrong in a UI is usually the invisible middle hop — read `finalDestChainId` and `finalToToken*`, not `destChainId` and `toToken*`. ### TransactionLeg One leg of a chained journey, as returned in `TrackedTransaction.legs[]`.

Field	Type	Description
`index`	integer	Position in the journey, 0-based.
`role`	string	What the leg is for, so a consumer can label it without re-deriving intent from the token pair. `source-swap` turns the user's bid into the internal connector and parks it on the destination chain — its ask side is not what the user bought, and its final step is a bridge-and-park rather than a delivery. `delivery` turns the connector into the asset the user asked for and delivers it.
`orderId`	string	On-chain order id for this leg.
`txHash`	string	Submit transaction hash for this leg.
`sourceChainId` / `destChainId`	string	Chain IDs for this leg, serialized as strings.
`fromTokenAddress` / `fromTokenSymbol` / `fromTokenAmount`	—	What this leg sold.
`toTokenAddress` / `toTokenSymbol` / `toTokenAmount`	—	What this leg bought.
`status`	TrackingStatus	Status of this leg alone.
`completedSteps` / `totalSteps`	integer	Step progress for this leg.
`submittedAt` / `arrivedAt` / `filledAt` / `deliveredAt`	string or null	Lifecycle timestamps for this leg.
`steps`	TransactionStep[]	Step entries for this leg.

### TransactionStep

Field	Type	Description
`stepNumber`	integer	Step index.
`stepName`	string	One of `submitted`, `arrived`, `filled`, `delivered`.
`stepStatus`	string	One of `completed`, `pending`, `failed`, `recovered`.
`eventType`	string	Underlying event type.
`chainName` / `chainId`	string	Chain this step occurred on.
`txHash`	string	Step transaction hash.
`explorerLink` / `protocolExplorerLink`	string	Explorer links.
`blockNumber`	integer	Block number.
`blockTimestamp`	string or null	Block timestamp.
`gasUsed`	integer	Gas units consumed (omitted when unknown).
`gasPriceWei`	string	Effective gas price in wei (omitted when unknown).

### TransactionStats | Field | Type | Description | | ------------------------------- | -------------- | -------------------------------------- | | `total` | integer | Total matching transactions. | | `byStatus` | object | Count keyed by TrackingStatus. | | `byProtocol` | object | Count keyed by protocol. | | `avgDeliveryMs` | number or null | Average delivery time in milliseconds. | | `bySourceChain` / `byDestChain` | object | Counts keyed by chain ID. | # Smart Contracts Contract interface, data types, events, error codes, deployments, and coverage. For the REST API, see the API Reference. Compiler: Solidity 0.8.19 (optimizer enabled, 200 runs). License: BUSL-1.1 The contracts and error codes use the **ZDLite** identifier (the on-chain name for the product branded ZeroDelta). Contract sources carry an SPDX `BUSL-1.1` header (source-available); test sources are MIT. Integration and use are permitted. > **Per-(chain, token) addresses:** the canonical source for token contract addresses on each chain is `GET /api/v1/tokens` (see Coverage and the Integration Guide). Addresses change as chains/tokens are onboarded; do not hardcode them. ### Data types ```solidity struct OrderRequest { address owner; // Order owner (the user); need not equal msg.sender address bidToken; // Token being sold — always a local EVM address on the source chain uint256 bidTokenAmount; // Amount of bidToken to sell bytes askToken; // Token being bought, on destinationChainId (20 packed bytes for EVM) uint256 askTokenAmount; // Minimum acceptable output (fill threshold) bytes destinationReceiver; // Recipient on the destination chain (20 bytes EVM, 32 bytes Solana-style) uint64 destinationChainId; // Target chain ID uint64 executionChainId; // Chain this order clears on; must be in allowedExecutionChains uint64 deadline; // Unix expiry (0 = no deadline) } struct Order { address owner; uint64 nonce; // Auto-incremented, set by the contract (the first order from a chain is nonce 1) uint64 deadline; uint64 sourceChainId; // Set by the contract uint64 destinationChainId; bytes bidToken; uint256 bidTokenAmount; // Actual amount escrowed (balance-based accounting) bytes askToken; uint256 askTokenAmount; // Minimum acceptable output (fill threshold) bytes destinationReceiver; bytes nextOrders; // abi.encode(OrderRequest[]) of chained follow-ups; empty for normal orders } // Returned by getPendingChain(prevOrderId) for a chained order whose leg 1 has // landed and whose funds are parked awaiting leg 2. struct PendingChain { address owner; // Who may claimChain() the parked funds address token; // The parked asset (leg 1's output, leg 2's bid token) uint256 amount; // Parked amount. ZERO means already continued or claimed. bytes requests; // abi.encode(OrderRequest[]) of the follow-up leg } enum OrderStatus { Nonexistent, Pending, Filled, Cancelled } ``` **The ask side is `bytes`, not `address`.** `askToken` and `destinationReceiver` are chain-agnostic byte strings so a non-EVM destination can be expressed at all. For every EVM destination you pass the plain 20-byte address as `bytes` — a `0x`-prefixed 20-byte hex string in ethers/viem, exactly what the API returns in `orderRequests[]`. The contract rejects any other width than 20 or 32 bytes (`ZDLite__UnsupportedReceiver`), and requires exactly 20 when the destination chain is the order's own execution chain. `bidToken` stays an `address`: it is pulled with `IERC20` from `msg.sender`, so the bid side is always local and always EVM. **Chain IDs are `uint64`** on both structs, and there is no `data` field: the old pass-through `bytes data` is now `Order.nextOrders`, which the contract owns (it carries the chained follow-up requests and is empty for a normal order). **`PendingChain.amount == 0` is the resolved sentinel.** `getPendingChain` returns a zeroed struct for a chain that was never parked *and* for one already continued or claimed — the two are indistinguishable from the return value alone. Treat a zero `amount` as "nothing to act on" rather than as "claimable", and drive UI from the `ChainedOrderParked` / `ChainedOrderContinued` / `ChainedOrderClaimed` events when you need to tell those cases apart. **`executionChainId` is per order.** Each request names the chain it clears on, and the contract checks it against the `allowedExecutionChains` registry — there is no single protocol-wide setting. The API fills this in for you (`orderRequests[].executionChainId`); a `0` or non-allowlisted value reverts (`ZDLite__InvalidExecutionChainId` / `ZDLite__ExecutionChainNotAllowed(uint256)`). **On-chain enum vs. read-API status — two different vocabularies.** The on-chain `OrderStatus` enum above (`Nonexistent` / `Pending` / `Filled` / `Cancelled`) is what `orderStatuses(orderId)` returns. The **read API** (`GET /api/v1/transactions/{txHash}`) returns its own lowercase status string, **not** the enum names — if you poll the API, compare against the lowercase values, not `Filled` / `Cancelled`. The full read-API set (code-verified), with terminal classification:

Status	Terminal?
`pending`	no
`in_progress`	no
`outbound_bridging`	no
`cancel_pending`	no
`awaiting_claim`	no
`continuing`	no
`delivered`	yes (success)
`expired`	yes
`cancelled`	yes
`fill_failed`	yes
`delivery_failed`	yes
`failed`	yes

Happy path: `pending → in_progress → outbound_bridging → delivered`. This is the canonical set the Integration Guide poller mirrors; treat anything outside the non-terminal set (the first six) as terminal. > **`continuing` belongs to `journeyStatus`, not `status`.** On a chained order the parent's per-order `status` reads `delivered` the moment leg 1 lands — that leg really is done — while the journey-scoped `journeyStatus` reads `continuing` because the value is parked awaiting leg 2, not in the receiver's wallet. Branch completion checks on `journeyStatus` (falling back to `status` when it is absent, as it is on non-chained orders). See the Integration Guide poller. The order is identified by `orderId`, an immutable identity derived by the contract from `owner`, `nonce`, and `sourceChainId` (not a function of amounts). The contract computes it as `keccak256(abi.encode(owner, nonce, sourceChainId))` (code-verified against the live contract). Do not precompute or reconstruct `orderId`. `nonce` and `sourceChainId` are assigned by the contract at submit, so an off-chain caller cannot know them in advance, and under concurrency a precomputed id can be wrong. Obtain `orderId` after submission from the `OrderSubmitted` event in the transaction receipt, or from an `eth_call` simulation of `submitOrder`. A normal state-changing send does not return the value to an off-chain caller. On-chain events key on `orderId`; the read API is queryable by source transaction hash. Persist both: `orderId` for the on-chain cancel/read path (`getOrder`, `orderStatuses`), the source tx hash for API status polling. Note that the read API's `id` field is a **deployment-scoped uid** (for example `"rwa:0x52b1…"`), not `orderId` — the escrow's cancel/claim calls take `orderId`, and passing `id` there reverts. *** ### Integrator-relevant functions ```solidity // ── Source chain ─────────────────────────────────────────── // Submit one or more chained orders. Pulls requests[0].bidToken from msg.sender, // bridges it to that request's execution chain, emits OrderSubmitted. // msg.value covers the bridge fee. Returns (orderId, order) on-chain; off-chain // callers do NOT receive these from a normal send — read orderId from the // OrderSubmitted event, or use eth_call to simulate. // // requests — length 1 (normal order) or 2 (chained: request 0's swap output // funds request 1). The API returns exactly this array as // `orderRequests`; pass it through unchanged. // partnerId — attribution metadata only, read by no on-chain logic. Pass // bytes32(0) unless the Glacis team issued you an id; a non-zero // value emits PartnerOrder(partnerId). function submitOrder(OrderRequest[] calldata requests, bytes32 partnerId) external payable returns (bytes32 orderId, Order memory order); // ── Execution chain: cancel / claim ─────────────────────────────── function cancel(Order calldata order) external; // owner cancels; funds released once arrived function claimCancellation(Order calldata order) external; // withdraw a pre-arrival cancellation once it lands function cancelFor(Order calldata order, bytes calldata signature) external; // gasless: a relayer submits the owner's signed cancel // ── Execution chain: chained orders (only when order.nextOrders is non-empty) ─ // continueChain is PERMISSIONLESS and PAYABLE: anyone may push the journey // forward, and the caller pays leg 2's bridge fee out of their own msg.value. // claimChain is OWNER-ONLY: only the parked order's owner can take the funds back. function continueChain(bytes32 prevOrderId) external payable returns (bytes32 orderId, Order memory order); function claimChain(bytes32 prevOrderId) external; // owner takes the parked funds back instead // ── Views ───────────────────────────────────────────── // getOrder / orderStatuses resolve the canonical order state on the order's // EXECUTION chain. A source-chain instance will not hold the canonical record // post-bridge (returns Nonexistent). function getOrder(bytes32 orderId) external view returns (Order memory); function orderStatuses(bytes32 orderId) external view returns (OrderStatus); function getPendingChain(bytes32 prevOrderId) external view returns (PendingChain memory); function isSupportedToken(uint256 chainId, address token) external view returns (bool); function isSupportedToken(uint256 chainId, bytes memory token) external view returns (bool); function getBridgeAdapter(address token, uint256 destChainId) external view returns (address); function getEquivalentToken(uint256 destChainId, address destToken) external view returns (address); function getEquivalentToken(uint256 destChainId, bytes memory destToken) external view returns (address); function allowedExecutionChains(uint256 chainId) external view returns (bool); function domainSeparator() external view returns (bytes32); // EIP-712 domain, for cancelFor relayers ``` `getOrder` and `orderStatuses` are **execution-chain** views. Every order names its own execution chain in `OrderRequest.executionChainId`; the quote surfaces the resolved pair as `executionChainId` + `executionEscrowAddress`, and that is the contract to read and to cancel against. Point a provider at that chain — not at the source chain — before calling. See the cancel snippet in the Integration Guide. > **`getOrder` is only populated after arrival.** Before the order bridges and arrives on its execution chain, `getOrder(orderId)` returns a zeroed struct. Passing that to `cancel()` derives `keccak256(0, 0, 0)` and reverts with `ZDLite__UnauthorizedCaller` — which looks like a permissions problem and is not one. Persist the `Order` tuple from the `OrderSubmitted` event at submit time; pre-arrival it is the only copy in existence. **Chained orders: who may call what.** `continueChain(prevOrderId)` is **permissionless** — any address may call it to push a parked journey forward — and it is **`payable`**, because the caller funds leg 2's bridge messaging fee from their own `msg.value`. That is deliberate: a relayer or the counterparty can complete a journey the user has walked away from. `claimChain(prevOrderId)` is the opposite: **owner-only**, and it abandons the follow-up leg to return the parked funds. Both are no-ops once the chain is resolved (`PendingChain.amount == 0`). **Direct-bridged orders store no state.** When a single request's ask token is the same asset as its bid token on the destination chain (a same-ticker lane, e.g. USDC → USDC), `submitOrder` bridges straight to `destinationReceiver` and emits **only** `OrderDirectBridged`. No order is stored, nothing arrives, nothing fills — and there is nothing to cancel: `cancel()` on such an id registers a harmless pre-cancellation and `claimCancellation` reverts `ZDLite__OrderNotArrived`. `askTokenAmount` acts as a minimum-delivered floor. The API flags these quotes with `isDirect: true`; suppress cancel affordances for them. **Gasless cancel (`cancelFor`).** The owner signs an EIP-712 `Cancel` message and any relayer submits it. Domain: `name = "ZDLiteEscrow"`, `version = "1"`, `chainId` = the execution chain, `verifyingContract` = that chain's escrow (read `domainSeparator()` to verify). Typed struct: `Cancel(address owner,uint64 orderNonce,uint64 sourceChainId)` — the same triple that derives `orderId`. Replay protection is the order's one-way status machine, not a separate nonce: once the cancel lands the status is no longer `Pending`/`Nonexistent`, so a replay reverts. Contract signatures (EIP-1271) are accepted. The contract also exposes a `nonce()` view, but do not use it to precompute `orderId`: `nonce` is contract-assigned and advances as orders are submitted, so a read-then-derive sequence is racy under concurrency. Always read `orderId` back from the `OrderSubmitted` event instead. The contract also exposes administrative functions (token/adapter registration, execution-chain allowlisting, pause, role management) that are operator-only and not part of the integration surface. The full interface is available in the OpenAPI/ABI package provided on onboarding. *** ### Events | Event | Indexed | Emitted when | | -------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- | | `OrderSubmitted(bytes32 orderId, Order order)` | `orderId` | An order is submitted on the source chain. | | `OrderDirectBridged(bytes32 orderId, Order order)` | `orderId` | A same-token direct bridge is submitted — emitted **instead of** `OrderSubmitted`, and terminal at submit. | | `OrderArrived(bytes32 orderId, Order order)` | `orderId` | An order arrives on the execution chain (or same-chain submit). | | `OrderFilled(bytes32 orderId, Order order)` | `orderId` | An order is filled. | | `OrderCancelled(bytes32 orderId, Order order)` | `orderId` | A cancel returns funds. | | `PartnerOrder(bytes32 partnerId)` | `partnerId` | A submit carried a non-zero `partnerId` (attribution only). | Pre-arrival cancellations and claims emit their own events (`OrderPreCancelled`, `EscrowClaimed`), and chained orders emit `ChainedOrderParked` / `ChainedOrderContinued` / `ChainedOrderClaimed`, all keyed by the funding order's id. See the ABI package for the complete list. *** ### Error codes The errors integrators encounter most often: All names below are code-verified against the deployed contract source. Match by selector against these exact signatures — **including parameters**: an error that carries arguments hashes to a different selector than its bare name, so deriving a selector from the name alone will never match the revert data.

Error	Meaning
`ZDLite__UnsupportedToken`	The bid or ask token is not registered on that chain.
`ZDLite__BridgeAdapterNotFound`	No adapter is registered for the `(token, destChain)` route.
`ZDLite__ZeroAddress`	A required address (`owner` or `destinationReceiver`) is the zero address; both must be real addresses.
`ZDLite__ZeroAmount`	`bidTokenAmount` (or a required amount) is zero.
`ZDLite__UnsupportedReceiver`	`destinationReceiver` is not 20 or 32 bytes — or not exactly 20 when the destination chain is the order's execution chain.
`ZDLite__InvalidExecutionChainId`	`executionChainId` is `0`.
`ZDLite__ExecutionChainNotAllowed(uint256)`	`executionChainId` is not in the escrow's allowlist. The revert data carries the rejected chain id, so the selector is that of the `(uint256)` signature — not of the bare name.
`ZDLite__NoOrderRequests`	The `requests` array is empty.
`ZDLite__TooManyOrderRequests`	More than two requests were submitted (max chain length is 2).
`ZDLite__InvalidDeadline`	`deadline` is in the past (and not `0`).
`ZDLite__OrderExpired`	The order's deadline passed before it could be filled.
`ZDLite__InsufficientAskToken(expected, actual)`	A fill could not meet the user's minimum output; the fill reverts.
`ZDLite__DirectBridgeInsufficientAmount(askTokenAmount, actualAmount)`	A direct bridge would deliver less than the `askTokenAmount` floor.
`ZDLite__OrderNotPending`	The order is not in `Pending` state for the requested action.
`ZDLite__OrderNotArrived`	A cancel/claim was attempted before the order arrived on the execution chain.
`ZDLite__OrderAlreadyArrived`	Re-delivery guard (bridge replay protection).
`ZDLite__OrderAlreadyFilled`	The order was already filled.
`ZDLite__OrderNotCancellable`	The order is not in a cancellable state.
`ZDLite__UnauthorizedCaller`	Caller is not permitted for that action (e.g. cancel by non-owner) — also what a zeroed `Order` struct produces, see the `getOrder` note above.
`ZDLite__InvalidSignature`	A `cancelFor` signature did not validate against `owner`.
`ZDLite__ChainedTokenMismatch` / `ZDLite__ChainedChainMismatch`	A two-request submit does not satisfy `askToken[0] == bidToken[1]` and `destinationChainId[0] == executionChainId[1]`.
`ZDLite__ChainAlreadyParked`	A chained order's funds are already parked for that funding order id — the park step cannot run twice.
`ZDLite__ChainNotParked` / `ZDLite__ChainAlreadyResolved`	`continueChain` / `claimChain` was called for a chain that is not parked, or was already continued or claimed.

These are the common subset an integrator hits; the complete error set ships in the ABI package. **On underpaid `msg.value`:** there is no `ZDLite__` error for an insufficient bridge fee. If `msg.value` does not cover the bridge adapter's native messaging fee, `submitOrder` reverts with the bridge adapter's own error, which is adapter-specific (CCTP vs LayerZero) — do not match it by a `ZDLite__` name. Send `gasCostSource` from the quote. See the Integration Guide. > **Buffer the fee on LayerZero lanes only — never on CCTP.** On a LayerZero-source order the escrow passes `msg.sender` as the OFT `refundAddress`, so the adapter refunds whatever excess you send; a small buffer (say +10–20%) is cheap insurance against the fee moving between quote and inclusion. CCTP (USDC) lanes are the opposite: they quote `gasCostSource: 0`, and the CCTP adapter's refund-address parameter is declared but **unused**, so native value attached to a USDC order is **stranded in the contract, not refunded**. Send exactly the quoted `gasCostSource` on CCTP lanes. **On a paused contract:** pause uses OpenZeppelin `PausableUpgradeable` (`whenNotPaused`), so a submission against a paused contract reverts with OpenZeppelin's `EnforcedPause` selector (older deployments: the `"Pausable: paused"` revert string), not a `ZDLite__` error. Note that the pause also freezes `cancel`, `claimCancellation`, `continueChain`, `claimChain`, and the bridge-delivery entrypoints. *** ### Deployments ZeroDelta runs two live deployments: **`prod`** (production) and **`dev`** (pre-production). They are independent on-chain deployments — same nine chains, same execution-chain allowlist, entirely different addresses — and are reached through different API base URLs and API keys. The addresses below are the **`prod` deployment**; `dev` addresses are not published here, and integrators read them from `GET /api/v1/chains` on their `dev` base URL. The escrow is deployed at the same address across all 9 supported chains, and Ethereum is the default execution chain. * **Escrow (`prod`, all chains):** `0x5e25c8ABc19b88d6A7Ab0D805C77A34987a68b40` * **Roles (`prod`, all chains):** `0x4248EA01aB83541d1406e23250FCAE6c29D2fF13` * **Default execution chain:** Ethereum (`chainId 1`). * **Allowed execution chains:** Ethereum (`1`), Base (`8453`), Arbitrum (`42161`), Plume (`98866`). An order's `executionChainId` must be one of these; the API picks it for you. > **Confirm your environment before you wire addresses in.** The deployment name scopes the CREATE2 salt, so **every address rotates between deployments** — the `dev` deployment does not share a single address with `prod`, even for the same contract on the same chain. Use the base URL and deployment you were given at onboarding, and read addresses from `GET /api/v1/chains` for that environment rather than hardcoding them. `GET /api/v1/chains` is canonical: per chain it returns the escrow address, the bridge adapter addresses, the roles-contract address, and whether the chain is an execution chain. That makes the `submitOrder` requirement "a bridge adapter must exist for `(bidToken, executionChainId)`" checkable from the API before you submit. Keep the chain set in sync with the Integration Guide coverage matrix. *** ### Coverage * **Bridged bid stablecoins:** USDC (Circle CCTP V2), USDT and USDe (LayerZero V2 OFT) are the core set; USDtb, AUSD, PYUSD and USDG are also bridge-configured over LayerZero OFT. * **Ask-only outputs:** additional tokens can be bought but not bridged — DAI, RLUSD, USD1, USDS, wM, rUSDY, PAXG, USDY, sUSDf, USDf, USD3 and PRIME — plus the tokenized-asset set (13: eleven Nest `n*` vault tokens and two Centrifuge `de*` tokens). They are delivered on the chain the order executes on, so `destinationChainId` must equal `executionChainId` for those. XAUT is the exception among tokenized assets — it carries its own OFT mesh and can be delivered cross-chain. * **Chains:** Ethereum (default execution chain), Optimism, Arbitrum, Base, Ink, Unichain, Plasma, Sonic, Plume. Chain IDs and the per-cell bridge matrix are in the Integration Guide. * **Per-(chain, token) addresses:** retrieved from `GET /api/v1/tokens` (e.g. `?chainId=42161`), which returns `symbol`, `chainId`, `address`, and `decimals` per token. This is the canonical source; addresses are not hardcoded here because they change as coverage expands. * Coverage is not uniform per (chain, token) cell — `GET /api/v1/routes` returns the live per-cell set. New chains, tokens, and routes are onboarded on partner request. The live `/chains`, `/tokens`, and `/routes` endpoints are the source of truth for what is enabled in your environment. *** ### Audit Halborn and Sherlock have audited the ZeroDelta (ZDLite) smart contracts; all important findings addressed. Report available on request. # Widget Prebuilt UI for cross-chain stablecoin and real-world-asset settlement. Drop it in; the user's wallet always signs. The ZeroDelta Widget is a set of prebuilt UI components that put the clearing house into your app. It is the four-call integration from the [Integration Guide](/zero-delta/integration-guide) — quote, approve, `submitOrder`, track — already built, tested and themed. One npm package, **zero runtime dependencies**, and no iframe: it renders in your page's own realm, styled with your tokens. {% columns %} {% column %} #### Install & Embed React, `mount()`, a ` ``` The global exposes five helpers, each taking the same props as the matching React component — including the display `variant` — and returning an unmount function: | Helper | Renders | | ----------------------------- | ------------------------------------------- | | `mountPay(el, props)` | `StableGeniePay` | | `mountSwap(el, props)` | `StableGenieSwap` | | `mountExchange(el, props)` | `StableGenieExchange` | | `mountRwaExchange(el, props)` | `StableGenieExchange` with `product: "rwa"` | | `mountExpress(el, props)` | `PaymentIsland` — ZeroDelta Link | **jsDelivr** works too: `https://cdn.jsdelivr.net/npm/@glacislabs/stablegenie-zerodelta@4.0.0/dist/standalone.global.js` > **Pin an exact version, and prefer self-hosting if your CSP disallows third-party script origins — this widget sits in a payment path.** The file ships inside the package at `dist/standalone.global.js`, so you can copy it into your own static assets at build time: > > ```jsonc > "scripts": { > "vendor:widget": "cp node_modules/@glacislabs/stablegenie-zerodelta/dist/standalone.global.js public/vendor/" > } > ``` ### Next.js and server rendering The widget is a client component. Importing it on the server does not crash — style injection, `localStorage` and wallet discovery are all guarded on `typeof window` — but it renders nothing useful there. 1. **The package ships no `"use client"` directive.** Wrap it in your own client component: ```tsx // app/components/Checkout.tsx "use client"; import { StableGeniePay } from "@glacislabs/stablegenie-zerodelta"; export function Checkout({ amount }: { amount: string }) { return ; } ``` 2. **Or skip SSR entirely** where you would rather not ship it in the server bundle: ```tsx import dynamic from "next/dynamic"; const Checkout = dynamic(() => import("./Checkout").then((m) => m.Checkout), { ssr: false }); ``` 3. **Route the proxy as a Next handler.** Mount it at `app/api/widget/v1/[...path]/route.ts` so the widget's default `apiBase` resolves without configuration. The proxy logic is plain data in and plain data out — see [The Keyless Proxy](/zero-delta/widget/keyless-proxy) for a complete handler. ### Compatibility | | | | -------------------- | ------------------------------------------------------------------ | | React | 18 and 19 (peer dependency) | | Module formats | ESM + CJS, with `.d.ts` and `.d.cts` types | | Bundlers | Vite, webpack, Next.js, Rollup, esbuild — nothing special required | | Node | >= 20, for building only | | Runtime dependencies | none | | Licence | MIT | **Browser APIs used:** `fetch`, `BigInt`, `URL` / `URLSearchParams`, `Promise.all`, `CustomEvent`, and `localStorage` (guarded — it degrades cleanly in private or sandboxed contexts). Any browser with those needs no polyfill; there is no `viem` or `ethers` to shim because neither is used. ### When something does not render | Symptom | Cause | | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Every request answers `503 proxy_misconfigured` | The proxy has no `STABLEGENIE_API_KEY` set | | `403 origin_not_allowed` | Cross-origin embed with the origin missing from `WIDGET_ALLOWED_ORIGINS` | | Card renders but no chains or tokens load | The `/api/widget/v1/*` route is not mounted or not rewritten to your handler | | **Direct settlement never appears as a route** | Your proxy does not allow `screen/wallet` — the engine cannot screen, so it fails closed. See [The Keyless Proxy](/zero-delta/widget/keyless-proxy) | | A payment succeeds on-chain but `onSuccess` never fires | Your CSP `connect-src` does not allow the verification RPC — see [The Keyless Proxy](/zero-delta/widget/keyless-proxy) | | `variant: "pill"` is ignored | You used `mount()`, which cannot express a display variant | ### Try a configuration first The [widget playground](https://playground.glacislabs.com/) renders every component against the production gateway and prints the exact React, `mount()` and `