diff --git a/orchestrator.json b/orchestrator.json index e4ee9a2..8b68c3a 100644 --- a/orchestrator.json +++ b/orchestrator.json @@ -27,13 +27,6 @@ "description": "API version (YYYY-MM.name). Will become required in a future release.", "example": "2026-01.alps" } - }, - { - "name": "x-feature-flags", - "in": "header", - "schema": { - "type": "string" - } } ], "requestBody": { @@ -129,7 +122,7 @@ "type": "string", "pattern": "^0x[a-fA-F0-9]*$" }, - "description": "Per-chain SSX mock signatures for gas estimation. Keys are chain IDs as decimal strings. The special key `\"0\"` is a cross-chain fallback applied when no specific chain entry matches." + "description": "Per-chain stub signatures used only during gas estimation. Required for smart-session flows where the real signature length depends on session policy — the orchestrator needs a same-shape placeholder to simulate the verification cost. Keys are chain IDs as decimal strings; `\"0\"` is a cross-chain fallback applied when no chain-specific entry matches." }, "delegations": { "type": "object", @@ -485,7 +478,7 @@ "type": "string", "pattern": "^0x[a-fA-F0-9]*$" }, - "description": "Per-chain SSX mock signatures for gas estimation. Keys are chain IDs as decimal strings. The special key `\"0\"` is a cross-chain fallback applied when no specific chain entry matches." + "description": "Per-chain stub signatures used only during gas estimation. Required for smart-session flows where the real signature length depends on session policy — the orchestrator needs a same-shape placeholder to simulate the verification cost. Keys are chain IDs as decimal strings; `\"0\"` is a cross-chain fallback applied when no chain-specific entry matches." }, "delegations": { "type": "object", @@ -525,7 +518,7 @@ "CCTP" ] }, - "description": "The settlement layer to be used to settle intents", + "description": "Allow-list filter on which settlement layers the orchestrator may use for this quote. Default is unset (all supported layers are eligible). Use this to opt out of layers you don't want — e.g. `[ECO]` will only consider Eco-routed quotes.", "example": [ "ECO" ] @@ -575,7 +568,7 @@ 5, 6 ], - "description": "The signature mode to be used", + "description": "How the user's intent signature will be verified onchain. `ECDSA` for plain EOA signatures; `ERC1271_EMISSARY` for smart-account signatures verified via TheCompact emissary delegation. The orchestrator picks a default based on `account.accountType` — only set this if you need to override.", "example": 3 }, "feeToken": { @@ -605,7 +598,8 @@ "WTRX", "SOL", "WSOL" - ] + ], + "description": "Reserved for future use. No effect today." }, "executionTokensReceived": { "type": "array", @@ -626,7 +620,7 @@ "format": "uint256" } }, - "description": "Additional token balances to consider during route finding Object keyed by CAIP-2 chain identifier (e.g. `eip155:42161`).", + "description": "Additional balances the quote should treat as available, beyond what is currently on the account. Use this to get a preliminary quote against funds you can produce by the time you submit — e.g. liquidity in a DeFi vault you will withdraw, an in-flight CEX deposit, or a parallel transfer from another wallet. Keyed by chain ID, then token address; amounts in the token's smallest unit. Object keyed by CAIP-2 chain identifier (e.g. `eip155:42161`).", "example": { "eip155:42161": { "0xaf88d065e77c8cC2239327C5EDb3A432268e5831": "500000000" @@ -1188,14 +1182,17 @@ "type": "string", "enum": [ "approval" - ] + ], + "description": "Discriminator: `approval` means the user must ERC-20 approve `spender` for at least `amount` before submission." }, "amount": { "type": "string", - "format": "uint256" + "format": "uint256", + "description": "Minimum required allowance, in the token's smallest unit." }, "spender": { - "type": "string" + "type": "string", + "description": "Always the canonical Permit2 contract on this chain. The EOA approves Permit2; the settlement contract pulls funds via Permit2 at claim time." } }, "required": [ @@ -1211,11 +1208,13 @@ "type": "string", "enum": [ "wrap" - ] + ], + "description": "Discriminator: `wrap` means the user must wrap native ETH into the chain's WETH-equivalent before submission." }, "amount": { "type": "string", - "format": "uint256" + "format": "uint256", + "description": "Minimum amount to wrap, in wei." } }, "required": [ @@ -1226,7 +1225,16 @@ ] } }, - "description": "Token approvals / wrapping required before submission. Emitted for EOAs only; smart accounts handle approvals internally. Object keyed by CAIP-2 chain identifier (e.g. `eip155:42161`)." + "description": "Pre-flight token operations the user must perform before submitting this route (approvals, wrapping). Emitted for EOA accounts only — smart accounts handle these internally. Object keyed by CAIP-2 chain identifier (e.g. `eip155:42161`).", + "example": { + "eip155:8453": { + "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913": { + "type": "approval", + "amount": "1000000", + "spender": "0x000000000022d473030f116ddee9f6b43ac78ba3" + } + } + } }, "bridgeFill": { "discriminator": { @@ -1242,12 +1250,17 @@ "description": "Destination chain ID for the bridge fill", "example": "eip155:42161" }, + "fillExpirationPeriod": { + "type": "integer", + "minimum": 0, + "description": "Optional bridge-specific fill deadline duration, in seconds. Preserved on stored quote reload so checksum validation uses the same bridgeFill payload that was signed at quote time." + }, "type": { "type": "string", "enum": [ "OFT" ], - "description": "Bridge type" + "description": "LayerZero OFT" } }, "required": [ @@ -1264,16 +1277,21 @@ "description": "Destination chain ID for the bridge fill", "example": "eip155:42161" }, + "fillExpirationPeriod": { + "type": "integer", + "minimum": 0, + "description": "Optional bridge-specific fill deadline duration, in seconds. Preserved on stored quote reload so checksum validation uses the same bridgeFill payload that was signed at quote time." + }, "type": { "type": "string", "enum": [ "RELAY" ], - "description": "Bridge type" + "description": "Relay.link" }, "requestId": { "type": "string", - "description": "Relay API request ID" + "description": "Relay.link request ID. Use against Relay.link's status API to track the destination-chain fill." } }, "required": [ @@ -1291,16 +1309,21 @@ "description": "Destination chain ID for the bridge fill", "example": "eip155:42161" }, + "fillExpirationPeriod": { + "type": "integer", + "minimum": 0, + "description": "Optional bridge-specific fill deadline duration, in seconds. Preserved on stored quote reload so checksum validation uses the same bridgeFill payload that was signed at quote time." + }, "type": { "type": "string", "enum": [ "NEAR" ], - "description": "Bridge type" + "description": "NEAR Intents" }, "depositAddress": { "type": "string", - "description": "NEAR 1Click deposit address for status tracking" + "description": "NEAR Intents deposit address. Track fill status via the NEAR Intents status API keyed on this address." } }, "required": [ @@ -1318,16 +1341,21 @@ "description": "Destination chain ID for the bridge fill", "example": "eip155:42161" }, + "fillExpirationPeriod": { + "type": "integer", + "minimum": 0, + "description": "Optional bridge-specific fill deadline duration, in seconds. Preserved on stored quote reload so checksum validation uses the same bridgeFill payload that was signed at quote time." + }, "type": { "type": "string", "enum": [ "RHINO" ], - "description": "Bridge type" + "description": "Rhino.fi" }, "commitmentId": { "type": "string", - "description": "Rhino.fi commitment ID (hex ObjectId) for fill tracking" + "description": "Rhino.fi commitment ID. Use against Rhino.fi's status API to track the destination-chain fill." } }, "required": [ @@ -1345,20 +1373,25 @@ "description": "Destination chain ID for the bridge fill", "example": "eip155:42161" }, + "fillExpirationPeriod": { + "type": "integer", + "minimum": 0, + "description": "Optional bridge-specific fill deadline duration, in seconds. Preserved on stored quote reload so checksum validation uses the same bridgeFill payload that was signed at quote time." + }, "type": { "type": "string", "enum": [ "CCTP" ], - "description": "Bridge type" + "description": "Circle CCTP" }, "sourceDomainId": { "type": "number", - "description": "CCTP source domain ID" + "description": "Circle CCTP source domain ID — needed to fetch the attestation for the burn message on the source chain." }, "destinationDomainId": { "type": "number", - "description": "CCTP destination domain ID" + "description": "Circle CCTP destination domain ID." } }, "required": [ @@ -1382,7 +1415,7 @@ ], "description": "A single ranked route candidate" }, - "description": "Pre-ranked route candidates (first entry is the recommended route)" + "description": "Route candidates ranked by the orchestrator's internal scoring (cheaper + faster wins). The first entry is the recommended route — most clients should submit it without inspecting the rest." } }, "required": [ @@ -1416,11 +1449,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -1447,8 +1475,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -1465,11 +1492,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -1500,8 +1522,93 @@ }, "required": [ "code", - "message", - "traceId" + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" ] }, { @@ -1527,17 +1634,11 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ], @@ -1546,8 +1647,8 @@ } } }, - "500": { - "description": "500", + "403": { + "description": "403", "content": { "application/json": { "schema": { @@ -1569,11 +1670,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -1600,8 +1696,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -1618,11 +1713,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -1653,8 +1743,93 @@ }, "required": [ "code", - "message", - "traceId" + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" ] }, { @@ -1680,151 +1855,21 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ], - "description": "Server error" + "description": "API key scope denied" } } } - } - } - } - }, - "/intents/splits": { - "post": { - "description": "Splits token amounts into multiple intents based on available relayer liquidity. Each returned intent can be filled by a single relayer.", - "summary": "Split Intent by Liquidity", - "tags": [ - "Intents" - ], - "parameters": [ - { - "name": "x-api-key", - "in": "header", - "required": true, - "schema": { - "type": "string", - "description": "Rhinestone API key" - } }, - { - "name": "x-api-version", - "in": "header", - "schema": { - "type": "string", - "pattern": "^\\d{4}-\\d{2}\\.[a-z0-9]+$", - "description": "API version (YYYY-MM.name). Will become required in a future release.", - "example": "2026-01.alps" - } - } - ], - "requestBody": { - "description": "Body", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "chainId": { - "type": "string", - "pattern": "^eip155:\\d+$", - "description": "The destination chain ID", - "example": "eip155:42161" - }, - "tokens": { - "type": "object", - "additionalProperties": { - "type": "string", - "format": "uint256" - }, - "description": "Map of token addresses to amounts", - "example": { - "0xaf88d065e77c8cc2239327c5edb3a432268e5831": "5000000000000" - } - }, - "settlementLayers": { - "type": "array", - "items": { - "type": "string", - "enum": [ - "INTENT_EXECUTOR", - "SAME_CHAIN", - "ACROSS", - "ECO", - "RELAY", - "OFT", - "NEAR", - "RHINO", - "CCTP" - ] - }, - "description": "Optional array of settlement layers to filter by. If not provided, all layers are considered.", - "example": [ - "ACROSS", - "ECO" - ] - } - }, - "required": [ - "chainId", - "tokens" - ] - } - } - } - }, - "responses": { - "200": { - "description": "200", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "intents": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "description": "Array of intents, each mapping token addresses to amounts that can be filled by a single relayer", - "example": [ - { - "0xaf88d065e77c8cc2239327c5edb3a432268e5831": "2400000000000" - }, - { - "0xaf88d065e77c8cc2239327c5edb3a432268e5831": "1700000000000" - }, - { - "0xaf88d065e77c8cc2239327c5edb3a432268e5831": "900000000000" - } - ] - } - }, - "required": [ - "intents" - ], - "description": "Successfully split the intent by available liquidity" - } - } - } - }, - "400": { - "description": "400", + "500": { + "description": "500", "content": { "application/json": { "schema": { @@ -1846,11 +1891,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -1877,8 +1917,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -1895,11 +1934,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -1930,8 +1964,93 @@ }, "required": [ "code", - "message", - "traceId" + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" ] }, { @@ -1957,88 +2076,145 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ], - "description": "Invalid request parameters" + "description": "Server error" } } } + } + } + } + }, + "/intents/splits": { + "post": { + "description": "Splits token amounts into multiple intents based on available relayer liquidity. Each returned intent can be filled by a single relayer.", + "summary": "Split Intent by Liquidity", + "tags": [ + "Intents" + ], + "parameters": [ + { + "name": "x-api-key", + "in": "header", + "required": true, + "schema": { + "type": "string", + "description": "Rhinestone API key" + } }, - "422": { - "description": "422", + { + "name": "x-api-version", + "in": "header", + "schema": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}\\.[a-z0-9]+$", + "description": "API version (YYYY-MM.name). Will become required in a future release.", + "example": "2026-01.alps" + } + } + ], + "requestBody": { + "description": "Body", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "chainId": { + "type": "string", + "pattern": "^eip155:\\d+$", + "description": "The destination chain ID", + "example": "eip155:42161" + }, + "tokens": { + "type": "object", + "additionalProperties": { + "type": "string", + "format": "uint256" + }, + "description": "Map of token addresses to amounts", + "example": { + "0xaf88d065e77c8cc2239327c5edb3a432268e5831": "5000000000000" + } + }, + "settlementLayers": { + "type": "array", + "items": { + "type": "string", + "enum": [ + "INTENT_EXECUTOR", + "SAME_CHAIN", + "ACROSS", + "ECO", + "RELAY", + "OFT", + "NEAR", + "RHINO", + "CCTP" + ] + }, + "description": "Optional array of settlement layers to filter by. If not provided, all layers are considered.", + "example": [ + "ACROSS", + "ECO" + ] + } + }, + "required": [ + "chainId", + "tokens" + ] + } + } + } + }, + "responses": { + "200": { + "description": "200", "content": { "application/json": { "schema": { "type": "object", "properties": { - "code": { - "type": "string", - "enum": [ - "INSUFFICIENT_LIQUIDITY" - ], - "description": "Machine-readable error code" - }, - "message": { - "type": "string", - "description": "Human-readable error message", - "example": "Insufficient liquidity to fill the requested amounts. Partial splits available." - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, - "details": { - "type": "object", - "properties": { - "availableIntents": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "description": "Intents that can be filled with available liquidity" - }, - "unfillable": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "Token amounts that cannot be filled due to insufficient liquidity" + "intents": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "type": "string" } }, - "required": [ - "availableIntents", - "unfillable" + "description": "Array of intents, each mapping token addresses to amounts that can be filled by a single relayer", + "example": [ + { + "0xaf88d065e77c8cc2239327c5edb3a432268e5831": "2400000000000" + }, + { + "0xaf88d065e77c8cc2239327c5edb3a432268e5831": "1700000000000" + }, + { + "0xaf88d065e77c8cc2239327c5edb3a432268e5831": "900000000000" + } ] } }, "required": [ - "code", - "message", - "traceId" + "intents" ], - "description": "Insufficient liquidity to fill the full amount. Partial splits returned." + "description": "Successfully split the intent by available liquidity" } } } }, - "500": { - "description": "500", + "400": { + "description": "400", "content": { "application/json": { "schema": { @@ -2060,11 +2236,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -2091,8 +2262,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -2109,11 +2279,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -2144,8 +2309,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -2154,17 +2318,7 @@ "code": { "type": "string", "enum": [ - "NOT_FOUND", - "UNAUTHORIZED", - "FORBIDDEN", - "CONFLICT", - "UNPROCESSABLE_CONTENT", - "TOO_MANY_REQUESTS", - "SETTLEMENT_QUOTE_ERROR", - "SETTLEMENT_EXECUTION_ERROR", - "EXTERNAL_SERVICE_TIMEOUT", - "RELAYER_MARKET_UNAVAILABLE", - "INTERNAL_ERROR" + "KEY_SCOPE_DENIED" ] }, "message": { @@ -2172,16 +2326,603 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - } - }, - "required": [ - "code", - "message", - "traceId" + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "NOT_FOUND", + "UNAUTHORIZED", + "FORBIDDEN", + "CONFLICT", + "UNPROCESSABLE_CONTENT", + "TOO_MANY_REQUESTS", + "SETTLEMENT_QUOTE_ERROR", + "SETTLEMENT_EXECUTION_ERROR", + "EXTERNAL_SERVICE_TIMEOUT", + "RELAYER_MARKET_UNAVAILABLE", + "INTERNAL_ERROR" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + } + }, + "required": [ + "code", + "message" + ] + } + ], + "description": "Invalid request parameters" + } + } + } + }, + "403": { + "description": "403", + "content": { + "application/json": { + "schema": { + "discriminator": { + "propertyName": "code" + }, + "oneOf": [ + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "VALIDATION_ERROR" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Human-readable issue description" + }, + "context": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Structured issue context (e.g. `{ path: \"body.accountAddress\" }`)" + } + }, + "required": [ + "message" + ] + }, + "description": "Per-field validation issues" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "INSUFFICIENT_LIQUIDITY" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "object", + "properties": { + "availableIntents": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "description": "Intents fillable with current liquidity" + }, + "unfillable": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Token amounts that cannot be filled" + } + }, + "required": [ + "availableIntents", + "unfillable" + ], + "description": "Fillable subset and unfillable remainder" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "NOT_FOUND", + "UNAUTHORIZED", + "FORBIDDEN", + "CONFLICT", + "UNPROCESSABLE_CONTENT", + "TOO_MANY_REQUESTS", + "SETTLEMENT_QUOTE_ERROR", + "SETTLEMENT_EXECUTION_ERROR", + "EXTERNAL_SERVICE_TIMEOUT", + "RELAYER_MARKET_UNAVAILABLE", + "INTERNAL_ERROR" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + } + }, + "required": [ + "code", + "message" + ] + } + ], + "description": "API key scope denied" + } + } + } + }, + "422": { + "description": "422", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "INSUFFICIENT_LIQUIDITY" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Insufficient liquidity to fill the requested amounts. Partial splits available." + }, + "details": { + "type": "object", + "properties": { + "availableIntents": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "description": "Intents that can be filled with available liquidity" + }, + "unfillable": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Token amounts that cannot be filled due to insufficient liquidity" + } + }, + "required": [ + "availableIntents", + "unfillable" + ] + } + }, + "required": [ + "code", + "message" + ], + "description": "Insufficient liquidity to fill the full amount. Partial splits returned." + } + } + } + }, + "500": { + "description": "500", + "content": { + "application/json": { + "schema": { + "discriminator": { + "propertyName": "code" + }, + "oneOf": [ + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "VALIDATION_ERROR" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Human-readable issue description" + }, + "context": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Structured issue context (e.g. `{ path: \"body.accountAddress\" }`)" + } + }, + "required": [ + "message" + ] + }, + "description": "Per-field validation issues" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "INSUFFICIENT_LIQUIDITY" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "object", + "properties": { + "availableIntents": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "description": "Intents fillable with current liquidity" + }, + "unfillable": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Token amounts that cannot be filled" + } + }, + "required": [ + "availableIntents", + "unfillable" + ], + "description": "Fillable subset and unfillable remainder" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "NOT_FOUND", + "UNAUTHORIZED", + "FORBIDDEN", + "CONFLICT", + "UNPROCESSABLE_CONTENT", + "TOO_MANY_REQUESTS", + "SETTLEMENT_QUOTE_ERROR", + "SETTLEMENT_EXECUTION_ERROR", + "EXTERNAL_SERVICE_TIMEOUT", + "RELAYER_MARKET_UNAVAILABLE", + "INTERNAL_ERROR" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + } + }, + "required": [ + "code", + "message" ] } ], @@ -2372,58 +3113,279 @@ "description": "R value for EIP-7702 delegation", "example": "0x..." }, - "s": { - "type": "string", - "pattern": "^0x[a-fA-F0-9]*$", - "description": "S value for EIP-7702 delegation", - "example": "0x..." - } + "s": { + "type": "string", + "pattern": "^0x[a-fA-F0-9]*$", + "description": "S value for EIP-7702 delegation", + "example": "0x..." + } + }, + "required": [ + "chainId", + "address", + "nonce", + "yParity", + "r", + "s" + ] + }, + "description": "EIP-7702 authorizations signed by the recipient account" + } + } + } + }, + "required": [ + "intentId", + "signatures" + ] + } + } + } + }, + "responses": { + "201": { + "description": "201", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "intentId": { + "type": "string", + "pattern": "^\\d+$" + } + }, + "required": [ + "intentId" + ], + "description": "Intent operations submitted successfully" + } + } + } + }, + "400": { + "description": "400", + "content": { + "application/json": { + "schema": { + "discriminator": { + "propertyName": "code" + }, + "oneOf": [ + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "VALIDATION_ERROR" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Human-readable issue description" + }, + "context": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Structured issue context (e.g. `{ path: \"body.accountAddress\" }`)" + } + }, + "required": [ + "message" + ] + }, + "description": "Per-field validation issues" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "INSUFFICIENT_LIQUIDITY" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "object", + "properties": { + "availableIntents": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "description": "Intents fillable with current liquidity" + }, + "unfillable": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Token amounts that cannot be filled" + } + }, + "required": [ + "availableIntents", + "unfillable" + ], + "description": "Fillable subset and unfillable remainder" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] }, - "required": [ - "chainId", - "address", - "nonce", - "yParity", - "r", - "s" + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "NOT_FOUND", + "UNAUTHORIZED", + "FORBIDDEN", + "CONFLICT", + "UNPROCESSABLE_CONTENT", + "TOO_MANY_REQUESTS", + "SETTLEMENT_QUOTE_ERROR", + "SETTLEMENT_EXECUTION_ERROR", + "EXTERNAL_SERVICE_TIMEOUT", + "RELAYER_MARKET_UNAVAILABLE", + "INTERNAL_ERROR" ] }, - "description": "EIP-7702 authorizations signed by the recipient account" - } - } - } - }, - "required": [ - "intentId", - "signatures" - ] - } - } - } - }, - "responses": { - "201": { - "description": "201", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "intentId": { - "type": "string", - "pattern": "^\\d+$" + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + } + }, + "required": [ + "code", + "message" + ] } - }, - "required": [ - "intentId" ], - "description": "Intent operations submitted successfully" + "description": "Invalid request parameters" } } } }, - "400": { - "description": "400", + "403": { + "description": "403", "content": { "application/json": { "schema": { @@ -2445,11 +3407,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -2476,8 +3433,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -2494,11 +3450,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -2529,8 +3480,93 @@ }, "required": [ "code", - "message", - "traceId" + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" ] }, { @@ -2556,21 +3592,15 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ], - "description": "Invalid request parameters" + "description": "API key scope denied" } } } @@ -2598,11 +3628,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -2617,73 +3642,152 @@ "additionalProperties": { "nullable": true }, - "description": "Structured issue context (e.g. `{ path: \"body.accountAddress\" }`)" + "description": "Structured issue context (e.g. `{ path: \"body.accountAddress\" }`)" + } + }, + "required": [ + "message" + ] + }, + "description": "Per-field validation issues" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "INSUFFICIENT_LIQUIDITY" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "object", + "properties": { + "availableIntents": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "description": "Intents fillable with current liquidity" + }, + "unfillable": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Token amounts that cannot be filled" + } + }, + "required": [ + "availableIntents", + "unfillable" + ], + "description": "Fillable subset and unfillable remainder" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] } }, "required": [ - "message" + "message", + "context" ] }, - "description": "Per-field validation issues" - } - }, - "required": [ - "code", - "message", - "traceId" - ] - }, - { - "type": "object", - "properties": { - "code": { - "type": "string", - "enum": [ - "INSUFFICIENT_LIQUIDITY" - ] - }, - "message": { - "type": "string", - "description": "Human-readable error message", - "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, - "details": { - "type": "object", - "properties": { - "availableIntents": { - "type": "array", - "items": { - "type": "object", - "additionalProperties": { - "type": "string" - } - }, - "description": "Intents fillable with current liquidity" - }, - "unfillable": { - "type": "object", - "additionalProperties": { - "type": "string" - }, - "description": "Token amounts that cannot be filled" - } - }, - "required": [ - "availableIntents", - "unfillable" - ], - "description": "Fillable subset and unfillable remainder" + "description": "Single-element list describing the failing scope" } }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -2709,17 +3813,11 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ], @@ -2751,11 +3849,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -2782,8 +3875,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -2800,11 +3892,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -2835,8 +3922,93 @@ }, "required": [ "code", - "message", - "traceId" + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" ] }, { @@ -2862,17 +4034,11 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ], @@ -2966,58 +4132,279 @@ "example": 10 }, "items": { - "type": "array", - "items": { - "type": "object", - "properties": { - "status": { - "type": "string", - "enum": [ - "PENDING", - "COMPLETED", - "FAILED" - ], - "description": "Operation status", - "example": "COMPLETED" - }, - "txHash": { - "type": "string", - "description": "Transaction hash (present when COMPLETED)", - "example": "0xc1674f4671accbceec3f22c2c9cfa4f7aead7183f48df90c239e0d85d6c31e21" - }, - "timestamp": { - "type": "number", - "description": "Block timestamp in unix seconds (present when COMPLETED)", - "example": 1633493192 - } + "type": "array", + "items": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "PENDING", + "COMPLETED", + "FAILED" + ], + "description": "Operation status", + "example": "COMPLETED" + }, + "txHash": { + "type": "string", + "description": "Transaction hash (present when COMPLETED)", + "example": "0xc1674f4671accbceec3f22c2c9cfa4f7aead7183f48df90c239e0d85d6c31e21" + }, + "timestamp": { + "type": "number", + "description": "Block timestamp in unix seconds (present when COMPLETED)", + "example": 1633493192 + } + }, + "required": [ + "status" + ] + }, + "description": "Operations on this chain" + } + }, + "required": [ + "chain", + "items" + ] + }, + "description": "Operations grouped by chain. Each chain has one or more operations (e.g. CLAIM, FILL, BRIDGE_FILL)." + } + }, + "required": [ + "status", + "accountAddress", + "operations" + ], + "description": "Successfully retrieved intent operation status" + } + } + } + }, + "400": { + "description": "400", + "content": { + "application/json": { + "schema": { + "discriminator": { + "propertyName": "code" + }, + "oneOf": [ + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "VALIDATION_ERROR" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Human-readable issue description" + }, + "context": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Structured issue context (e.g. `{ path: \"body.accountAddress\" }`)" + } + }, + "required": [ + "message" + ] + }, + "description": "Per-field validation issues" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "INSUFFICIENT_LIQUIDITY" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "object", + "properties": { + "availableIntents": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "description": "Intents fillable with current liquidity" + }, + "unfillable": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Token amounts that cannot be filled" + } + }, + "required": [ + "availableIntents", + "unfillable" + ], + "description": "Fillable subset and unfillable remainder" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" }, - "required": [ - "status" - ] + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } }, - "description": "Operations on this chain" - } + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "NOT_FOUND", + "UNAUTHORIZED", + "FORBIDDEN", + "CONFLICT", + "UNPROCESSABLE_CONTENT", + "TOO_MANY_REQUESTS", + "SETTLEMENT_QUOTE_ERROR", + "SETTLEMENT_EXECUTION_ERROR", + "EXTERNAL_SERVICE_TIMEOUT", + "RELAYER_MARKET_UNAVAILABLE", + "INTERNAL_ERROR" + ] }, - "required": [ - "chain", - "items" - ] + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + } }, - "description": "Operations grouped by chain. Each chain has one or more operations (e.g. CLAIM, FILL, BRIDGE_FILL)." + "required": [ + "code", + "message" + ] } - }, - "required": [ - "status", - "accountAddress", - "operations" ], - "description": "Successfully retrieved intent operation status" + "description": "Invalid intent ID" } } } }, - "400": { - "description": "400", + "403": { + "description": "403", "content": { "application/json": { "schema": { @@ -3039,11 +4426,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -3070,8 +4452,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -3088,11 +4469,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -3123,8 +4499,93 @@ }, "required": [ "code", - "message", - "traceId" + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" ] }, { @@ -3150,21 +4611,15 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ], - "description": "Invalid intent ID" + "description": "API key scope denied" } } } @@ -3192,11 +4647,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -3223,8 +4673,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -3241,11 +4690,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -3267,17 +4711,102 @@ "description": "Token amounts that cannot be filled" } }, - "required": [ - "availableIntents", - "unfillable" - ], - "description": "Fillable subset and unfillable remainder" + "required": [ + "availableIntents", + "unfillable" + ], + "description": "Fillable subset and unfillable remainder" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" } }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -3303,17 +4832,11 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ], @@ -3345,11 +4868,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -3376,8 +4894,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -3394,11 +4911,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -3429,8 +4941,93 @@ }, "required": [ "code", - "message", - "traceId" + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" ] }, { @@ -3456,17 +5053,11 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ], @@ -3667,32 +5258,253 @@ } ] }, - { - "symbol": "WETH", - "chains": [ - { - "chainId": "eip155:10", - "address": "0x4200000000000000000000000000000000000006", - "decimals": 18, - "amount": "2000000000000000000" - }, - { - "chainId": "eip155:8453", - "address": "0x4200000000000000000000000000000000000006", - "decimals": 18, - "amount": "1000000000000000000" - } - ] + { + "symbol": "WETH", + "chains": [ + { + "chainId": "eip155:10", + "address": "0x4200000000000000000000000000000000000006", + "decimals": 18, + "amount": "2000000000000000000" + }, + { + "chainId": "eip155:8453", + "address": "0x4200000000000000000000000000000000000006", + "decimals": 18, + "amount": "1000000000000000000" + } + ] + } + ] + } + } + } + } + } + }, + "400": { + "description": "400", + "content": { + "application/json": { + "schema": { + "discriminator": { + "propertyName": "code" + }, + "oneOf": [ + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "VALIDATION_ERROR" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Human-readable issue description" + }, + "context": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Structured issue context (e.g. `{ path: \"body.accountAddress\" }`)" + } + }, + "required": [ + "message" + ] + }, + "description": "Per-field validation issues" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "INSUFFICIENT_LIQUIDITY" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "object", + "properties": { + "availableIntents": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "description": "Intents fillable with current liquidity" + }, + "unfillable": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Token amounts that cannot be filled" + } + }, + "required": [ + "availableIntents", + "unfillable" + ], + "description": "Fillable subset and unfillable remainder" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "NOT_FOUND", + "UNAUTHORIZED", + "FORBIDDEN", + "CONFLICT", + "UNPROCESSABLE_CONTENT", + "TOO_MANY_REQUESTS", + "SETTLEMENT_QUOTE_ERROR", + "SETTLEMENT_EXECUTION_ERROR", + "EXTERNAL_SERVICE_TIMEOUT", + "RELAYER_MARKET_UNAVAILABLE", + "INTERNAL_ERROR" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" } + }, + "required": [ + "code", + "message" ] } - } + ], + "description": "Invalid request parameters" } } } }, - "400": { - "description": "400", + "403": { + "description": "403", "content": { "application/json": { "schema": { @@ -3714,11 +5526,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -3745,8 +5552,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -3763,11 +5569,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -3798,8 +5599,93 @@ }, "required": [ "code", - "message", - "traceId" + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" ] }, { @@ -3825,21 +5711,15 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ], - "description": "Invalid request parameters" + "description": "API key scope denied" } } } @@ -3867,11 +5747,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -3898,8 +5773,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -3916,11 +5790,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -3951,8 +5820,93 @@ }, "required": [ "code", - "message", - "traceId" + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" ] }, { @@ -3978,17 +5932,11 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ], @@ -4086,7 +6034,7 @@ }, "/liquidity": { "get": { - "description": "Returns the maximum fillable amount for a single deposit on the given source→destination route.", + "description": "Returns the largest known fillable amount for a single deposit on the given source→destination route. Relayer-market layers return exact capacity; bridge-backed layers return a conservative probed lower bound.", "summary": "Route liquidity limit", "tags": [ "Utilities" @@ -4174,31 +6122,252 @@ "description": "Destination token decimals", "example": 6 }, - "unlimited": { - "type": "boolean", - "description": "True when an uncapped settlement layer (e.g. OFT) supports this route", - "example": false + "unlimited": { + "type": "boolean", + "description": "True when an uncapped settlement layer (e.g. OFT) supports this route", + "example": false + }, + "maxAmount": { + "type": "string", + "nullable": true, + "description": "Largest known fillable amount for this token by a single relayer instance. Exact for relayer-market settlement layers (ACROSS, ECO); bridge-backed layers (Relay, NEAR, Rhino) return a conservative probed lower bound. Null when unlimited.", + "example": "200000000000" + } + }, + "required": [ + "symbol", + "decimals", + "unlimited", + "maxAmount" + ], + "description": "Liquidity information for the requested route" + } + } + } + }, + "400": { + "description": "400", + "content": { + "application/json": { + "schema": { + "discriminator": { + "propertyName": "code" + }, + "oneOf": [ + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "VALIDATION_ERROR" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Human-readable issue description" + }, + "context": { + "type": "object", + "additionalProperties": { + "nullable": true + }, + "description": "Structured issue context (e.g. `{ path: \"body.accountAddress\" }`)" + } + }, + "required": [ + "message" + ] + }, + "description": "Per-field validation issues" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "INSUFFICIENT_LIQUIDITY" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "object", + "properties": { + "availableIntents": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "description": "Intents fillable with current liquidity" + }, + "unfillable": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Token amounts that cannot be filled" + } + }, + "required": [ + "availableIntents", + "unfillable" + ], + "description": "Fillable subset and unfillable remainder" + } + }, + "required": [ + "code", + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" + ] }, - "maxAmount": { - "type": "string", - "nullable": true, - "description": "Largest fillable amount for this token by a single relayer instance. Null when unlimited.", - "example": "200000000000" + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "NOT_FOUND", + "UNAUTHORIZED", + "FORBIDDEN", + "CONFLICT", + "UNPROCESSABLE_CONTENT", + "TOO_MANY_REQUESTS", + "SETTLEMENT_QUOTE_ERROR", + "SETTLEMENT_EXECUTION_ERROR", + "EXTERNAL_SERVICE_TIMEOUT", + "RELAYER_MARKET_UNAVAILABLE", + "INTERNAL_ERROR" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + } + }, + "required": [ + "code", + "message" + ] } - }, - "required": [ - "symbol", - "decimals", - "unlimited", - "maxAmount" ], - "description": "Liquidity information for the requested route" + "description": "Invalid request parameters" } } } }, - "400": { - "description": "400", + "403": { + "description": "403", "content": { "application/json": { "schema": { @@ -4220,11 +6389,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -4251,8 +6415,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -4269,11 +6432,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -4304,8 +6462,93 @@ }, "required": [ "code", - "message", - "traceId" + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" ] }, { @@ -4331,21 +6574,15 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ], - "description": "Invalid request parameters" + "description": "API key scope denied" } } } @@ -4373,11 +6610,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "array", "items": { @@ -4404,8 +6636,7 @@ }, "required": [ "code", - "message", - "traceId" + "message" ] }, { @@ -4422,11 +6653,6 @@ "description": "Human-readable error message", "example": "Invalid input" }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" - }, "details": { "type": "object", "properties": { @@ -4457,8 +6683,93 @@ }, "required": [ "code", - "message", - "traceId" + "message" + ] + }, + { + "type": "object", + "properties": { + "code": { + "type": "string", + "enum": [ + "KEY_SCOPE_DENIED" + ] + }, + "message": { + "type": "string", + "description": "Human-readable error message", + "example": "Invalid input" + }, + "details": { + "type": "array", + "items": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "context": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "enum": [ + "allowMainnet", + "intents", + "deposits" + ], + "description": "Which scope rejected the request" + }, + "required": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "read", + "write" + ] + } + ], + "description": "Minimum level the endpoint demands" + }, + "actual": { + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "none", + "read", + "write" + ] + } + ], + "description": "Level resolved on the key" + } + }, + "required": [ + "scope", + "required", + "actual" + ] + } + }, + "required": [ + "message", + "context" + ] + }, + "description": "Single-element list describing the failing scope" + } + }, + "required": [ + "code", + "message" ] }, { @@ -4484,17 +6795,11 @@ "type": "string", "description": "Human-readable error message", "example": "Invalid input" - }, - "traceId": { - "type": "string", - "description": "Trace ID", - "example": "eb0ba4657f36364b33ec565c15f98368" } }, "required": [ "code", - "message", - "traceId" + "message" ] } ],