{ "openapi": "3.1.0", "info": { "title": "Eco API", "version": "v1", "description": "Reference for the Eco API at https://api.eco.com/v1: quotes, chain and token discovery, gasless funding, intent status, and Circle Gateway fast deposits. Every operation requires an API key except the Circle Gateway operations, which are open." }, "tags": [ { "name": "quotes" }, { "name": "intents" }, { "name": "status" }, { "name": "discovery" }, { "name": "circle-gateway" } ], "paths": { "/v1/quotes": { "post": { "operationId": "quotes.create", "summary": "Request a quote", "tags": [ "quotes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "exact-in", "exact-out", "custom" ], "description": "Which amount is fixed. `exact-in`: `source.amount` is spent and `destination.minAmountOut` is guaranteed. `exact-out`: `destination.amount` arrives and the response's `source.amount` is the required input. `custom`: `source.amount` is spent and the supplied `destination.calls` execute on the destination chain." }, "source": { "type": "object", "properties": { "chainId": { "type": "integer", "exclusiveMinimum": 0 }, "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string", "maxLength": 78, "description": "Base-10 unsigned integer string in smallest units; must be greater than 0" }, "funder": { "description": "Wallet that funds the intent on the source chain. The quote, its intent, and its signature are built for this address. Address on the source chain: `0x\u2026` hex for EVM chains, base58 for Solana.", "type": "string" } }, "required": [ "chainId", "token", "funder" ], "additionalProperties": false }, "destination": { "type": "object", "properties": { "chainId": { "type": "integer", "exclusiveMinimum": 0 }, "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string", "maxLength": 78, "description": "Base-10 unsigned integer string in smallest units; must be greater than 0" }, "recipient": { "description": "Required. Receives the output on the destination chain. Address on the destination chain: `0x\u2026` hex for EVM chains, base58 for Solana.", "type": "string" }, "calls": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "data": { "type": "string" }, "value": { "type": "string", "maxLength": 78 }, "tokenOut": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "gasLimit": { "type": "string", "maxLength": 78 } }, "required": [ "target", "data", "value" ], "additionalProperties": false }, "description": "Destination calls to execute, for `type: custom` only. Each call is `target`, `data`, and a base-unit `value` string; `tokenOut` and `gasLimit` are optional." } }, "required": [ "chainId", "token", "recipient" ], "additionalProperties": false }, "refundRecipient": { "description": "Receives the source funds if the intent is refunded. Defaults to `source.funder`. Address on the source chain.", "type": "string" }, "slippage": { "type": "number", "description": "Decimal fraction of the destination amount: 0.005 = 0.5%. Range 0.0001-1; a percent-style 0.5 would mean 50%.", "minimum": 0.0001, "maximum": 1 }, "dappId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Required. Attribution label for the integration. Does not authenticate and does not change pricing." }, "options": { "type": "object", "properties": { "deadlineSec": { "type": "integer", "exclusiveMinimum": 0, "description": "Requested intent deadline, in seconds from now." }, "allQuotes": { "type": "boolean", "description": "Return every competing quote in `quotes`, ranked best first and each independently signed. Default: winner only, `quotes: null`." } }, "additionalProperties": false } }, "required": [ "type", "source", "destination", "dappId" ], "additionalProperties": false }, "examples": { "exact-in": { "summary": "Exact-in: send 1 USDC from Base, receive USDC on OP Mainnet", "value": { "type": "exact-in", "source": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000", "funder": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" }, "destination": { "chainId": 10, "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "recipient": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8" }, "slippage": 0.005, "dappId": "your-app" } }, "exact-out": { "summary": "Exact-out: receive exactly 25 USDC on Arbitrum, pay USDC from Base", "value": { "type": "exact-out", "source": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "funder": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" }, "destination": { "chainId": 42161, "token": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "amount": "25000000", "recipient": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8" }, "dappId": "your-app" } }, "all-quotes": { "summary": "Exact-in with every competing quote returned", "value": { "type": "exact-in", "source": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000", "funder": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" }, "destination": { "chainId": 10, "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "recipient": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8" }, "slippage": 0.005, "dappId": "your-app", "options": { "allQuotes": true } } } } } } }, "responses": { "200": { "description": "The winning quote. Verify `signature` against the source chain's `quoteSigner`, then fund before `expiresAt`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Quote ID, prefixed `quote:`. Status lookups take the bare UUID." }, "type": { "type": "string", "enum": [ "exact-in", "exact-out", "custom" ], "description": "Echo of the request `type`." }, "source": { "type": "object", "properties": { "chainId": { "type": "integer" }, "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" }, "funder": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "symbol": { "type": [ "string", "null" ] }, "decimals": { "type": [ "integer", "null" ] } }, "required": [ "chainId", "token", "amount", "funder", "symbol", "decimals" ] }, "destination": { "type": "object", "properties": { "chainId": { "type": "integer" }, "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amountOut": { "type": "string", "description": "Expected output amount in base units." }, "minAmountOut": { "type": "string", "description": "Guaranteed minimum output after `slippage`. The recipient receives at least this or the source funds refund." }, "recipient": { "type": [ "string", "null" ], "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "symbol": { "type": [ "string", "null" ] }, "decimals": { "type": [ "integer", "null" ] } }, "required": [ "chainId", "token", "amountOut", "minAmountOut", "recipient", "symbol", "decimals" ] }, "slippage": { "type": "number", "description": "Tolerance actually bound into destination.minAmountOut, as a decimal fraction" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gas", "proving", "protocol", "gateway" ] }, "amount": { "type": "string" }, "token": { "type": "object", "properties": { "chainId": { "type": "integer" }, "address": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "symbol": { "type": [ "string", "null" ] }, "decimals": { "type": [ "integer", "null" ] } }, "required": [ "chainId", "address", "symbol", "decimals" ] }, "estimate": { "type": "boolean" } }, "required": [ "type", "amount", "token", "estimate" ] }, "description": "Fees charged for the whole quote, by `type` (`gas`, `proving`, `protocol`, `gateway`). `estimate: false` means the amount is binding." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "swap", "bridge", "deposit", "transfer" ] }, "provider": { "type": "string" }, "aggregator": { "type": "string" }, "from": { "type": "object", "properties": { "chainId": { "type": "integer" }, "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" } }, "required": [ "chainId", "token", "amount" ] }, "to": { "type": "object", "properties": { "chainId": { "type": "integer" }, "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" } }, "required": [ "chainId", "token", "amount" ] }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gas", "proving", "protocol", "gateway" ] }, "amount": { "type": "string" }, "token": { "type": "object", "properties": { "chainId": { "type": "integer" }, "address": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "symbol": { "type": [ "string", "null" ] }, "decimals": { "type": [ "integer", "null" ] } }, "required": [ "chainId", "address", "symbol", "decimals" ] }, "estimate": { "type": "boolean" } }, "required": [ "type", "amount", "token", "estimate" ] } }, "estimatedDurationSec": { "type": "integer" }, "intents": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "local", "bucket-candidate", "stitched-destination" ], "description": "`local`: same-chain leg. `stitched-destination`: final leg that credits the recipient. `bucket-candidate`: one of several candidate routes." }, "intentHash": { "type": "string" }, "routeHash": { "type": "string" }, "bucketIndex": { "type": "integer" }, "intent": { "type": "object", "properties": { "route": { "type": "object", "properties": { "salt": { "type": "string" }, "deadline": { "type": "integer" }, "source": { "type": "integer" }, "destination": { "type": "integer" }, "portal": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "nativeAmount": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" } }, "required": [ "token", "amount" ] } }, "calls": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "data": { "type": "string" }, "value": { "type": "string" } }, "required": [ "target", "data", "value" ] } } }, "required": [ "salt", "deadline", "source", "destination", "portal", "nativeAmount", "tokens", "calls" ] }, "reward": { "type": "object", "properties": { "deadline": { "type": "integer" }, "creator": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "prover": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "nativeAmount": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" } }, "required": [ "token", "amount" ] } } }, "required": [ "deadline", "creator", "prover", "nativeAmount", "tokens" ] } }, "required": [ "route", "reward" ] } }, "required": [ "role", "intentHash", "intent" ] } } }, "required": [ "type", "provider", "from", "to", "fees", "estimatedDurationSec", "intents" ] }, "description": "Ordered legs of the route. Each step names its `provider` and lists the `intents` it is realized by, with the full decoded intent. A `stitched-destination` intent credits the recipient on a multi-hop route and is the one to track for delivery; `bucket-candidate` entries are alternative routes, not all of which fill." }, "solver": { "type": "object", "properties": { "id": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "name": { "type": "string" } }, "required": [ "id" ], "description": "The solver that will fulfil the intent." }, "intentHash": { "description": "Hash of the primary intent; the handle for `GET /v1/intents/status?intentHash=`. Null when every intent is listed under `steps[].intents`.", "type": [ "string", "null" ] }, "execution": { "description": "Everything needed to fund the quote: the ready-to-send `transaction`, the decoded `intent` (route and reward), and the `vault` the source Portal funds the intent through, which is also the counterparty for gasless submits. Sent as-is.", "type": [ "object", "null" ], "properties": { "transaction": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "evm" }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "data": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "chainId", "to", "data", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "svm" }, "chainId": { "type": "integer" }, "feePayer": { "type": "string" }, "instructions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "pubkey": { "type": "string" }, "isSigner": { "type": "boolean" }, "isWritable": { "type": "boolean" } }, "required": [ "pubkey", "isSigner", "isWritable" ] } }, "data": { "type": "string" } }, "required": [ "programId", "accounts", "data" ] } } }, "required": [ "type", "chainId", "feePayer", "instructions" ] } ] }, "intent": { "type": "object", "properties": { "route": { "type": "object", "properties": { "salt": { "type": "string" }, "deadline": { "type": "integer" }, "source": { "type": "integer" }, "destination": { "type": "integer" }, "portal": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "nativeAmount": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" } }, "required": [ "token", "amount" ] } }, "calls": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "data": { "type": "string" }, "value": { "type": "string" } }, "required": [ "target", "data", "value" ] } } }, "required": [ "salt", "deadline", "source", "destination", "portal", "nativeAmount", "tokens", "calls" ] }, "reward": { "type": "object", "properties": { "deadline": { "type": "integer" }, "creator": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "prover": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "nativeAmount": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" } }, "required": [ "token", "amount" ] } } }, "required": [ "deadline", "creator", "prover", "nativeAmount", "tokens" ] } }, "required": [ "route", "reward" ] }, "vault": { "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron.", "type": [ "string", "null" ] } }, "required": [ "transaction", "intent" ] }, "expiresAt": { "type": "integer", "description": "Quote expiry, Unix seconds. Covered by `signature`. Fund before it passes; afterwards request a new quote." }, "signature": { "type": "string", "description": "EIP-712 signature by the source chain's `quoteSigner` (see `GET /v1/chains`) over `Quote(string id, bytes32[] intentHashes, uint64 expiresAt)` with domain `{ name: \"EcoQuoteV1\", version: \"1\", chainId: source.chainId }`. `intentHashes` is `intentHash` plus every `steps[].intents[].intentHash`, lowercased, de-duplicated, sorted ascending." }, "quotes": { "description": "Every competing quote, ranked best first, when `options.allQuotes` is true; each entry is independently signed. Null otherwise. The top-level object is always the winner.", "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "exact-in", "exact-out", "custom" ] }, "source": { "type": "object", "properties": { "chainId": { "type": "integer" }, "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" }, "funder": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "symbol": { "type": [ "string", "null" ] }, "decimals": { "type": [ "integer", "null" ] } }, "required": [ "chainId", "token", "amount", "funder", "symbol", "decimals" ] }, "destination": { "type": "object", "properties": { "chainId": { "type": "integer" }, "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amountOut": { "type": "string" }, "minAmountOut": { "type": "string" }, "recipient": { "type": [ "string", "null" ], "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "symbol": { "type": [ "string", "null" ] }, "decimals": { "type": [ "integer", "null" ] } }, "required": [ "chainId", "token", "amountOut", "minAmountOut", "recipient", "symbol", "decimals" ] }, "slippage": { "type": "number", "description": "Tolerance actually bound into destination.minAmountOut, as a decimal fraction" }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gas", "proving", "protocol", "gateway" ] }, "amount": { "type": "string" }, "token": { "type": "object", "properties": { "chainId": { "type": "integer" }, "address": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "symbol": { "type": [ "string", "null" ] }, "decimals": { "type": [ "integer", "null" ] } }, "required": [ "chainId", "address", "symbol", "decimals" ] }, "estimate": { "type": "boolean" } }, "required": [ "type", "amount", "token", "estimate" ] } }, "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "swap", "bridge", "deposit", "transfer" ] }, "provider": { "type": "string" }, "aggregator": { "type": "string" }, "from": { "type": "object", "properties": { "chainId": { "type": "integer" }, "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" } }, "required": [ "chainId", "token", "amount" ] }, "to": { "type": "object", "properties": { "chainId": { "type": "integer" }, "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" } }, "required": [ "chainId", "token", "amount" ] }, "fees": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "gas", "proving", "protocol", "gateway" ] }, "amount": { "type": "string" }, "token": { "type": "object", "properties": { "chainId": { "type": "integer" }, "address": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "symbol": { "type": [ "string", "null" ] }, "decimals": { "type": [ "integer", "null" ] } }, "required": [ "chainId", "address", "symbol", "decimals" ] }, "estimate": { "type": "boolean" } }, "required": [ "type", "amount", "token", "estimate" ] } }, "estimatedDurationSec": { "type": "integer" }, "intents": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "local", "bucket-candidate", "stitched-destination" ] }, "intentHash": { "type": "string" }, "routeHash": { "type": "string" }, "bucketIndex": { "type": "integer" }, "intent": { "type": "object", "properties": { "route": { "type": "object", "properties": { "salt": { "type": "string" }, "deadline": { "type": "integer" }, "source": { "type": "integer" }, "destination": { "type": "integer" }, "portal": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "nativeAmount": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" } }, "required": [ "token", "amount" ] } }, "calls": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "data": { "type": "string" }, "value": { "type": "string" } }, "required": [ "target", "data", "value" ] } } }, "required": [ "salt", "deadline", "source", "destination", "portal", "nativeAmount", "tokens", "calls" ] }, "reward": { "type": "object", "properties": { "deadline": { "type": "integer" }, "creator": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "prover": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "nativeAmount": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" } }, "required": [ "token", "amount" ] } } }, "required": [ "deadline", "creator", "prover", "nativeAmount", "tokens" ] } }, "required": [ "route", "reward" ] } }, "required": [ "role", "intentHash", "intent" ] } } }, "required": [ "type", "provider", "from", "to", "fees", "estimatedDurationSec", "intents" ] } }, "solver": { "type": "object", "properties": { "id": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "name": { "type": "string" } }, "required": [ "id" ] }, "intentHash": { "type": [ "string", "null" ] }, "execution": { "type": [ "object", "null" ], "properties": { "transaction": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "evm" }, "chainId": { "type": "integer" }, "to": { "type": "string" }, "data": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "chainId", "to", "data", "value" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "svm" }, "chainId": { "type": "integer" }, "feePayer": { "type": "string" }, "instructions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "pubkey": { "type": "string" }, "isSigner": { "type": "boolean" }, "isWritable": { "type": "boolean" } }, "required": [ "pubkey", "isSigner", "isWritable" ] } }, "data": { "type": "string" } }, "required": [ "programId", "accounts", "data" ] } } }, "required": [ "type", "chainId", "feePayer", "instructions" ] } ] }, "intent": { "type": "object", "properties": { "route": { "type": "object", "properties": { "salt": { "type": "string" }, "deadline": { "type": "integer" }, "source": { "type": "integer" }, "destination": { "type": "integer" }, "portal": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "nativeAmount": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" } }, "required": [ "token", "amount" ] } }, "calls": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "data": { "type": "string" }, "value": { "type": "string" } }, "required": [ "target", "data", "value" ] } } }, "required": [ "salt", "deadline", "source", "destination", "portal", "nativeAmount", "tokens", "calls" ] }, "reward": { "type": "object", "properties": { "deadline": { "type": "integer" }, "creator": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "prover": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "nativeAmount": { "type": "string" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "amount": { "type": "string" } }, "required": [ "token", "amount" ] } } }, "required": [ "deadline", "creator", "prover", "nativeAmount", "tokens" ] } }, "required": [ "route", "reward" ] }, "vault": { "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron.", "type": [ "string", "null" ] } }, "required": [ "transaction", "intent" ] }, "expiresAt": { "type": "integer" }, "signature": { "type": "string" } }, "required": [ "id", "type", "source", "destination", "slippage", "fees", "steps", "solver", "intentHash", "execution", "expiresAt", "signature" ] } } }, "required": [ "id", "type", "source", "destination", "slippage", "fees", "steps", "solver", "intentHash", "execution", "expiresAt", "signature", "quotes" ] }, "examples": { "exact-in": { "summary": "Live 0.9.0 response shape (Base USDC to OP Mainnet USDC). Calldata trimmed; the real value is ~2 KB.", "value": { "id": "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23", "type": "exact-in", "source": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000", "funder": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "symbol": null, "decimals": null }, "destination": { "chainId": 10, "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amountOut": "989500", "minAmountOut": "989500", "recipient": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", "symbol": null, "decimals": null }, "slippage": 0.005, "fees": [ { "type": "protocol", "amount": "10500", "token": { "chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "symbol": "USDC", "decimals": 6 }, "estimate": false } ], "steps": [ { "type": "bridge", "provider": "eco", "from": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" }, "to": { "chainId": 10, "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "989500" }, "fees": [], "estimatedDurationSec": 7, "intents": [ { "role": "local", "intentHash": "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749", "intent": { "route": { "salt": "0xec00ec00ec00ec00ec00ec00ec00ec00aaaf8940ec75ab106feed1a7498e986f", "deadline": 1789523774, "source": 8453, "destination": 10, "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "nativeAmount": "0", "tokens": [ { "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "989500" } ], "calls": [ { "target": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "data": "0xa9059cbb00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c800000000000000000000000000000000000000000000000000000000000f193c", "value": "0" } ] }, "reward": { "deadline": 1789524404, "creator": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "prover": "0xec004Ab4870c4e177c66949329dCdb503CE41022", "nativeAmount": "0", "tokens": [ { "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" } ] } } } ] } ], "solver": { "id": "0x1Da38A31F369343bdD33cCc48E89D165E8ab3450" }, "intentHash": "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749", "execution": { "transaction": { "type": "evm", "chainId": 8453, "to": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "data": "0xdf00f8fa000000000000000000000000000000000000000000000000000000000000000a\u2026", "value": "0" }, "intent": { "route": { "salt": "0xec00ec00ec00ec00ec00ec00ec00ec00aaaf8940ec75ab106feed1a7498e986f", "deadline": 1789523774, "source": 8453, "destination": 10, "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "nativeAmount": "0", "tokens": [ { "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "989500" } ], "calls": [ { "target": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "data": "0xa9059cbb00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c800000000000000000000000000000000000000000000000000000000000f193c", "value": "0" } ] }, "reward": { "deadline": 1789524404, "creator": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "prover": "0xec004Ab4870c4e177c66949329dCdb503CE41022", "nativeAmount": "0", "tokens": [ { "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" } ] } }, "vault": "0xf6358b8f1d0Ec04EBc9Fe8FdEe5e6791640D1c2F" }, "expiresAt": 1789522904, "signature": "0xedc90fdd27654dd49ac1087901450c9c5fdf444943f61faa8d787bee86304d821f06a5db4a67eddf5cf286014d6ec8bd33c64f9e072045a9f3c5e50cc28960fc1b", "quotes": null } }, "all-quotes": { "summary": "With options.allQuotes: the winner at the top level and every candidate, each signed, in quotes[]", "value": { "id": "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23", "type": "exact-in", "source": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000", "funder": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "symbol": null, "decimals": null }, "destination": { "chainId": 10, "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amountOut": "989500", "minAmountOut": "989500", "recipient": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", "symbol": null, "decimals": null }, "slippage": 0.005, "fees": [ { "type": "protocol", "amount": "10500", "token": { "chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "symbol": "USDC", "decimals": 6 }, "estimate": false } ], "steps": [ { "type": "bridge", "provider": "eco", "from": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" }, "to": { "chainId": 10, "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "989500" }, "fees": [], "estimatedDurationSec": 7, "intents": [ { "role": "local", "intentHash": "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749", "intent": { "route": { "salt": "0xec00ec00ec00ec00ec00ec00ec00ec00aaaf8940ec75ab106feed1a7498e986f", "deadline": 1789523774, "source": 8453, "destination": 10, "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "nativeAmount": "0", "tokens": [ { "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "989500" } ], "calls": [ { "target": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "data": "0xa9059cbb00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c800000000000000000000000000000000000000000000000000000000000f193c", "value": "0" } ] }, "reward": { "deadline": 1789524404, "creator": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "prover": "0xec004Ab4870c4e177c66949329dCdb503CE41022", "nativeAmount": "0", "tokens": [ { "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" } ] } } } ] } ], "solver": { "id": "0x1Da38A31F369343bdD33cCc48E89D165E8ab3450" }, "intentHash": "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749", "execution": { "transaction": { "type": "evm", "chainId": 8453, "to": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "data": "0xdf00f8fa000000000000000000000000000000000000000000000000000000000000000a\u2026", "value": "0" }, "intent": { "route": { "salt": "0xec00ec00ec00ec00ec00ec00ec00ec00aaaf8940ec75ab106feed1a7498e986f", "deadline": 1789523774, "source": 8453, "destination": 10, "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "nativeAmount": "0", "tokens": [ { "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "989500" } ], "calls": [ { "target": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "data": "0xa9059cbb00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c800000000000000000000000000000000000000000000000000000000000f193c", "value": "0" } ] }, "reward": { "deadline": 1789524404, "creator": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "prover": "0xec004Ab4870c4e177c66949329dCdb503CE41022", "nativeAmount": "0", "tokens": [ { "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" } ] } }, "vault": "0xf6358b8f1d0Ec04EBc9Fe8FdEe5e6791640D1c2F" }, "expiresAt": 1789522904, "signature": "0xedc90fdd27654dd49ac1087901450c9c5fdf444943f61faa8d787bee86304d821f06a5db4a67eddf5cf286014d6ec8bd33c64f9e072045a9f3c5e50cc28960fc1b", "quotes": [ { "id": "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23", "type": "exact-in", "source": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000", "funder": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "symbol": null, "decimals": null }, "destination": { "chainId": 10, "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amountOut": "989500", "minAmountOut": "989500", "recipient": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", "symbol": null, "decimals": null }, "slippage": 0.005, "fees": [ { "type": "protocol", "amount": "10500", "token": { "chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "symbol": "USDC", "decimals": 6 }, "estimate": false } ], "steps": [ { "type": "bridge", "provider": "eco", "from": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" }, "to": { "chainId": 10, "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "989500" }, "fees": [], "estimatedDurationSec": 7, "intents": [ { "role": "local", "intentHash": "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749", "intent": { "route": { "salt": "0xec00ec00ec00ec00ec00ec00ec00ec00aaaf8940ec75ab106feed1a7498e986f", "deadline": 1789523774, "source": 8453, "destination": 10, "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "nativeAmount": "0", "tokens": [ { "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "989500" } ], "calls": [ { "target": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "data": "0xa9059cbb00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c800000000000000000000000000000000000000000000000000000000000f193c", "value": "0" } ] }, "reward": { "deadline": 1789524404, "creator": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "prover": "0xec004Ab4870c4e177c66949329dCdb503CE41022", "nativeAmount": "0", "tokens": [ { "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" } ] } } } ] } ], "solver": { "id": "0x1Da38A31F369343bdD33cCc48E89D165E8ab3450" }, "intentHash": "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749", "execution": { "transaction": { "type": "evm", "chainId": 8453, "to": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "data": "0xdf00f8fa000000000000000000000000000000000000000000000000000000000000000a\u2026", "value": "0" }, "intent": { "route": { "salt": "0xec00ec00ec00ec00ec00ec00ec00ec00aaaf8940ec75ab106feed1a7498e986f", "deadline": 1789523774, "source": 8453, "destination": 10, "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "nativeAmount": "0", "tokens": [ { "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "989500" } ], "calls": [ { "target": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "data": "0xa9059cbb00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c800000000000000000000000000000000000000000000000000000000000f193c", "value": "0" } ] }, "reward": { "deadline": 1789524404, "creator": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "prover": "0xec004Ab4870c4e177c66949329dCdb503CE41022", "nativeAmount": "0", "tokens": [ { "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" } ] } }, "vault": "0xf6358b8f1d0Ec04EBc9Fe8FdEe5e6791640D1c2F" }, "expiresAt": 1789522904, "signature": "0xedc90fdd27654dd49ac1087901450c9c5fdf444943f61faa8d787bee86304d821f06a5db4a67eddf5cf286014d6ec8bd33c64f9e072045a9f3c5e50cc28960fc1b" }, { "id": "quote:203ccc0b-fcd6-4a2c-9f65-2b7d1e4a8c10", "type": "exact-in", "source": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000", "funder": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "symbol": null, "decimals": null }, "destination": { "chainId": 10, "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amountOut": "969873", "minAmountOut": "969873", "recipient": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", "symbol": null, "decimals": null }, "slippage": 0.005, "fees": [ { "type": "protocol", "amount": "30127", "token": { "chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "symbol": "USDC", "decimals": 6 }, "estimate": false } ], "steps": [ { "type": "bridge", "provider": "eco", "from": { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" }, "to": { "chainId": 10, "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "969873" }, "fees": [], "estimatedDurationSec": 7, "intents": [ { "role": "local", "intentHash": "0x239539a7cc10146f96a4c17cf041abaf19452c7dab4d0d6437d3b3c4ac03d0e3", "intent": { "route": { "salt": "0xec00ec00ec00ec00ec00ec00ec00ec00aaaf8940ec75ab106feed1a7498e986f", "deadline": 1789523774, "source": 8453, "destination": 10, "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "nativeAmount": "0", "tokens": [ { "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "969873" } ], "calls": [ { "target": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "data": "0xa9059cbb00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c800000000000000000000000000000000000000000000000000000000000f193c", "value": "0" } ] }, "reward": { "deadline": 1789524404, "creator": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "prover": "0xec004Ab4870c4e177c66949329dCdb503CE41022", "nativeAmount": "0", "tokens": [ { "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" } ] } } } ] } ], "solver": { "id": "0x466caF9F946c9C2A76Cb7CD680c53C91CbBb7Ff1" }, "intentHash": "0x239539a7cc10146f96a4c17cf041abaf19452c7dab4d0d6437d3b3c4ac03d0e3", "execution": { "transaction": { "type": "evm", "chainId": 8453, "to": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "data": "0xdf00f8fa000000000000000000000000000000000000000000000000000000000000000a\u2026", "value": "0" }, "intent": { "route": { "salt": "0xec00ec00ec00ec00ec00ec00ec00ec00aaaf8940ec75ab106feed1a7498e986f", "deadline": 1789523774, "source": 8453, "destination": 10, "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "nativeAmount": "0", "tokens": [ { "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "969873" } ], "calls": [ { "target": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "data": "0xa9059cbb00000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c800000000000000000000000000000000000000000000000000000000000f193c", "value": "0" } ] }, "reward": { "deadline": 1789524404, "creator": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "prover": "0xec004Ab4870c4e177c66949329dCdb503CE41022", "nativeAmount": "0", "tokens": [ { "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" } ] } }, "vault": "0xf6358b8f1d0Ec04EBc9Fe8FdEe5e6791640D1c2F" }, "expiresAt": 1789522904, "signature": "0xc8839424faed5c9b27eb0bfc788afdfa49e9bebd5e5c1f7f7f697719d6ee8ac78791f8fcf074ab63cd2b5ffb87561825f579c1d982bf4a4f7e0dce8bf2136a9c1c" } ] } } } } } }, "default": { "description": "Error (RFC 9457 problem+json; see x-error-catalog)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "400": { "description": "Request failed validation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "legacy-shape": { "summary": "Live: pre-0.9.0 field names (swapType, root funder)", "value": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "detail": "type: Invalid option: expected one of \"exact-in\"|\"exact-out\"|\"custom\"; source.funder: Invalid input; Unrecognized keys: \"swapType\", \"funder\"", "errors": [ { "field": "type", "detail": "Invalid option: expected one of \"exact-in\"|\"exact-out\"|\"custom\"" }, { "field": "source.funder", "detail": "Invalid input" } ], "requestId": "f371e43e6fd4406b10e19487b3170edf" } }, "missing-recipient": { "summary": "Live: destination.recipient omitted", "value": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "detail": "destination.recipient: Invalid input", "errors": [ { "field": "destination.recipient", "detail": "Invalid input" } ], "requestId": "f371e43e6fd4406b10e19487b3170edf" } }, "slippage-out-of-bounds": { "summary": "Live: slippage sent as a percent", "value": { "type": "https://api.eco.com/v1/errors/slippage-out-of-bounds", "title": "slippage is outside the valid 0.0001-1 range; it is a decimal fraction (0.005 = 0.5%), not a percent (0.5 means 50%)", "status": 400, "code": "slippage-out-of-bounds", "detail": "slippage: slippage is outside the valid 0.0001-1 range (error code: slippage-out-of-bounds)", "errors": [ { "field": "slippage", "detail": "slippage is outside the valid 0.0001-1 range; it is a decimal fraction (0.005 = 0.5%), not a percent (0.5 means 50%)" } ], "requestId": "5abcdddf67907072db4af0c1caa39fcd" } } } } } }, "401": { "description": "The supplied x-api-key is unknown, revoked, or not enabled for the v1 API. Returned for every v1 endpoint by the gateway, with Content-Type application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "98e4c42f-9c70-4539-843e-8d31803001e6" } } } }, "403": { "description": "No API key supplied. The gateway rejects the request before it reaches the API, with a plain JSON body.", "content": { "application/json": { "example": { "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded", "requestId": "1eac3d6cc2aafa524b0c47a039576f8c" } } } }, "500": { "description": "Internal error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal-error", "requestId": "02dabcf0f4e3def9a6091526d3d21022" } } } }, "422": { "description": "Every solver rejected the request for a deterministic reason.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/chain-not-supported", "title": "A chain in the route is not supported", "status": 422, "code": "chain-not-supported", "detail": "Every solver rejected the request: a chain in the route is not supported.", "requestId": "252dbcdeebe5465fdc089843e8643b37" } } } }, "502": { "description": "No solver returned a usable quote. Also returned for unlisted tokens, unavailable liquidity, and amounts no solver can fill.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/solver-error", "title": "An upstream solver rejected or failed the quote request", "status": 502, "code": "solver-error", "requestId": "b76e20a9b3eea8cf85d424073229ef92" } } } } }, "security": [ { "ApiKey": [] } ], "description": "Returns one executable, signed quote for moving a stablecoin between chains, or within a chain, for `source.funder`. `type` fixes either `source.amount` (`exact-in`) or `destination.amount` (`exact-out`); `custom` requires user-authored `destination.calls`. `dappId` is required. The response is a top-level quote object with the transaction to send from the funder (`execution.transaction`), the decoded intent, `destination.amountOut` and `minAmountOut`, fees, per-step intents, and `expiresAt`. `signature` verifies against the source chain's `quoteSigner` from `GET /v1/chains`; the returned `intentHash` is the handle for `GET /v1/intents/status`.\n\nAn unsupported chain returns `422 chain-not-supported`. Routes no solver will fill (unlisted tokens, unavailable liquidity, amounts above what solvers hold) currently return `502 solver-error`.\n\nRequires `x-api-key`. Partner pricing, attribution, and enabled features are tied to the key. Without a key the gateway answers `403` with a plain JSON body (`{\"Message\": \"User is not authorized ...\"}`); a key that is unknown, revoked, or not enabled for v1 answers `401 invalid-api-key`.\n\nNo requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.\n\nExamples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.", "x-audience": "keyed", "parameters": [] } }, "/v1/intents/submit/erc-3009": { "post": { "operationId": "intents.submit.erc-3009", "summary": "Initiate an intent with ERC-3009", "tags": [ "intents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chainId": { "type": "integer", "exclusiveMinimum": 0 }, "authorization": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "value": { "type": "string", "maxLength": 78 }, "validAfter": { "type": "string", "maxLength": 78 }, "validBefore": { "type": "string", "maxLength": 78 }, "nonce": { "type": "string" } }, "required": [ "from", "to", "value", "validAfter", "validBefore", "nonce" ] }, "signature": { "type": "string", "minLength": 130, "maxLength": 132 }, "target": { "type": "object", "properties": { "quoteId": { "type": "string" } }, "required": [ "quoteId" ], "additionalProperties": false } }, "required": [ "chainId", "authorization", "signature", "target" ] }, "examples": { "quote-target": { "summary": "Fund the exact-in quote above with ERC-3009; to is the quote's execution.vault (placeholder signature)", "value": { "chainId": 8453, "target": { "quoteId": "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" }, "authorization": { "from": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "to": "0xf6358b8f1d0Ec04EBc9Fe8FdEe5e6791640D1c2F", "value": "1000000", "validAfter": "0", "validBefore": "1789526504", "nonce": "0xbeadaa19d3a655b73b7bd81214d497f1b211a52168d1ef43788619daba97d274" }, "signature": "0xedc90fdd27654dd49ac1087901450c9c5fdf444943f61faa8d787bee86304d821f06a5db4a67eddf5cf286014d6ec8bd33c64f9e072045a9f3c5e50cc28960fc1b" } } } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "published", "partial", "failed", "unknown" ] }, "signatureHash": { "type": "string" }, "subStatuses": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "quoteIds": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "submitted", "published", "failed" ] } }, "required": [ "chainId", "quoteIds", "txHash", "intentHashes", "state" ] } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } }, "required": [ "id", "status", "signatureHash", "subStatuses", "createdAt", "updatedAt" ] }, "examples": { "job": { "summary": "New gasless job accepted", "value": { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "status": "processing", "signatureHash": "0x94245dddfb2339e6e06fe251c90de895bf2995ff3c5a5fb185390f1850ed6726", "subStatuses": [ { "chainId": 8453, "quoteIds": [ "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" ], "txHash": null, "intentHashes": [], "state": "pending" } ], "createdAt": 1789522604, "updatedAt": 1789522614 } } } } } }, "default": { "description": "Error (RFC 9457 problem+json; see x-error-catalog)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "200": { "description": "Existing job for the same signature and target.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "published", "partial", "failed", "unknown" ] }, "signatureHash": { "type": "string" }, "subStatuses": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "quoteIds": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "submitted", "published", "failed" ] } }, "required": [ "chainId", "quoteIds", "txHash", "intentHashes", "state" ] } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } }, "required": [ "id", "status", "signatureHash", "subStatuses", "createdAt", "updatedAt" ] }, "examples": { "job": { "summary": "Same signature resent: the existing job", "value": { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "status": "published", "signatureHash": "0x94245dddfb2339e6e06fe251c90de895bf2995ff3c5a5fb185390f1850ed6726", "subStatuses": [ { "chainId": 8453, "quoteIds": [ "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" ], "txHash": "0x3ef97346fd076aadb54c851f33ba9234feb34d27442b9bb0abc7a0d75827af13", "intentHashes": [ "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749" ], "state": "published" } ], "createdAt": 1789522604, "updatedAt": 1789522654 } } } } } }, "400": { "description": "Request failed validation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "detail": "chainId: Invalid input: expected number, received undefined; authorization: Invalid input: expected object, received undefined; signature: Invalid input: expected string, received undefined; target: Invalid input", "errors": [ { "field": "chainId", "detail": "Invalid input: expected number, received undefined" }, { "field": "authorization", "detail": "Invalid input: expected object, received undefined" }, { "field": "signature", "detail": "Invalid input: expected string, received undefined" }, { "field": "target", "detail": "Invalid input" } ], "requestId": "f371e43e6fd4406b10e19487b3170edf" } } } }, "401": { "description": "From the gateway (application/json), without `detail`: the key is unknown, revoked, or not enabled for v1. From the API (application/problem+json): `invalid-api-key` with `detail: \"The request could not be attributed to an authorized API key.\"` means the key is enabled for v1 but not yet mapped to a partner (contact Eco); `invalid-signature` means the signature does not recover to the expected signer; `authorization-expired` means its validity window has passed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "98e4c42f-9c70-4539-843e-8d31803001e6" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unmapped": { "summary": "Live: key valid for v1 but not mapped to a partner", "value": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "f81fb73d-0fd2-4cdc-a14d-882797bb89a7", "detail": "The request could not be attributed to an authorized API key." } }, "invalid-signature": { "summary": "Live: signature does not verify", "value": { "type": "https://api.eco.com/v1/errors/invalid-signature", "title": "Signature verification failed", "status": 401, "code": "invalid-signature", "requestId": "4ece761247bfc14267057f95ee3071bc", "legacyCode": "eco-quotes:1003" } } } } } }, "403": { "description": "No API key supplied. The gateway rejects the request before it reaches the API, with a plain JSON body.", "content": { "application/json": { "example": { "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded", "requestId": "1eac3d6cc2aafa524b0c47a039576f8c" } } } }, "500": { "description": "Internal error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal-error", "requestId": "02dabcf0f4e3def9a6091526d3d21022" } } } }, "422": { "description": "Chain is not supported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/chain-not-supported", "title": "Chain is not supported", "status": 422, "code": "chain-not-supported", "requestId": "252dbcdeebe5465fdc089843e8643b37" } } } }, "409": { "description": "This signature is already pinned to a different target", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/signature-already-bound", "title": "This signature is already pinned to a different target", "status": 409, "code": "signature-already-bound", "requestId": "3ff33e83251b3cdb7d3daf15d186b89b" } } } }, "410": { "description": "The quote is unknown or expired at submit time", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/quote-expired", "title": "The quote is unknown or expired at submit time", "status": 410, "code": "quote-expired", "requestId": "19ff8aa0914e6fbe2fcb7fbe930bf0ea" } } } } }, "security": [ { "ApiKey": [] } ], "description": "Funds a quote gaslessly with a signed ERC-3009 `transferWithAuthorization`. `chainId` is the chain the authorization executes on, `target.quoteId` names the quote, and `authorization.to` is the quote's `execution.vault`. The first submission answers `202` with a gasless job; resending the same signature returns the existing job with `200`.\n\nRequires `x-api-key`. Partner pricing, attribution, and enabled features are tied to the key. Without a key the gateway answers `403` with a plain JSON body (`{\"Message\": \"User is not authorized ...\"}`); a key that is unknown, revoked, or not enabled for v1 answers `401 invalid-api-key`.\n\nNo requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.\n\nExamples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.", "x-audience": "keyed", "parameters": [] } }, "/v1/intents/submit/permit2": { "post": { "operationId": "intents.submit.permit2", "summary": "Initiate an intent with Permit2", "tags": [ "intents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chainId": { "type": "integer", "exclusiveMinimum": 0 }, "target": { "type": "object", "properties": { "quoteId": { "type": "string" } }, "required": [ "quoteId" ], "additionalProperties": false }, "permit2": { "type": "object", "properties": { "details": { "type": "object", "properties": { "token": { "type": "string" }, "amount": { "type": "string", "maxLength": 78 }, "expiration": { "type": "integer", "minimum": 0, "maximum": 281474976710655, "description": "Permit2 allowance expiration (uint48, Unix seconds)" }, "nonce": { "type": "integer", "minimum": 0, "maximum": 281474976710655 } }, "required": [ "token", "amount", "expiration", "nonce" ] }, "spender": { "type": "string", "description": "The Permit2 spender \u2014 on a quote target, the quote's execution.vault" }, "sigDeadline": { "type": "string", "maxLength": 78, "description": "Signature deadline (uint256 Unix seconds, decimal string; max-uint = no expiry)" } }, "required": [ "details", "spender", "sigDeadline" ] }, "signature": { "type": "string", "minLength": 130, "maxLength": 132 } }, "required": [ "chainId", "target", "permit2", "signature" ] }, "examples": { "quote-target": { "summary": "Fund the exact-in quote above with Permit2; spender is the quote's execution.vault (placeholder signature)", "value": { "chainId": 8453, "target": { "quoteId": "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" }, "permit2": { "details": { "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000", "expiration": 1789526504, "nonce": 0 }, "spender": "0xf6358b8f1d0Ec04EBc9Fe8FdEe5e6791640D1c2F", "sigDeadline": "1789526504" }, "signature": "0xedc90fdd27654dd49ac1087901450c9c5fdf444943f61faa8d787bee86304d821f06a5db4a67eddf5cf286014d6ec8bd33c64f9e072045a9f3c5e50cc28960fc1b" } } } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "published", "partial", "failed", "unknown" ] }, "signatureHash": { "type": "string" }, "subStatuses": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "quoteIds": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "submitted", "published", "failed" ] } }, "required": [ "chainId", "quoteIds", "txHash", "intentHashes", "state" ] } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } }, "required": [ "id", "status", "signatureHash", "subStatuses", "createdAt", "updatedAt" ] }, "examples": { "job": { "summary": "New gasless job accepted", "value": { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "status": "processing", "signatureHash": "0x94245dddfb2339e6e06fe251c90de895bf2995ff3c5a5fb185390f1850ed6726", "subStatuses": [ { "chainId": 8453, "quoteIds": [ "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" ], "txHash": null, "intentHashes": [], "state": "pending" } ], "createdAt": 1789522604, "updatedAt": 1789522614 } } } } } }, "default": { "description": "Error (RFC 9457 problem+json; see x-error-catalog)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "200": { "description": "Existing job for the same signature and target.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "published", "partial", "failed", "unknown" ] }, "signatureHash": { "type": "string" }, "subStatuses": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "quoteIds": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "submitted", "published", "failed" ] } }, "required": [ "chainId", "quoteIds", "txHash", "intentHashes", "state" ] } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } }, "required": [ "id", "status", "signatureHash", "subStatuses", "createdAt", "updatedAt" ] }, "examples": { "job": { "summary": "Same signature resent: the existing job", "value": { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "status": "published", "signatureHash": "0x94245dddfb2339e6e06fe251c90de895bf2995ff3c5a5fb185390f1850ed6726", "subStatuses": [ { "chainId": 8453, "quoteIds": [ "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" ], "txHash": "0x3ef97346fd076aadb54c851f33ba9234feb34d27442b9bb0abc7a0d75827af13", "intentHashes": [ "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749" ], "state": "published" } ], "createdAt": 1789522604, "updatedAt": 1789522654 } } } } } }, "400": { "description": "Request failed validation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "detail": "chainId: Invalid input: expected number, received undefined; permit2.sigDeadline: Invalid input: expected string, received number", "errors": [ { "field": "chainId", "detail": "Invalid input: expected number, received undefined" }, { "field": "permit2.sigDeadline", "detail": "Invalid input: expected string, received number" } ], "requestId": "f371e43e6fd4406b10e19487b3170edf" } } } }, "401": { "description": "From the gateway (application/json), without `detail`: the key is unknown, revoked, or not enabled for v1. From the API (application/problem+json): `invalid-api-key` with `detail: \"The request could not be attributed to an authorized API key.\"` means the key is enabled for v1 but not yet mapped to a partner (contact Eco); `invalid-signature` means the signature does not recover to the expected signer; `authorization-expired` means its validity window has passed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "98e4c42f-9c70-4539-843e-8d31803001e6" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unmapped": { "summary": "Live: key valid for v1 but not mapped to a partner", "value": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "f81fb73d-0fd2-4cdc-a14d-882797bb89a7", "detail": "The request could not be attributed to an authorized API key." } }, "invalid-signature": { "summary": "Live: signature does not verify", "value": { "type": "https://api.eco.com/v1/errors/invalid-signature", "title": "Signature verification failed", "status": 401, "code": "invalid-signature", "requestId": "4ece761247bfc14267057f95ee3071bc", "legacyCode": "eco-quotes:1003" } } } } } }, "403": { "description": "No API key supplied. The gateway rejects the request before it reaches the API, with a plain JSON body.", "content": { "application/json": { "example": { "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded", "requestId": "1eac3d6cc2aafa524b0c47a039576f8c" } } } }, "500": { "description": "Internal error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal-error", "requestId": "02dabcf0f4e3def9a6091526d3d21022" } } } }, "422": { "description": "Chain is not supported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/chain-not-supported", "title": "Chain is not supported", "status": 422, "code": "chain-not-supported", "requestId": "252dbcdeebe5465fdc089843e8643b37" } } } }, "409": { "description": "This signature is already pinned to a different target", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/signature-already-bound", "title": "This signature is already pinned to a different target", "status": 409, "code": "signature-already-bound", "requestId": "3ff33e83251b3cdb7d3daf15d186b89b" } } } }, "410": { "description": "The quote is unknown or expired at submit time", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/quote-expired", "title": "The quote is unknown or expired at submit time", "status": 410, "code": "quote-expired", "requestId": "19ff8aa0914e6fbe2fcb7fbe930bf0ea" } } } } }, "security": [ { "ApiKey": [] } ], "description": "Funds a quote gaslessly with a signed Permit2 `PermitSingle` (AllowanceTransfer, not SignatureTransfer). `chainId` is the chain the permit was signed for, `target.quoteId` names the quote, `permit2.spender` is the quote's `execution.vault`, and `signature` is the top-level EIP-712 signature. `permit2.sigDeadline` is a decimal string. The first submission answers `202` with a gasless job; resending the same signature returns the existing job with `200`.\n\nRequires `x-api-key`. Partner pricing, attribution, and enabled features are tied to the key. Without a key the gateway answers `403` with a plain JSON body (`{\"Message\": \"User is not authorized ...\"}`); a key that is unknown, revoked, or not enabled for v1 answers `401 invalid-api-key`.\n\nNo requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.\n\nExamples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.", "x-audience": "keyed", "parameters": [] } }, "/v1/intents/submit/permit3": { "post": { "operationId": "intents.submit.permit3", "summary": "Initiate an intent with Permit3", "tags": [ "intents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target": { "type": "object", "properties": { "quoteId": { "type": "string" } }, "required": [ "quoteId" ], "additionalProperties": false }, "permit3": { "type": "object", "properties": { "owner": { "type": "string" }, "permitContract": { "type": "string", "description": "The Permit3 contract the legs were signed against (the EIP-712 verifyingContract)" }, "salt": { "type": "string" }, "deadline": { "type": "integer", "minimum": 0 }, "timestamp": { "type": "integer", "minimum": 0, "maximum": 281474976710655, "description": "Permit3 ordering timestamp (uint48, Unix seconds)" }, "merkleRoot": { "type": "string", "description": "Merkle root over the legs, as signed" }, "permits": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer", "exclusiveMinimum": 0 }, "token": { "type": "string" }, "amount": { "type": "string", "maxLength": 78 }, "account": { "type": "string", "description": "Recipient (transfer mode) or spender (allowance mode) \u2014 on a quote target, the quote's execution.vault" }, "modeOrExpiration": { "type": "integer", "minimum": 0, "maximum": 281474976710655, "description": "0 = transfer mode (funds pushed to account); any other value = allowance mode with this expiration, Unix seconds" } }, "required": [ "chainId", "token", "amount", "account", "modeOrExpiration" ] } } }, "required": [ "owner", "permitContract", "salt", "deadline", "timestamp", "merkleRoot", "permits" ] }, "signature": { "type": "string", "minLength": 130, "maxLength": 132 } }, "required": [ "target", "permit3", "signature" ] }, "examples": { "quote-target": { "summary": "Fund the exact-in quote above with Permit3; account is the quote's execution.vault (placeholder signature)", "value": { "target": { "quoteId": "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" }, "permit3": { "owner": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "permitContract": "0xEc00030C0000245E27d1521Cc2EE88F071c2Ae34", "salt": "0xec00ec00ec00ec00ec00ec00ec00ec00aaaf8940ec75ab106feed1a7498e986f", "deadline": 1789526504, "timestamp": 1789522844, "merkleRoot": "0xcf68ff94aa42b6f2cc5e6edc42c853b2bd81dcfc43d892062fac723945cef113", "permits": [ { "chainId": 8453, "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000", "account": "0xf6358b8f1d0Ec04EBc9Fe8FdEe5e6791640D1c2F", "modeOrExpiration": 0 } ] }, "signature": "0xedc90fdd27654dd49ac1087901450c9c5fdf444943f61faa8d787bee86304d821f06a5db4a67eddf5cf286014d6ec8bd33c64f9e072045a9f3c5e50cc28960fc1b" } } } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "published", "partial", "failed", "unknown" ] }, "signatureHash": { "type": "string" }, "subStatuses": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "quoteIds": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "submitted", "published", "failed" ] } }, "required": [ "chainId", "quoteIds", "txHash", "intentHashes", "state" ] } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } }, "required": [ "id", "status", "signatureHash", "subStatuses", "createdAt", "updatedAt" ] }, "examples": { "job": { "summary": "New gasless job accepted", "value": { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "status": "processing", "signatureHash": "0x94245dddfb2339e6e06fe251c90de895bf2995ff3c5a5fb185390f1850ed6726", "subStatuses": [ { "chainId": 8453, "quoteIds": [ "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" ], "txHash": null, "intentHashes": [], "state": "pending" } ], "createdAt": 1789522604, "updatedAt": 1789522614 } } } } } }, "default": { "description": "Error (RFC 9457 problem+json; see x-error-catalog)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "200": { "description": "Existing job for the same signature and target.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "published", "partial", "failed", "unknown" ] }, "signatureHash": { "type": "string" }, "subStatuses": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "quoteIds": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "submitted", "published", "failed" ] } }, "required": [ "chainId", "quoteIds", "txHash", "intentHashes", "state" ] } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } }, "required": [ "id", "status", "signatureHash", "subStatuses", "createdAt", "updatedAt" ] }, "examples": { "job": { "summary": "Same signature resent: the existing job", "value": { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "status": "published", "signatureHash": "0x94245dddfb2339e6e06fe251c90de895bf2995ff3c5a5fb185390f1850ed6726", "subStatuses": [ { "chainId": 8453, "quoteIds": [ "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" ], "txHash": "0x3ef97346fd076aadb54c851f33ba9234feb34d27442b9bb0abc7a0d75827af13", "intentHashes": [ "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749" ], "state": "published" } ], "createdAt": 1789522604, "updatedAt": 1789522654 } } } } } }, "400": { "description": "Request failed validation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "detail": "target: Invalid input: expected object, received undefined; permit3: Invalid input: expected object, received undefined; signature: Invalid input: expected string, received undefined", "errors": [ { "field": "target", "detail": "Invalid input: expected object, received undefined" }, { "field": "permit3", "detail": "Invalid input: expected object, received undefined" }, { "field": "signature", "detail": "Invalid input: expected string, received undefined" } ], "requestId": "f371e43e6fd4406b10e19487b3170edf" } } } }, "401": { "description": "From the gateway (application/json), without `detail`: the key is unknown, revoked, or not enabled for v1. From the API (application/problem+json): `invalid-api-key` with `detail: \"The request could not be attributed to an authorized API key.\"` means the key is enabled for v1 but not yet mapped to a partner (contact Eco); `invalid-signature` means the signature does not recover to the expected signer; `authorization-expired` means its validity window has passed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "98e4c42f-9c70-4539-843e-8d31803001e6" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unmapped": { "summary": "Live: key valid for v1 but not mapped to a partner", "value": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "f81fb73d-0fd2-4cdc-a14d-882797bb89a7", "detail": "The request could not be attributed to an authorized API key." } }, "invalid-signature": { "summary": "Live: signature does not verify", "value": { "type": "https://api.eco.com/v1/errors/invalid-signature", "title": "Signature verification failed", "status": 401, "code": "invalid-signature", "requestId": "4ece761247bfc14267057f95ee3071bc", "legacyCode": "eco-quotes:1003" } } } } } }, "403": { "description": "No API key supplied. The gateway rejects the request before it reaches the API, with a plain JSON body.", "content": { "application/json": { "example": { "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded", "requestId": "1eac3d6cc2aafa524b0c47a039576f8c" } } } }, "500": { "description": "Internal error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal-error", "requestId": "02dabcf0f4e3def9a6091526d3d21022" } } } }, "422": { "description": "Chain is not supported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/chain-not-supported", "title": "Chain is not supported", "status": 422, "code": "chain-not-supported", "requestId": "252dbcdeebe5465fdc089843e8643b37" } } } }, "409": { "description": "This signature is already pinned to a different target", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/signature-already-bound", "title": "This signature is already pinned to a different target", "status": 409, "code": "signature-already-bound", "requestId": "3ff33e83251b3cdb7d3daf15d186b89b" } } } }, "410": { "description": "The quote is unknown or expired at submit time", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/quote-expired", "title": "The quote is unknown or expired at submit time", "status": 410, "code": "quote-expired", "requestId": "19ff8aa0914e6fbe2fcb7fbe930bf0ea" } } } } }, "security": [ { "ApiKey": [] } ], "description": "Funds a quote gaslessly with a signed Permit3 authorization. `target.quoteId` names the quote, each `permit3.permits[]` entry names the quote's `execution.vault` as its `account`, and `signature` is the top-level EIP-712 signature over the Permit3 payload. The first submission answers `202` with a gasless job; resending the same signature returns the existing job with `200`.\n\nRequires `x-api-key`. Partner pricing, attribution, and enabled features are tied to the key. Without a key the gateway answers `403` with a plain JSON body (`{\"Message\": \"User is not authorized ...\"}`); a key that is unknown, revoked, or not enabled for v1 answers `401 invalid-api-key`.\n\nNo requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.\n\nExamples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.", "x-audience": "keyed", "parameters": [] } }, "/v1/intents/status": { "get": { "operationId": "intents.status", "summary": "Track the status of an intent", "tags": [ "status" ], "parameters": [ { "name": "intentHash", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact lookup of one intent by its hash, as returned by `POST /v1/quotes`.", "example": "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749" }, { "name": "sourceTxHash", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact lookup by the source-chain funding transaction hash." }, { "name": "destinationTxHash", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact lookup by the destination-chain fulfillment transaction hash." }, { "name": "quoteId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Exact lookup of a quote by its bare UUID, without the `quote:` prefix.", "example": "8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" }, { "name": "jobId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Exact lookup of a gasless funding job by its bare UUID, without the `gasless:` prefix.", "example": "0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a" }, { "name": "wallet", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Pages through intents funded by, or delivered to, this wallet. The only filter that returns a collection.", "example": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "filled", "settled", "refunded", "refundable", "expired", "failed", "unknown" ] }, "description": "Narrows a `wallet` page to one status. Rejected with `400` unless `wallet` is also supplied." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Opaque cursor from a previous `nextCursor`." }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Page size for `wallet` lookups, 1-50. Default 20." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "intent", "quote", "gasless", "deposit-address" ] }, "status": { "type": "string" }, "updatedAt": { "type": [ "integer", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "subStatuses": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "quoteIds": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "submitted", "published", "failed" ] } }, "required": [ "chainId", "quoteIds", "txHash", "intentHashes", "state" ] } }, "sourceTx": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": "string" }, "token": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "chainId", "txHash", "token", "amount" ] }, "destinationTx": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": "string" }, "token": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "chainId", "txHash", "token", "amount" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SWAP", "BRIDGE" ] }, "intentHash": { "type": "string" }, "status": { "type": "string" }, "from": { "type": "object", "properties": { "token": { "type": "string" }, "amount": { "type": "string" }, "chainId": { "type": "integer" } }, "required": [ "token", "amount", "chainId" ] }, "to": { "type": "object", "properties": { "token": { "type": "string" }, "amount": { "type": "string" }, "chainId": { "type": "integer" } }, "required": [ "token", "amount", "chainId" ] }, "transactions": { "type": "object", "properties": { "created": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": "string" } }, "required": [ "chainId", "txHash" ] }, "fulfilled": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": "string" } }, "required": [ "chainId", "txHash" ] }, "refunded": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": "string" } }, "required": [ "chainId", "txHash" ] } } } }, "required": [ "type", "intentHash", "status", "from", "to", "transactions" ] } } }, "required": [ "id", "type", "status", "updatedAt" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "results", "nextCursor" ] }, "examples": { "quote-active": { "summary": "Live: a quote that has not been funded yet (GET ?quoteId=)", "value": { "results": [ { "id": "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23", "type": "quote", "status": "active", "updatedAt": 1789522700, "steps": [] } ], "nextCursor": null } }, "quote-filled-detail": { "summary": "Live: a funded quote whose intent was fulfilled, with per-step transactions", "value": { "results": [ { "id": "quote:c1ed3798-e227-45a6-ad7c-b805f9e7a392", "type": "quote", "status": "submitted", "intentHashes": [ "0x28cf072bb7fcd236cb417ef542f91002a84e04afb4c144ceb3ded8056bfa790f" ], "updatedAt": 1789432832, "steps": [ { "type": "BRIDGE", "intentHash": "0x28cf072bb7fcd236cb417ef542f91002a84e04afb4c144ceb3ded8056bfa790f", "status": "FULFILLED", "from": { "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000", "chainId": 8453 }, "to": { "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "989500", "chainId": 10 }, "transactions": { "created": { "chainId": 8453, "txHash": "0x522dc811ae11692c9066747d24e96fa6d42315945aef9246ac19adb5663fe5c9" }, "fulfilled": { "chainId": 10, "txHash": "0xace13db990e6c9aac0957510443262a90c128795c30086a5b0e62ac713c20866" } } } ], "sourceTx": { "chainId": 8453, "txHash": "0x522dc811ae11692c9066747d24e96fa6d42315945aef9246ac19adb5663fe5c9", "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "amount": "1000000" }, "destinationTx": { "chainId": 10, "txHash": "0xace13db990e6c9aac0957510443262a90c128795c30086a5b0e62ac713c20866", "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "amount": "989500" } } ], "nextCursor": null } }, "intent-filled": { "summary": "An intent delivered on the destination chain", "value": { "results": [ { "id": "intent:0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749", "type": "intent", "status": "filled", "updatedAt": 1767225600, "txHash": "0xbee3c510b4e912445589df6b04b46f5650604426e8c6200179df512a47f11459" } ], "nextCursor": null } }, "gasless-handoff": { "summary": "A gasless funding job whose intent has been published", "value": { "results": [ { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "type": "gasless", "status": "published", "updatedAt": 1767225600, "intentHashes": [ "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749" ], "subStatuses": [ { "chainId": 8453, "quoteIds": [ "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" ], "txHash": "0xbee3c510b4e912445589df6b04b46f5650604426e8c6200179df512a47f11459", "intentHashes": [ "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749" ], "state": "published" } ] } ], "nextCursor": null } }, "intent-unknown": { "summary": "Live: an intent hash the API has not seen (still 200)", "value": { "results": [ { "id": "intent:0x239539a7cc10146f96a4c17cf041abaf19452c7dab4d0d6437d3b3c4ac03d0e3", "type": "intent", "status": "unknown", "updatedAt": null } ], "nextCursor": null } }, "wallet-page": { "summary": "A wallet page (GET ?wallet=\u2026&limit=\u2026)", "value": { "results": [ { "id": "intent:0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749", "type": "intent", "status": "filled", "updatedAt": 1767225600, "txHash": "0xbee3c510b4e912445589df6b04b46f5650604426e8c6200179df512a47f11459" }, { "id": "intent:0x239539a7cc10146f96a4c17cf041abaf19452c7dab4d0d6437d3b3c4ac03d0e3", "type": "intent", "status": "unknown", "updatedAt": null } ], "nextCursor": "Y3Vyc29yOjE3NjcyMjU2MDA6aW50ZW50OjB4YWJhYg" } } } } } }, "default": { "description": "Error (RFC 9457 problem+json; see x-error-catalog)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "400": { "description": "Request failed validation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "no-filter": { "summary": "No filter supplied", "value": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "detail": "at least one filter required (intentHash, sourceTxHash, destinationTxHash, quoteId, jobId, wallet, status); paging controls alone are not a filter", "requestId": "f371e43e6fd4406b10e19487b3170edf" } }, "prefixed-quote-id": { "summary": "quoteId sent with its quote: prefix", "value": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "detail": "Invalid UUID", "requestId": "f371e43e6fd4406b10e19487b3170edf" } }, "status-without-wallet": { "summary": "status without wallet", "value": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "detail": "status narrows a collection and cannot identify one on its own; combine it with wallet", "requestId": "f371e43e6fd4406b10e19487b3170edf" } }, "limit-too-large": { "summary": "limit above 50", "value": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "detail": "Too big: expected number to be <=50", "requestId": "f371e43e6fd4406b10e19487b3170edf" } } } } } }, "401": { "description": "The supplied x-api-key is unknown, revoked, or not enabled for the v1 API. Returned for every v1 endpoint by the gateway, with Content-Type application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "98e4c42f-9c70-4539-843e-8d31803001e6" } } } }, "403": { "description": "No API key supplied. The gateway rejects the request before it reaches the API, with a plain JSON body.", "content": { "application/json": { "example": { "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded", "requestId": "1eac3d6cc2aafa524b0c47a039576f8c" } } } }, "500": { "description": "Internal error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal-error", "requestId": "02dabcf0f4e3def9a6091526d3d21022" } } } } }, "security": [ { "ApiKey": [] } ], "description": "Returns the state of intents, quotes, and gasless funding jobs. At least one filter is required; paging controls alone are rejected with `400`. Exact lookups (`intentHash`, `sourceTxHash`, `destinationTxHash`, `quoteId`, `jobId`) always return `200`; an unknown ID is reported with `status: \"unknown\"`. `wallet` returns a page of intents and is the only filter `status` can be combined with. A consumed quote reports `submitted` with its `intentHashes`, per-step `steps[]`, and `sourceTx` / `destinationTx` once known.\n\n`quoteId` and `jobId` are bare UUIDs, without the `quote:` or `gasless:` prefix.\n\nRequires `x-api-key`. Partner pricing, attribution, and enabled features are tied to the key. Without a key the gateway answers `403` with a plain JSON body (`{\"Message\": \"User is not authorized ...\"}`); a key that is unknown, revoked, or not enabled for v1 answers `401 invalid-api-key`.\n\nNo requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.\n\nExamples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.", "x-audience": "keyed" } }, "/v1/chains": { "get": { "operationId": "chains.list", "summary": "List chains", "tags": [ "discovery" ], "parameters": [ { "name": "chainId", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0 }, "description": "Returns only this chain. Example: `8453` for Base.", "example": 8453 } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "chains": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "name": { "type": "string" }, "quoteSigner": { "description": "Address whose EIP-712 signature appears as `signature` on every quote for this chain. Read it from here and cache with a refresh rather than pinning it; it can rotate.", "type": "string" }, "type": { "type": "string", "enum": [ "evm", "svm", "tvm" ] }, "encoding": { "type": "string", "enum": [ "abi", "borsh" ] }, "status": { "type": "string", "enum": [ "live", "paused" ] }, "contracts": { "type": "object", "properties": { "portal": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "executor": { "type": [ "string", "null" ], "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." } }, "required": [ "portal", "executor" ], "description": "Deployed Eco contracts: `portal` is the funding target for this chain's intents, `executor` runs destination calls (null where not deployed)." } }, "required": [ "chainId", "name", "quoteSigner", "type", "encoding", "status", "contracts" ] } }, "limits": { "type": "object", "properties": { "paging": { "type": "object", "properties": { "maxLimit": { "type": "integer" }, "defaultLimit": { "type": "integer" } }, "required": [ "maxLimit", "defaultLimit" ] } }, "required": [ "paging" ] } }, "required": [ "chains" ] }, "examples": { "all-chains": { "summary": "Live response on 2026-09-15", "value": { "chains": [ { "chainId": 1, "name": "Ethereum", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": "0xEc2C96e75B09e29b66bf2Ee5C37fa749eF9AA7c7" } }, { "chainId": 10, "name": "OP Mainnet", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": "0xEc2C96e75B09e29b66bf2Ee5C37fa749eF9AA7c7" } }, { "chainId": 130, "name": "Unichain", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": "0xEc2C96e75B09e29b66bf2Ee5C37fa749eF9AA7c7" } }, { "chainId": 137, "name": "Polygon", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": "0xEc2C96e75B09e29b66bf2Ee5C37fa749eF9AA7c7" } }, { "chainId": 143, "name": "Monad", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": null } }, { "chainId": 480, "name": "World Chain", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": "0xEc2C96e75B09e29b66bf2Ee5C37fa749eF9AA7c7" } }, { "chainId": 999, "name": "HyperEVM", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": "0xEc2C96e75B09e29b66bf2Ee5C37fa749eF9AA7c7" } }, { "chainId": 2020, "name": "Ronin", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": "0xEc2C96e75B09e29b66bf2Ee5C37fa749eF9AA7c7" } }, { "chainId": 5042, "name": "Arc", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": null } }, { "chainId": 8453, "name": "Base", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": "0xEc2C96e75B09e29b66bf2Ee5C37fa749eF9AA7c7" } }, { "chainId": 9745, "name": "Plasma", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": "0xEc2C96e75B09e29b66bf2Ee5C37fa749eF9AA7c7" } }, { "chainId": 42161, "name": "Arbitrum One", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": "0xEc2C96e75B09e29b66bf2Ee5C37fa749eF9AA7c7" } }, { "chainId": 1399811149, "name": "Solana", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "svm", "encoding": "abi", "status": "live", "contracts": { "portal": "EcooswwC1NggsckZyF5SeAL9WsgJs3UhPbrqY1apV73F", "executor": "Gk1ZpHHx9tgSo68hiT2prBQCjkstdUYVZn4SWL3NzR2U" } } ], "limits": { "paging": { "maxLimit": 50, "defaultLimit": 20 } } } }, "one-chain": { "summary": "GET /v1/chains?chainId=8453", "value": { "chains": [ { "chainId": 8453, "name": "Base", "quoteSigner": "0x1D636584Eec22B53Be1930daF6B12a0E13C8B870", "type": "evm", "encoding": "abi", "status": "live", "contracts": { "portal": "0xEC000064576f9C95a8623Bc0eff3db6d296ea6df", "executor": "0xEc2C96e75B09e29b66bf2Ee5C37fa749eF9AA7c7" } } ], "limits": { "paging": { "maxLimit": 50, "defaultLimit": 20 } } } } } } } }, "default": { "description": "Error (RFC 9457 problem+json; see x-error-catalog)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "400": { "description": "Request failed validation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "requestId": "f371e43e6fd4406b10e19487b3170edf" } } } }, "401": { "description": "The supplied x-api-key is unknown, revoked, or not enabled for the v1 API. Returned for every v1 endpoint by the gateway, with Content-Type application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "98e4c42f-9c70-4539-843e-8d31803001e6" } } } }, "403": { "description": "No API key supplied. The gateway rejects the request before it reaches the API, with a plain JSON body.", "content": { "application/json": { "example": { "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded", "requestId": "1eac3d6cc2aafa524b0c47a039576f8c" } } } }, "500": { "description": "Internal error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal-error", "requestId": "02dabcf0f4e3def9a6091526d3d21022" } } } } }, "security": [ { "ApiKey": [] } ], "description": "Returns every chain the API can quote, with its Portal and Executor contract addresses and the address that signs quotes. `chainId` filters to one chain. Solana is chain `1399811149`.\n\nRequires `x-api-key`. Partner pricing, attribution, and enabled features are tied to the key. Without a key the gateway answers `403` with a plain JSON body (`{\"Message\": \"User is not authorized ...\"}`); a key that is unknown, revoked, or not enabled for v1 answers `401 invalid-api-key`.\n\nNo requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.\n\nExamples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.", "x-audience": "keyed" } }, "/v1/tokens": { "get": { "operationId": "tokens.list", "summary": "List tokens", "tags": [ "discovery" ], "parameters": [ { "name": "chainId", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0 }, "description": "Returns only tokens on this chain. Example: `8453` for Base.", "example": 8453 } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "address": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "symbol": { "type": [ "string", "null" ] }, "decimals": { "type": [ "integer", "null" ] }, "supports": { "type": "object", "properties": { "quote": { "type": "array", "items": { "type": "string", "enum": [ "permit3", "permit2", "erc-3009", "erc-2612" ] } }, "depositAddress": { "type": "array", "items": { "type": "string", "enum": [ "permit3", "permit2", "erc-3009", "erc-2612" ] } } }, "required": [ "quote", "depositAddress" ] } }, "required": [ "chainId", "address", "symbol", "decimals", "supports" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "tokens", "nextCursor" ] }, "examples": { "tokens": { "summary": "Abridged live response on 2026-09-15 (32 tokens across 13 chains in full)", "value": { "tokens": [ { "chainId": 1, "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "symbol": "USDC", "decimals": 6, "supports": { "quote": [ "erc-3009", "permit2", "permit3" ], "depositAddress": [ "erc-2612", "erc-3009" ] } }, { "chainId": 1, "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "symbol": "USDT", "decimals": 6, "supports": { "quote": [ "erc-3009", "permit2", "permit3" ], "depositAddress": [ "erc-2612", "erc-3009" ] } }, { "chainId": 10, "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "symbol": "USDC", "decimals": 6, "supports": { "quote": [ "erc-3009", "permit2", "permit3" ], "depositAddress": [ "erc-2612", "erc-3009" ] } }, { "chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "symbol": "USDC", "decimals": 6, "supports": { "quote": [ "erc-3009", "permit2", "permit3" ], "depositAddress": [ "erc-2612", "erc-3009" ] } }, { "chainId": 8453, "address": "0x1217BfE6c773EEC6cc4A38b5Dc45B92292B6E189", "symbol": "oUSDT", "decimals": 6, "supports": { "quote": [ "erc-3009", "permit2", "permit3" ], "depositAddress": [ "erc-2612", "erc-3009" ] } }, { "chainId": 42161, "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "symbol": "USDC", "decimals": 6, "supports": { "quote": [ "erc-3009", "permit2", "permit3" ], "depositAddress": [ "erc-2612", "erc-3009" ] } }, { "chainId": 1399811149, "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "symbol": "USDC", "decimals": 6, "supports": { "quote": [ "erc-3009", "permit2", "permit3" ], "depositAddress": [ "erc-2612", "erc-3009" ] } } ], "nextCursor": null } }, "one-chain": { "summary": "GET /v1/tokens?chainId=8453 (abridged)", "value": { "tokens": [ { "chainId": 8453, "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "symbol": "USDC", "decimals": 6, "supports": { "quote": [ "erc-3009", "permit2", "permit3" ], "depositAddress": [ "erc-2612", "erc-3009" ] } }, { "chainId": 8453, "address": "0x1217BfE6c773EEC6cc4A38b5Dc45B92292B6E189", "symbol": "oUSDT", "decimals": 6, "supports": { "quote": [ "erc-3009", "permit2", "permit3" ], "depositAddress": [ "erc-2612", "erc-3009" ] } } ], "nextCursor": null } } } } } }, "default": { "description": "Error (RFC 9457 problem+json; see x-error-catalog)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "400": { "description": "Request failed validation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "requestId": "f371e43e6fd4406b10e19487b3170edf" } } } }, "401": { "description": "The supplied x-api-key is unknown, revoked, or not enabled for the v1 API. Returned for every v1 endpoint by the gateway, with Content-Type application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "98e4c42f-9c70-4539-843e-8d31803001e6" } } } }, "403": { "description": "No API key supplied. The gateway rejects the request before it reaches the API, with a plain JSON body.", "content": { "application/json": { "example": { "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded", "requestId": "1eac3d6cc2aafa524b0c47a039576f8c" } } } }, "500": { "description": "Internal error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal-error", "requestId": "02dabcf0f4e3def9a6091526d3d21022" } } } } }, "security": [ { "ApiKey": [] } ], "description": "Returns every token the API can quote, with decimals and the gasless standards each token supports for quote funding (`permit3`, `permit2`, `erc-3009`) and deposit-address funding (`erc-2612`, `erc-3009`). `chainId` filters to one chain. A listed token does not guarantee that every pair and amount can be quoted.\n\nRequires `x-api-key`. Partner pricing, attribution, and enabled features are tied to the key. Without a key the gateway answers `403` with a plain JSON body (`{\"Message\": \"User is not authorized ...\"}`); a key that is unknown, revoked, or not enabled for v1 answers `401 invalid-api-key`.\n\nNo requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.\n\nExamples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.", "x-audience": "keyed" } }, "/v1/circle-gateway/deposit-addresses": { "post": { "tags": [ "circle-gateway" ], "summary": "Get a Circle Gateway deposit address", "description": "Creates a quoted Circle Gateway deposit address and returns it as `vaultAddress`, with the quoted `amount` and the quote `deadline` (Unix seconds). The address must receive at least `amount` before `deadline`, gaslessly or by plain transfer. Repeating the same request while the quote is pending returns the same address. Responses keep the `{ data: \u2026 }` envelope and the deposit-address validation error format.\n\nNo API key is required: Circle Gateway operations are open so that any wallet or relay can create and fund a deposit address. A supplied key that is unknown, revoked, or not enabled for v1 is still rejected with `401 invalid-api-key`, so send no key rather than a wrong one.\n\nNo requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.\n\nExamples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.", "operationId": "gateway-create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CircleGatewayDepositAddressDTO" }, "examples": { "base-usdc": { "summary": "Deposit 1 USDC from Base into the recipient's Gateway balance", "value": { "sourceChainId": 8453, "amount": "1000000", "recipient": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", "depositor": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" } }, "with-refund-recipient": { "summary": "Same, with an explicit refund recipient", "value": { "sourceChainId": 8453, "amount": "1000000", "recipient": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8", "depositor": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "refundRecipient": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" } } } } } }, "responses": { "201": { "description": "Quoted vault created successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CircleGatewayDepositAddressResponseDTO" } } }, "examples": { "vault": { "summary": "Quoted deposit address (placeholder)", "value": { "data": { "vaultAddress": "0x379BAB257e7Eb159538F01165B766A1BEaf2D954", "amount": "1000000", "deadline": 1789526504 } } } } } } }, "400": { "description": "Validation failure in the deposit-address service's format.", "content": { "application/json": { "examples": { "empty-body": { "summary": "Live: empty body", "value": { "statusCode": 400, "createdBy": "ValidationFilter", "validationErrors": { "sourceChainId": "sourceChainId must not be less than 1, sourceChainId should not be empty, sourceChainId must be an integer number, sourceChainId must be a number conforming to the specified constraints", "amount": "amount must be a positive integer string <= 115792089237316195423570985008687907853269984665640564039457584007913129639935, amount must be a positive integer string, amount should not be empty, amount must be a string", "recipient": "recipient must be an Ethereum address, recipient should not be empty, recipient must be a string", "depositor": "depositor must be an Ethereum address, depositor should not be empty, depositor must be a string" } } }, "zero-refund-recipient": { "summary": "refundRecipient set to the zero address", "value": { "statusCode": 400, "createdBy": "ValidationFilter", "validationErrors": { "refundRecipient": "refundRecipient must not be the zero address" } } } } } } }, "401": { "description": "The supplied x-api-key is unknown, revoked, or not enabled for the v1 API. Returned for every v1 endpoint by the gateway, with Content-Type application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "98e4c42f-9c70-4539-843e-8d31803001e6" } } } }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit; honor Retry-After when supplied." }, "500": { "description": "Service failure; preserve identifiers before retrying." } }, "security": [], "x-audience": "anonymous", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. A key that is unknown, revoked, or not enabled for v1 is rejected with 401." } ] } }, "/v1/circle-gateway/deposit-addresses/{vaultAddress}": { "get": { "tags": [ "circle-gateway" ], "summary": "Check the status of a deposit", "description": "Returns a deposit address's state, quoted amount, deadline, and destination `intentHash`. `sourceChainId` is required. An unknown address returns `404` in the deposit-address error format. Responses keep the `{ data: \u2026 }` envelope.\n\nNo API key is required: Circle Gateway operations are open so that any wallet or relay can create and fund a deposit address. A supplied key that is unknown, revoked, or not enabled for v1 is still rejected with `401 invalid-api-key`, so send no key rather than a wrong one.\n\nNo requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.\n\nExamples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.", "operationId": "gateway-lookup", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. A key that is unknown, revoked, or not enabled for v1 is rejected with 401." }, { "name": "vaultAddress", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EvmAddress" }, "example": "0x379BAB257e7Eb159538F01165B766A1BEaf2D954", "description": "The `vaultAddress` returned when the deposit address was created." }, { "name": "sourceChainId", "in": "query", "required": true, "description": "The `sourceChainId` the deposit address was created for. Required; omitting it returns `400`.", "schema": { "type": "number", "example": 8453 }, "example": 8453 } ], "responses": { "200": { "description": "Quoted vault record retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CircleGatewayDepositAddressStatusResponseDTO" } } }, "examples": { "pending": { "summary": "Deposit address created, not yet funded", "value": { "data": { "vaultAddress": "0x379BAB257e7Eb159538F01165B766A1BEaf2D954", "amount": "1000000", "deadline": 1789526504, "state": "PENDING", "intentHash": "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749", "sourceChainId": 8453 } } }, "published": { "summary": "Deposit address funded and deposit intent published", "value": { "data": { "vaultAddress": "0x379BAB257e7Eb159538F01165B766A1BEaf2D954", "amount": "1000000", "deadline": 1789526504, "state": "PUBLISHED", "intentHash": "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749", "sourceChainId": 8453 } } } } } } }, "400": { "description": "Validation failure in the deposit-address service's format.", "content": { "application/json": { "example": { "statusCode": 400, "createdBy": "ValidationFilter", "validationErrors": { "sourceChainId": "sourceChainId must not be less than 1, sourceChainId should not be empty, sourceChainId must be an integer number, sourceChainId must be a number conforming to the specified constraints" } } } } }, "404": { "description": "No quoted deposit address at this address on the requested source chain.", "content": { "application/json": { "example": { "statusCode": 404, "createdBy": "HttpExceptionFilter", "details": { "message": "No quoted gateway intent found for vault 0x379BAB257e7Eb159538F01165B766A1BEaf2D954", "error": "Not Found", "statusCode": 404 } } } } }, "401": { "description": "The supplied x-api-key is unknown, revoked, or not enabled for the v1 API. Returned for every v1 endpoint by the gateway, with Content-Type application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "98e4c42f-9c70-4539-843e-8d31803001e6" } } } }, "403": { "description": "Access denied." }, "429": { "description": "Rate limit; honor Retry-After when supplied." }, "500": { "description": "Service failure; preserve identifiers before retrying." } }, "security": [], "x-audience": "anonymous" } }, "/v1/circle-gateway/deposit-addresses/submit/erc-3009": { "post": { "operationId": "gateway-submit-erc-3009", "summary": "Initiate a gasless deposit with ERC-3009", "tags": [ "circle-gateway" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chainId": { "type": "integer", "exclusiveMinimum": 0 }, "authorization": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "value": { "type": "string", "maxLength": 78 }, "validAfter": { "type": "string", "maxLength": 78 }, "validBefore": { "type": "string", "maxLength": 78 }, "nonce": { "type": "string" } }, "required": [ "from", "to", "value", "validAfter", "validBefore", "nonce" ] }, "signature": { "type": "string", "minLength": 130, "maxLength": 132 }, "target": { "type": "object", "properties": { "depositAddress": { "type": "string" } }, "required": [ "depositAddress" ], "additionalProperties": false } }, "required": [ "chainId", "authorization", "signature", "target" ] }, "examples": { "vault-target": { "summary": "Fund the deposit address above with ERC-3009; authorization.to must equal target.depositAddress (placeholder signature)", "value": { "chainId": 8453, "target": { "depositAddress": "0x379BAB257e7Eb159538F01165B766A1BEaf2D954" }, "authorization": { "from": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "to": "0x379BAB257e7Eb159538F01165B766A1BEaf2D954", "value": "1000000", "validAfter": "0", "validBefore": "1789526504", "nonce": "0xbeadaa19d3a655b73b7bd81214d497f1b211a52168d1ef43788619daba97d274" }, "signature": "0xedc90fdd27654dd49ac1087901450c9c5fdf444943f61faa8d787bee86304d821f06a5db4a67eddf5cf286014d6ec8bd33c64f9e072045a9f3c5e50cc28960fc1b" } } } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "published", "partial", "failed", "unknown" ] }, "signatureHash": { "type": "string" }, "subStatuses": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "quoteIds": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "submitted", "published", "failed" ] } }, "required": [ "chainId", "quoteIds", "txHash", "intentHashes", "state" ] } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } }, "required": [ "id", "status", "signatureHash", "subStatuses", "createdAt", "updatedAt" ] }, "examples": { "job": { "summary": "New gasless job accepted", "value": { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "status": "processing", "signatureHash": "0x94245dddfb2339e6e06fe251c90de895bf2995ff3c5a5fb185390f1850ed6726", "subStatuses": [ { "chainId": 8453, "quoteIds": [ "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" ], "txHash": null, "intentHashes": [], "state": "pending" } ], "createdAt": 1789522604, "updatedAt": 1789522614 } } } } } }, "default": { "description": "Error (RFC 9457 problem+json; see x-error-catalog)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "200": { "description": "Existing job for the same signature and target.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "published", "partial", "failed", "unknown" ] }, "signatureHash": { "type": "string" }, "subStatuses": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "quoteIds": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "submitted", "published", "failed" ] } }, "required": [ "chainId", "quoteIds", "txHash", "intentHashes", "state" ] } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } }, "required": [ "id", "status", "signatureHash", "subStatuses", "createdAt", "updatedAt" ] }, "examples": { "job": { "summary": "Same signature resent: the existing job", "value": { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "status": "published", "signatureHash": "0x94245dddfb2339e6e06fe251c90de895bf2995ff3c5a5fb185390f1850ed6726", "subStatuses": [ { "chainId": 8453, "quoteIds": [ "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" ], "txHash": "0x3ef97346fd076aadb54c851f33ba9234feb34d27442b9bb0abc7a0d75827af13", "intentHashes": [ "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749" ], "state": "published" } ], "createdAt": 1789522604, "updatedAt": 1789522654 } } } } } }, "400": { "description": "Request failed validation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "detail": "chainId: Invalid input: expected number, received undefined; authorization: Invalid input: expected object, received undefined; signature: Invalid input: expected string, received undefined; target: Invalid input", "errors": [ { "field": "chainId", "detail": "Invalid input: expected number, received undefined" }, { "field": "authorization", "detail": "Invalid input: expected object, received undefined" }, { "field": "signature", "detail": "Invalid input: expected string, received undefined" }, { "field": "target", "detail": "Invalid input" } ], "requestId": "f371e43e6fd4406b10e19487b3170edf" } } } }, "401": { "description": "The supplied x-api-key is unknown, revoked, or not enabled for the v1 API. Returned for every v1 endpoint by the gateway, with Content-Type application/json. Submit endpoints also answer 401 from the API itself, as application/problem+json: `invalid-signature` when the signature does not recover to the expected signer, `authorization-expired` when its validity window has passed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "98e4c42f-9c70-4539-843e-8d31803001e6" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-signature": { "summary": "Live: signature does not verify", "value": { "type": "https://api.eco.com/v1/errors/invalid-signature", "title": "Signature verification failed", "status": 401, "code": "invalid-signature", "requestId": "4ece761247bfc14267057f95ee3071bc", "legacyCode": "eco-quotes:1003" } } } } } }, "403": { "description": "Access denied for the supplied key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/permission-denied", "title": "The caller may not perform this operation", "status": 403, "code": "permission-denied", "requestId": "a9a151aa45c9dbf44c78513905f6606a" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded", "requestId": "1eac3d6cc2aafa524b0c47a039576f8c" } } } }, "500": { "description": "Internal error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal-error", "requestId": "02dabcf0f4e3def9a6091526d3d21022" } } } }, "422": { "description": "Chain is not supported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/chain-not-supported", "title": "Chain is not supported", "status": 422, "code": "chain-not-supported", "requestId": "252dbcdeebe5465fdc089843e8643b37" } } } }, "409": { "description": "This signature is already pinned to a different target", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/signature-already-bound", "title": "This signature is already pinned to a different target", "status": 409, "code": "signature-already-bound", "requestId": "3ff33e83251b3cdb7d3daf15d186b89b" } } } }, "410": { "description": "The quote is unknown or expired at submit time", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/quote-expired", "title": "The quote is unknown or expired at submit time", "status": 410, "code": "quote-expired", "requestId": "19ff8aa0914e6fbe2fcb7fbe930bf0ea" } } } } }, "security": [], "description": "Funds a deposit address gaslessly with a signed ERC-3009 `transferWithAuthorization`. `target.depositAddress` must equal `authorization.to`. The first submission answers `202` with a gasless job; resending the same signature returns the existing job with `200`.\n\nNo API key is required: Circle Gateway operations are open so that any wallet or relay can create and fund a deposit address. A supplied key that is unknown, revoked, or not enabled for v1 is still rejected with `401 invalid-api-key`, so send no key rather than a wrong one.\n\nNo requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.\n\nExamples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.", "x-audience": "anonymous", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. A key that is unknown, revoked, or not enabled for v1 is rejected with 401." } ] } }, "/v1/circle-gateway/deposit-addresses/submit/erc-2612": { "post": { "operationId": "gateway-submit-erc-2612", "summary": "Initiate a gasless deposit with EIP-2612", "tags": [ "circle-gateway" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chainId": { "type": "integer", "exclusiveMinimum": 0 }, "target": { "type": "object", "properties": { "depositAddress": { "type": "string" } }, "required": [ "depositAddress" ], "additionalProperties": false }, "permit": { "type": "object", "properties": { "owner": { "type": "string" }, "spender": { "type": "string" }, "value": { "type": "string", "maxLength": 78 }, "nonce": { "type": "string", "maxLength": 78 }, "deadline": { "type": "integer", "minimum": 0 } }, "required": [ "owner", "spender", "value", "nonce", "deadline" ] }, "signature": { "type": "string", "minLength": 130, "maxLength": 132 } }, "required": [ "chainId", "target", "permit", "signature" ] }, "examples": { "vault-target": { "summary": "Fund the deposit address above with an EIP-2612 permit; permit.spender must equal target.depositAddress (placeholder signature)", "value": { "chainId": 8453, "target": { "depositAddress": "0x379BAB257e7Eb159538F01165B766A1BEaf2D954" }, "permit": { "owner": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266", "spender": "0x379BAB257e7Eb159538F01165B766A1BEaf2D954", "value": "1000000", "nonce": "0", "deadline": 1789526504 }, "signature": "0xedc90fdd27654dd49ac1087901450c9c5fdf444943f61faa8d787bee86304d821f06a5db4a67eddf5cf286014d6ec8bd33c64f9e072045a9f3c5e50cc28960fc1b" } } } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "published", "partial", "failed", "unknown" ] }, "signatureHash": { "type": "string" }, "subStatuses": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "quoteIds": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "submitted", "published", "failed" ] } }, "required": [ "chainId", "quoteIds", "txHash", "intentHashes", "state" ] } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } }, "required": [ "id", "status", "signatureHash", "subStatuses", "createdAt", "updatedAt" ] }, "examples": { "job": { "summary": "New gasless job accepted", "value": { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "status": "processing", "signatureHash": "0x94245dddfb2339e6e06fe251c90de895bf2995ff3c5a5fb185390f1850ed6726", "subStatuses": [ { "chainId": 8453, "quoteIds": [ "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" ], "txHash": null, "intentHashes": [], "state": "pending" } ], "createdAt": 1789522604, "updatedAt": 1789522614 } } } } } }, "default": { "description": "Error (RFC 9457 problem+json; see x-error-catalog)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "200": { "description": "Existing job for the same signature and target.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "published", "partial", "failed", "unknown" ] }, "signatureHash": { "type": "string" }, "subStatuses": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "quoteIds": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "submitted", "published", "failed" ] } }, "required": [ "chainId", "quoteIds", "txHash", "intentHashes", "state" ] } }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } }, "required": [ "id", "status", "signatureHash", "subStatuses", "createdAt", "updatedAt" ] }, "examples": { "job": { "summary": "Same signature resent: the existing job", "value": { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "status": "published", "signatureHash": "0x94245dddfb2339e6e06fe251c90de895bf2995ff3c5a5fb185390f1850ed6726", "subStatuses": [ { "chainId": 8453, "quoteIds": [ "quote:8a7cbdcd-2aed-40b0-ab08-c4c10af15f23" ], "txHash": "0x3ef97346fd076aadb54c851f33ba9234feb34d27442b9bb0abc7a0d75827af13", "intentHashes": [ "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749" ], "state": "published" } ], "createdAt": 1789522604, "updatedAt": 1789522654 } } } } } }, "400": { "description": "Request failed validation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-request", "title": "Request failed validation", "status": 400, "code": "invalid-request", "detail": "chainId: Invalid input: expected number, received undefined; target: Invalid input: expected object, received undefined; permit: Invalid input: expected object, received undefined; signature: Invalid input: expected string, received undefined", "errors": [ { "field": "chainId", "detail": "Invalid input: expected number, received undefined" }, { "field": "target", "detail": "Invalid input: expected object, received undefined" }, { "field": "permit", "detail": "Invalid input: expected object, received undefined" }, { "field": "signature", "detail": "Invalid input: expected string, received undefined" } ], "requestId": "f371e43e6fd4406b10e19487b3170edf" } } } }, "401": { "description": "The supplied x-api-key is unknown, revoked, or not enabled for the v1 API. Returned for every v1 endpoint by the gateway, with Content-Type application/json. Submit endpoints also answer 401 from the API itself, as application/problem+json: `invalid-signature` when the signature does not recover to the expected signer, `authorization-expired` when its validity window has passed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "98e4c42f-9c70-4539-843e-8d31803001e6" } }, "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid-signature": { "summary": "Live: signature does not verify", "value": { "type": "https://api.eco.com/v1/errors/invalid-signature", "title": "Signature verification failed", "status": 401, "code": "invalid-signature", "requestId": "4ece761247bfc14267057f95ee3071bc", "legacyCode": "eco-quotes:1003" } } } } } }, "403": { "description": "Access denied for the supplied key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/permission-denied", "title": "The caller may not perform this operation", "status": 403, "code": "permission-denied", "requestId": "a9a151aa45c9dbf44c78513905f6606a" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded", "requestId": "1eac3d6cc2aafa524b0c47a039576f8c" } } } }, "500": { "description": "Internal error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal-error", "requestId": "02dabcf0f4e3def9a6091526d3d21022" } } } }, "422": { "description": "Chain is not supported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/chain-not-supported", "title": "Chain is not supported", "status": 422, "code": "chain-not-supported", "requestId": "252dbcdeebe5465fdc089843e8643b37" } } } }, "409": { "description": "This signature is already pinned to a different target", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/signature-already-bound", "title": "This signature is already pinned to a different target", "status": 409, "code": "signature-already-bound", "requestId": "3ff33e83251b3cdb7d3daf15d186b89b" } } } }, "410": { "description": "The quote is unknown or expired at submit time", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/quote-expired", "title": "The quote is unknown or expired at submit time", "status": 410, "code": "quote-expired", "requestId": "19ff8aa0914e6fbe2fcb7fbe930bf0ea" } } } } }, "security": [], "description": "Funds a deposit address gaslessly with a signed EIP-2612 permit. `target.depositAddress` must equal `permit.spender`. The first submission answers `202` with a gasless job; resending the same signature returns the existing job with `200`.\n\nNo API key is required: Circle Gateway operations are open so that any wallet or relay can create and fund a deposit address. A supplied key that is unknown, revoked, or not enabled for v1 is still rejected with `401 invalid-api-key`, so send no key rather than a wrong one.\n\nNo requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.\n\nExamples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.", "x-audience": "anonymous", "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. A key that is unknown, revoked, or not enabled for v1 is rejected with 401." } ] } }, "/v1/circle-gateway/deposit-addresses/status": { "get": { "operationId": "gateway-status", "summary": "Track a gasless deposit job", "tags": [ "circle-gateway" ], "parameters": [ { "name": "x-api-key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Optional. A key that is unknown, revoked, or not enabled for v1 is rejected with 401." }, { "name": "address", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The deposit address to track.", "example": "0x379BAB257e7Eb159538F01165B766A1BEaf2D954" }, { "name": "jobId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The gasless funding job to track, as a bare UUID or a 24-character legacy job ID, without the `gasless:` prefix.", "example": "0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Opaque cursor from a previous `nextCursor`." }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Page size, 1-50. Default 20." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "intent", "quote", "gasless", "deposit-address" ] }, "status": { "type": "string" }, "updatedAt": { "type": [ "integer", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "subStatuses": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "quoteIds": { "type": "array", "items": { "type": "string" } }, "txHash": { "type": [ "string", "null" ] }, "intentHashes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string", "enum": [ "pending", "submitted", "published", "failed" ] } }, "required": [ "chainId", "quoteIds", "txHash", "intentHashes", "state" ] } }, "sourceTx": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": "string" }, "token": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "chainId", "txHash", "token", "amount" ] }, "destinationTx": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": "string" }, "token": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "chainId", "txHash", "token", "amount" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SWAP", "BRIDGE" ] }, "intentHash": { "type": "string" }, "status": { "type": "string" }, "from": { "type": "object", "properties": { "token": { "type": "string" }, "amount": { "type": "string" }, "chainId": { "type": "integer" } }, "required": [ "token", "amount", "chainId" ] }, "to": { "type": "object", "properties": { "token": { "type": "string" }, "amount": { "type": "string" }, "chainId": { "type": "integer" } }, "required": [ "token", "amount", "chainId" ] }, "transactions": { "type": "object", "properties": { "created": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": "string" } }, "required": [ "chainId", "txHash" ] }, "fulfilled": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": "string" } }, "required": [ "chainId", "txHash" ] }, "refunded": { "type": "object", "properties": { "chainId": { "type": "integer" }, "txHash": { "type": "string" } }, "required": [ "chainId", "txHash" ] } } } }, "required": [ "type", "intentHash", "status", "from", "to", "transactions" ] } } }, "required": [ "id", "type", "status", "updatedAt" ] } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "results", "nextCursor" ] }, "examples": { "job-completed": { "summary": "A gasless funding job that landed on chain", "value": { "results": [ { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "type": "gasless", "status": "published", "updatedAt": 1789522704, "intentHashes": [ "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749" ], "subStatuses": [ { "chainId": 8453, "quoteIds": [], "txHash": "0x3ef97346fd076aadb54c851f33ba9234feb34d27442b9bb0abc7a0d75827af13", "intentHashes": [ "0x3f1886e7c3a4cab62b4a0661e393600f0917d5a514652e96623b0f17ce0d3749" ], "state": "published" } ] } ], "nextCursor": null } }, "address-unknown": { "summary": "Live: a deposit address the service has not seen (still 200)", "value": { "results": [ { "id": "deposit-address:0x379BAB257e7Eb159538F01165B766A1BEaf2D954", "type": "deposit-address", "status": "unknown", "updatedAt": null } ], "nextCursor": null } }, "job-unknown": { "summary": "Live: a job ID the service has not seen (still 200)", "value": { "results": [ { "id": "gasless:0f450218-1b2c-4d3e-8f9a-0b1c2d3e4f5a", "type": "gasless", "status": "unknown", "updatedAt": null } ], "nextCursor": null } } } } } }, "default": { "description": "Error (RFC 9457 problem+json; see x-error-catalog)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "400": { "description": "Request failed validation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/missing-parameter", "title": "A required parameter is missing", "status": 400, "code": "missing-parameter", "detail": "at least one filter required (address, jobId); paging controls alone are not a filter", "requestId": "180e4b3e4bfeff1dec42814b33e66dba" } } } }, "401": { "description": "The supplied x-api-key is unknown, revoked, or not enabled for the v1 API. Returned for every v1 endpoint by the gateway, with Content-Type application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/invalid-api-key", "title": "API key is missing, unknown, or revoked", "status": 401, "code": "invalid-api-key", "requestId": "98e4c42f-9c70-4539-843e-8d31803001e6" } } } }, "403": { "description": "Access denied for the supplied key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/permission-denied", "title": "The caller may not perform this operation", "status": 403, "code": "permission-denied", "requestId": "a9a151aa45c9dbf44c78513905f6606a" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/rate-limit-exceeded", "title": "Rate limit exceeded", "status": 429, "code": "rate-limit-exceeded", "requestId": "1eac3d6cc2aafa524b0c47a039576f8c" } } } }, "500": { "description": "Internal error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "https://api.eco.com/v1/errors/internal-error", "title": "Internal error", "status": 500, "code": "internal-error", "requestId": "02dabcf0f4e3def9a6091526d3d21022" } } } } }, "security": [], "description": "Returns the state of a deposit address (`address`) or a gasless funding job (`jobId`). One filter is required. Always `200`; an unknown address or job is reported with `status: \"unknown\"`. Job status covers the funding transaction; the deposit lookup covers the deposit itself.\n\nNo API key is required: Circle Gateway operations are open so that any wallet or relay can create and fund a deposit address. A supplied key that is unknown, revoked, or not enabled for v1 is still rejected with `401 invalid-api-key`, so send no key rather than a wrong one.\n\nNo requests-per-second quota is published. Handle `429` and honor `Retry-After` when present.\n\nExamples use real mainnet token and contract addresses with placeholder wallets, hashes, signatures, and IDs.", "x-audience": "anonymous" } } }, "components": { "schemas": { "Problem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string", "minLength": 1 }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "code": { "type": "string", "description": "Stable, machine-readable error code from the catalog. Branch on this and `status`, not on `title` or `detail`." }, "detail": { "type": "string" }, "instance": { "type": "string" }, "legacyCode": { "type": "string", "description": "The pre-v1 numeric error code this problem maps to, for integrations migrating from the older services." }, "solverErrors": { "type": "array", "items": { "type": "object", "properties": { "solver": { "type": "string", "description": "Address on the relevant chain: `0x\u2026` hex for EVM chains, base58 for Solana, `T\u2026` base58 for Tron." }, "solverName": { "type": "string", "minLength": 1 }, "code": { "type": "string", "minLength": 1 }, "message": { "type": "string" } }, "required": [ "solver", "message" ] } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1 }, "detail": { "type": "string", "minLength": 1 } }, "required": [ "field", "detail" ] }, "description": "Field-level validation failures." }, "requestId": { "type": "string", "description": "Correlation ID for support. Present on router-served errors; deposit-address-served errors carry a short numeric value." } }, "required": [ "type", "title", "status", "code" ] }, "EvmAddress": { "type": "string", "description": "EIP-55 / lowercase hex 20-byte address", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" }, "Hex32": { "type": "string", "description": "0x-prefixed 32-byte hex (64 hex chars)" }, "QuotedGatewayIntentState": { "type": "string", "description": "Current quoted gateway intent state. `PENDING`: vault created, waiting for funds. `FUNDING_DETECTED`: vault balance reached the quoted amount. `PUBLISHED`: deposit intent published onchain. `EXPIRED_UNFUNDED`: quote deadline passed without funding. `FAILED`, `REFUNDED_BY_USER`, `RECOVERY_PUBLISHED`: terminal recovery outcomes.", "enum": [ "PENDING", "FUNDING_DETECTED", "PUBLISHED", "FAILED", "REFUNDED_BY_USER", "RECOVERY_PUBLISHED", "EXPIRED_UNFUNDED" ] }, "CircleGatewayDepositAddressDTO": { "type": "object", "required": [ "sourceChainId", "amount", "recipient", "depositor" ], "properties": { "sourceChainId": { "type": "integer", "minimum": 1, "example": 8453, "description": "Source chain of the deposit." }, "amount": { "type": "string", "description": "Required positive integer source-chain USDC amount in base units. Must fit uint256.", "example": "1000000" }, "recipient": { "$ref": "#/components/schemas/EvmAddress", "description": "Gateway depositFor target on the destination chain." }, "depositor": { "$ref": "#/components/schemas/EvmAddress", "description": "Address that will fund the vault." }, "refundRecipient": { "$ref": "#/components/schemas/EvmAddress", "description": "Address that receives expiry refunds. Defaults to depositor." } } }, "CircleGatewayDepositAddressResponseDTO": { "type": "object", "required": [ "vaultAddress", "amount", "deadline" ], "properties": { "vaultAddress": { "$ref": "#/components/schemas/EvmAddress", "description": "Vault address on the source chain." }, "amount": { "type": "string", "description": "Requested source-chain USDC amount in base units.", "example": "1000000" }, "deadline": { "type": "number", "description": "Unix seconds quote deadline.", "example": 1798915200 } } }, "CircleGatewayDepositAddressStatusResponseDTO": { "type": "object", "required": [ "vaultAddress", "amount", "deadline", "state", "intentHash", "sourceChainId" ], "properties": { "vaultAddress": { "$ref": "#/components/schemas/EvmAddress", "description": "Vault address on the source chain." }, "amount": { "type": "string", "description": "Requested source-chain USDC amount in base units.", "example": "1000000" }, "deadline": { "type": "number", "description": "Unix seconds quote deadline.", "example": 1798915200 }, "state": { "$ref": "#/components/schemas/QuotedGatewayIntentState" }, "intentHash": { "$ref": "#/components/schemas/Hex32", "description": "Intent hash for this quoted vault, assigned at quote creation and preserved through publish." }, "sourceChainId": { "type": "number", "description": "Source chain ID where the vault is funded.", "example": 8453 }, "stitched": { "type": "object", "required": [ "finalDestinationChainID", "destinationIntentHash" ], "description": "Present for stitched deposits. PUBLISHED is source-leg publication, not destination delivery.", "properties": { "finalDestinationChainID": { "type": "integer", "example": 42161 }, "destinationIntentHash": { "$ref": "#/components/schemas/Hex32" } } } } } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" } } }, "x-error-catalog": [ { "code": "invalid-request", "status": 400, "title": "Request failed validation", "type": "https://api.eco.com/v1/errors/invalid-request" }, { "code": "missing-parameter", "status": 400, "title": "A required parameter is missing", "type": "https://api.eco.com/v1/errors/missing-parameter" }, { "code": "invalid-parameter", "status": 400, "title": "A parameter value is invalid", "type": "https://api.eco.com/v1/errors/invalid-parameter" }, { "code": "slippage-out-of-bounds", "status": 400, "title": "slippage is outside the valid 0.0001-1 range; it is a decimal fraction (0.005 = 0.5%), not a percent (0.5 means 50%)", "type": "https://api.eco.com/v1/errors/slippage-out-of-bounds" }, { "code": "deposit-address-mismatch", "status": 400, "title": "The signed counterparty does not equal target.depositAddress", "type": "https://api.eco.com/v1/errors/deposit-address-mismatch" }, { "code": "vault-mismatch", "status": 400, "title": "The signed counterparty does not equal the quote's intent vault (execution.vault)", "type": "https://api.eco.com/v1/errors/vault-mismatch" }, { "code": "invalid-signature", "status": 401, "title": "Signature verification failed", "type": "https://api.eco.com/v1/errors/invalid-signature" }, { "code": "authorization-expired", "status": 401, "title": "The signed authorization window has expired", "type": "https://api.eco.com/v1/errors/authorization-expired" }, { "code": "invalid-api-key", "status": 401, "title": "API key is missing, unknown, or revoked", "type": "https://api.eco.com/v1/errors/invalid-api-key" }, { "code": "api-key-expired", "status": 401, "title": "API key has expired", "type": "https://api.eco.com/v1/errors/api-key-expired" }, { "code": "permission-denied", "status": 403, "title": "The caller may not perform this operation", "type": "https://api.eco.com/v1/errors/permission-denied" }, { "code": "funder-mismatch", "status": 403, "title": "The quote funder does not match the recovered signer", "type": "https://api.eco.com/v1/errors/funder-mismatch" }, { "code": "token-not-found", "status": 404, "title": "Token is unknown on the requested chain", "type": "https://api.eco.com/v1/errors/token-not-found" }, { "code": "endpoint-not-found", "status": 404, "title": "No /v1 endpoint exists at this path \u2014 check the path and the version segment", "type": "https://api.eco.com/v1/errors/endpoint-not-found" }, { "code": "method-not-allowed", "status": 405, "title": "The HTTP method is not allowed on this path \u2014 check the method for this endpoint", "type": "https://api.eco.com/v1/errors/method-not-allowed" }, { "code": "signature-already-bound", "status": 409, "title": "This signature is already pinned to a different target", "type": "https://api.eco.com/v1/errors/signature-already-bound" }, { "code": "nonce-used", "status": 409, "title": "The nonce is already consumed on-chain", "type": "https://api.eco.com/v1/errors/nonce-used" }, { "code": "quote-expired", "status": 410, "title": "The quote is unknown or expired at submit time", "type": "https://api.eco.com/v1/errors/quote-expired" }, { "code": "request-too-large", "status": 413, "title": "The request exceeds the maximum accepted size \u2014 reduce the body or the number of parameters", "type": "https://api.eco.com/v1/errors/request-too-large" }, { "code": "unsupported-media-type", "status": 415, "title": "The request media type, charset, or content encoding is not supported \u2014 send application/json as unencoded utf-8", "type": "https://api.eco.com/v1/errors/unsupported-media-type" }, { "code": "no-route-found", "status": 422, "title": "No solver can serve the requested route", "type": "https://api.eco.com/v1/errors/no-route-found" }, { "code": "token-not-supported", "status": 422, "title": "Token is not supported for this operation", "type": "https://api.eco.com/v1/errors/token-not-supported" }, { "code": "simulation-failed", "status": 422, "title": "Fulfillment simulation of the call-bearing quote failed", "type": "https://api.eco.com/v1/errors/simulation-failed" }, { "code": "insufficient-funds", "status": 422, "title": "The signer balance cannot cover the transfer", "type": "https://api.eco.com/v1/errors/insufficient-funds" }, { "code": "chain-not-supported", "status": 422, "title": "Chain is not supported", "type": "https://api.eco.com/v1/errors/chain-not-supported" }, { "code": "chain-pair-unsupported", "status": 422, "title": "This source/destination pair is not available", "type": "https://api.eco.com/v1/errors/chain-pair-unsupported" }, { "code": "amount-too-low", "status": 422, "title": "Amount is below the minimum transfer threshold", "type": "https://api.eco.com/v1/errors/amount-too-low" }, { "code": "amount-too-high", "status": 422, "title": "Amount exceeds the configured maximum order size (not a liquidity shortfall \u2014 see insufficient-liquidity)", "type": "https://api.eco.com/v1/errors/amount-too-high" }, { "code": "insufficient-liquidity", "status": 422, "title": "The route cannot fill an order this size", "type": "https://api.eco.com/v1/errors/insufficient-liquidity" }, { "code": "insufficient-balance", "status": 422, "title": "The wallet balance cannot cover the amount", "type": "https://api.eco.com/v1/errors/insufficient-balance" }, { "code": "insufficient-allowance", "status": 422, "title": "The permit or approval is insufficient", "type": "https://api.eco.com/v1/errors/insufficient-allowance" }, { "code": "insufficient-gas", "status": 422, "title": "Not enough native token to cover gas", "type": "https://api.eco.com/v1/errors/insufficient-gas" }, { "code": "unsupported-authorization", "status": 422, "title": "The token does not implement this signature standard \u2014 check /v1/tokens supports[]", "type": "https://api.eco.com/v1/errors/unsupported-authorization" }, { "code": "permit2-approval-missing", "status": 422, "title": "permit2 requires a prior approve() to the Permit2 contract", "type": "https://api.eco.com/v1/errors/permit2-approval-missing" }, { "code": "rate-limit-exceeded", "status": 429, "title": "Rate limit exceeded", "type": "https://api.eco.com/v1/errors/rate-limit-exceeded" }, { "code": "internal-error", "status": 500, "title": "Internal error", "type": "https://api.eco.com/v1/errors/internal-error" }, { "code": "solver-timeout", "status": 502, "title": "Upstream solver quote fan-out timed out", "type": "https://api.eco.com/v1/errors/solver-timeout" }, { "code": "solver-error", "status": 502, "title": "An upstream solver rejected or failed the quote request", "type": "https://api.eco.com/v1/errors/solver-error" }, { "code": "service-unavailable", "status": 503, "title": "Service temporarily unavailable", "type": "https://api.eco.com/v1/errors/service-unavailable" } ], "servers": [ { "url": "https://api.eco.com", "description": "Eco API" } ] }