{ "openapi": "3.0.3", "info": { "title": "CoW Protocol x402 Quote API", "version": "0.1.0", "description": "Pay for CoW Protocol quotes with x402 v2 batch settlement. No API key or sign-up is required.\nThe quote network in the URL is independent of the network used to pay.\nThis reference describes the batch-only production API at `https://x402.cow.fi`.\n\n### Make a paid request\n\n1. POST a quote request without a payment header. A `402` response carries a base64-encoded JSON challenge in `PAYMENT-REQUIRED`; its JSON body is normally `{}`.\n2. Use the x402 SDK to select an entry from `accepts`, open or reuse a payment channel, and sign the payment. Read the price, token, receiver and minimum deposit from that challenge.\n3. Retry the quote with the SDK's base64-encoded `PAYMENT-SIGNATURE`. The first deposit or a top-up waits for its on-chain receipt. Later requests use cumulative vouchers and do not submit a transaction per quote.\n4. Let the SDK validate a successful `PAYMENT-RESPONSE` before updating local state and sending the next request on that channel. A voucher receipt usually has an empty `transaction`; collection happens later when economic.\n\nUse the tested [**2.26.0 Node SDK**](https://www.npmjs.com/package/@x402/evm/v/2.26.0).\nSDK versions 2.22–2.25 ignore `extra.minDeposit`; use 2.26.0 for the documented flow.\nKeep channel storage across restarts and serialize requests sharing one channel, including requests for different quote networks.\nA quote's `from` identifies the trader and need not equal the payment wallet.\n\n### Payment options\n\nSelect an entry from the live challenge by scheme, payment network, token and expected receiver.\nRead `amount` for the quote price, `extra.minDeposit` for the deposit/top-up minimum, and\n`extra.withdrawDelay` for a new channel's withdrawal delay. These are deployment terms and can change.\nCheck them against your own price, deposit and maximum withdrawal-delay limits before signing.\nAmounts use the selected token's decimals; BNB USDC and Base COW use 18, while Base and Ethereum USDC use 6.\nPrices and deposits are **atomic integer strings**, including `extra.minDeposit`.\nCOW and BNB USDC require explicit SDK asset spending permission and a payer-funded Permit2 approval before the first deposit.\nThe service pays the gas to submit deposits and collect vouchers. Deposits are prepaid balances, not an extra quote fee.\nSDK 2.26.0 targets `extra.minDeposit`, or more if needed for the next voucher, but its spend cap can clip the deposit below that minimum.\nThe cap is `maxAmountPerPayment × depositPolicy.depositMultiplier` (default multiplier 5).\nUse `depositStrategy` to choose a larger deposit or enforce your budget; increasing the cap alone does not select a larger deposit.\nKeep a separate quote-price limit and never automatically raise your budgets to match a challenge.\n\n### Validate receipts\n\nOnly successful receipts may update local charged state. Add `extra.chargedAmount` to the previous local charged total;\na missing charge means zero. It must be a non-negative atomic integer string no greater than the selected request's `amount`.\nIf `extra.channelState.chargedCumulativeAmount` is present, it must equal that calculated total.\nOtherwise leave local state unchanged and reconcile; never blindly copy a reported total.\nThe next voucher is the validated local total plus the next request's price. SDK 2.26.0 performs these checks.\nThe top-level receipt `amount` is the settlement amount, not the quote charge; voucher receipts currently use an empty string there.\n\n### Retries and withdrawals\n\nInspect the HTTP status, both decoded payment headers and any response body together.\nVerification rejections normally report `error` in `PAYMENT-REQUIRED`.\nSettlement failures normally carry `success: false` and `errorReason` in `PAYMENT-RESPONSE`, with body `{}` and no challenge.\nAn undecodable `PAYMENT-SIGNATURE` is treated as missing payment and receives a fresh `402` challenge.\nA missing or insufficient Permit2 allowance returns `402`\n(`invalid_batch_settlement_evm_permit2_allowance_required`) with `Retry-After`.\nIf sufficient approval is already confirmed, retry the same unexpired payment after that delay;\ndo not approve again. After a definite pre-submission rejection, an expired authorization needs a fresh signature.\nExpiry alone does not prove that a submitted deposit failed: check its original transaction and channel before signing another deposit.\n\nFor a corrective `402`, the SDK validates the attached signed voucher proof before adopting a recovered total.\nUse an RPC-backed signer and retain local state; on-chain `totalClaimed` alone omits uncollected charges.\n`transaction_pending` means a deposit was submitted but confirmation is unresolved. Keep the original channel, signed attempt and hash;\ncheck the transaction and reuse confirmed funding rather than creating a duplicate deposit.\n`batch_accounting_unavailable` and settlement-stage `batch_unavailable` can leave a charge recorded if a write committed before its acknowledgement was lost.\nQuote-validation failures and definite payment rejections before settlement are uncharged, but an unsuccessful HTTP response alone does not prove no charge.\nA timeout or lost response is an unknown outcome. Quote bodies are not deduplicated; a new request can incur another charge.\nReconcile before retrying, keep retries bounded, and contact [Discord](https://discord.com/invite/cowprotocol) if the outcome remains unclear.\n\nUnused deposits can be withdrawn on chain. Initiate withdrawal, wait the original saved channel's `withdrawDelay`, then submit a separate finalization transaction. New vouchers for that channel\nare rejected once withdrawal is pending. The payer funds withdrawal gas. Cooperative refund HTTP endpoints are not exposed.\nEligibility is the on-chain initiation timestamp plus that channel's original delay; finalization is not automatic.\nCollection only runs when the collected amount is worth the estimated transaction cost under current policy.\nNeither age nor a pending withdrawal overrides the economic check, so fees can remain uncollected when withdrawal becomes eligible.\nClaims during the waiting period reduce the available payout; finalization does not wait for all fees to be collected or erase the recorded charge history.\n\n### Free endpoints and limits\n\nOther public orderbook endpoints under `/{network}/api/` are forwarded without x402 payment.\nTheir contracts are maintained in the [orderbook API reference](https://docs.cow.fi/cow-protocol/reference/apis/orderbook).\nPublic ingress blocks auction, debug, restricted and quote-stream endpoints with `403`.\nFree and quote routes have separate configurable rate limits per IP per ingress controller.\nThese are not global quotas. Rate limiting returns `429`; retry with backoff.\nDeposits/top-ups also have per-payer and global hourly budgets; paid requests have a separate global hourly budget.\nThese are shared across payment chains and use fixed UTC-hour buckets. Exceeding them returns `402 deposit_budget_exhausted`\nor `402 request_budget_exhausted`; wait for the next bucket. An unresolved attempt can retain its reservation until it expires.\nPaths are case-sensitive, with no trailing slash; `arbitrum-one` is also accepted as an alias for `arbitrum_one`.\nThis page is a reference; use a Node client to sign payments and manage persistent channel state.\nSee the [public integration guide](https://app.notion.com/p/3d48da5f04ca81d6a5d3c1801767a9f4) for client and withdrawal examples.\n", "license": { "name": "GPL-3.0-or-later", "url": "https://www.gnu.org/licenses/gpl-3.0.html" }, "contact": { "name": "CoW Protocol", "url": "https://cow.fi" } }, "security": [], "servers": [ { "url": "https://x402.cow.fi/{network}", "description": "Production", "variables": { "network": { "description": "The orderbook to quote on; independent of the payment chain.", "default": "mainnet", "enum": [ "mainnet", "base", "bnb", "xdai", "polygon", "arbitrum_one", "avalanche", "ink", "sepolia", "linea", "plasma" ] } } } ], "tags": [ { "name": "Quotes", "description": "Pay for a quote, then sign and submit an order separately through the orderbook API." } ], "paths": { "/api/v1/quote": { "post": { "tags": [ "Quotes" ], "operationId": "getPaidQuote", "summary": "Get a quote using an x402 payment", "description": "Request and response bodies follow the orderbook quote contract. The proxy adds payment handling.\nOmit `PAYMENT-SIGNATURE` to obtain the challenge, then retry with an SDK-generated payment.\nA successful quote does not place or execute an order. Quote responses are not cacheable.\nDeposit transactions can take longer than voucher-only requests; allow time for an on-chain receipt.\nJSON request bodies are limited to 128 KiB.\n", "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "description": "Base64-encoded UTF-8 JSON matching PaymentPayload. Required to obtain a paid quote;\nomit it to request a challenge. Generate it with the SDK, not an API key or bearer token.\n", "schema": { "type": "string", "description": "Base64 text, not a file upload." }, "x-decoded-schema": { "type": "object", "description": "The SDK-generated envelope encoded in PAYMENT-SIGNATURE. This is not the quote request body.", "required": [ "x402Version", "accepted", "payload" ], "properties": { "x402Version": { "type": "integer", "enum": [ 2 ] }, "resource": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "mimeType": { "type": "string", "example": "application/json" } } }, "accepted": { "type": "object", "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds", "extra" ], "properties": { "scheme": { "type": "string", "enum": [ "batch-settlement" ] }, "network": { "type": "string", "pattern": "^eip155:[0-9]+$", "description": "Payment chain identifier, independent of the quote URL.", "example": "eip155:8453" }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "payTo": { "allOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } ], "description": "Receiver advertised by this deployment. Always use the live challenge; do not hardcode example addresses." }, "maxTimeoutSeconds": { "type": "integer", "minimum": 1, "description": "Deposit-authorization validity from the current challenge; expiry does not prove a submitted transaction failed." }, "extra": { "type": "object", "required": [ "minDeposit", "receiverAuthorizer", "withdrawDelay" ], "additionalProperties": true, "properties": { "minDeposit": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Minimum initial deposit and top-up as a plain atomic integer string. SDK 2.26.0 targets this hint, but its spend cap can clip the deposit below the minimum; check your budget and cap before signing." }, "receiverAuthorizer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "withdrawDelay": { "type": "integer", "minimum": 0, "description": "New-channel delay in seconds. Save it in the channel configuration; later advertisements cannot change an existing channel." }, "name": { "type": "string", "description": "Token EIP-712 domain name when required." }, "version": { "type": "string", "description": "Token EIP-712 domain version when required." }, "assetTransferMethod": { "type": "string", "description": "Permit2 is indicated by permit2; an omitted value uses the scheme default.", "example": "permit2" }, "channelState": { "type": "object", "description": "Channel accounting observations. Ordinary receipts must agree with locally calculated charges; corrective recovery requires validating the attached signed voucher proof. Fields may be partial.", "properties": { "channelId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "balance": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Deposits minus withdrawals/refunds; includes amounts already counted in totalClaimed. balance minus totalClaimed is the remaining unclaimed escrow." }, "totalClaimed": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Collected on-chain so far. May lag accepted charges while collection is uneconomic, including at withdrawal eligibility." }, "chargedCumulativeAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "On a successful ordinary receipt, must equal previous local total plus validated extra.chargedAmount. Leave local state unchanged on mismatch. Recorded charges can exceed the remaining balance after withdrawal; do not treat the difference as withdrawable funds." }, "withdrawRequestedAt": { "type": "integer", "minimum": 0, "description": "Unix time in seconds; zero if no withdrawal is pending." }, "refundNonce": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } }, "additionalProperties": true } } } } }, "payload": { "type": "object", "description": "Scheme-specific signed deposit or cumulative voucher, including channelConfig and voucher.\nGenerate and validate this with @x402/evm; token authorization shapes differ between EIP-3009 and Permit2.\nHand-written signatures and channel state are not an integration interface.\n", "additionalProperties": true }, "extensions": { "type": "object", "additionalProperties": true } } } } ], "requestBody": { "required": true, "description": "Order parameters on the selected quote network. Token amounts use that token's atomic units.", "content": { "application/json": { "schema": { "description": "Request fee and price quote.", "allOf": [ { "description": "The buy or sell side when quoting an order.", "oneOf": [ { "type": "object", "description": "Quote a sell order given the final total `sellAmount` including fees.", "properties": { "kind": { "allOf": [ { "type": "string", "enum": [ "sell" ] } ] }, "sellAmountBeforeFee": { "description": "The total amount that is available for the order. From this value, the fee is deducted and the buy amount is calculated.\n", "allOf": [ { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" } ] } }, "required": [ "kind", "sellAmountBeforeFee" ] }, { "type": "object", "description": "Quote a sell order given the `sellAmount`.", "properties": { "kind": { "allOf": [ { "type": "string", "enum": [ "sell" ] } ] }, "sellAmountAfterFee": { "description": "The `sellAmount` for the order.", "allOf": [ { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" } ] } }, "required": [ "kind", "sellAmountAfterFee" ] }, { "type": "object", "description": "Quote a buy order given an exact `buyAmount`.", "properties": { "kind": { "allOf": [ { "type": "string", "enum": [ "buy" ] } ] }, "buyAmountAfterFee": { "description": "The `buyAmount` for the order.", "allOf": [ { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" } ] } }, "required": [ "kind", "buyAmountAfterFee" ] } ] }, { "type": "object", "description": "Optional validity: validTo is a Unix timestamp; validFor is a duration in seconds. Supply at most one non-null value. Omitting both uses the orderbook default.", "properties": { "validTo": { "type": "integer", "minimum": 0, "maximum": 4294967295, "nullable": true }, "validFor": { "type": "integer", "minimum": 0, "maximum": 4294967295, "nullable": true } }, "not": { "required": [ "validTo", "validFor" ], "properties": { "validTo": { "type": "integer" }, "validFor": { "type": "integer" } } } }, { "type": "object", "properties": { "sellToken": { "description": "ERC-20 token to be sold", "allOf": [ { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" } ] }, "buyToken": { "description": "ERC-20 token to be bought", "allOf": [ { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" } ] }, "receiver": { "description": "An optional address to receive the proceeds of the trade instead of the\n`owner` (i.e. the order signer).\n", "nullable": true, "type": "string" }, "appData": { "description": "AppData which will be assigned to the order.\n\nExpects either a string JSON doc as defined on\n[AppData](https://github.com/cowprotocol/app-data) or a hex\nencoded string for backwards compatibility.\n\nWhen the first format is used, it's possible to provide the\nderived appDataHash field.", "anyOf": [ { "description": "The string encoding of a JSON object representing some `appData`. The\nformat of the JSON expected in the `appData` field is defined\n[here](https://github.com/cowprotocol/app-data).\n", "type": "string", "example": "{\"version\":\"0.9.0\",\"metadata\":{}}" }, { "description": "32 bytes encoded as hex with `0x` prefix.\nIt's expected to be the hash of the stringified JSON object representing the `appData`.\n", "type": "string", "example": "0x0000000000000000000000000000000000000000000000000000000000000000" } ] }, "appDataHash": { "description": "The hash of the stringified JSON appData doc.\n\nIf present, `appData` field must be set with the aforementioned\ndata where this hash is derived from.\n\nIn case they differ, the call will fail.", "anyOf": [ { "description": "32 bytes encoded as hex with `0x` prefix.\nIt's expected to be the hash of the stringified JSON object representing the `appData`.\n", "type": "string", "example": "0x0000000000000000000000000000000000000000000000000000000000000000" } ] }, "sellTokenBalance": { "deprecated": true, "allOf": [ { "description": "Where should the `sellToken` be drawn from?\n\n**Only `erc20` is accepted for new orders.** The `internal` and `external`\n(Balancer Vault) sources are deprecated: orders using them are rejected at\ncreation with `UnsupportedSellTokenSource`. The values remain in the enum\nbecause they may still appear on historical orders returned by the API.", "type": "string", "enum": [ "erc20", "internal", "external" ] } ], "default": "erc20" }, "buyTokenBalance": { "deprecated": true, "allOf": [ { "description": "Where should the `buyToken` be transferred to?\n\n**Only `erc20` is accepted for new orders.** The `internal` (Balancer Vault)\ndestination is rejected at creation with `UnsupportedBuyTokenDestination`.\nThe value remains in the enum because it may still appear on historical\norders returned by the API.", "type": "string", "enum": [ "erc20", "internal" ] } ], "default": "erc20" }, "from": { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" }, "priceQuality": { "allOf": [ { "description": "How good should the price estimate be?\n\nFast: The price estimate is chosen among the fastest N price estimates.\nEstimates do not get verified by simulation.\nOptimal: The price estimate is chosen among all price estimates, ranked\npurely by the promised price. Estimates do not get verified by simulation.\nVerified: All price estimates get verified by simulation whenever\npossible and verified estimates are preferred over unverified ones,\neven when an unverified estimate promises a better price. The\nresponse's `verified` flag indicates whether the returned estimate\nwas actually verified.\n\n**NOTE**: Orders are supposed to be created from `verified` or `optimal`\nprice estimates.", "type": "string", "enum": [ "fast", "optimal", "verified" ] } ], "default": "verified" }, "fastPath": { "description": "Signals that this quote is intended for fast-path (out-of-competition) execution. Propagated to the solver. Mutually exclusive with the `appData` `validFrom` field: an order that sets both is rejected.\n", "type": "boolean", "default": false }, "signingScheme": { "allOf": [ { "description": "How was the order signed?", "type": "string", "enum": [ "eip712", "ethsign", "presign", "eip1271" ] } ], "default": "eip712" }, "onchainOrder": { "description": "Flag to signal whether the order is intended for on-chain order placement. Only valid for non ECDSA-signed orders.\"\n", "default": false }, "timeout": { "type": "integer", "description": "User provided timeout in milliseconds. If no value is provided the systems default quote timeout will be used. Values get capped at a generous maximum timeout. Note that reducing the timeout can result in worse quotes because it might be too short for some price estimators.\n" } }, "required": [ "sellToken", "buyToken", "from" ] } ] }, "examples": { "mainnetSell": { "summary": "Sell 0.1 WETH for USDC on Ethereum (illustrative trader)", "value": { "sellToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "buyToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "from": "0x0000000000000000000000000000000000000001", "kind": "sell", "sellAmountBeforeFee": "100000000000000000" } } } } } }, "responses": { "200": { "description": "Quoted order. The batch charge is committed and PAYMENT-RESPONSE carries the channel receipt.\nIllustrative decoded voucher receipt below: amounts are arbitrary atomic units, not advertised prices;\naddresses and channel ID are placeholders. The HTTP body remains the quote, not this receipt.\n\n```json\n{\n \"success\": true,\n \"transaction\": \"\",\n \"network\": \"eip155:8453\",\n \"payer\": \"0x0000000000000000000000000000000000000001\",\n \"amount\": \"\",\n \"extra\": {\n \"chargedAmount\": \"3\",\n \"channelState\": {\n \"channelId\": \"0x1111111111111111111111111111111111111111111111111111111111111111\",\n \"balance\": \"100\",\n \"totalClaimed\": \"0\",\n \"chargedCumulativeAmount\": \"3\",\n \"withdrawRequestedAt\": 0,\n \"refundNonce\": \"0\"\n }\n }\n}\n```\n", "headers": { "PAYMENT-RESPONSE": { "description": "Base64-encoded UTF-8 JSON matching PaymentResponse. Present on successful payments and settlement failures.\nLet the SDK validate successful receipts before updating local state; never blindly persist the reported cumulative total.\nA failed receipt has success: false and errorReason; reconcile pending or uncertain outcomes before retrying.\nAn empty transaction is normal for a voucher or a reused deposit; it does not indicate that payment failed.\n", "schema": { "type": "string", "format": "byte" }, "x-decoded-schema": { "type": "object", "description": "Decoded settlement result from PAYMENT-RESPONSE. A failed result can still correspond to a submitted deposit or recorded charge.", "required": [ "success", "transaction", "network" ], "properties": { "success": { "type": "boolean" }, "transaction": { "type": "string", "description": "Deposit transaction hash when available, including unresolved deposits; can be empty for a voucher or reused funding.", "example": "" }, "network": { "type": "string", "example": "eip155:8453" }, "payer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "string", "pattern": "^(\\d+)?$", "description": "Settlement amount in atomic units; empty for a voucher and zero for reused funding. This is not the quote charge; use extra.chargedAmount." }, "errorReason": { "type": "string", "description": "Open set of settlement failures. transaction_pending requires checking the original transaction. batch_accounting_unavailable and settlement-stage batch_unavailable require reconciling any recorded charge before retrying." }, "errorMessage": { "type": "string" }, "extra": { "type": "object", "additionalProperties": true, "properties": { "chargedAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Request charge on a successful receipt; absent means zero. Must not exceed the selected request amount. Add it to the previous local total and validate any reported cumulative total before persisting." }, "depositReused": { "type": "boolean", "description": "True when an already-funded channel was reused instead of broadcasting another deposit." }, "channelState": { "type": "object", "description": "Channel accounting observations. Ordinary receipts must agree with locally calculated charges; corrective recovery requires validating the attached signed voucher proof. Fields may be partial.", "properties": { "channelId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "balance": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Deposits minus withdrawals/refunds; includes amounts already counted in totalClaimed. balance minus totalClaimed is the remaining unclaimed escrow." }, "totalClaimed": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Collected on-chain so far. May lag accepted charges while collection is uneconomic, including at withdrawal eligibility." }, "chargedCumulativeAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "On a successful ordinary receipt, must equal previous local total plus validated extra.chargedAmount. Leave local state unchanged on mismatch. Recorded charges can exceed the remaining balance after withdrawal; do not treat the difference as withdrawable funds." }, "withdrawRequestedAt": { "type": "integer", "minimum": 0, "description": "Unix time in seconds; zero if no withdrawal is pending." }, "refundNonce": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } }, "additionalProperties": true } } } } }, "examples": { "voucher": { "summary": "Illustrative successful voucher receipt", "description": "Illustrative encoded receipt; see the decoded response examples. Values are not deployment terms or live transactions.", "value": "eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IiIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MyIsInBheWVyIjoiMHgwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAxIiwiYW1vdW50IjoiIiwiZXh0cmEiOnsiY2hhcmdlZEFtb3VudCI6IjMiLCJjaGFubmVsU3RhdGUiOnsiY2hhbm5lbElkIjoiMHgxMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExIiwiYmFsYW5jZSI6IjEwMCIsInRvdGFsQ2xhaW1lZCI6IjAiLCJjaGFyZ2VkQ3VtdWxhdGl2ZUFtb3VudCI6IjMiLCJ3aXRoZHJhd1JlcXVlc3RlZEF0IjowLCJyZWZ1bmROb25jZSI6IjAifX19" }, "pendingDeposit": { "summary": "Illustrative pending deposit; preserve the hash and check its outcome", "description": "Illustrative encoded receipt; see the decoded response examples. Values are not deployment terms or live transactions.", "value": "eyJzdWNjZXNzIjpmYWxzZSwiZXJyb3JSZWFzb24iOiJ0cmFuc2FjdGlvbl9wZW5kaW5nIiwidHJhbnNhY3Rpb24iOiIweDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIiLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMiLCJwYXllciI6IjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMSJ9" }, "accountingFailure": { "summary": "Illustrative accounting failure; a charge may already be recorded", "description": "Illustrative encoded receipt; see the decoded response examples. Values are not deployment terms or live transactions.", "value": "eyJzdWNjZXNzIjpmYWxzZSwiZXJyb3JSZWFzb24iOiJiYXRjaF9hY2NvdW50aW5nX3VuYXZhaWxhYmxlIiwidHJhbnNhY3Rpb24iOiIiLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMiLCJwYXllciI6IjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMSJ9" } } }, "Cache-Control": { "description": "Quotes and payment challenges must not be cached.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "description": "An order quoted by the backend that can be directly signed and\nsubmitted to the order creation backend.\n", "type": "object", "properties": { "quote": { "description": "The quoted order parameters. These values can be used directly to create and sign an order.\n", "allOf": [ { "description": "Order parameters.", "type": "object", "properties": { "sellToken": { "description": "ERC-20 token to be sold.", "allOf": [ { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" } ] }, "buyToken": { "description": "ERC-20 token to be bought.", "allOf": [ { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" } ] }, "receiver": { "description": "An optional Ethereum address to receive the proceeds of the trade instead of the owner (i.e. the order signer).\n", "nullable": true, "type": "string" }, "sellAmount": { "description": "Amount of `sellToken` to be sold in atoms.", "allOf": [ { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" } ] }, "buyAmount": { "description": "Amount of `buyToken` to be bought in atoms.", "allOf": [ { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" } ] }, "validTo": { "description": "Unix timestamp (`uint32`) until which the order is valid.", "type": "integer" }, "appData": { "description": "The app data associated with the order. In quote responses, this can be either the full app data JSON string or the app data hash, depending on what was provided in the quote request.\n", "anyOf": [ { "description": "The string encoding of a JSON object representing some `appData`. The\nformat of the JSON expected in the `appData` field is defined\n[here](https://github.com/cowprotocol/app-data).\n", "type": "string", "example": "{\"version\":\"0.9.0\",\"metadata\":{}}" }, { "description": "32 bytes encoded as hex with `0x` prefix.\nIt's expected to be the hash of the stringified JSON object representing the `appData`.\n", "type": "string", "example": "0x0000000000000000000000000000000000000000000000000000000000000000" } ] }, "appDataHash": { "description": "The hash of the app data. Only present when the full app data is also provided in the `appData` field.\n", "allOf": [ { "description": "32 bytes encoded as hex with `0x` prefix.\nIt's expected to be the hash of the stringified JSON object representing the `appData`.\n", "type": "string", "example": "0x0000000000000000000000000000000000000000000000000000000000000000" } ] }, "feeAmount": { "description": "The fee amount in sell token atoms. For quote responses, this represents\nthe estimated network fee, calculated as:\n`feeAmount = ceil((gasAmount * gasPrice) / sellTokenPrice)`.\n\nWhen creating an order, this should be set to zero as fees are now\ncomputed dynamically by solvers.\n", "allOf": [ { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" } ] }, "gasAmount": { "description": "The estimated gas units required to execute the quoted trade.\n", "type": "string", "example": "150000" }, "gasPrice": { "description": "The estimated gas price at the time of quoting, measured in Wei per gas unit.\n", "type": "string", "example": "15000000000" }, "sellTokenPrice": { "description": "Represents how much one atomic unit of the sell token is worth\nin the network's native token (in Wei or the equivalent atom).\n", "type": "string", "example": "0.0004" }, "kind": { "description": "The kind is either a buy or sell order.", "allOf": [ { "description": "Is this order a buy or sell?", "type": "string", "enum": [ "buy", "sell" ] } ] }, "partiallyFillable": { "description": "Is the order fill-or-kill or partially fillable?", "type": "boolean" }, "sellTokenBalance": { "deprecated": true, "description": "Where the sell token should be drawn from. Defaults to `erc20` for standard ERC-20 token transfers.\n", "allOf": [ { "description": "Where should the `sellToken` be drawn from?\n\n**Only `erc20` is accepted for new orders.** The `internal` and `external`\n(Balancer Vault) sources are deprecated: orders using them are rejected at\ncreation with `UnsupportedSellTokenSource`. The values remain in the enum\nbecause they may still appear on historical orders returned by the API.", "type": "string", "enum": [ "erc20", "internal", "external" ] } ], "default": "erc20" }, "buyTokenBalance": { "deprecated": true, "description": "Where the buy token should be transferred to. Defaults to `erc20` for standard ERC-20 token transfers.\n", "allOf": [ { "description": "Where should the `buyToken` be transferred to?\n\n**Only `erc20` is accepted for new orders.** The `internal` (Balancer Vault)\ndestination is rejected at creation with `UnsupportedBuyTokenDestination`.\nThe value remains in the enum because it may still appear on historical\norders returned by the API.", "type": "string", "enum": [ "erc20", "internal" ] } ], "default": "erc20" }, "signingScheme": { "description": "The signing scheme to use for the order. Defaults to `eip712` for standard typed data signing.\n", "allOf": [ { "description": "How was the order signed?", "type": "string", "enum": [ "eip712", "ethsign", "presign", "eip1271" ] } ], "default": "eip712" } }, "required": [ "sellToken", "buyToken", "sellAmount", "buyAmount", "validTo", "appData", "feeAmount", "gasAmount", "gasPrice", "sellTokenPrice", "kind", "partiallyFillable" ] } ] }, "from": { "description": "The address of the trader for whom the quote was requested.\n", "allOf": [ { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" } ] }, "expiration": { "description": "Expiration date of the offered fee. Order service might not accept\nthe fee after this expiration date. Encoded as ISO 8601 UTC.\n", "type": "string", "example": "1985-03-10T18:35:18.814523Z" }, "id": { "description": "Quote ID linked to a quote to enable providing more metadata when analysing order slippage.\n", "type": "integer" }, "verified": { "description": "Whether it was possible to verify that the quoted amounts are accurate using a simulation.\n", "type": "boolean" }, "protocolFeeBps": { "description": "Protocol fee in basis points (e.g., \"2\" for 0.02%). This represents the volume-based fee policy. Only present when a volume fee is configured.\n", "type": "string", "example": "2" } }, "required": [ "quote", "expiration", "verified" ] }, "examples": { "mainnetSell": { "summary": "Illustrative quote only; amounts, fees and expiry come from the live response", "value": { "quote": { "sellToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", "buyToken": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "receiver": "0x0000000000000000000000000000000000000001", "sellAmount": "99900000000000000", "buyAmount": "299700000", "validTo": 1800000000, "appData": "0x0000000000000000000000000000000000000000000000000000000000000000", "feeAmount": "100000000000000", "gasAmount": "100000", "gasPrice": "1000000000", "sellTokenPrice": "1", "kind": "sell", "partiallyFillable": false }, "from": "0x0000000000000000000000000000000000000001", "expiration": "2027-01-15T08:00:00Z", "id": 12345, "verified": true } } } } } }, "400": { "description": "Malformed JSON, noncanonical path or an orderbook quote-validation error.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, { "description": "Error quoting an order.\n\nPossible `errorType` values per HTTP status:\n* 400: `AppDataHashMismatch`, `ExcessiveValidTo`,\n `InsufficientLiquidity`, `InsufficientValidTo`, `InvalidAppData`,\n `InvalidNativeSellToken`, `QuoteNotVerified`, `SameBuyAndSellToken`,\n `SellAmountDoesNotCoverFee`, `TokenTemporarilySuspended`,\n `TradingOutsideAllowedWindow`, `UnsupportedBuyTokenDestination`,\n `UnsupportedOrderType`, `UnsupportedSellTokenSource`,\n `UnsupportedToken`\n* 403: `Forbidden`\n* 404: `NoLiquidity`\n* 500: `InternalServerError`\n", "type": "object", "properties": { "errorType": { "type": "string", "enum": [ "AppDataHashMismatch", "CustomSolverError", "ExcessiveValidTo", "Forbidden", "InsufficientLiquidity", "InsufficientValidTo", "InternalServerError", "InvalidAppData", "InvalidNativeSellToken", "NoLiquidity", "QuoteNotVerified", "SameBuyAndSellToken", "SellAmountDoesNotCoverFee", "TokenTemporarilySuspended", "TradingOutsideAllowedWindow", "UnsupportedBuyTokenDestination", "UnsupportedOrderType", "UnsupportedSellTokenSource", "UnsupportedToken" ] }, "description": { "type": "string" }, "data": { "type": "object", "description": "Optional error-specific payload: `SellAmountDoesNotCoverFee` returns an object with `fee_amount`." } }, "required": [ "errorType", "description" ] } ] }, "example": { "error": "invalid_json" } } } }, "402": { "description": "Payment is missing, invalid, unavailable or could not be settled.\nMissing-payment and verification responses normally include PAYMENT-REQUIRED with the challenge and any error.\nSettlement failures normally include a failed PAYMENT-RESPONSE, body {}, and no PAYMENT-REQUIRED.\nunsupported_payment_scheme is a body-only rejection. An undecodable payment header receives a fresh challenge.\nAdmission denials such as request_budget_exhausted and deposit_budget_exhausted also use 402, not 429.\ntransaction_pending requires checking the original deposit hash. batch_accounting_unavailable or settlement-stage\nbatch_unavailable can leave a recorded charge; reconcile before retrying. HTTP status alone does not establish no charge.\nThe following are decoded PAYMENT-RESPONSE examples, not response bodies or live transactions.\nTheir encoded header values are also included in the downloadable OpenAPI document.\n\n**Pending deposit:**\n\n```json\n{\n \"success\": false,\n \"errorReason\": \"transaction_pending\",\n \"transaction\": \"0x2222222222222222222222222222222222222222222222222222222222222222\",\n \"network\": \"eip155:8453\",\n \"payer\": \"0x0000000000000000000000000000000000000001\"\n}\n```\n\n**Uncertain accounting outcome:**\n\n```json\n{\n \"success\": false,\n \"errorReason\": \"batch_accounting_unavailable\",\n \"transaction\": \"\",\n \"network\": \"eip155:8453\",\n \"payer\": \"0x0000000000000000000000000000000000000001\"\n}\n```\n", "headers": { "PAYMENT-REQUIRED": { "description": "Base64-encoded UTF-8 JSON matching PaymentRequired on a challenge or verification rejection. Settlement failures may omit this header; also inspect PAYMENT-RESPONSE.", "schema": { "type": "string", "format": "byte" }, "x-decoded-schema": { "type": "object", "required": [ "x402Version", "resource", "accepts" ], "properties": { "x402Version": { "type": "integer", "enum": [ 2 ] }, "resource": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "mimeType": { "type": "string", "example": "application/json" } } }, "accepts": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds", "extra" ], "properties": { "scheme": { "type": "string", "enum": [ "batch-settlement" ] }, "network": { "type": "string", "pattern": "^eip155:[0-9]+$", "description": "Payment chain identifier, independent of the quote URL.", "example": "eip155:8453" }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "payTo": { "allOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } ], "description": "Receiver advertised by this deployment. Always use the live challenge; do not hardcode example addresses." }, "maxTimeoutSeconds": { "type": "integer", "minimum": 1, "description": "Deposit-authorization validity from the current challenge; expiry does not prove a submitted transaction failed." }, "extra": { "type": "object", "required": [ "minDeposit", "receiverAuthorizer", "withdrawDelay" ], "additionalProperties": true, "properties": { "minDeposit": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Minimum initial deposit and top-up as a plain atomic integer string. SDK 2.26.0 targets this hint, but its spend cap can clip the deposit below the minimum; check your budget and cap before signing." }, "receiverAuthorizer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "withdrawDelay": { "type": "integer", "minimum": 0, "description": "New-channel delay in seconds. Save it in the channel configuration; later advertisements cannot change an existing channel." }, "name": { "type": "string", "description": "Token EIP-712 domain name when required." }, "version": { "type": "string", "description": "Token EIP-712 domain version when required." }, "assetTransferMethod": { "type": "string", "description": "Permit2 is indicated by permit2; an omitted value uses the scheme default.", "example": "permit2" }, "channelState": { "type": "object", "description": "Channel accounting observations. Ordinary receipts must agree with locally calculated charges; corrective recovery requires validating the attached signed voucher proof. Fields may be partial.", "properties": { "channelId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "balance": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Deposits minus withdrawals/refunds; includes amounts already counted in totalClaimed. balance minus totalClaimed is the remaining unclaimed escrow." }, "totalClaimed": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Collected on-chain so far. May lag accepted charges while collection is uneconomic, including at withdrawal eligibility." }, "chargedCumulativeAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "On a successful ordinary receipt, must equal previous local total plus validated extra.chargedAmount. Leave local state unchanged on mismatch. Recorded charges can exceed the remaining balance after withdrawal; do not treat the difference as withdrawable funds." }, "withdrawRequestedAt": { "type": "integer", "minimum": 0, "description": "Unix time in seconds; zero if no withdrawal is pending." }, "refundNonce": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } }, "additionalProperties": true } } } } } }, "error": { "type": "string", "nullable": true, "description": "Open set of rejection reasons. Common examples: deposit_below_minimum, batch_withdrawal_pending,\nsettlement_unhealthy, batch_unavailable, request_budget_exhausted, deposit_budget_exhausted,\ninvalid_batch_settlement_evm_permit2_allowance_required,\nand invalid_batch_settlement_evm_cumulative_exceeds_balance.\n" }, "extensions": { "type": "object", "additionalProperties": true } } } }, "PAYMENT-RESPONSE": { "description": "Base64-encoded UTF-8 JSON matching PaymentResponse. Present on successful payments and settlement failures.\nLet the SDK validate successful receipts before updating local state; never blindly persist the reported cumulative total.\nA failed receipt has success: false and errorReason; reconcile pending or uncertain outcomes before retrying.\nAn empty transaction is normal for a voucher or a reused deposit; it does not indicate that payment failed.\n", "schema": { "type": "string", "format": "byte" }, "x-decoded-schema": { "type": "object", "description": "Decoded settlement result from PAYMENT-RESPONSE. A failed result can still correspond to a submitted deposit or recorded charge.", "required": [ "success", "transaction", "network" ], "properties": { "success": { "type": "boolean" }, "transaction": { "type": "string", "description": "Deposit transaction hash when available, including unresolved deposits; can be empty for a voucher or reused funding.", "example": "" }, "network": { "type": "string", "example": "eip155:8453" }, "payer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "string", "pattern": "^(\\d+)?$", "description": "Settlement amount in atomic units; empty for a voucher and zero for reused funding. This is not the quote charge; use extra.chargedAmount." }, "errorReason": { "type": "string", "description": "Open set of settlement failures. transaction_pending requires checking the original transaction. batch_accounting_unavailable and settlement-stage batch_unavailable require reconciling any recorded charge before retrying." }, "errorMessage": { "type": "string" }, "extra": { "type": "object", "additionalProperties": true, "properties": { "chargedAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Request charge on a successful receipt; absent means zero. Must not exceed the selected request amount. Add it to the previous local total and validate any reported cumulative total before persisting." }, "depositReused": { "type": "boolean", "description": "True when an already-funded channel was reused instead of broadcasting another deposit." }, "channelState": { "type": "object", "description": "Channel accounting observations. Ordinary receipts must agree with locally calculated charges; corrective recovery requires validating the attached signed voucher proof. Fields may be partial.", "properties": { "channelId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "balance": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Deposits minus withdrawals/refunds; includes amounts already counted in totalClaimed. balance minus totalClaimed is the remaining unclaimed escrow." }, "totalClaimed": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Collected on-chain so far. May lag accepted charges while collection is uneconomic, including at withdrawal eligibility." }, "chargedCumulativeAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "On a successful ordinary receipt, must equal previous local total plus validated extra.chargedAmount. Leave local state unchanged on mismatch. Recorded charges can exceed the remaining balance after withdrawal; do not treat the difference as withdrawable funds." }, "withdrawRequestedAt": { "type": "integer", "minimum": 0, "description": "Unix time in seconds; zero if no withdrawal is pending." }, "refundNonce": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } }, "additionalProperties": true } } } } }, "examples": { "voucher": { "summary": "Illustrative successful voucher receipt", "description": "Illustrative encoded receipt; see the decoded response examples. Values are not deployment terms or live transactions.", "value": "eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IiIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MyIsInBheWVyIjoiMHgwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAxIiwiYW1vdW50IjoiIiwiZXh0cmEiOnsiY2hhcmdlZEFtb3VudCI6IjMiLCJjaGFubmVsU3RhdGUiOnsiY2hhbm5lbElkIjoiMHgxMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExIiwiYmFsYW5jZSI6IjEwMCIsInRvdGFsQ2xhaW1lZCI6IjAiLCJjaGFyZ2VkQ3VtdWxhdGl2ZUFtb3VudCI6IjMiLCJ3aXRoZHJhd1JlcXVlc3RlZEF0IjowLCJyZWZ1bmROb25jZSI6IjAifX19" }, "pendingDeposit": { "summary": "Illustrative pending deposit; preserve the hash and check its outcome", "description": "Illustrative encoded receipt; see the decoded response examples. Values are not deployment terms or live transactions.", "value": "eyJzdWNjZXNzIjpmYWxzZSwiZXJyb3JSZWFzb24iOiJ0cmFuc2FjdGlvbl9wZW5kaW5nIiwidHJhbnNhY3Rpb24iOiIweDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIiLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMiLCJwYXllciI6IjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMSJ9" }, "accountingFailure": { "summary": "Illustrative accounting failure; a charge may already be recorded", "description": "Illustrative encoded receipt; see the decoded response examples. Values are not deployment terms or live transactions.", "value": "eyJzdWNjZXNzIjpmYWxzZSwiZXJyb3JSZWFzb24iOiJiYXRjaF9hY2NvdW50aW5nX3VuYXZhaWxhYmxlIiwidHJhbnNhY3Rpb24iOiIiLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMiLCJwYXllciI6IjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMSJ9" } } }, "Retry-After": { "description": "Present for the batch Permit2 allowance error documented above; delay in seconds.", "schema": { "type": "string", "example": "2" } }, "Cache-Control": { "description": "Quotes and payment challenges must not be cached.", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true }, "examples": { "unpaid": { "summary": "Normal unpaid response (challenge is in the header)", "value": {} }, "settlementFailure": { "summary": "Settlement failure (reason and any transaction hash are in PAYMENT-RESPONSE)", "value": {} }, "unsupportedScheme": { "value": { "error": "unsupported_payment_scheme" } }, "allowance": { "value": { "error": "invalid_batch_settlement_evm_permit2_allowance_required", "message": "If sufficient approval is confirmed, wait 2 seconds and retry the same payment before its signature deadline." } } } } } }, "403": { "description": "The orderbook rejected the order owner, or an ingress policy blocked the request.", "content": { "application/json": { "schema": { "description": "Error quoting an order.\n\nPossible `errorType` values per HTTP status:\n* 400: `AppDataHashMismatch`, `ExcessiveValidTo`,\n `InsufficientLiquidity`, `InsufficientValidTo`, `InvalidAppData`,\n `InvalidNativeSellToken`, `QuoteNotVerified`, `SameBuyAndSellToken`,\n `SellAmountDoesNotCoverFee`, `TokenTemporarilySuspended`,\n `TradingOutsideAllowedWindow`, `UnsupportedBuyTokenDestination`,\n `UnsupportedOrderType`, `UnsupportedSellTokenSource`,\n `UnsupportedToken`\n* 403: `Forbidden`\n* 404: `NoLiquidity`\n* 500: `InternalServerError`\n", "type": "object", "properties": { "errorType": { "type": "string", "enum": [ "AppDataHashMismatch", "CustomSolverError", "ExcessiveValidTo", "Forbidden", "InsufficientLiquidity", "InsufficientValidTo", "InternalServerError", "InvalidAppData", "InvalidNativeSellToken", "NoLiquidity", "QuoteNotVerified", "SameBuyAndSellToken", "SellAmountDoesNotCoverFee", "TokenTemporarilySuspended", "TradingOutsideAllowedWindow", "UnsupportedBuyTokenDestination", "UnsupportedOrderType", "UnsupportedSellTokenSource", "UnsupportedToken" ] }, "description": { "type": "string" }, "data": { "type": "object", "description": "Optional error-specific payload: `SellAmountDoesNotCoverFee` returns an object with `fee_amount`." } }, "required": [ "errorType", "description" ] } }, "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "Unknown network/route or no liquidity for the requested trade. Unknown routes may return HTML.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, { "description": "Error quoting an order.\n\nPossible `errorType` values per HTTP status:\n* 400: `AppDataHashMismatch`, `ExcessiveValidTo`,\n `InsufficientLiquidity`, `InsufficientValidTo`, `InvalidAppData`,\n `InvalidNativeSellToken`, `QuoteNotVerified`, `SameBuyAndSellToken`,\n `SellAmountDoesNotCoverFee`, `TokenTemporarilySuspended`,\n `TradingOutsideAllowedWindow`, `UnsupportedBuyTokenDestination`,\n `UnsupportedOrderType`, `UnsupportedSellTokenSource`,\n `UnsupportedToken`\n* 403: `Forbidden`\n* 404: `NoLiquidity`\n* 500: `InternalServerError`\n", "type": "object", "properties": { "errorType": { "type": "string", "enum": [ "AppDataHashMismatch", "CustomSolverError", "ExcessiveValidTo", "Forbidden", "InsufficientLiquidity", "InsufficientValidTo", "InternalServerError", "InvalidAppData", "InvalidNativeSellToken", "NoLiquidity", "QuoteNotVerified", "SameBuyAndSellToken", "SellAmountDoesNotCoverFee", "TokenTemporarilySuspended", "TradingOutsideAllowedWindow", "UnsupportedBuyTokenDestination", "UnsupportedOrderType", "UnsupportedSellTokenSource", "UnsupportedToken" ] }, "description": { "type": "string" }, "data": { "type": "object", "description": "Optional error-specific payload: `SellAmountDoesNotCoverFee` returns an object with `fee_amount`." } }, "required": [ "errorType", "description" ] } ] } }, "text/html": { "schema": { "type": "string" } } } }, "413": { "description": "Request body exceeds 128 KiB. Ingress may return HTML; the application returns entity.too.large.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } }, "text/html": { "schema": { "type": "string" } } } }, "422": { "description": "The orderbook could not interpret the request. Its validation response is forwarded." }, "429": { "description": "Ingress or orderbook rate limit exceeded. Back off; do not create another deposit. Retry-After is not guaranteed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/html": { "schema": { "type": "string" } } } }, "500": { "description": "Unexpected orderbook error.", "content": { "application/json": { "schema": { "description": "Error quoting an order.\n\nPossible `errorType` values per HTTP status:\n* 400: `AppDataHashMismatch`, `ExcessiveValidTo`,\n `InsufficientLiquidity`, `InsufficientValidTo`, `InvalidAppData`,\n `InvalidNativeSellToken`, `QuoteNotVerified`, `SameBuyAndSellToken`,\n `SellAmountDoesNotCoverFee`, `TokenTemporarilySuspended`,\n `TradingOutsideAllowedWindow`, `UnsupportedBuyTokenDestination`,\n `UnsupportedOrderType`, `UnsupportedSellTokenSource`,\n `UnsupportedToken`\n* 403: `Forbidden`\n* 404: `NoLiquidity`\n* 500: `InternalServerError`\n", "type": "object", "properties": { "errorType": { "type": "string", "enum": [ "AppDataHashMismatch", "CustomSolverError", "ExcessiveValidTo", "Forbidden", "InsufficientLiquidity", "InsufficientValidTo", "InternalServerError", "InvalidAppData", "InvalidNativeSellToken", "NoLiquidity", "QuoteNotVerified", "SameBuyAndSellToken", "SellAmountDoesNotCoverFee", "TokenTemporarilySuspended", "TradingOutsideAllowedWindow", "UnsupportedBuyTokenDestination", "UnsupportedOrderType", "UnsupportedSellTokenSource", "UnsupportedToken" ] }, "description": { "type": "string" }, "data": { "type": "object", "description": "Optional error-specific payload: `SellAmountDoesNotCoverFee` returns an object with `fee_amount`." } }, "required": [ "errorType", "description" ] } } } }, "502": { "description": "The proxy could not contact or read the orderbook.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "example": { "error": "upstream_error" } } } }, "503": { "description": "The payment service is unavailable. Back off and recover any ambiguous payment state before retrying.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "example": { "error": "payment_service_unavailable" } } } }, "504": { "description": "The orderbook request timed out.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "example": { "error": "upstream_timeout" } } } } } } } }, "components": { "headers": { "PaymentRequired": { "description": "Base64-encoded UTF-8 JSON matching PaymentRequired on a challenge or verification rejection. Settlement failures may omit this header; also inspect PAYMENT-RESPONSE.", "schema": { "type": "string", "format": "byte" }, "x-decoded-schema": { "type": "object", "required": [ "x402Version", "resource", "accepts" ], "properties": { "x402Version": { "type": "integer", "enum": [ 2 ] }, "resource": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "mimeType": { "type": "string", "example": "application/json" } } }, "accepts": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds", "extra" ], "properties": { "scheme": { "type": "string", "enum": [ "batch-settlement" ] }, "network": { "type": "string", "pattern": "^eip155:[0-9]+$", "description": "Payment chain identifier, independent of the quote URL.", "example": "eip155:8453" }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "payTo": { "allOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } ], "description": "Receiver advertised by this deployment. Always use the live challenge; do not hardcode example addresses." }, "maxTimeoutSeconds": { "type": "integer", "minimum": 1, "description": "Deposit-authorization validity from the current challenge; expiry does not prove a submitted transaction failed." }, "extra": { "type": "object", "required": [ "minDeposit", "receiverAuthorizer", "withdrawDelay" ], "additionalProperties": true, "properties": { "minDeposit": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Minimum initial deposit and top-up as a plain atomic integer string. SDK 2.26.0 targets this hint, but its spend cap can clip the deposit below the minimum; check your budget and cap before signing." }, "receiverAuthorizer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "withdrawDelay": { "type": "integer", "minimum": 0, "description": "New-channel delay in seconds. Save it in the channel configuration; later advertisements cannot change an existing channel." }, "name": { "type": "string", "description": "Token EIP-712 domain name when required." }, "version": { "type": "string", "description": "Token EIP-712 domain version when required." }, "assetTransferMethod": { "type": "string", "description": "Permit2 is indicated by permit2; an omitted value uses the scheme default.", "example": "permit2" }, "channelState": { "type": "object", "description": "Channel accounting observations. Ordinary receipts must agree with locally calculated charges; corrective recovery requires validating the attached signed voucher proof. Fields may be partial.", "properties": { "channelId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "balance": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Deposits minus withdrawals/refunds; includes amounts already counted in totalClaimed. balance minus totalClaimed is the remaining unclaimed escrow." }, "totalClaimed": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Collected on-chain so far. May lag accepted charges while collection is uneconomic, including at withdrawal eligibility." }, "chargedCumulativeAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "On a successful ordinary receipt, must equal previous local total plus validated extra.chargedAmount. Leave local state unchanged on mismatch. Recorded charges can exceed the remaining balance after withdrawal; do not treat the difference as withdrawable funds." }, "withdrawRequestedAt": { "type": "integer", "minimum": 0, "description": "Unix time in seconds; zero if no withdrawal is pending." }, "refundNonce": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } }, "additionalProperties": true } } } } } }, "error": { "type": "string", "nullable": true, "description": "Open set of rejection reasons. Common examples: deposit_below_minimum, batch_withdrawal_pending,\nsettlement_unhealthy, batch_unavailable, request_budget_exhausted, deposit_budget_exhausted,\ninvalid_batch_settlement_evm_permit2_allowance_required,\nand invalid_batch_settlement_evm_cumulative_exceeds_balance.\n" }, "extensions": { "type": "object", "additionalProperties": true } } } }, "PaymentResponse": { "description": "Base64-encoded UTF-8 JSON matching PaymentResponse. Present on successful payments and settlement failures.\nLet the SDK validate successful receipts before updating local state; never blindly persist the reported cumulative total.\nA failed receipt has success: false and errorReason; reconcile pending or uncertain outcomes before retrying.\nAn empty transaction is normal for a voucher or a reused deposit; it does not indicate that payment failed.\n", "schema": { "type": "string", "format": "byte" }, "x-decoded-schema": { "type": "object", "description": "Decoded settlement result from PAYMENT-RESPONSE. A failed result can still correspond to a submitted deposit or recorded charge.", "required": [ "success", "transaction", "network" ], "properties": { "success": { "type": "boolean" }, "transaction": { "type": "string", "description": "Deposit transaction hash when available, including unresolved deposits; can be empty for a voucher or reused funding.", "example": "" }, "network": { "type": "string", "example": "eip155:8453" }, "payer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "string", "pattern": "^(\\d+)?$", "description": "Settlement amount in atomic units; empty for a voucher and zero for reused funding. This is not the quote charge; use extra.chargedAmount." }, "errorReason": { "type": "string", "description": "Open set of settlement failures. transaction_pending requires checking the original transaction. batch_accounting_unavailable and settlement-stage batch_unavailable require reconciling any recorded charge before retrying." }, "errorMessage": { "type": "string" }, "extra": { "type": "object", "additionalProperties": true, "properties": { "chargedAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Request charge on a successful receipt; absent means zero. Must not exceed the selected request amount. Add it to the previous local total and validate any reported cumulative total before persisting." }, "depositReused": { "type": "boolean", "description": "True when an already-funded channel was reused instead of broadcasting another deposit." }, "channelState": { "type": "object", "description": "Channel accounting observations. Ordinary receipts must agree with locally calculated charges; corrective recovery requires validating the attached signed voucher proof. Fields may be partial.", "properties": { "channelId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "balance": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Deposits minus withdrawals/refunds; includes amounts already counted in totalClaimed. balance minus totalClaimed is the remaining unclaimed escrow." }, "totalClaimed": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Collected on-chain so far. May lag accepted charges while collection is uneconomic, including at withdrawal eligibility." }, "chargedCumulativeAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "On a successful ordinary receipt, must equal previous local total plus validated extra.chargedAmount. Leave local state unchanged on mismatch. Recorded charges can exceed the remaining balance after withdrawal; do not treat the difference as withdrawable funds." }, "withdrawRequestedAt": { "type": "integer", "minimum": 0, "description": "Unix time in seconds; zero if no withdrawal is pending." }, "refundNonce": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } }, "additionalProperties": true } } } } }, "examples": { "voucher": { "summary": "Illustrative successful voucher receipt", "description": "Illustrative encoded receipt; see the decoded response examples. Values are not deployment terms or live transactions.", "value": "eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IiIsIm5ldHdvcmsiOiJlaXAxNTU6ODQ1MyIsInBheWVyIjoiMHgwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAxIiwiYW1vdW50IjoiIiwiZXh0cmEiOnsiY2hhcmdlZEFtb3VudCI6IjMiLCJjaGFubmVsU3RhdGUiOnsiY2hhbm5lbElkIjoiMHgxMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExMTExIiwiYmFsYW5jZSI6IjEwMCIsInRvdGFsQ2xhaW1lZCI6IjAiLCJjaGFyZ2VkQ3VtdWxhdGl2ZUFtb3VudCI6IjMiLCJ3aXRoZHJhd1JlcXVlc3RlZEF0IjowLCJyZWZ1bmROb25jZSI6IjAifX19" }, "pendingDeposit": { "summary": "Illustrative pending deposit; preserve the hash and check its outcome", "description": "Illustrative encoded receipt; see the decoded response examples. Values are not deployment terms or live transactions.", "value": "eyJzdWNjZXNzIjpmYWxzZSwiZXJyb3JSZWFzb24iOiJ0cmFuc2FjdGlvbl9wZW5kaW5nIiwidHJhbnNhY3Rpb24iOiIweDIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIiLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMiLCJwYXllciI6IjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMSJ9" }, "accountingFailure": { "summary": "Illustrative accounting failure; a charge may already be recorded", "description": "Illustrative encoded receipt; see the decoded response examples. Values are not deployment terms or live transactions.", "value": "eyJzdWNjZXNzIjpmYWxzZSwiZXJyb3JSZWFzb24iOiJiYXRjaF9hY2NvdW50aW5nX3VuYXZhaWxhYmxlIiwidHJhbnNhY3Rpb24iOiIiLCJuZXR3b3JrIjoiZWlwMTU1Ojg0NTMiLCJwYXllciI6IjB4MDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMSJ9" } } }, "NoStore": { "description": "Quotes and payment challenges must not be cached.", "schema": { "type": "string", "example": "no-store" } }, "AllowanceRetry": { "description": "Present for the batch Permit2 allowance error documented above; delay in seconds.", "schema": { "type": "string", "example": "2" } } }, "schemas": { "OrderQuoteRequest": { "description": "Request fee and price quote.", "allOf": [ { "description": "The buy or sell side when quoting an order.", "oneOf": [ { "type": "object", "description": "Quote a sell order given the final total `sellAmount` including fees.", "properties": { "kind": { "allOf": [ { "type": "string", "enum": [ "sell" ] } ] }, "sellAmountBeforeFee": { "description": "The total amount that is available for the order. From this value, the fee is deducted and the buy amount is calculated.\n", "allOf": [ { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" } ] } }, "required": [ "kind", "sellAmountBeforeFee" ] }, { "type": "object", "description": "Quote a sell order given the `sellAmount`.", "properties": { "kind": { "allOf": [ { "type": "string", "enum": [ "sell" ] } ] }, "sellAmountAfterFee": { "description": "The `sellAmount` for the order.", "allOf": [ { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" } ] } }, "required": [ "kind", "sellAmountAfterFee" ] }, { "type": "object", "description": "Quote a buy order given an exact `buyAmount`.", "properties": { "kind": { "allOf": [ { "type": "string", "enum": [ "buy" ] } ] }, "buyAmountAfterFee": { "description": "The `buyAmount` for the order.", "allOf": [ { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" } ] } }, "required": [ "kind", "buyAmountAfterFee" ] } ] }, { "type": "object", "description": "Optional validity: validTo is a Unix timestamp; validFor is a duration in seconds. Supply at most one non-null value. Omitting both uses the orderbook default.", "properties": { "validTo": { "type": "integer", "minimum": 0, "maximum": 4294967295, "nullable": true }, "validFor": { "type": "integer", "minimum": 0, "maximum": 4294967295, "nullable": true } }, "not": { "required": [ "validTo", "validFor" ], "properties": { "validTo": { "type": "integer" }, "validFor": { "type": "integer" } } } }, { "type": "object", "properties": { "sellToken": { "description": "ERC-20 token to be sold", "allOf": [ { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" } ] }, "buyToken": { "description": "ERC-20 token to be bought", "allOf": [ { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" } ] }, "receiver": { "description": "An optional address to receive the proceeds of the trade instead of the\n`owner` (i.e. the order signer).\n", "nullable": true, "type": "string" }, "appData": { "description": "AppData which will be assigned to the order.\n\nExpects either a string JSON doc as defined on\n[AppData](https://github.com/cowprotocol/app-data) or a hex\nencoded string for backwards compatibility.\n\nWhen the first format is used, it's possible to provide the\nderived appDataHash field.", "anyOf": [ { "description": "The string encoding of a JSON object representing some `appData`. The\nformat of the JSON expected in the `appData` field is defined\n[here](https://github.com/cowprotocol/app-data).\n", "type": "string", "example": "{\"version\":\"0.9.0\",\"metadata\":{}}" }, { "description": "32 bytes encoded as hex with `0x` prefix.\nIt's expected to be the hash of the stringified JSON object representing the `appData`.\n", "type": "string", "example": "0x0000000000000000000000000000000000000000000000000000000000000000" } ] }, "appDataHash": { "description": "The hash of the stringified JSON appData doc.\n\nIf present, `appData` field must be set with the aforementioned\ndata where this hash is derived from.\n\nIn case they differ, the call will fail.", "anyOf": [ { "description": "32 bytes encoded as hex with `0x` prefix.\nIt's expected to be the hash of the stringified JSON object representing the `appData`.\n", "type": "string", "example": "0x0000000000000000000000000000000000000000000000000000000000000000" } ] }, "sellTokenBalance": { "deprecated": true, "allOf": [ { "description": "Where should the `sellToken` be drawn from?\n\n**Only `erc20` is accepted for new orders.** The `internal` and `external`\n(Balancer Vault) sources are deprecated: orders using them are rejected at\ncreation with `UnsupportedSellTokenSource`. The values remain in the enum\nbecause they may still appear on historical orders returned by the API.", "type": "string", "enum": [ "erc20", "internal", "external" ] } ], "default": "erc20" }, "buyTokenBalance": { "deprecated": true, "allOf": [ { "description": "Where should the `buyToken` be transferred to?\n\n**Only `erc20` is accepted for new orders.** The `internal` (Balancer Vault)\ndestination is rejected at creation with `UnsupportedBuyTokenDestination`.\nThe value remains in the enum because it may still appear on historical\norders returned by the API.", "type": "string", "enum": [ "erc20", "internal" ] } ], "default": "erc20" }, "from": { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" }, "priceQuality": { "allOf": [ { "description": "How good should the price estimate be?\n\nFast: The price estimate is chosen among the fastest N price estimates.\nEstimates do not get verified by simulation.\nOptimal: The price estimate is chosen among all price estimates, ranked\npurely by the promised price. Estimates do not get verified by simulation.\nVerified: All price estimates get verified by simulation whenever\npossible and verified estimates are preferred over unverified ones,\neven when an unverified estimate promises a better price. The\nresponse's `verified` flag indicates whether the returned estimate\nwas actually verified.\n\n**NOTE**: Orders are supposed to be created from `verified` or `optimal`\nprice estimates.", "type": "string", "enum": [ "fast", "optimal", "verified" ] } ], "default": "verified" }, "fastPath": { "description": "Signals that this quote is intended for fast-path (out-of-competition) execution. Propagated to the solver. Mutually exclusive with the `appData` `validFrom` field: an order that sets both is rejected.\n", "type": "boolean", "default": false }, "signingScheme": { "allOf": [ { "description": "How was the order signed?", "type": "string", "enum": [ "eip712", "ethsign", "presign", "eip1271" ] } ], "default": "eip712" }, "onchainOrder": { "description": "Flag to signal whether the order is intended for on-chain order placement. Only valid for non ECDSA-signed orders.\"\n", "default": false }, "timeout": { "type": "integer", "description": "User provided timeout in milliseconds. If no value is provided the systems default quote timeout will be used. Values get capped at a generous maximum timeout. Note that reducing the timeout can result in worse quotes because it might be too short for some price estimators.\n" } }, "required": [ "sellToken", "buyToken", "from" ] } ] }, "OrderQuoteResponse": { "description": "An order quoted by the backend that can be directly signed and\nsubmitted to the order creation backend.\n", "type": "object", "properties": { "quote": { "description": "The quoted order parameters. These values can be used directly to create and sign an order.\n", "allOf": [ { "description": "Order parameters.", "type": "object", "properties": { "sellToken": { "description": "ERC-20 token to be sold.", "allOf": [ { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" } ] }, "buyToken": { "description": "ERC-20 token to be bought.", "allOf": [ { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" } ] }, "receiver": { "description": "An optional Ethereum address to receive the proceeds of the trade instead of the owner (i.e. the order signer).\n", "nullable": true, "type": "string" }, "sellAmount": { "description": "Amount of `sellToken` to be sold in atoms.", "allOf": [ { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" } ] }, "buyAmount": { "description": "Amount of `buyToken` to be bought in atoms.", "allOf": [ { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" } ] }, "validTo": { "description": "Unix timestamp (`uint32`) until which the order is valid.", "type": "integer" }, "appData": { "description": "The app data associated with the order. In quote responses, this can be either the full app data JSON string or the app data hash, depending on what was provided in the quote request.\n", "anyOf": [ { "description": "The string encoding of a JSON object representing some `appData`. The\nformat of the JSON expected in the `appData` field is defined\n[here](https://github.com/cowprotocol/app-data).\n", "type": "string", "example": "{\"version\":\"0.9.0\",\"metadata\":{}}" }, { "description": "32 bytes encoded as hex with `0x` prefix.\nIt's expected to be the hash of the stringified JSON object representing the `appData`.\n", "type": "string", "example": "0x0000000000000000000000000000000000000000000000000000000000000000" } ] }, "appDataHash": { "description": "The hash of the app data. Only present when the full app data is also provided in the `appData` field.\n", "allOf": [ { "description": "32 bytes encoded as hex with `0x` prefix.\nIt's expected to be the hash of the stringified JSON object representing the `appData`.\n", "type": "string", "example": "0x0000000000000000000000000000000000000000000000000000000000000000" } ] }, "feeAmount": { "description": "The fee amount in sell token atoms. For quote responses, this represents\nthe estimated network fee, calculated as:\n`feeAmount = ceil((gasAmount * gasPrice) / sellTokenPrice)`.\n\nWhen creating an order, this should be set to zero as fees are now\ncomputed dynamically by solvers.\n", "allOf": [ { "description": "Amount of a token. `uint256` encoded in decimal.", "type": "string", "example": "1234567890" } ] }, "gasAmount": { "description": "The estimated gas units required to execute the quoted trade.\n", "type": "string", "example": "150000" }, "gasPrice": { "description": "The estimated gas price at the time of quoting, measured in Wei per gas unit.\n", "type": "string", "example": "15000000000" }, "sellTokenPrice": { "description": "Represents how much one atomic unit of the sell token is worth\nin the network's native token (in Wei or the equivalent atom).\n", "type": "string", "example": "0.0004" }, "kind": { "description": "The kind is either a buy or sell order.", "allOf": [ { "description": "Is this order a buy or sell?", "type": "string", "enum": [ "buy", "sell" ] } ] }, "partiallyFillable": { "description": "Is the order fill-or-kill or partially fillable?", "type": "boolean" }, "sellTokenBalance": { "deprecated": true, "description": "Where the sell token should be drawn from. Defaults to `erc20` for standard ERC-20 token transfers.\n", "allOf": [ { "description": "Where should the `sellToken` be drawn from?\n\n**Only `erc20` is accepted for new orders.** The `internal` and `external`\n(Balancer Vault) sources are deprecated: orders using them are rejected at\ncreation with `UnsupportedSellTokenSource`. The values remain in the enum\nbecause they may still appear on historical orders returned by the API.", "type": "string", "enum": [ "erc20", "internal", "external" ] } ], "default": "erc20" }, "buyTokenBalance": { "deprecated": true, "description": "Where the buy token should be transferred to. Defaults to `erc20` for standard ERC-20 token transfers.\n", "allOf": [ { "description": "Where should the `buyToken` be transferred to?\n\n**Only `erc20` is accepted for new orders.** The `internal` (Balancer Vault)\ndestination is rejected at creation with `UnsupportedBuyTokenDestination`.\nThe value remains in the enum because it may still appear on historical\norders returned by the API.", "type": "string", "enum": [ "erc20", "internal" ] } ], "default": "erc20" }, "signingScheme": { "description": "The signing scheme to use for the order. Defaults to `eip712` for standard typed data signing.\n", "allOf": [ { "description": "How was the order signed?", "type": "string", "enum": [ "eip712", "ethsign", "presign", "eip1271" ] } ], "default": "eip712" } }, "required": [ "sellToken", "buyToken", "sellAmount", "buyAmount", "validTo", "appData", "feeAmount", "gasAmount", "gasPrice", "sellTokenPrice", "kind", "partiallyFillable" ] } ] }, "from": { "description": "The address of the trader for whom the quote was requested.\n", "allOf": [ { "description": "20 byte Ethereum address encoded as a hex with `0x` prefix.", "type": "string", "example": "0x6810e776880c02933d47db1b9fc05908e5386b96" } ] }, "expiration": { "description": "Expiration date of the offered fee. Order service might not accept\nthe fee after this expiration date. Encoded as ISO 8601 UTC.\n", "type": "string", "example": "1985-03-10T18:35:18.814523Z" }, "id": { "description": "Quote ID linked to a quote to enable providing more metadata when analysing order slippage.\n", "type": "integer" }, "verified": { "description": "Whether it was possible to verify that the quoted amounts are accurate using a simulation.\n", "type": "boolean" }, "protocolFeeBps": { "description": "Protocol fee in basis points (e.g., \"2\" for 0.02%). This represents the volume-based fee policy. Only present when a volume fee is configured.\n", "type": "string", "example": "2" } }, "required": [ "quote", "expiration", "verified" ] }, "PriceEstimationError": { "description": "Error quoting an order.\n\nPossible `errorType` values per HTTP status:\n* 400: `AppDataHashMismatch`, `ExcessiveValidTo`,\n `InsufficientLiquidity`, `InsufficientValidTo`, `InvalidAppData`,\n `InvalidNativeSellToken`, `QuoteNotVerified`, `SameBuyAndSellToken`,\n `SellAmountDoesNotCoverFee`, `TokenTemporarilySuspended`,\n `TradingOutsideAllowedWindow`, `UnsupportedBuyTokenDestination`,\n `UnsupportedOrderType`, `UnsupportedSellTokenSource`,\n `UnsupportedToken`\n* 403: `Forbidden`\n* 404: `NoLiquidity`\n* 500: `InternalServerError`\n", "type": "object", "properties": { "errorType": { "type": "string", "enum": [ "AppDataHashMismatch", "CustomSolverError", "ExcessiveValidTo", "Forbidden", "InsufficientLiquidity", "InsufficientValidTo", "InternalServerError", "InvalidAppData", "InvalidNativeSellToken", "NoLiquidity", "QuoteNotVerified", "SameBuyAndSellToken", "SellAmountDoesNotCoverFee", "TokenTemporarilySuspended", "TradingOutsideAllowedWindow", "UnsupportedBuyTokenDestination", "UnsupportedOrderType", "UnsupportedSellTokenSource", "UnsupportedToken" ] }, "description": { "type": "string" }, "data": { "type": "object", "description": "Optional error-specific payload: `SellAmountDoesNotCoverFee` returns an object with `fee_amount`." } }, "required": [ "errorType", "description" ] }, "AtomicAmount": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." }, "EvmAddress": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "Resource": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "mimeType": { "type": "string", "example": "application/json" } } }, "PaymentRequirements": { "type": "object", "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds", "extra" ], "properties": { "scheme": { "type": "string", "enum": [ "batch-settlement" ] }, "network": { "type": "string", "pattern": "^eip155:[0-9]+$", "description": "Payment chain identifier, independent of the quote URL.", "example": "eip155:8453" }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "payTo": { "allOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } ], "description": "Receiver advertised by this deployment. Always use the live challenge; do not hardcode example addresses." }, "maxTimeoutSeconds": { "type": "integer", "minimum": 1, "description": "Deposit-authorization validity from the current challenge; expiry does not prove a submitted transaction failed." }, "extra": { "type": "object", "required": [ "minDeposit", "receiverAuthorizer", "withdrawDelay" ], "additionalProperties": true, "properties": { "minDeposit": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Minimum initial deposit and top-up as a plain atomic integer string. SDK 2.26.0 targets this hint, but its spend cap can clip the deposit below the minimum; check your budget and cap before signing." }, "receiverAuthorizer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "withdrawDelay": { "type": "integer", "minimum": 0, "description": "New-channel delay in seconds. Save it in the channel configuration; later advertisements cannot change an existing channel." }, "name": { "type": "string", "description": "Token EIP-712 domain name when required." }, "version": { "type": "string", "description": "Token EIP-712 domain version when required." }, "assetTransferMethod": { "type": "string", "description": "Permit2 is indicated by permit2; an omitted value uses the scheme default.", "example": "permit2" }, "channelState": { "type": "object", "description": "Channel accounting observations. Ordinary receipts must agree with locally calculated charges; corrective recovery requires validating the attached signed voucher proof. Fields may be partial.", "properties": { "channelId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "balance": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Deposits minus withdrawals/refunds; includes amounts already counted in totalClaimed. balance minus totalClaimed is the remaining unclaimed escrow." }, "totalClaimed": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Collected on-chain so far. May lag accepted charges while collection is uneconomic, including at withdrawal eligibility." }, "chargedCumulativeAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "On a successful ordinary receipt, must equal previous local total plus validated extra.chargedAmount. Leave local state unchanged on mismatch. Recorded charges can exceed the remaining balance after withdrawal; do not treat the difference as withdrawable funds." }, "withdrawRequestedAt": { "type": "integer", "minimum": 0, "description": "Unix time in seconds; zero if no withdrawal is pending." }, "refundNonce": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } }, "additionalProperties": true } } } } }, "PaymentRequired": { "type": "object", "required": [ "x402Version", "resource", "accepts" ], "properties": { "x402Version": { "type": "integer", "enum": [ 2 ] }, "resource": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "mimeType": { "type": "string", "example": "application/json" } } }, "accepts": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds", "extra" ], "properties": { "scheme": { "type": "string", "enum": [ "batch-settlement" ] }, "network": { "type": "string", "pattern": "^eip155:[0-9]+$", "description": "Payment chain identifier, independent of the quote URL.", "example": "eip155:8453" }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "payTo": { "allOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } ], "description": "Receiver advertised by this deployment. Always use the live challenge; do not hardcode example addresses." }, "maxTimeoutSeconds": { "type": "integer", "minimum": 1, "description": "Deposit-authorization validity from the current challenge; expiry does not prove a submitted transaction failed." }, "extra": { "type": "object", "required": [ "minDeposit", "receiverAuthorizer", "withdrawDelay" ], "additionalProperties": true, "properties": { "minDeposit": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Minimum initial deposit and top-up as a plain atomic integer string. SDK 2.26.0 targets this hint, but its spend cap can clip the deposit below the minimum; check your budget and cap before signing." }, "receiverAuthorizer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "withdrawDelay": { "type": "integer", "minimum": 0, "description": "New-channel delay in seconds. Save it in the channel configuration; later advertisements cannot change an existing channel." }, "name": { "type": "string", "description": "Token EIP-712 domain name when required." }, "version": { "type": "string", "description": "Token EIP-712 domain version when required." }, "assetTransferMethod": { "type": "string", "description": "Permit2 is indicated by permit2; an omitted value uses the scheme default.", "example": "permit2" }, "channelState": { "type": "object", "description": "Channel accounting observations. Ordinary receipts must agree with locally calculated charges; corrective recovery requires validating the attached signed voucher proof. Fields may be partial.", "properties": { "channelId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "balance": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Deposits minus withdrawals/refunds; includes amounts already counted in totalClaimed. balance minus totalClaimed is the remaining unclaimed escrow." }, "totalClaimed": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Collected on-chain so far. May lag accepted charges while collection is uneconomic, including at withdrawal eligibility." }, "chargedCumulativeAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "On a successful ordinary receipt, must equal previous local total plus validated extra.chargedAmount. Leave local state unchanged on mismatch. Recorded charges can exceed the remaining balance after withdrawal; do not treat the difference as withdrawable funds." }, "withdrawRequestedAt": { "type": "integer", "minimum": 0, "description": "Unix time in seconds; zero if no withdrawal is pending." }, "refundNonce": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } }, "additionalProperties": true } } } } } }, "error": { "type": "string", "nullable": true, "description": "Open set of rejection reasons. Common examples: deposit_below_minimum, batch_withdrawal_pending,\nsettlement_unhealthy, batch_unavailable, request_budget_exhausted, deposit_budget_exhausted,\ninvalid_batch_settlement_evm_permit2_allowance_required,\nand invalid_batch_settlement_evm_cumulative_exceeds_balance.\n" }, "extensions": { "type": "object", "additionalProperties": true } } }, "PaymentPayload": { "type": "object", "description": "The SDK-generated envelope encoded in PAYMENT-SIGNATURE. This is not the quote request body.", "required": [ "x402Version", "accepted", "payload" ], "properties": { "x402Version": { "type": "integer", "enum": [ 2 ] }, "resource": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "mimeType": { "type": "string", "example": "application/json" } } }, "accepted": { "type": "object", "required": [ "scheme", "network", "amount", "asset", "payTo", "maxTimeoutSeconds", "extra" ], "properties": { "scheme": { "type": "string", "enum": [ "batch-settlement" ] }, "network": { "type": "string", "pattern": "^eip155:[0-9]+$", "description": "Payment chain identifier, independent of the quote URL.", "example": "eip155:8453" }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." }, "asset": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "payTo": { "allOf": [ { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" } ], "description": "Receiver advertised by this deployment. Always use the live challenge; do not hardcode example addresses." }, "maxTimeoutSeconds": { "type": "integer", "minimum": 1, "description": "Deposit-authorization validity from the current challenge; expiry does not prove a submitted transaction failed." }, "extra": { "type": "object", "required": [ "minDeposit", "receiverAuthorizer", "withdrawDelay" ], "additionalProperties": true, "properties": { "minDeposit": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Minimum initial deposit and top-up as a plain atomic integer string. SDK 2.26.0 targets this hint, but its spend cap can clip the deposit below the minimum; check your budget and cap before signing." }, "receiverAuthorizer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "withdrawDelay": { "type": "integer", "minimum": 0, "description": "New-channel delay in seconds. Save it in the channel configuration; later advertisements cannot change an existing channel." }, "name": { "type": "string", "description": "Token EIP-712 domain name when required." }, "version": { "type": "string", "description": "Token EIP-712 domain version when required." }, "assetTransferMethod": { "type": "string", "description": "Permit2 is indicated by permit2; an omitted value uses the scheme default.", "example": "permit2" }, "channelState": { "type": "object", "description": "Channel accounting observations. Ordinary receipts must agree with locally calculated charges; corrective recovery requires validating the attached signed voucher proof. Fields may be partial.", "properties": { "channelId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "balance": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Deposits minus withdrawals/refunds; includes amounts already counted in totalClaimed. balance minus totalClaimed is the remaining unclaimed escrow." }, "totalClaimed": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Collected on-chain so far. May lag accepted charges while collection is uneconomic, including at withdrawal eligibility." }, "chargedCumulativeAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "On a successful ordinary receipt, must equal previous local total plus validated extra.chargedAmount. Leave local state unchanged on mismatch. Recorded charges can exceed the remaining balance after withdrawal; do not treat the difference as withdrawable funds." }, "withdrawRequestedAt": { "type": "integer", "minimum": 0, "description": "Unix time in seconds; zero if no withdrawal is pending." }, "refundNonce": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } }, "additionalProperties": true } } } } }, "payload": { "type": "object", "description": "Scheme-specific signed deposit or cumulative voucher, including channelConfig and voucher.\nGenerate and validate this with @x402/evm; token authorization shapes differ between EIP-3009 and Permit2.\nHand-written signatures and channel state are not an integration interface.\n", "additionalProperties": true }, "extensions": { "type": "object", "additionalProperties": true } } }, "PaymentResponse": { "type": "object", "description": "Decoded settlement result from PAYMENT-RESPONSE. A failed result can still correspond to a submitted deposit or recorded charge.", "required": [ "success", "transaction", "network" ], "properties": { "success": { "type": "boolean" }, "transaction": { "type": "string", "description": "Deposit transaction hash when available, including unresolved deposits; can be empty for a voucher or reused funding.", "example": "" }, "network": { "type": "string", "example": "eip155:8453" }, "payer": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$" }, "amount": { "type": "string", "pattern": "^(\\d+)?$", "description": "Settlement amount in atomic units; empty for a voucher and zero for reused funding. This is not the quote charge; use extra.chargedAmount." }, "errorReason": { "type": "string", "description": "Open set of settlement failures. transaction_pending requires checking the original transaction. batch_accounting_unavailable and settlement-stage batch_unavailable require reconciling any recorded charge before retrying." }, "errorMessage": { "type": "string" }, "extra": { "type": "object", "additionalProperties": true, "properties": { "chargedAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Request charge on a successful receipt; absent means zero. Must not exceed the selected request amount. Add it to the previous local total and validate any reported cumulative total before persisting." }, "depositReused": { "type": "boolean", "description": "True when an already-funded channel was reused instead of broadcasting another deposit." }, "channelState": { "type": "object", "description": "Channel accounting observations. Ordinary receipts must agree with locally calculated charges; corrective recovery requires validating the attached signed voucher proof. Fields may be partial.", "properties": { "channelId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "balance": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Deposits minus withdrawals/refunds; includes amounts already counted in totalClaimed. balance minus totalClaimed is the remaining unclaimed escrow." }, "totalClaimed": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Collected on-chain so far. May lag accepted charges while collection is uneconomic, including at withdrawal eligibility." }, "chargedCumulativeAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "On a successful ordinary receipt, must equal previous local total plus validated extra.chargedAmount. Leave local state unchanged on mismatch. Recorded charges can exceed the remaining balance after withdrawal; do not treat the difference as withdrawable funds." }, "withdrawRequestedAt": { "type": "integer", "minimum": 0, "description": "Unix time in seconds; zero if no withdrawal is pending." }, "refundNonce": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } }, "additionalProperties": true } } } } }, "ChannelState": { "type": "object", "description": "Channel accounting observations. Ordinary receipts must agree with locally calculated charges; corrective recovery requires validating the attached signed voucher proof. Fields may be partial.", "properties": { "channelId": { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$" }, "balance": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Deposits minus withdrawals/refunds; includes amounts already counted in totalClaimed. balance minus totalClaimed is the remaining unclaimed escrow." }, "totalClaimed": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "Collected on-chain so far. May lag accepted charges while collection is uneconomic, including at withdrawal eligibility." }, "chargedCumulativeAmount": { "allOf": [ { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } ], "description": "On a successful ordinary receipt, must equal previous local total plus validated extra.chargedAmount. Leave local state unchanged on mismatch. Recorded charges can exceed the remaining balance after withdrawal; do not treat the difference as withdrawable funds." }, "withdrawRequestedAt": { "type": "integer", "minimum": 0, "description": "Unix time in seconds; zero if no withdrawal is pending." }, "refundNonce": { "type": "string", "pattern": "^\\d+$", "description": "Unsigned base-10 integer in token atomic units. Keep it as a string to avoid precision loss." } }, "additionalProperties": true }, "ProxyError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } } } }