{ "openapi": "3.0.0", "info": { "title": "Rhinestone Orchestrator API", "version": "2026-04.blanc" }, "servers": [ { "url": "https://v1.orchestrator.rhinestone.dev" } ], "paths": { "/chains": { "get": { "operationId": "listChains", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the chain", "example": "Arbitrum One" }, "testnet": { "type": "boolean" }, "supportedTokens": { "oneOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "address": { "type": "string", "minLength": 1, "description": "Token contract address (format depends on the chain)" }, "decimals": { "type": "number" } }, "required": [ "symbol", "address", "decimals" ] } } ] }, "wrappedNativeToken": { "type": "object", "properties": { "symbol": { "type": "string" }, "address": { "type": "string", "minLength": 1, "description": "Token contract address (format depends on the chain)" }, "decimals": { "type": "number" } }, "required": [ "symbol", "address", "decimals" ], "description": "The wrapped-native token (e.g. WETH) for the chain. Lets clients resolve the wrapped-native address without bundling a token registry." } }, "required": [ "name", "testnet", "supportedTokens", "wrappedNativeToken" ] }, "description": "Supported chains and tokens, keyed by CAIP-2 chain id" } } } }, "400": { "description": "Validation error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "Supported chains and tokens", "description": "Get supported chains and tokens with additional metadata", "tags": [ "Utilities" ] } }, "/liquidity": { "get": { "operationId": "listLiquidity", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." }, { "name": "sourceChainId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^eip155:[0-9]{1,32}$", "description": "Source chain ID (CAIP-2)", "example": "eip155:1" }, "description": "Source chain ID (CAIP-2)" }, { "name": "sourceToken", "in": "query", "required": true, "schema": { "type": "string", "description": "Source token address", "example": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" }, "description": "Source token address" }, { "name": "destinationChainId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^(eip155|solana|tron|hypercore):[-_a-zA-Z0-9]{1,32}$", "description": "Destination chain ID (CAIP-2)", "example": "eip155:8453" }, "description": "Destination chain ID (CAIP-2)" }, { "name": "destinationToken", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "Destination token address (EVM 0x or non-EVM base58)", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "description": "Destination token address (EVM 0x or non-EVM base58)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Destination token symbol", "example": "USDC" }, "decimals": { "type": "number", "description": "Destination token decimals", "example": 6 }, "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" ] } } } }, "400": { "description": "Validation error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "403": { "description": "API key scope denied", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "Route liquidity limit", "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.", "tags": [ "Utilities" ] } }, "/intents/{id}": { "get": { "operationId": "getIntent", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$", "description": "Unique identifier of the intent operation", "example": "77119256265773742309930654065362693497375232736834856992878277299604179621015" }, "description": "Unique identifier of the intent operation" }, { "name": "full", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Whether to include intent operation details", "example": "true" }, "description": "Whether to include intent operation details" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ], "description": "Overall intent status: PENDING, COMPLETED, or FAILED", "example": "COMPLETED" }, "accountAddress": { "type": "string", "description": "Account address", "example": "0x3672e268a79bd4acc5ee646bdda652547c7a435c" }, "operations": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "number", "description": "Chain ID", "example": 10 }, "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CLAIM", "FILL", "BRIDGE_FILL" ], "description": "Operation type: CLAIM, FILL, or BRIDGE_FILL", "example": "FILL" }, "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": [ "type", "status" ], "description": "A single operation on a chain" }, "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)." }, "details": { "type": "object", "properties": { "id": { "type": "string", "description": "Intent id — pass to `GET /intents/:id`", "example": "12345678901234567890" }, "nonce": { "type": "string", "description": "Intent nonce (hex)", "example": "0x000000000000000000000000000000000000000000000000ab54a98ceb1f0ad2" }, "recipient": { "type": "string", "description": "Destination recipient account", "example": "0x3672e268a79bd4acc5ee646bdda652547c7a435c" }, "createdAt": { "type": "number", "description": "Intent creation time in unix seconds", "example": 1633493100 }, "latencyMs": { "type": "number", "nullable": true, "description": "Time from creation to the latest leg landing, in ms. Null until any leg lands.", "example": 8100 }, "settlementLayer": { "type": "string", "enum": [ "INTENT_EXECUTOR", "SAME_CHAIN", "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP" ], "nullable": true, "description": "Settlement layer; null if the routing strategy is unrecognized", "example": "ACROSS" }, "source": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "number", "description": "Chain ID", "example": 10 }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "Token address", "example": "0x0b2c639c533813f4aa9d7837caf62653d097ff85" }, "symbol": { "type": "string", "nullable": true, "description": "Token symbol. `null` when the internal token registry has no entry for this address.", "example": "USDC" }, "decimals": { "type": "integer", "nullable": true, "description": "Token decimals. `null` when the internal token registry has no entry for this address.", "example": 6 }, "amount": { "type": "string", "description": "Token amount in base units", "example": "1000000" } }, "required": [ "token", "symbol", "decimals", "amount" ], "description": "A token moved on this leg" }, "description": "All tokens moved on this leg" }, "txHash": { "type": "string", "description": "Transaction hash (present once the leg lands)", "example": "0xc1674f4671accbceec3f22c2c9cfa4f7aead7183f48df90c239e0d85d6c31e21" }, "timestamp": { "type": "number", "description": "Block timestamp in unix seconds (present once landed)", "example": 1633493192 }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ], "description": "Leg status", "example": "COMPLETED" } }, "required": [ "chain", "tokens", "status" ], "description": "A single source or destination leg" }, "description": "Source (claim) legs" }, "destination": { "type": "object", "properties": { "chain": { "type": "number", "description": "Chain ID", "example": 10 }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "token": { "type": "string", "description": "Token address", "example": "0x0b2c639c533813f4aa9d7837caf62653d097ff85" }, "symbol": { "type": "string", "nullable": true, "description": "Token symbol. `null` when the internal token registry has no entry for this address.", "example": "USDC" }, "decimals": { "type": "integer", "nullable": true, "description": "Token decimals. `null` when the internal token registry has no entry for this address.", "example": 6 }, "amount": { "type": "string", "description": "Token amount in base units", "example": "1000000" } }, "required": [ "token", "symbol", "decimals", "amount" ], "description": "A token moved on this leg" }, "description": "All tokens moved on this leg" }, "txHash": { "type": "string", "description": "Transaction hash (present once the leg lands)", "example": "0xc1674f4671accbceec3f22c2c9cfa4f7aead7183f48df90c239e0d85d6c31e21" }, "timestamp": { "type": "number", "description": "Block timestamp in unix seconds (present once landed)", "example": 1633493192 }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ], "description": "Leg status", "example": "COMPLETED" } }, "required": [ "chain", "tokens", "status" ], "description": "Destination (fill) leg; null before a fill is dispatched", "nullable": true }, "executions": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "number", "description": "Chain ID the call executes on", "example": 8453 }, "phase": { "type": "string", "enum": [ "PRE_CLAIM", "DESTINATION" ], "description": "PRE_CLAIM runs on the origin chain before funds are claimed; DESTINATION runs on the destination chain after funds are delivered.", "example": "DESTINATION" }, "to": { "type": "string", "description": "Call target address", "example": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" }, "value": { "type": "string", "description": "Native value sent with the call, in wei (base units)", "example": "0" }, "data": { "type": "string", "description": "Encoded calldata", "example": "0xa9059cbb000000000000000000000000579d5631f76126991c00fb8fe5467fa9d49e5f6a00000000000000000000000000000000000000000000000000000000000f4240" } }, "required": [ "chain", "phase", "to", "value", "data" ], "description": "A single call executed by the intent" }, "description": "Calls the intent executes — preClaim ops on their origin chain and destination ops on the destination chain. The signed intended calls; no per-call result is recorded. Empty for token-only intents with no custom calls." }, "cost": { "type": "object", "properties": { "sponsored": { "type": "boolean", "description": "Whether gas/fees were sponsored for this intent", "example": true }, "sponsoredValue": { "type": "string", "description": "Sponsored value in fee-token base units", "example": "210000" }, "protocolFee": { "type": "string", "description": "Protocol fee in fee-token base units", "example": "10000" } }, "required": [ "sponsored" ], "description": "Cost summary from the recorded fee sponsorship. Amounts are raw base units; omitted when no sponsorship row exists." } }, "required": [ "id", "nonce", "recipient", "createdAt", "latencyMs", "settlementLayer", "source", "destination", "executions", "cost" ], "description": "Extended intent details, returned only when `full=true`" } }, "required": [ "status", "accountAddress", "operations" ], "description": "Successfully retrieved intent operation status" } } } }, "400": { "description": "Invalid intent ID", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "403": { "description": "API key scope denied", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "404": { "description": "Intent ID not found", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "Get Intent", "description": "Retrieves the status of an intent along with per-claim progress across chains.", "tags": [ "Intents" ] } }, "/accounts/{accountAddress}/portfolio": { "get": { "operationId": "getPortfolio", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." }, { "name": "accountAddress", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "chainIds", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "array", "items": { "type": "string", "pattern": "^eip155:[0-9]{1,32}$" } }, { "type": "string", "pattern": "^eip155:[0-9]{1,32}$" } ] } }, { "name": "tokens", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "array", "items": { "type": "string", "pattern": "^eip155:[0-9]{1,32}:0x[a-fA-F0-9]{40}$" } }, { "type": "string", "pattern": "^eip155:[0-9]{1,32}:0x[a-fA-F0-9]{40}$" } ] } }, { "name": "filterEmpty", "in": "query", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "portfolio": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string", "description": "Short name (symbol) of the token", "example": "USDC" }, "chains": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "string", "pattern": "^eip155:[0-9]{1,32}$", "description": "Chain ID where the token balance exists (CAIP-2)", "example": "eip155:1" }, "address": { "type": "string", "description": "Token contract address on this chain", "example": "0xa0B86A33e6441B8C4505B8C4505b8C4505B8C450" }, "decimals": { "type": "number", "minimum": 0, "description": "Decimal places for this token on this chain. Sourced per-chain because the same logical token can have different on-chain decimals across chains (e.g. USDC: 6 on Ethereum, 18 on BNB Smart Chain).", "example": 6 }, "amount": { "type": "string", "format": "uint256", "description": "Token balance on this chain in the token's smallest unit", "example": "1000000" } }, "required": [ "chainId", "address", "decimals", "amount" ] }, "description": "Array of token balances per chain" } }, "required": [ "symbol", "chains" ] }, "description": "Array of token portfolio entries" } }, "required": [ "portfolio" ] } } } }, "400": { "description": "Invalid request parameters", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "403": { "description": "API key scope denied", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "Get Account Portfolio", "description": "Retrieves the token balances across all supported chains for a user's abstracted account", "tags": [ "Utilities" ] } }, "/intents": { "get": { "operationId": "listIntents", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d+$", "description": "Opaque cursor from a previous response (`pagination.nextCursor`). Omit for the first page.", "example": "1024" }, "description": "Opaque cursor from a previous response (`pagination.nextCursor`). Omit for the first page." }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100, "description": "Max items per page (max 100)", "example": 20 }, "description": "Max items per page (max 100)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Intent id — pass to `GET /intents/:id`", "example": "12345678901234567890" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ], "description": "Overall intent status", "example": "COMPLETED" }, "fromChains": { "type": "array", "items": { "type": "number" }, "description": "Source chain IDs — one per distinct chain the intent spends on", "example": [ 1, 8453 ] }, "toChain": { "type": "number", "description": "Destination chain ID", "example": 10 }, "token": { "type": "string", "description": "Intent value token. The token delivered on the destination chain, or the spent token for same-chain intents (which have no persisted delivery).", "example": "0x0b2c639c533813f4aa9d7837caf62653d097ff85" }, "symbol": { "type": "string", "nullable": true, "description": "Token symbol. `null` when the internal token registry has no entry for this address.", "example": "USDC" }, "decimals": { "type": "integer", "nullable": true, "description": "Token decimals. `null` when the internal token registry has no entry for this address.", "example": 6 }, "amount": { "type": "string", "description": "Intent value in base units — delivered on the destination chain, or spent for same-chain intents (which have no persisted delivery; for same-chain swaps this is the input, not the received amount).", "example": "1000000" }, "account": { "type": "string", "description": "Account that submitted the intent", "example": "0x3672e268a79bd4acc5ee646bdda652547c7a435c" }, "createdAt": { "type": "number", "description": "Intent creation time in unix seconds", "example": 1633493100 } }, "required": [ "id", "status", "fromChains", "account", "createdAt" ], "description": "A single intent list entry" }, "description": "Intents on this page, newest first" }, "pagination": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Pass as `cursor` to fetch the next page; null when no more results.", "example": "1024" }, "hasNextPage": { "type": "boolean", "example": true } }, "required": [ "nextCursor", "hasNextPage" ], "description": "Keyset pagination metadata" } }, "required": [ "data", "pagination" ], "description": "Paginated list of the client’s intents" } } } }, "400": { "description": "Validation error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "403": { "description": "API key scope denied", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "List Intents", "description": "Retrieves a paginated list of the authenticated client's intents, newest first.", "tags": [ "Intents" ] }, "post": { "operationId": "createIntent", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "intentId": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "intentId" ] } } } }, "400": { "description": "Validation error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "403": { "description": "API key scope denied", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "404": { "description": "The quoted intent has expired or was already submitted. Request a new route to retry.", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "Create Intent", "description": "Submits a quoted intent for execution. Takes the `intentId` from `POST /quotes` (`routes[].intentId`) plus signatures (origin, destination, optionally target-execution) and optional EIP-7702 authorizations.", "tags": [ "Intents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "intentId": { "type": "string", "pattern": "^\\d+$", "description": "Identifier of the intent returned by `POST /quotes` (as `routes[].intentId`)." }, "signatures": { "type": "object", "properties": { "origin": { "type": "array", "items": { "oneOf": [ { "type": "string", "pattern": "^0x[a-fA-F0-9]*$" }, { "type": "object", "properties": { "preClaimSig": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$" }, "notarizedClaimSig": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$" } }, "required": [ "preClaimSig", "notarizedClaimSig" ] } ] }, "description": "Origin (source chain) signatures", "example": [ "0x...", "0x..." ] }, "destination": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$", "description": "Destination (target chain) signature", "example": "0x..." }, "targetExecution": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$", "description": "Target execution signature (smart sessions only; omit for EOA)", "example": "0x..." } }, "required": [ "origin", "destination" ] }, "authorizations": { "type": "object", "properties": { "sponsor": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number", "description": "Chain ID for EIP-7702 delegation, 0 means it can be applied to any chain", "example": 8453 }, "address": { "type": "string", "description": "Address of the delegate for EIP-7702 delegation", "example": "0x579d5631f76126991c00fb8fe5467fa9d49e5f6a" }, "nonce": { "type": "number", "description": "Nonce for EIP-7702 delegation", "example": "0" }, "yParity": { "type": "number", "description": "Y parity for EIP-7702 delegation", "example": 27 }, "r": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$", "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..." } }, "required": [ "chainId", "address", "nonce", "yParity", "r", "s" ] }, "description": "EIP-7702 authorizations signed by the sponsor account. Each entry `chainId` is a CAIP-2 string (e.g. `eip155:8453`); the `0` any-chain sentinel is sent as a number." }, "recipient": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "number", "description": "Chain ID for EIP-7702 delegation, 0 means it can be applied to any chain", "example": 8453 }, "address": { "type": "string", "description": "Address of the delegate for EIP-7702 delegation", "example": "0x579d5631f76126991c00fb8fe5467fa9d49e5f6a" }, "nonce": { "type": "number", "description": "Nonce for EIP-7702 delegation", "example": "0" }, "yParity": { "type": "number", "description": "Y parity for EIP-7702 delegation", "example": 27 }, "r": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$", "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..." } }, "required": [ "chainId", "address", "nonce", "yParity", "r", "s" ] }, "description": "EIP-7702 authorizations signed by the recipient account. Each entry `chainId` is a CAIP-2 string (e.g. `eip155:8453`); the `0` any-chain sentinel is sent as a number." } } } }, "required": [ "intentId", "signatures" ] } } } } } }, "/intents/splits": { "post": { "operationId": "getSplit", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." } ], "responses": { "200": { "description": "OK", "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" ] } } } }, "400": { "description": "Invalid request parameters", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "403": { "description": "API key scope denied", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "422": { "description": "Insufficient liquidity to fill the full amount. Partial splits returned.", "content": { "application/json": { "schema": { "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" ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "Split Intent by Liquidity", "description": "Splits token amounts into multiple intents based on available relayer liquidity. Each returned intent can be filled by a single relayer.", "tags": [ "Intents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "chainId": { "type": "string", "pattern": "^eip155:[0-9]{1,32}$", "description": "The chain ID the intents settle on (CAIP-2)", "example": "eip155:42161" }, "tokens": { "type": "object", "additionalProperties": { "type": "string", "format": "uint256" }, "description": "Map of token addresses to amounts", "example": { "0xaf88d065e77c8cc2239327c5edb3a432268e5831": "5000000000000" } }, "settlementLayers": { "oneOf": [ { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP" ] } }, { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP" ] } } }, "required": [ "include" ], "additionalProperties": false }, { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP" ] } } }, "required": [ "exclude" ], "additionalProperties": false } ], "description": "Which settlement layers the orchestrator may use. `{ include: [...] }` (allow-list) or `{ exclude: [...] }` (deny-list, inverted against the orchestrator's live layer set); a bare array means `include`. Internal modes (`SAME_CHAIN`, `INTENT_EXECUTOR`) are not selectable. Default unset = all layers eligible.", "example": { "exclude": [ "RELAY" ] } } }, "required": [ "chainId", "tokens" ] } } } } } }, "/quotes": { "post": { "operationId": "createQuote", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "intentId": { "type": "string", "pattern": "^\\d+$", "description": "Server-stored intent identifier. Pass back to `POST /intents` to submit." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Quote expiry timestamp (Unix seconds). After this point, assume the quote is dead and re-quote.", "example": 1733493192 }, "estimatedFillTime": { "type": "object", "properties": { "seconds": { "type": "number", "description": "Typical end-to-end fill time for this route in seconds. Directional, not guaranteed.", "example": 3 } }, "required": [ "seconds" ], "description": "Estimated fill time for the route" }, "settlementLayer": { "type": "string", "enum": [ "INTENT_EXECUTOR", "SAME_CHAIN", "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP" ], "description": "Settlement layer selected for this route", "example": "RELAY" }, "signData": { "type": "object", "properties": { "origin": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" }, "salt": { "type": "string" } }, "description": "EIP-712 domain separator fields" }, "types": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ] } }, "description": "EIP-712 type definitions keyed by type name" }, "primaryType": { "type": "string", "description": "Name of the top-level type to sign", "example": "PermitBatchWitnessTransferFrom" }, "message": { "type": "object", "additionalProperties": {}, "description": "Message values keyed by field name. uint256 fields are encoded as decimal strings on the wire and re-coerced to bigint client-side before signing." } }, "required": [ "domain", "types", "primaryType", "message" ], "description": "EIP-712 typed data definition ready for `signTypedData`" }, "description": "Typed data payloads for the origin legs, in submission order. Sign each entry and submit the signatures in matching order via `signatures.origin`." }, "destination": { "type": "object", "properties": { "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" }, "salt": { "type": "string" } }, "description": "EIP-712 domain separator fields" }, "types": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ] } }, "description": "EIP-712 type definitions keyed by type name" }, "primaryType": { "type": "string", "description": "Name of the top-level type to sign", "example": "PermitBatchWitnessTransferFrom" }, "message": { "type": "object", "additionalProperties": {}, "description": "Message values keyed by field name. uint256 fields are encoded as decimal strings on the wire and re-coerced to bigint client-side before signing." } }, "required": [ "domain", "types", "primaryType", "message" ], "description": "Typed data for the destination leg" }, "targetExecution": { "type": "object", "properties": { "domain": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "number" }, "verifyingContract": { "type": "string" }, "salt": { "type": "string" } }, "description": "EIP-712 domain separator fields" }, "types": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ] } }, "description": "EIP-712 type definitions keyed by type name" }, "primaryType": { "type": "string", "description": "Name of the top-level type to sign", "example": "PermitBatchWitnessTransferFrom" }, "message": { "type": "object", "additionalProperties": {}, "description": "Message values keyed by field name. uint256 fields are encoded as decimal strings on the wire and re-coerced to bigint client-side before signing." } }, "required": [ "domain", "types", "primaryType", "message" ], "description": "Typed data for the target execution, smart sessions only. Omitted for EOA accounts." } }, "required": [ "origin", "destination" ], "description": "EIP-712 sign payloads the client submits back on `POST /intents`" }, "cost": { "type": "object", "properties": { "input": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "string", "pattern": "^eip155:[0-9]{1,32}$", "description": "Chain where this token leg settles", "example": "eip155:8453" }, "tokenAddress": { "type": "string", "description": "ERC-20 contract address for this token", "example": "0xaf88d065e77c8cc2239327c5edb3a432268e5831" }, "symbol": { "type": "string", "nullable": true, "description": "Token symbol. `null` when the internal token registry has no entry for this address.", "example": "USDC" }, "decimals": { "type": "integer", "nullable": true, "description": "Token decimals. `null` when the internal token registry has no entry for this address.", "example": 6 }, "price": { "type": "object", "properties": { "usd": { "type": "number", "description": "Unit price in USD", "example": 1 } }, "required": [ "usd" ], "nullable": true, "description": "Unit price in USD. `null` when the price oracle has no data for this token." }, "amount": { "type": "string", "format": "uint256", "description": "Token amount in the token's smallest unit", "example": "1050000" } }, "required": [ "chainId", "tokenAddress", "symbol", "decimals", "price", "amount" ], "description": "A single (chain, token) leg with amount, price, and metadata" }, "description": "Tokens debited from the user, coalesced by (chainId, tokenAddress)" }, "output": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "string", "pattern": "^(eip155|solana|tron|hypercore):[-_a-zA-Z0-9]{1,32}$", "description": "Chain where this token leg settles (CAIP-2, any namespace)", "example": "eip155:8453" }, "tokenAddress": { "type": "string", "minLength": 1, "description": "Contract address of the delivered token (EVM 0x or non-EVM base58)", "example": "0xaf88d065e77c8cc2239327c5edb3a432268e5831" }, "symbol": { "type": "string", "nullable": true, "description": "Token symbol. `null` when the internal token registry has no entry for this address.", "example": "USDC" }, "decimals": { "type": "integer", "nullable": true, "description": "Token decimals. `null` when the internal token registry has no entry for this address.", "example": 6 }, "price": { "type": "object", "properties": { "usd": { "type": "number", "description": "Unit price in USD", "example": 1 } }, "required": [ "usd" ], "nullable": true, "description": "Unit price in USD. `null` when the price oracle has no data for this token." }, "amount": { "type": "string", "format": "uint256", "description": "Token amount in the token's smallest unit", "example": "1050000" } }, "required": [ "chainId", "tokenAddress", "symbol", "decimals", "price", "amount" ], "description": "A single (chain, token) leg with amount, price, and metadata" }, "description": "Tokens delivered to the recipient, coalesced by (chainId, tokenAddress)" }, "fees": { "type": "object", "properties": { "total": { "type": "object", "properties": { "usd": { "type": "number", "description": "USD-denominated value", "example": 0.029 } }, "required": [ "usd" ], "description": "Full route cost in USD, regardless of who pays. Equal to `sum(breakdown.*.usd)` modulo rounding." }, "breakdown": { "type": "object", "properties": { "gas": { "type": "object", "properties": { "usd": { "type": "number", "description": "Total cost of this category in USD, regardless of who pays.", "example": 0.029 }, "sponsored": { "type": "boolean", "description": "True when a sponsor absorbs some or all of this category. The user-vs-sponsor split is not surfaced.", "example": false } }, "required": [ "usd", "sponsored" ], "description": "Aggregate gas cost (destination fill, swap execution, origin gas)" }, "bridge": { "type": "object", "properties": { "usd": { "type": "number", "description": "Total cost of this category in USD, regardless of who pays.", "example": 0.029 }, "sponsored": { "type": "boolean", "description": "True when a sponsor absorbs some or all of this category. The user-vs-sponsor split is not surfaced.", "example": false } }, "required": [ "usd", "sponsored" ], "description": "Aggregate settlement-layer bridge cost" }, "swap": { "type": "object", "properties": { "usd": { "type": "number", "description": "Total cost of this category in USD, regardless of who pays.", "example": 0.029 }, "sponsored": { "type": "boolean", "description": "True when a sponsor absorbs some or all of this category. The user-vs-sponsor split is not surfaced.", "example": false } }, "required": [ "usd", "sponsored" ], "description": "Aggregate solver swap commission" }, "app": { "type": "object", "properties": { "usd": { "type": "number", "description": "Total cost of this category in USD, regardless of who pays.", "example": 0.029 }, "sponsored": { "type": "boolean", "description": "True when a sponsor absorbs some or all of this category. The user-vs-sponsor split is not surfaced.", "example": false } }, "required": [ "usd", "sponsored" ], "description": "Aggregate integrator app fee" }, "protocol": { "type": "object", "properties": { "usd": { "type": "number", "description": "Total cost of this category in USD, regardless of who pays.", "example": 0.029 }, "sponsored": { "type": "boolean", "description": "True when a sponsor absorbs some or all of this category. The user-vs-sponsor split is not surfaced.", "example": false } }, "required": [ "usd", "sponsored" ], "description": "Rhinestone protocol fee (`options.protocolFees`). `sponsored: true` when the integrator sponsorship balance pays it instead of the user." }, "sponsorSurcharge": { "type": "object", "properties": { "usd": { "type": "number", "description": "Total cost of this category in USD, regardless of who pays.", "example": 0.029 }, "sponsored": { "type": "boolean", "description": "True when a sponsor absorbs some or all of this category. The user-vs-sponsor split is not surfaced.", "example": false } }, "required": [ "usd", "sponsored" ], "description": "Rhinestone's surcharge on the sponsored relayer coverage, charged to the sponsor. 0 when the intent is not sponsored. Pure surcharge — a sponsored protocol fee is shown on `protocol`, never here." } }, "required": [ "gas", "bridge", "swap", "app", "protocol", "sponsorSurcharge" ], "description": "Per-category fee breakdown" } }, "required": [ "total", "breakdown" ], "description": "Aggregate route fees with per-category breakdown" } }, "required": [ "input", "output", "fees" ], "description": "Route cost: inputs, outputs, and fee breakdown" }, "tokenRequirements": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "type": { "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", "description": "Minimum required allowance, in the token's smallest unit." }, "spender": { "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": [ "type", "amount", "spender" ] }, { "type": "object", "properties": { "type": { "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", "description": "Minimum amount to wrap, in wei." } }, "required": [ "type", "amount" ] } ] } }, "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.", "example": { "8453": { "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913": { "type": "approval", "amount": "1000000", "spender": "0x000000000022d473030f116ddee9f6b43ac78ba3" } } } }, "bridgeFill": { "discriminator": { "propertyName": "type" }, "oneOf": [ { "type": "object", "properties": { "destinationChainId": { "type": "number", "description": "Destination chain ID for the bridge fill" }, "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." }, "fillStatusTimeout": { "type": "integer", "minimum": 0, "description": "Fill-tracker watch window, in seconds. The orchestrator owns this timeout; the fill-tracker reads it here to decide when a bridge fill has timed out." }, "type": { "type": "string", "enum": [ "OFT" ], "description": "LayerZero OFT" } }, "required": [ "destinationChainId", "fillStatusTimeout", "type" ] }, { "type": "object", "properties": { "destinationChainId": { "type": "number", "description": "Destination chain ID for the bridge fill" }, "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." }, "fillStatusTimeout": { "type": "integer", "minimum": 0, "description": "Fill-tracker watch window, in seconds. The orchestrator owns this timeout; the fill-tracker reads it here to decide when a bridge fill has timed out." }, "type": { "type": "string", "enum": [ "RELAY" ], "description": "Relay.link" }, "requestId": { "type": "string", "description": "Relay.link request ID. Use against Relay.link's status API to track the destination-chain fill." } }, "required": [ "destinationChainId", "fillStatusTimeout", "type", "requestId" ] }, { "type": "object", "properties": { "destinationChainId": { "type": "number", "description": "Destination chain ID for the bridge fill" }, "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." }, "fillStatusTimeout": { "type": "integer", "minimum": 0, "description": "Fill-tracker watch window, in seconds. The orchestrator owns this timeout; the fill-tracker reads it here to decide when a bridge fill has timed out." }, "type": { "type": "string", "enum": [ "NEAR" ], "description": "NEAR Intents" }, "depositAddress": { "type": "string", "description": "NEAR Intents deposit address. Track fill status via the NEAR Intents status API keyed on this address." } }, "required": [ "destinationChainId", "fillStatusTimeout", "type", "depositAddress" ] }, { "type": "object", "properties": { "destinationChainId": { "type": "number", "description": "Destination chain ID for the bridge fill" }, "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." }, "fillStatusTimeout": { "type": "integer", "minimum": 0, "description": "Fill-tracker watch window, in seconds. The orchestrator owns this timeout; the fill-tracker reads it here to decide when a bridge fill has timed out." }, "type": { "type": "string", "enum": [ "RHINO" ], "description": "Rhino.fi" }, "commitmentId": { "type": "string", "description": "Rhino.fi commitment ID. Use against Rhino.fi's status API to track the destination-chain fill." } }, "required": [ "destinationChainId", "fillStatusTimeout", "type", "commitmentId" ] }, { "type": "object", "properties": { "destinationChainId": { "type": "number", "description": "Destination chain ID for the bridge fill" }, "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." }, "fillStatusTimeout": { "type": "integer", "minimum": 0, "description": "Fill-tracker watch window, in seconds. The orchestrator owns this timeout; the fill-tracker reads it here to decide when a bridge fill has timed out." }, "type": { "type": "string", "enum": [ "CCTP" ], "description": "Circle CCTP" }, "sourceDomainId": { "type": "number", "description": "Circle CCTP source domain ID — needed to fetch the attestation for the burn message on the source chain." }, "destinationDomainId": { "type": "number", "description": "Circle CCTP destination domain ID." } }, "required": [ "destinationChainId", "fillStatusTimeout", "type", "sourceDomainId", "destinationDomainId" ] } ], "description": "Provider handle for resolving the destination-chain delivery transaction when settlement hands off to a third-party bridge (RHINO, RELAY, NEAR, CCTP, OFT). Absent when the orchestrator settles end-to-end (e.g. ACROSS, ECO)." } }, "required": [ "intentId", "expiresAt", "estimatedFillTime", "settlementLayer", "signData", "cost" ], "description": "A single ranked route candidate" }, "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": [ "routes" ], "description": "Response body for `POST /quotes` on the blanc API version" } } } }, "400": { "description": "Invalid request parameters", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "403": { "description": "API key scope denied", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "Create Quote", "description": "Computes a quote for an intent: token transfers, target executions, and cost breakdown. Returns a pre-ranked `routes[]` with per-route `intentId` to pass to `POST /intents` for execution.", "tags": [ "Quotes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destinationChainId": { "type": "string", "pattern": "^(eip155|solana|tron|hypercore):[-_a-zA-Z0-9]{1,32}$", "description": "CAIP-2 chain identifier of the destination chain (EVM `eip155:`, or non-EVM `solana:…`/`tron:…`)", "example": "eip155:8453" }, "tokenRequests": { "type": "array", "items": { "type": "object", "properties": { "tokenAddress": { "type": "string", "minLength": 1, "description": "The address of the requested token. Format depends on destination chain — 0x-hex for EVM, base58 SPL mint for Solana, T-address for Tron.", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "amount": { "type": "string", "format": "uint256", "description": "The amount of the requested token (in the smallest unit). Omit for max-out.", "example": "1000000" }, "balance": { "type": "string", "enum": [ "spot", "perp" ], "description": "Which HyperCore balance receives this token request — 'spot' (the spot wallet) or 'perp' (the default perp dex's margin account). REQUIRED when destinationChainId is HyperCore, with no default: the two answers credit different accounts, so an unstated venue is rejected rather than guessed. Every tokenRequest in one intent must name the same venue. Rejected on every other destination.", "example": "spot" } }, "required": [ "tokenAddress" ] }, "description": "A list of token requested on the target chain" }, "account": { "type": "object", "properties": { "address": { "type": "string", "description": "Account address", "example": "0x579d5631f76126991c00fb8fe5467fa9d49e5f6a" }, "accountType": { "type": "string", "enum": [ "smartAccount", "GENERIC", "EOA", "ERC7579" ], "description": "Account type. Blanc clients should use `ERC7579`; the legacy `smartAccount` value is equivalent and accepted for alps wire compatibility, and gets rewritten to `ERC7579` by the `alpsAccountType` versioning change before Zod validation." }, "setupOps": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "string", "description": "Account deployment factory address", "example": "0x579d5631f76126991c00fb8fe5467fa9d49e5f6a" }, "data": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$", "description": "Account deployment data", "example": "0x..." } }, "required": [ "to", "data" ] }, "description": "Setup operations for the smart account. Only used if the account is not deployed" }, "mockSignatures": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$" }, "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." }, "mockSignature": { "description": "Deprecated. Must be omitted; use `mockSignatures` (keyed by chain id) instead." }, "delegations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "contract": { "type": "string", "description": "address of contract to which delegation on behalf of sponsor will be assumed for given chain ID" } }, "required": [ "contract" ] }, "description": "Per-chain specific map to delegated contract address for 7702 delegations. Use `0` to indicate cross-chain delegation" } }, "required": [ "address" ], "description": "Account details" }, "destinationExecutions": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "string", "description": "Target contract address for execution", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "value": { "type": "string", "format": "uint256", "description": "Amount of ETH (in wei) sent in the execution", "example": "0" }, "data": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$", "description": "Encoded function call data", "example": "0xa9059cbb000000000000000000000000579d5631f76126991c00fb8fe5467fa9d49e5f6a00000000000000000000000000000000000000000000000000000000000f4240" } }, "required": [ "to", "value", "data" ] }, "description": "Execution calls on the target chain." }, "preClaimExecutions": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "string", "description": "Target contract address for execution", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }, "value": { "type": "string", "format": "uint256", "description": "Amount of ETH (in wei) sent in the execution", "example": "0" }, "data": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$", "description": "Encoded function call data", "example": "0xa9059cbb000000000000000000000000579d5631f76126991c00fb8fe5467fa9d49e5f6a00000000000000000000000000000000000000000000000000000000000f4240" } }, "required": [ "to", "value", "data" ] }, "maxItems": 10 }, "description": "Execution calls to perform before the claim on each origin chain, keyed by CAIP-2 chain ID. Max 10 ops per chain, max 5 chains.", "example": { "eip155:8453": [ { "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "value": "0", "data": "0x" } ] } }, "destinationGasLimit": { "type": "string", "format": "uint256", "description": "The gas limit for the target chain executions", "example": "100000" }, "accountAccessList": { "type": "object", "properties": { "chainIds": { "type": "array", "items": { "type": "string", "pattern": "^(eip155|solana|tron|hypercore):[-_a-zA-Z0-9]{1,32}$", "description": "CAIP-2 chain identifier (e.g. `eip155:8453`, `solana:…`, `tron:…`, or `hypercore:mainnet`)", "example": "eip155:8453" } }, "tokens": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "string", "enum": [ "ETH", "USDC", "WETH", "USDT", "USDT0", "BNB", "WBNB", "XDAI", "WXDAI", "POL", "WPOL", "MON", "WMON", "S", "WS", "HYPE", "WHYPE", "USDG", "XPL", "WXPL", "AVAX", "WAVAX", "MockUSD", "TRX", "WTRX", "SOL", "WSOL" ] } ] } }, "chainTokens": { "type": "object", "additionalProperties": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "string", "enum": [ "ETH", "USDC", "WETH", "USDT", "USDT0", "BNB", "WBNB", "XDAI", "WXDAI", "POL", "WPOL", "MON", "WMON", "S", "WS", "HYPE", "WHYPE", "USDG", "XPL", "WXPL", "AVAX", "WAVAX", "MockUSD", "TRX", "WTRX", "SOL", "WSOL" ] } ] } }, "description": "Tokens keyed by CAIP-2 chain ID.", "example": { "eip155:8453": [ "USDC" ] } }, "chainTokenAmounts": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "format": "uint256" } }, "description": "Per-token maximum input amounts keyed by CAIP-2 chain ID.", "example": { "eip155:8453": { "USDC": "1000000" } } }, "exclude": { "type": "object", "properties": { "chainIds": { "type": "array", "items": { "type": "string", "pattern": "^(eip155|solana|tron|hypercore):[-_a-zA-Z0-9]{1,32}$", "description": "CAIP-2 chain identifier (e.g. `eip155:8453`, `solana:…`, `tron:…`, or `hypercore:mainnet`)", "example": "eip155:8453" } }, "tokens": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "string", "enum": [ "ETH", "USDC", "WETH", "USDT", "USDT0", "BNB", "WBNB", "XDAI", "WXDAI", "POL", "WPOL", "MON", "WMON", "S", "WS", "HYPE", "WHYPE", "USDG", "XPL", "WXPL", "AVAX", "WAVAX", "MockUSD", "TRX", "WTRX", "SOL", "WSOL" ] } ] } }, "chainTokens": { "type": "object", "additionalProperties": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "string", "enum": [ "ETH", "USDC", "WETH", "USDT", "USDT0", "BNB", "WBNB", "XDAI", "WXDAI", "POL", "WPOL", "MON", "WMON", "S", "WS", "HYPE", "WHYPE", "USDG", "XPL", "WXPL", "AVAX", "WAVAX", "MockUSD", "TRX", "WTRX", "SOL", "WSOL" ] } ] } }, "description": "Tokens keyed by CAIP-2 chain ID.", "example": { "eip155:8453": [ "USDC" ] } } } } }, "description": "Account access list specifying which CAIP-2 chains and tokens an account may access" }, "recipient": { "type": "object", "properties": { "address": { "type": "string", "minLength": 1, "description": "Recipient address. Format depends on destination chain — 0x-hex for EVM destinations, base58 for Solana, T-address for Tron.", "example": "0x579d5631f76126991c00fb8fe5467fa9d49e5f6a" }, "accountType": { "type": "string", "enum": [ "smartAccount", "GENERIC", "EOA", "ERC7579" ], "description": "Account type. Blanc clients should use `ERC7579`; the legacy `smartAccount` value is equivalent and accepted for alps wire compatibility, and gets rewritten to `ERC7579` by the `alpsAccountType` versioning change before Zod validation." }, "setupOps": { "type": "array", "items": { "type": "object", "properties": { "to": { "type": "string", "description": "Account deployment factory address", "example": "0x579d5631f76126991c00fb8fe5467fa9d49e5f6a" }, "data": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$", "description": "Account deployment data", "example": "0x..." } }, "required": [ "to", "data" ] }, "description": "Setup operations for the smart account. Only used if the account is not deployed" }, "mockSignatures": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$" }, "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." }, "mockSignature": { "description": "Deprecated. Must be omitted; use `mockSignatures` (keyed by chain id) instead." }, "delegations": { "type": "object", "additionalProperties": { "type": "object", "properties": { "contract": { "type": "string", "description": "address of contract to which delegation on behalf of sponsor will be assumed for given chain ID" } }, "required": [ "contract" ] }, "description": "Per-chain specific map to delegated contract address for 7702 delegations. Use `0` to indicate cross-chain delegation" } }, "required": [ "address" ] }, "options": { "type": "object", "properties": { "settlementLayers": { "oneOf": [ { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP" ] } }, { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP" ] } } }, "required": [ "include" ], "additionalProperties": false }, { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP" ] } } }, "required": [ "exclude" ], "additionalProperties": false } ], "description": "Which settlement layers the orchestrator may use. `{ include: [...] }` (allow-list) or `{ exclude: [...] }` (deny-list, inverted against the orchestrator's live layer set); a bare array means `include`. Internal modes (`SAME_CHAIN`, `INTENT_EXECUTOR`) are not selectable. Default unset = all layers eligible.", "example": { "exclude": [ "RELAY" ] } }, "sponsorSettings": { "type": "object", "properties": { "gas": { "default": false, "type": "boolean", "description": "Whether to sponsor gas for the intent", "example": true }, "bridgeFees": { "default": false, "type": "boolean", "description": "Whether to sponsor bridge fees for the intent" }, "swapFees": { "default": false, "type": "boolean", "description": "Whether to sponsor swap fees for the intent" }, "protocolFees": { "default": false, "type": "boolean", "description": "Whether to sponsor the Rhinestone protocol fee (`options.protocolFees`) for the intent. When `true`, the fee is charged to the integrator's sponsorship balance instead of carved from the user, without the sponsorship surcharge." } }, "description": "Sponsor settings for the intent", "example": { "gas": true, "bridgeFees": true, "swapFees": true } }, "signatureMode": { "type": "string", "enum": [ "EMISSARY", "ERC1271", "EMISSARY_ERC1271", "ERC1271_EMISSARY", "EMISSARY_EXECUTION", "EMISSARY_EXECUTION_ERC1271", "ERC1271_EMISSARY_EXECUTION", 0, 1, 2, 3, 4, 5, 6 ], "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 }, "appFees": { "type": "object", "properties": { "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "App fee rate in basis points of the input value (0–10000 = 0–100%).", "example": 25 } }, "required": [ "feeBps" ] }, "protocolFees": { "type": "object", "properties": { "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Rhinestone protocol fee rate in basis points of the input value (0–10000 = 0–100%). Collected alongside the app fee in one batched transfer and always accrues to Rhinestone; sponsor it via `sponsorSettings.protocolFees` to charge the integrator balance instead of the user.", "example": 35 } }, "required": [ "feeBps" ] }, "executionTokensReceived": { "type": "array", "items": { "type": "string" }, "description": "Tokens that will be received by EOA executions. These will be swept to the recipient account.", "example": [ "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" ] }, "auxiliaryFunds": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string", "format": "uint256" } }, "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 CAIP-2 chain ID, then token address; amounts in the token's smallest unit.", "example": { "eip155:42161": { "0xaf88d065e77c8cC2239327C5EDb3A432268e5831": "500000000" } } }, "selectionStrategy": { "type": "string", "enum": [ "cheapest", "fastest", "best" ], "description": "How to rank candidate plans. `cheapest` minimizes direct USD cost. `fastest` minimizes estimated fill time (with cost tiebreaker). `best` minimizes total USD given up: delivered-output forgone versus the best candidate, plus cost, plus the cost of waiting. Waiting is charged both in proportion to notional (0.8 bps per minute, modelling price risk on funds in flight) and as a flat $0.10 per minute independent of size, so small intents are ranked mostly on speed and large ones mostly on price. The two are equal at $1,250 of notional.", "example": "best" }, "customDeadline": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "Absolute unix timestamp (seconds) overriding the on-chain fill deadline. **TOKENLESS intents only.** If the intent resolves to any other route (cross-chain or same-chain), the request is **rejected** with `INVALID_CUSTOM_DEADLINE` (422) rather than silently ignoring the override. Must be between `now + 120s` and `now + 86400s`. The bundle claim/nonce expiry and the response `expiresAt` track this value automatically.", "example": 1893456000 } }, "description": "Intent options", "example": { "settlementLayers": { "include": [ "ECO" ] }, "sponsorSettings": { "gas": true, "bridgeFees": true, "swapFees": true } } } }, "required": [ "destinationChainId", "tokenRequests", "account" ], "description": "Quote request. Chain ids are CAIP-2 strings (e.g. `eip155:8453`, `solana:…`, `tron:…`); bare numeric ids are rejected.", "example": { "destinationChainId": "eip155:8453", "tokenRequests": [ { "tokenAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "1000000" } ], "account": { "address": "0x579d5631f76126991c00fb8fe5467fa9d49e5f6a" } } } } } } } }, "/quotes/estimate": { "post": { "operationId": "createQuoteEstimate", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "routes": { "type": "array", "items": { "type": "object", "properties": { "settlementLayer": { "type": "string", "enum": [ "INTENT_EXECUTOR", "SAME_CHAIN", "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP" ], "description": "Settlement layer this estimate is for", "example": "ACROSS" }, "accuracy": { "type": "string", "enum": [ "exact", "approximated" ], "description": "`exact` for formula-priced layers; `approximated` for solver-market layers estimated from a typical-fee table.", "example": "exact" }, "status": { "type": "string", "enum": [ "ok", "over_capacity" ], "description": "`over_capacity` when the delivered notional exceeds the known liquidity ceiling for this route; such routes rank below fillable ones.", "example": "ok" }, "input": { "type": "object", "properties": { "chainId": { "type": "string", "pattern": "^eip155:[0-9]{1,32}$", "description": "Chain where this token leg settles", "example": "eip155:8453" }, "tokenAddress": { "type": "string", "description": "ERC-20 contract address for this token", "example": "0xaf88d065e77c8cc2239327c5edb3a432268e5831" }, "symbol": { "type": "string", "nullable": true, "description": "Token symbol. `null` when the internal token registry has no entry for this address.", "example": "USDC" }, "decimals": { "type": "integer", "nullable": true, "description": "Token decimals. `null` when the internal token registry has no entry for this address.", "example": 6 }, "price": { "type": "object", "properties": { "usd": { "type": "number", "description": "Unit price in USD", "example": 1 } }, "required": [ "usd" ], "nullable": true, "description": "Unit price in USD. `null` when the price oracle has no data for this token." }, "amount": { "type": "string", "format": "uint256", "description": "Token amount in the token's smallest unit", "example": "1050000" } }, "required": [ "chainId", "tokenAddress", "symbol", "decimals", "price", "amount" ], "description": "A single (chain, token) leg with amount, price, and metadata" }, "output": { "type": "object", "properties": { "chainId": { "type": "string", "pattern": "^(eip155|solana|tron|hypercore):[-_a-zA-Z0-9]{1,32}$", "description": "Chain where this token leg settles (CAIP-2, any namespace)", "example": "eip155:8453" }, "tokenAddress": { "type": "string", "minLength": 1, "description": "Contract address of the delivered token (EVM 0x or non-EVM base58)", "example": "0xaf88d065e77c8cc2239327c5edb3a432268e5831" }, "symbol": { "type": "string", "nullable": true, "description": "Token symbol. `null` when the internal token registry has no entry for this address.", "example": "USDC" }, "decimals": { "type": "integer", "nullable": true, "description": "Token decimals. `null` when the internal token registry has no entry for this address.", "example": 6 }, "price": { "type": "object", "properties": { "usd": { "type": "number", "description": "Unit price in USD", "example": 1 } }, "required": [ "usd" ], "nullable": true, "description": "Unit price in USD. `null` when the price oracle has no data for this token." }, "amount": { "type": "string", "format": "uint256", "description": "Token amount in the token's smallest unit", "example": "1050000" } }, "required": [ "chainId", "tokenAddress", "symbol", "decimals", "price", "amount" ], "description": "A single (chain, token) leg with amount, price, and metadata" }, "fees": { "type": "object", "properties": { "total": { "type": "object", "properties": { "usd": { "type": "number", "description": "USD-denominated value", "example": 0.029 } }, "required": [ "usd" ], "description": "Full route cost in USD, regardless of who pays. Equal to `sum(breakdown.*.usd)` modulo rounding." }, "breakdown": { "type": "object", "properties": { "gas": { "type": "object", "properties": { "usd": { "type": "number", "description": "Total cost of this category in USD, regardless of who pays.", "example": 0.029 }, "sponsored": { "type": "boolean", "description": "True when a sponsor absorbs some or all of this category. The user-vs-sponsor split is not surfaced.", "example": false } }, "required": [ "usd", "sponsored" ], "description": "Aggregate gas cost (destination fill, swap execution, origin gas)" }, "bridge": { "type": "object", "properties": { "usd": { "type": "number", "description": "Total cost of this category in USD, regardless of who pays.", "example": 0.029 }, "sponsored": { "type": "boolean", "description": "True when a sponsor absorbs some or all of this category. The user-vs-sponsor split is not surfaced.", "example": false } }, "required": [ "usd", "sponsored" ], "description": "Aggregate settlement-layer bridge cost" }, "swap": { "type": "object", "properties": { "usd": { "type": "number", "description": "Total cost of this category in USD, regardless of who pays.", "example": 0.029 }, "sponsored": { "type": "boolean", "description": "True when a sponsor absorbs some or all of this category. The user-vs-sponsor split is not surfaced.", "example": false } }, "required": [ "usd", "sponsored" ], "description": "Aggregate solver swap commission" }, "app": { "type": "object", "properties": { "usd": { "type": "number", "description": "Total cost of this category in USD, regardless of who pays.", "example": 0.029 }, "sponsored": { "type": "boolean", "description": "True when a sponsor absorbs some or all of this category. The user-vs-sponsor split is not surfaced.", "example": false } }, "required": [ "usd", "sponsored" ], "description": "Aggregate integrator app fee" }, "protocol": { "type": "object", "properties": { "usd": { "type": "number", "description": "Total cost of this category in USD, regardless of who pays.", "example": 0.029 }, "sponsored": { "type": "boolean", "description": "True when a sponsor absorbs some or all of this category. The user-vs-sponsor split is not surfaced.", "example": false } }, "required": [ "usd", "sponsored" ], "description": "Rhinestone protocol fee (`options.protocolFees`). `sponsored: true` when the integrator sponsorship balance pays it instead of the user." }, "sponsorSurcharge": { "type": "object", "properties": { "usd": { "type": "number", "description": "Total cost of this category in USD, regardless of who pays.", "example": 0.029 }, "sponsored": { "type": "boolean", "description": "True when a sponsor absorbs some or all of this category. The user-vs-sponsor split is not surfaced.", "example": false } }, "required": [ "usd", "sponsored" ], "description": "Rhinestone's surcharge on the sponsored relayer coverage, charged to the sponsor. 0 when the intent is not sponsored. Pure surcharge — a sponsored protocol fee is shown on `protocol`, never here." } }, "required": [ "gas", "bridge", "swap", "app", "protocol", "sponsorSurcharge" ], "description": "Per-category fee breakdown" } }, "required": [ "total", "breakdown" ], "description": "Aggregate route fees with per-category breakdown" }, "estimatedFillTime": { "type": "object", "properties": { "seconds": { "type": "number", "description": "Typical end-to-end fill time for this route in seconds. Directional, not guaranteed.", "example": 3 } }, "required": [ "seconds" ], "description": "Estimated fill time for the route" } }, "required": [ "settlementLayer", "accuracy", "status", "input", "output", "fees", "estimatedFillTime" ], "description": "A single indicative route estimate" }, "description": "Indicative route estimates, best-first. Empty when no route is available." }, "unavailableReason": { "type": "string", "enum": [ "unsupported_token", "no_route_support", "no_price", "below_minimum" ], "description": "Set when `routes` is empty and there is a single explanatory reason." } }, "required": [ "routes" ], "description": "Response body for `POST /quotes/estimate`. Indicative (non-binding): carries no `intentId`, `signData`, or `expiresAt`." } } } }, "400": { "description": "Invalid request parameters", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "403": { "description": "API key scope denied", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "Create Indicative Quote", "description": "Computes an indicative (non-binding) quote: ranked route estimates with per-route cost breakdown and fill time. Unlike `POST /quotes`, it returns no `intentId`, `signData`, or `expiresAt` — it cannot be submitted to `POST /intents`. Use it for pre-quote UX (price previews, route discovery) without persisting an intent.", "tags": [ "Quotes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "exactIn", "exactOut" ], "description": "`exactIn` fixes the deposited `amountIn` and estimates the delivered output; `exactOut` fixes the desired `amountOut` and estimates the required input.", "example": "exactIn" }, "sourceChainId": { "type": "string", "pattern": "^eip155:[0-9]{1,32}$", "description": "Source chain id (CAIP-2, eip155)", "example": "eip155:8453" }, "sourceToken": { "type": "string", "description": "Source token address", "example": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" }, "destinationChainId": { "type": "string", "pattern": "^(eip155|solana|tron|hypercore):[-_a-zA-Z0-9]{1,32}$", "description": "Destination chain id (CAIP-2), matching the destinations `POST /quotes` accepts: EVM (`eip155:*`), the virtual `hypercore:mainnet`, or non-EVM `solana:…` / `tron:…`.", "example": "eip155:42161" }, "destinationToken": { "type": "string", "minLength": 1, "description": "Destination token address — EVM `0x…`, Solana base58 mint, or Tron T-address.", "example": "0xaf88d065e77c8cc2239327c5edb3a432268e5831" }, "amountIn": { "type": "string", "format": "uint256", "description": "Deposited amount in the source token's smallest unit. Required for (and only valid with) `direction: exactIn`.", "example": "1000000" }, "amountOut": { "type": "string", "format": "uint256", "description": "Desired delivered amount in the destination token's smallest unit. Required for (and only valid with) `direction: exactOut`.", "example": "1000000" }, "balance": { "type": "string", "enum": [ "spot", "perp" ], "description": "Which HyperCore balance receives this token request — 'spot' (the spot wallet) or 'perp' (the default perp dex's margin account). REQUIRED when destinationChainId is HyperCore, with no default: the two answers credit different accounts, so an unstated venue is rejected rather than guessed. Every tokenRequest in one intent must name the same venue. Rejected on every other destination.", "example": "spot" }, "accountType": { "type": "string", "enum": [ "EOA", "SMART_ACCOUNT" ], "description": "Account the route would execute against. Settlement layers filter on account type, so declaring it yields an estimate that matches what `POST /quotes` would plan. Defaults to `EOA` — the more restrictive of the two — so an undeclared caller is never shown smart-account-only routes.", "example": "SMART_ACCOUNT" }, "accountDeployed": { "type": "boolean", "description": "Whether the smart account is already deployed on the source chain. An undeployed account pays one-time setup gas, so declaring it avoids over-charging repeat users. Defaults to undeployed (charges setup) for a smart account when omitted — the conservative direction. Ignored for EOAs.", "example": true }, "options": { "type": "object", "properties": { "settlementLayers": { "oneOf": [ { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP" ] } } }, "required": [ "include" ], "additionalProperties": false }, { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP" ] } } }, "required": [ "exclude" ], "additionalProperties": false } ], "description": "Which settlement layers the estimate may rank. `{ include: [...] }` (allow-list) or `{ exclude: [...] }` (deny-list). Default unset = all layers eligible.", "example": { "exclude": [ "RELAY" ] } }, "sponsorSettings": { "type": "object", "properties": { "gas": { "default": false, "type": "boolean", "description": "Whether to sponsor gas for the intent", "example": true }, "bridgeFees": { "default": false, "type": "boolean", "description": "Whether to sponsor bridge fees for the intent" }, "swapFees": { "default": false, "type": "boolean", "description": "Whether to sponsor swap fees for the intent" }, "protocolFees": { "default": false, "type": "boolean", "description": "Whether to sponsor the Rhinestone protocol fee (`options.protocolFees`) for the intent. When `true`, the fee is charged to the integrator's sponsorship balance instead of carved from the user, without the sponsorship surcharge." } }, "description": "Which fee categories to treat as sponsored. Sponsored categories are absorbed by the sponsor and do not reduce the delivered amount.", "example": { "gas": true, "bridgeFees": true, "swapFees": false } }, "selectionStrategy": { "type": "string", "enum": [ "cheapest", "fastest", "best" ], "description": "How to rank candidate routes. `cheapest` minimizes USD cost, `fastest` minimizes fill time, `best` minimizes total USD given up — delivered-output forgone, plus cost, plus the cost of waiting (0.8 bps/min of notional for price risk plus a flat $0.10/min). Mirrors the binding `/quotes` selector, so the recommended route agrees with the one you will be quoted.", "example": "best" }, "appFees": { "type": "object", "properties": { "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "App fee rate in basis points of the input value (0–10000 = 0–100%).", "example": 25 } }, "required": [ "feeBps" ], "description": "Integrator app fee applied to the estimate" }, "protocolFees": { "type": "object", "properties": { "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Rhinestone protocol fee rate in basis points of the input value (0–10000 = 0–100%). Carved from the user unless `sponsorSettings.protocolFees` is set.", "example": 5 } }, "required": [ "feeBps" ], "description": "Rhinestone protocol fee applied to the estimate" } }, "description": "Optional estimate tuning knobs" } }, "required": [ "direction", "sourceChainId", "sourceToken", "destinationChainId", "destinationToken" ], "description": "Indicative-quote request. Chain ids are eip155 CAIP-2 strings; exactly one of `amountIn`/`amountOut` is required, matching `direction`." } } } } } }, "/app-fees/balances": { "get": { "operationId": "getAppFeeBalances", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawableUsd": { "type": "number" }, "pendingUsd": { "type": "number" } }, "required": [ "withdrawableUsd", "pendingUsd" ] } } } }, "400": { "description": "Validation error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "401": { "description": "Missing or invalid API key", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "Get App-Fee Balances", "description": "The authenticated project's app-fee balance as USD totals valued at collection time. `pendingUsd` is the payout value permanently reserved by signed withdrawals whose target-chain FILL has not completed, including failed or expired payouts.", "tags": [ "App Fees" ] } }, "/app-fees/withdrawal-targets": { "get": { "operationId": "getAppFeeWithdrawalTargets", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "string", "pattern": "^eip155:[0-9]{1,32}$" }, "tokens": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string", "enum": [ "USDC", "USDT0", "USDT" ] }, "decimals": { "type": "integer", "minimum": 0 } }, "required": [ "address", "symbol", "decimals" ], "additionalProperties": false } } }, "required": [ "chainId", "tokens" ], "additionalProperties": false } } }, "required": [ "targets" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "401": { "description": "Missing or invalid API key", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "403": { "description": "API key scope denied", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "Get App-Fee Withdrawal Targets", "description": "Get the enabled EVM chains and whitelisted stablecoins currently accepted for app-fee withdrawals.", "tags": [ "App Fees" ] } }, "/app-fees/withdrawals": { "post": { "operationId": "createAppFeeWithdrawal", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." } ], "responses": { "202": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestNonce": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "requestNonce" ] } } } }, "400": { "description": "No payout address, nothing to withdraw, or invalid target", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "401": { "description": "Missing or invalid API key", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "409": { "description": "A withdrawal is already being signed", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "Create App-Fee Withdrawal", "description": "Withdraw the authenticated project's full app-fee balance to a whitelisted stablecoin on the chosen chain, paid to the project's registered payout address.", "tags": [ "App Fees" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetChainId": { "type": "string", "pattern": "^eip155:[0-9]{1,32}$" }, "targetToken": { "type": "string" } }, "required": [ "targetChainId", "targetToken" ] } } } } }, "get": { "operationId": "listAppFeeWithdrawals", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "withdrawals": { "type": "array", "items": { "type": "object", "properties": { "requestNonce": { "type": "string", "pattern": "^\\d+$" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ] }, "payoutUsd": { "type": "number" }, "targetChainId": { "type": "string", "pattern": "^eip155:[0-9]{1,32}$" }, "targetToken": { "type": "string" }, "targetAmount": { "type": "string" }, "payoutAddress": { "type": "string" }, "txHash": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "requestNonce", "status", "payoutUsd", "targetChainId", "targetToken", "targetAmount", "payoutAddress", "txHash", "createdAt" ] } } }, "required": [ "withdrawals" ] } } } }, "400": { "description": "Validation error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "401": { "description": "Missing or invalid API key", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "403": { "description": "API key scope denied", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "List App-Fee Withdrawals", "description": "The authenticated project's app-fee withdrawals (newest first) with each withdrawal's status and USD value paid out.", "tags": [ "App Fees" ] } }, "/app-fees/withdrawals/{nonce}": { "get": { "operationId": "getAppFeeWithdrawal", "parameters": [ { "name": "x-api-version", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "2026-04.blanc" ] }, "description": "API version. Required; pinned to this document." }, { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "API key." }, { "name": "nonce", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestNonce": { "type": "string", "pattern": "^\\d+$" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "FAILED" ] }, "payoutUsd": { "type": "number" }, "targetChainId": { "type": "string", "pattern": "^eip155:[0-9]{1,32}$" }, "targetToken": { "type": "string" }, "targetAmount": { "type": "string" }, "payoutAddress": { "type": "string" }, "txHash": { "type": "string", "nullable": true }, "createdAt": { "type": "string" } }, "required": [ "requestNonce", "status", "payoutUsd", "targetChainId", "targetToken", "targetAmount", "payoutAddress", "txHash", "createdAt" ] } } } }, "400": { "description": "Validation error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "401": { "description": "Missing or invalid API key", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "403": { "description": "API key scope denied", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "404": { "description": "Withdrawal not found", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } }, "500": { "description": "Server error", "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": {}, "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": [ "SIMULATION_FAILED" ] }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid input" }, "details": { "type": "object", "properties": { "nonce": { "type": "string" }, "category": { "type": "string" }, "errorSelector": { "type": "string" }, "errorName": { "type": "string" }, "errorArgs": { "type": "object", "additionalProperties": { "type": "string" } }, "retryable": { "type": "boolean" }, "retryHint": { "type": "string", "enum": [ "RE_PREPARE", "RETRY_LATER" ] }, "simulations": {} }, "required": [ "category", "errorSelector", "errorName", "retryable" ], "additionalProperties": true, "description": "Classified on-chain simulation failure details" } }, "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", "WITHDRAWAL_IN_PROGRESS", "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" ] } ] } } } } }, "summary": "Get App-Fee Withdrawal", "description": "A single app-fee withdrawal owned by the authenticated project, with its status and USD value paid out.", "tags": [ "App Fees" ] } } } }