{ "openapi": "3.0.0", "info": { "title": "Rhinestone Orchestrator API", "version": "2026-04.blanc" }, "servers": [ { "url": "https://v1.orchestrator.rhinestone.dev" } ], "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Project API key." }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Integrator-issued access token (JWT authentication mode)." } } }, "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." }, "nativeToken": { "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 chain's gas asset. Lets a client name a native-value transfer without assuming ETH — a wallet on a non-ETH chain would otherwise label AVAX or BNB as ETH in every review and receipt." }, "explorer": { "type": "object", "properties": { "url": { "type": "string", "example": "https://basescan.org" }, "addressPath": { "type": "string", "example": "/address/" }, "txPath": { "type": "string", "example": "/tx/" } }, "required": [ "url", "addressPath", "txPath" ], "nullable": true, "description": "Block explorer, or null for a chain that has none. Lets a client link a transaction on a chain it was never compiled against, instead of bundling a per-chain URL table." }, "settlement": { "type": "object", "properties": { "cctp": { "type": "object", "properties": { "domain": { "type": "number" }, "tokenMessenger": { "type": "string" }, "usdc": { "type": "string" } }, "required": [ "domain", "tokenMessenger", "usdc" ] }, "oft": { "type": "object", "properties": { "adapter": { "type": "string" }, "eid": { "type": "number" }, "token": { "type": "string" } }, "required": [ "adapter", "eid", "token" ] }, "eco": { "type": "object", "properties": { "portal": { "type": "string" }, "provers": { "type": "array", "items": { "type": "string" } }, "stablecoins": { "type": "array", "items": { "type": "string" } } }, "required": [ "portal", "provers", "stablecoins" ] }, "lz": { "type": "object", "properties": { "multiCall": { "type": "string" }, "transferDelegate": { "type": "string" }, "stargateUsdc": { "type": "object", "properties": { "pool": { "type": "string" }, "token": { "type": "string" }, "eid": { "type": "number" } }, "required": [ "pool", "token", "eid" ] }, "cctp": { "type": "object", "properties": { "domain": { "type": "number" }, "token": { "type": "string" }, "feeReceiver": { "type": "string" }, "feeless": { "type": "boolean", "enum": [ true ] } }, "required": [ "domain", "token", "feeReceiver" ] } }, "required": [ "multiCall", "transferDelegate" ] }, "swapper": { "type": "object", "properties": { "swapper": { "type": "string" }, "proxy": { "type": "string" } }, "required": [ "swapper", "proxy" ] }, "fees": { "type": "object", "properties": { "appFeeCollector": { "type": "string" }, "paymaster": { "type": "string" } }, "required": [ "appFeeCollector", "paymaster" ] }, "usdStablecoins": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "number" } }, "required": [ "address", "symbol", "decimals" ] }, "description": "The USD stablecoins (6 or 18 decimals) a session stable-swap floor treats as 1:1." } }, "description": "What an SDK session pins on this chain: the contracts each settlement layer calls, and the USD stablecoins a stable-swap floor treats as 1:1. A layer appears only when every address it needs is known. Absent when the chain has none of these." } }, "required": [ "name", "testnet", "supportedTokens", "wrappedNativeToken", "nativeToken", "explorer" ] }, "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" ] } ] } } } } }, "security": [], "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": "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|stellar):[-_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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "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": "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 }, "failureReason": { "type": "string", "description": "Why the operation failed (present only when FAILED). `NOT_EXECUTED` means the source transaction did not land and can no longer land: the account’s funds never left, and the caller can safely re-quote and sign again. `failureEvidence` on the source operation carries the chain evidence.", "example": "BRIDGE_TIMEOUT" }, "failureEvidence": { "type": "object", "properties": { "vm": { "type": "string", "enum": [ "svm" ] }, "reason": { "type": "string", "enum": [ "COUNTER_UNCONSUMED" ], "description": "The role's on-chain counter never reached the one the payload signed" }, "swig": { "type": "string", "minLength": 1, "description": "The Swig state account, base58" }, "roleId": { "type": "integer", "minimum": 0, "description": "The Swig role the payload was signed under" }, "signedCounter": { "type": "integer", "minimum": 0, "description": "The replay counter the payload consumes" }, "observedCounter": { "type": "integer", "minimum": 0, "description": "The role's stored counter at `observedSlot`" }, "lastValidSlot": { "type": "string", "pattern": "^\\d+$", "description": "The last slot the payload could have executed in", "example": "312000060" }, "observedSlot": { "type": "string", "pattern": "^\\d+$", "description": "The finalized slot the role was read at", "example": "312000081" }, "commitment": { "type": "string", "enum": [ "finalized" ] } }, "required": [ "vm", "reason", "swig", "roleId", "signedCounter", "observedCounter", "lastValidSlot", "observedSlot", "commitment" ], "additionalProperties": false, "description": "Finalized chain evidence that the source transaction did not land and can no longer land: the cluster is past the payload’s last valid slot and the role never consumed its counter. The account’s funds never left; re-quote and sign again." }, "debitsAccount": { "type": "boolean", "enum": [ true ], "description": "This operation's transaction spends the account's own tokens. Absent means it moves none of them (a destination fill, or a tokenless intent). Read it together with the operation status: a FAILED intent none of whose debiting operations reached COMPLETED never took the account's funds. Per-operation rather than per-intent because a multi-origin intent has several claims and they can differ.", "example": true }, "allocation": { "type": "object", "properties": { "plannedGasMicroUsd": { "type": "string", "pattern": "^\\d+$", "description": "Sponsor-covered gas planned for this operation (micro-USD)", "example": "100" }, "fixedCompensationMicroUsd": { "type": "string", "pattern": "^\\d+$", "description": "Fixed non-gas compensation (micro-USD); nonzero only on FILL allocations", "example": "0" }, "executedGasMicroUsd": { "type": "string", "pattern": "^\\d+$", "description": "Receipt-derived actual gas (micro-USD); null means the planned fallback applies", "example": "80", "nullable": true }, "payableMicroUsd": { "type": "string", "pattern": "^\\d+$", "description": "fixedCompensation + (executedGas ?? plannedGas), in micro-USD", "example": "80" }, "counterparty": { "type": "string", "nullable": true, "description": "Canonical earner, stamped from the receipt sender this allocation reconciled to, in the chain's own address format (EVM hex, Solana base58); null until earned" }, "nativeTokenPriceUsd": { "type": "string", "nullable": true, "description": "Pinned POST (PATH-fallback) native-token USD price the gas micro-USD was valued at, as a decimal string; null when no price snapshot exists", "example": "2000" }, "receipt": { "type": "object", "properties": { "blockHash": { "type": "string", "nullable": true, "description": "Block hash" }, "blockNumber": { "type": "string", "description": "Block number" }, "gasUsed": { "type": "string", "nullable": true, "description": "Gas used" }, "effectiveGasPriceWei": { "type": "string", "nullable": true, "description": "Effective gas price (wei)" }, "l1FeeWei": { "type": "string", "nullable": true, "description": "L1 fee (wei), OP-stack chains only" }, "blobFeeWei": { "type": "string", "nullable": true, "description": "Blob fee (wei)" } }, "required": [ "blockHash", "blockNumber", "gasUsed", "effectiveGasPriceWei", "l1FeeWei", "blobFeeWei" ], "nullable": true, "description": "Canonical receipt evidence; txHash/timestamp already sit on the item" }, "payment": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "PAYMENT", "ADJUSTMENT" ] }, "effectiveDate": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "kind", "effectiveDate", "createdAt" ], "nullable": true, "description": "Treasury settlement of this allocation; null until settled. Destinations, references, and operator fields are never exposed." } }, "required": [ "plannedGasMicroUsd", "fixedCompensationMicroUsd", "executedGasMicroUsd", "payableMicroUsd", "counterparty", "nativeTokenPriceUsd", "receipt", "payment" ], "description": "Blanc only. Present only on operations the CALLER earned: the allocation's stamped `counterparty`, or — before conversion stamps one — the operation's canonical receipt sender, is one of the caller's registered `scopes.relayer.fillAddresses`. Holding the relayer scope is not sufficient, because `/intents/:id` is nonce-only and scope alone would disclose another relayer's counterparties, amounts and settlement dates off a guessed intent id. Everything else fails closed. Amounts are micro-USD." } }, "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)." }, "refunds": { "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "number", "description": "Chain the refund landed on", "example": 42161 }, "txHash": { "type": "string", "description": "Refund transaction hash, in the chain-native form (EVM hex, Solana base58, Tron hex) — interpret it against `chain`.", "example": "0x00ab46cc4d1e4b5d5f6a9a2b1c0d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d" } }, "required": [ "chain", "txHash" ], "description": "A bridge refund returned to the account for this intent" }, "description": "Bridge refunds observed for this intent — a settlement layer returned the funds to the account instead of delivering them. Not operations: Rhinestone neither built nor broadcast these transactions, and a refund never makes the intent succeed. Omitted when none are known, which is every delivered intent and also a failed one whose refund we have not (or not yet) observed — so its absence is not evidence that funds were kept." }, "hyperCore": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "pending", "accepted", "refused", "error", "unknown", "partial" ], "description": "`pending` while the action is still owed — the POST runs after the fill transaction commits, so this is normal for a few seconds after delivery. `accepted` means Hyperliquid took it; an order filled for less than asked is accepted, simply for less. `refused` is the exchange declining a well-formed action — an `Ioc` that no longer crossed by the time the bridge delivered is the expected one — and `error` is it never answering before the intent expired.\n\n`unknown` means a delivery attempt got no response at all, so the action MAY have been applied and only its answer lost. `partial` means some orders of one batch were placed and others rejected — an `order` action carries up to 100 and each is matched independently.\n\nEvery non-`accepted` terminal value reports the intent as FAILED, because reporting success on a maybe is the failure this field exists to prevent. Do NOT re-send a `partial` batch as-is: the orders that filled would open a second time. Check the account on Hyperliquid for `partial` and `unknown` alike — it holds the per-order record, and the funds are in its own HyperCore balance whatever happened.", "example": "accepted" } }, "required": [ "outcome" ], "description": "What Hyperliquid did with this intent's `options.hyperCore` action, and the only record of it — the action is the one leg of an intent that is not a transaction. Omitted for every intent that carried none.\n\nIt DECIDES `status` rather than annotating it: an intent whose action was refused reports FAILED even though every operation completed, because the delivery landed and the trade did not. The funds are in the account's own HyperCore balance either way, so a refusal is recoverable by trading again — it is not a loss." }, "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", "minLength": 1, "description": "Destination recipient account, in the destination chain's own address format", "example": "0x3672e268a79bd4acc5ee646bdda652547c7a435c" }, "createdAt": { "type": "number", "description": "Intent creation time in unix seconds", "example": 1633493100 }, "latencyMs": { "type": "number", "minimum": 0, "nullable": true, "description": "Milliseconds from recorded creation to the latest included receipt; null without receipts. Negative intervals clamp to zero, not evidence of instant execution. Receipt times use chain time (possibly second-precision) or server-observation fallbacks. This is not final completion latency or a guarantee of millisecond accuracy.", "example": 8100 }, "settlementLayer": { "type": "string", "enum": [ "INTENT_EXECUTOR", "SAME_CHAIN", "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP", "LZ" ], "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", "minLength": 1, "description": "Token address, in the format its chain uses (EVM hex, non-EVM base58)", "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", "minLength": 1, "description": "Token address, in the format its chain uses (EVM hex, non-EVM base58)", "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." }, "solanaExecution": { "type": "object", "properties": { "executedBy": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "account", "solver" ], "description": "Who runs the calls: the account itself, or a solver-operated contract running them on its behalf.", "example": "account" }, "address": { "type": "string", "minLength": 1, "description": "Address of the executing contract or account", "example": "0x579d5631f76126991c00fb8fe5467fa9d49e5f6a" } }, "required": [ "kind", "address" ], "description": "The executor of the disclosed calls" }, "instructions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string", "description": "Program to invoke, base58.", "example": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "pubkey": { "type": "string", "description": "Account address, base58.", "example": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" }, "isSigner": { "type": "boolean", "description": "Whether the instruction requires this account to sign." }, "isWritable": { "type": "boolean", "description": "Whether the instruction writes to this account." } }, "required": [ "pubkey", "isSigner", "isWritable" ] }, "maxItems": 64, "description": "Accounts the instruction reads or writes, in the order the program expects." }, "data": { "type": "string", "description": "Instruction data, base64.", "example": "CQ==" } }, "required": [ "programId", "accounts", "data" ], "description": "A Solana instruction in the JSON shape `@solana/web3.js` and Jupiter `/swap-instructions` produce, so protocol output passes through unchanged." }, "description": "The caller's own instructions, in execution order" }, "addressLookupTables": { "type": "array", "items": { "type": "string" }, "description": "Address lookup tables the instructions resolve against" } }, "required": [ "executedBy", "instructions", "addressLookupTables" ], "description": "Caller-supplied Solana instructions and lookup tables committed to by the intent. Present on instruction-only Solana intents." }, "cost": { "type": "object", "properties": { "sponsored": { "type": "boolean", "description": "Whether gas/fees were sponsored for this intent", "example": true }, "sponsoredValue": { "type": "string", "pattern": "^\\d+$", "description": "Sponsored value actually charged, in integer micro-USD (1 USD = 1,000,000 units). Once the intent executes this is reconciled from the receipt (planned gas replaced by executed), so it matches the sponsorship balance and the usage/billing reads rather than the amount reserved at quote time. On an allocation-backed intent this is the sum of its per-operation allocations, which is where reconciliation writes executed gas. Includes Relay's subsidy of its own bridge fee, charged at par.", "example": "210000" }, "protocolFee": { "type": "string", "pattern": "^\\d+$", "description": "Rhinestone-owed slice of the sponsor charge, in integer micro-USD (1 USD = 1,000,000 units): the sponsor surcharge plus a sponsored protocol fee (`sponsorSettings.protocolFees`) where one applies. Charged on allocation-backed intents too — the allocation ledger carries the relayer liability only.", "example": "10000" }, "sponsorSurcharge": { "type": "string", "pattern": "^\\d+$", "description": "Rhinestone's surcharge on the sponsored coverage, in integer micro-USD — the pure surcharge slice of `protocolFee` and reconciled with it, as `sponsorSurcharge` on a quote. Omitted where the charge was recorded without the split, which is never inferred by subtraction.", "example": "10000" } }, "required": [ "sponsored" ], "description": "Cost summary from the recorded fee sponsorship. Amounts are integer micro-USD; 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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "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": "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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "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": "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", "minLength": 1, "description": "Intent value token. Prefers the planned token delivered on the destination chain; falls back to the spent token when historical same-chain output accounting is unavailable.", "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 — the planned destination output when available, or the spent amount when historical same-chain output accounting is unavailable.", "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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "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." } ], "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" ] } ] } } } }, "409": { "description": "The intent or its shared sponsorship authorization was already used.", "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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "summary": "Create Intent", "description": "Submits a quoted intent for execution. Takes the `intentId` from `POST /quotes` (`routes[].intentId`) plus the proofs authorizing it: on `2026-09.caucasus` one ordered `proofs[]` answering the quote's `signingRequests[]` position by position; on earlier versions the role-keyed 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. Omit only when the route carried no `signData.destination`.", "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" ] }, "authorizations": { "type": "object", "properties": { "sponsor": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "oneOf": [ { "type": "number", "enum": [ 0 ], "description": "Numeric 0 means the EIP-7702 authorization can be applied to any chain." }, { "type": "string", "pattern": "^eip155:[0-9]{1,32}$", "description": "CAIP-2 chain identifier for a concrete EVM chain using the eip155 namespace.", "example": "eip155: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 chain ID is either a concrete eip155 CAIP-2 string or numeric 0 for an authorization valid on any chain." }, "recipient": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "oneOf": [ { "type": "number", "enum": [ 0 ], "description": "Numeric 0 means the EIP-7702 authorization can be applied to any chain." }, { "type": "string", "pattern": "^eip155:[0-9]{1,32}$", "description": "CAIP-2 chain identifier for a concrete EVM chain using the eip155 namespace.", "example": "eip155: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 chain ID is either a concrete eip155 CAIP-2 string or numeric 0 for an authorization valid on any chain." } } } }, "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." } ], "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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "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", "LZ" ] } }, { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP", "LZ" ] } } }, "required": [ "include" ], "additionalProperties": false }, { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP", "LZ" ] } } }, "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." } ], "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", "LZ" ], "description": "Settlement layer selected for this route", "example": "RELAY" }, "signData": { "type": "object", "properties": { "origin": { "type": "array", "items": { "discriminator": { "propertyName": "kind" }, "oneOf": [ { "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." }, "kind": { "type": "string", "enum": [ "eip712" ] } }, "required": [ "domain", "types", "primaryType", "message", "kind" ], "description": "EIP-712 typed data definition ready for `signTypedData`" }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "personalSign" ] }, "message": { "type": "string", "description": "Sign these characters as UTF-8 TEXT — viem `signMessage({ message })`, never `{ raw }`. Signing the decoded bytes yields a well-formed signature that the chain rejects.", "example": "a3f2c1d4e5b6a7980f1e2d3c4b5a69788796a5b4c3d2e1f0a1b2c3d4e5f60718" }, "expiresAtSlot": { "type": "string", "description": "Solana slot after which this payload is dead. Much shorter than the route `expiresAt` — about 24 seconds — and it is the binding one. Re-quote when it passes.", "example": "370123456" } }, "required": [ "kind", "message", "expiresAtSlot" ], "description": "An opaque payload for `personal_sign`" } ] }, "description": "Payloads for the origin legs, in submission order. Sign each entry and submit the signatures in matching order via `signatures.origin`. Discriminate on `kind`: `eip712` is signed as typed data, `personalSign` as a message." }, "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. Absent when a third-party bridge performs the delivery and there is nothing for the user to sign there." }, "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" ], "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|solana|tron|hypercore|stellar):[-_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 debited token (EVM 0x or non-EVM base58)", "example": "0xaf88d065e77c8cc2239327c5edb3a432268e5831" }, "symbol": { "type": "string", "nullable": true, "description": "Token symbol, from the internal token registry or, for a token it has no entry for, read on-chain while planning. `null` when neither resolved one.", "example": "USDC" }, "decimals": { "type": "integer", "nullable": true, "description": "Token decimals, from the internal token registry or, for a token it has no entry for, read on-chain while planning. `null` when neither resolved one.", "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 neither the price oracle nor this quote priced the 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|stellar):[-_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, from the internal token registry or, for a token it has no entry for, read on-chain while planning. `null` when neither resolved one.", "example": "USDC" }, "decimals": { "type": "integer", "nullable": true, "description": "Token decimals, from the internal token registry or, for a token it has no entry for, read on-chain while planning. `null` when neither resolved one.", "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 neither the price oracle nor this quote priced the 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" }, "executionPayment": { "discriminator": { "propertyName": "paidBy" }, "oneOf": [ { "type": "object", "properties": { "paidBy": { "type": "string", "enum": [ "wallet" ] }, "walletDebit": { "type": "object", "properties": { "chainId": { "type": "string", "pattern": "^(eip155|solana|tron|hypercore|stellar):[-_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 debited token (EVM 0x or non-EVM base58)", "example": "0xaf88d065e77c8cc2239327c5edb3a432268e5831" }, "symbol": { "type": "string", "nullable": true, "description": "Token symbol, from the internal token registry or, for a token it has no entry for, read on-chain while planning. `null` when neither resolved one.", "example": "USDC" }, "decimals": { "type": "integer", "nullable": true, "description": "Token decimals, from the internal token registry or, for a token it has no entry for, read on-chain while planning. `null` when neither resolved one.", "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 neither the price oracle nor this quote priced the 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" } }, "required": [ "paidBy", "walletDebit" ] }, { "type": "object", "properties": { "paidBy": { "type": "string", "enum": [ "sponsor" ] } }, "required": [ "paidBy" ] } ], "description": "Solana instruction execution only: the exact fixed wallet debit, or confirmation that the sponsor pays and the wallet has no execution debit. The wallet debit also appears in input." } }, "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": [ "ACROSS" ], "description": "Across spoke-pool deposit. Names a deposit to watch for a refund, not a delivery — an ACROSS intent is filled by our own relayer and tracked as an ordinary fill." }, "depositId": { "type": "string", "pattern": "^[0-9]{1,78}$", "description": "The Across deposit id our claim opens on the origin chain, as a decimal uint256. Derived as keccak(arbiter | sponsor | nonce)." } }, "required": [ "destinationChainId", "fillStatusTimeout", "type", "depositId" ] }, { "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": [ "ECO" ], "description": "Eco solver-network delivery" }, "quoteId": { "type": "string", "pattern": "^quote:[0-9a-f-]{36}$", "description": "Eco v1 quote ID for detailed delivery and refund tracking." }, "intentHash": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$", "description": "Eco Portal intent hash. Use against Eco's intent status API to resolve the destination delivery transaction." }, "providerDestinationChainId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "Eco's own id for the delivery chain, present only where it differs from `destinationChainId` (non-EVM destinations). Eco's status API reports fulfilment against this id." }, "providerSourceChainId": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "Eco's own id for the chain the reward was funded on, present only where it differs from the deposit chain (non-EVM origins)." } }, "required": [ "destinationChainId", "fillStatusTimeout", "type", "intentHash" ] }, { "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": { "oneOf": [ { "type": "string" }, { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$" } ], "description": "NEAR Intents deposit address on the origin chain, in its native form (EVM 0x or Solana base58). 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." }, "keyVariant": { "type": "string", "enum": [ "user_fee" ], "description": "Rhino.fi API key variant the commitment was quoted under. Rhino.fi answers a status lookup only under that key, so the fill-tracker asks for the same variant." } }, "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" ] }, { "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": [ "LZ" ], "description": "LayerZero Value Transfer" }, "quoteId": { "type": "string", "description": "LayerZero quote ID. Use against LayerZero's transfer status API to track the destination-chain fill." }, "dstChainKey": { "type": "string", "description": "LayerZero's own chain key for the destination (e.g. `base`). Its status response names chains by key rather than id." }, "routeTypes": { "type": "array", "items": { "type": "string" }, "description": "Protocols the quote routed through (e.g. STARGATE_V2_TAXI, CCTP_V2). One transfer can span several." } }, "required": [ "destinationChainId", "fillStatusTimeout", "type", "quoteId", "dstChainKey", "routeTypes" ] } ], "description": "Provider handle for resolving the destination-chain delivery transaction when settlement hands off to a third-party bridge (ECO, RHINO, RELAY, NEAR, CCTP, OFT). Absent when the orchestrator settles end-to-end (e.g. ACROSS)." } }, "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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "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|stellar):[-_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. IMPORTANT: for a self-send with no `destinationExecutions`, any balance of this token already held on the destination chain is CREDITED against the request, so this behaves as a target final balance and an already-satisfied request delivers nothing. The credit only applies when that destination balance is in scope as a source — pinning `sourceAssets` or `sourceChains` away from the destination chain excludes it, and then this amount is delivered in full on top of whatever is already there. Same-chain intents always have the destination balance in scope, so they always credit.", "example": "1000000" }, "balance": { "readOnly": true } }, "required": [ "tokenAddress" ] }, "description": "A list of tokens requested on the target chain. Note `amount` may be credited against a balance already held on the destination chain — see the field for exactly when." }, "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." }, "destinationInstructions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string", "description": "Program to invoke, base58.", "example": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "pubkey": { "type": "string", "description": "Account address, base58.", "example": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" }, "isSigner": { "type": "boolean", "description": "Whether the instruction requires this account to sign." }, "isWritable": { "type": "boolean", "description": "Whether the instruction writes to this account." } }, "required": [ "pubkey", "isSigner", "isWritable" ] }, "maxItems": 64, "description": "Accounts the instruction reads or writes, in the order the program expects." }, "data": { "type": "string", "description": "Instruction data, base64.", "example": "CQ==" } }, "required": [ "programId", "accounts", "data" ], "description": "A Solana instruction in the JSON shape `@solana/web3.js` and Jupiter `/swap-instructions` produce, so protocol output passes through unchanged." }, "minItems": 1, "maxItems": 32, "description": "Solana instructions to run, in order, out of the account's own Swig wallet on a Solana destination. They carry any transfers and payees, so omit `recipient` and `tokenRequests`; they cannot be combined with `destinationExecutions`. Unsponsored execution is paid from an eligible wallet SOL or SPL balance; `options.sponsorSettings.gas` bills the sponsor instead." }, "addressLookupTableAddresses": { "type": "array", "items": { "type": "string" }, "maxItems": 8, "description": "Address lookup tables the `destinationInstructions` resolve accounts through, base58, as Jupiter `/swap-instructions` returns them. Only with `destinationInstructions`." }, "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" }, "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", "LZ" ] } }, { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP", "LZ" ] } } }, "required": [ "include" ], "additionalProperties": false }, { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP", "LZ" ] } } }, "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" ] } }, "quoters": { "oneOf": [ { "type": "array", "items": { "type": "string", "enum": [ "1inch", "0x", "velora", "kyberswap", "fynd", "fynd-hosted", "bebop", "relay" ] } }, { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string", "enum": [ "1inch", "0x", "velora", "kyberswap", "fynd", "fynd-hosted", "bebop", "relay" ] } } }, "required": [ "include" ], "additionalProperties": false }, { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "1inch", "0x", "velora", "kyberswap", "fynd", "fynd-hosted", "bebop", "relay" ] } } }, "required": [ "exclude" ], "additionalProperties": false } ], "description": "Which swap quoters the orchestrator may source swap routes from. `{ include: [...] }` (allow-list) or `{ exclude: [...] }` (deny-list, inverted against the full quoter set); a bare array means `include`. Use this to keep a swap on the venue a smart-session policy is scoped to. Default unset = every quoter the chain supports.", "example": { "include": [ "0x" ] } }, "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. For an integrator enabled for it, this also sponsors the VALUE of an eligible same-chain swap, so the user trades at par: the user contributes the 1:1 amount and the sponsor pays whatever the market is short. That applies only to pairs where par is a meaningful rate (both sides USD-pegged) and only up to a configured per-swap ceiling; outside those bounds the swap is priced at market." }, "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 (0–10000 = 0–100%). The base is the USD value of the intent, and which value depends on the intent shape: for a fixed-output intent it is the requested destination target(s), summed across `tokenRequests`; for a max-out intent it is the spendable source balance; for a destination-swap intent it is the swap input. Note the fixed-output base is the full requested target, not the delta over any balance already held.", "example": 25 } }, "required": [ "feeBps" ] }, "protocolFees": { "type": "object", "properties": { "feeBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Rhinestone protocol fee rate in basis points (0–10000 = 0–100%), on the same base as `appFees.feeBps` — see that field. 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 }, "hyperCore": { "type": "object", "properties": { "action": { "discriminator": { "propertyName": "type" }, "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "orders": { "type": "array", "items": { "type": "object", "properties": { "a": { "type": "integer", "minimum": 0, "description": "Asset index. Perps use the index in the `meta` universe; spot uses `10000 + index` from `spotMeta`. This is an INDEX, not a ticker — resolve it from the info endpoint, and note that an index built against the wrong universe places a valid order in the wrong market.", "example": 0 }, "b": { "type": "boolean", "description": "Buy (`true`) or sell (`false`).", "example": true }, "p": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Limit price. Must satisfy Hyperliquid's tick rules — at most 5 significant figures and at most `6 - szDecimals` decimals for a perp — and is refused there, not here.\n\nThis price is fixed when you sign, and an intent that bridges to HyperCore takes ~30s to deliver. Price it to still cross after that move, or the order is refused with your funds already delivered.", "example": "64250.5" }, "s": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Size in units of the asset, to at most the asset's `szDecimals`. Hyperliquid refuses an order worth under ~$10.", "example": "0.0002" }, "r": { "type": "boolean", "description": "Reduce-only. `true` is how a position is CLOSED — pair it with a tokenless intent, since closing needs no delivered collateral.", "example": false }, "t": { "oneOf": [ { "type": "object", "properties": { "limit": { "type": "object", "properties": { "tif": { "type": "string", "enum": [ "Alo", "Ioc", "Gtc" ], "description": "Time in force. `Ioc` fills what it can and cancels the rest, which is how a market order is expressed here — there is no market order type. `Alo` is post-only. `Gtc` rests on the book.\n\nPrefer `Ioc` for anything an intent delivers funds for: a resting order leaves the account holding USDC and no position, and the agent that could have cancelled it is already spent.", "example": "Ioc" } }, "required": [ "tif" ], "additionalProperties": false } }, "required": [ "limit" ], "additionalProperties": false }, { "type": "object", "properties": { "trigger": { "type": "object", "properties": { "isMarket": { "type": "boolean" }, "triggerPx": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, "tpsl": { "type": "string", "enum": [ "tp", "sl" ], "description": "Take-profit or stop-loss.", "example": "sl" } }, "required": [ "isMarket", "triggerPx", "tpsl" ], "additionalProperties": false } }, "required": [ "trigger" ], "additionalProperties": false } ], "description": "Either `{ limit: { tif } }` or `{ trigger: { isMarket, triggerPx, tpsl } }`." }, "c": { "type": "string", "pattern": "^0x[0-9a-fA-F]{32}$", "description": "Optional client order id — 128-bit hex. Your handle on the order afterwards: the exchange echoes it back, so it is the only way to correlate a fill with the intent that placed it without polling by asset.", "example": "0x1234567890abcdef1234567890abcdef" } }, "required": [ "a", "b", "p", "s", "r", "t" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "grouping": { "type": "string", "enum": [ "na", "normalTpsl", "positionTpsl" ], "description": "`na` for a plain order. The TP/SL groupings attach the orders as a bracket around a position.", "example": "na" }, "builder": { "type": "object", "properties": { "b": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Address receiving the builder fee." }, "f": { "type": "integer", "minimum": 0, "description": "Builder fee in TENTHS of a basis point — `10` is 1bp of order notional.", "example": 10 } }, "required": [ "b", "f" ], "additionalProperties": false } }, "required": [ "type", "orders", "grouping" ], "additionalProperties": false, "description": "Place one or more orders. Opening a position needs an intent that delivers USDC; a reduce-only close does not." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cancel" ] }, "cancels": { "type": "array", "items": { "type": "object", "properties": { "a": { "type": "integer", "minimum": 0, "description": "Asset index." }, "o": { "type": "integer", "minimum": 0, "description": "Order id." } }, "required": [ "a", "o" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "f": { "type": "boolean", "description": "Fast cancel." } }, "required": [ "type", "cancels" ], "additionalProperties": false, "description": "Cancel resting orders by order id. Needs no delivered funds, so it rides a tokenless intent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cancelByCloid" ] }, "cancels": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "integer", "minimum": 0 }, "cloid": { "type": "string", "pattern": "^0x[0-9a-fA-F]{32}$", "description": "Optional client order id — 128-bit hex. Your handle on the order afterwards: the exchange echoes it back, so it is the only way to correlate a fill with the intent that placed it without polling by asset.", "example": "0x1234567890abcdef1234567890abcdef" } }, "required": [ "asset", "cloid" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "f": { "type": "boolean" } }, "required": [ "type", "cancels" ], "additionalProperties": false, "description": "Cancel resting orders by client order id." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "modify" ] }, "oid": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{32}$", "description": "Optional client order id — 128-bit hex. Your handle on the order afterwards: the exchange echoes it back, so it is the only way to correlate a fill with the intent that placed it without polling by asset.", "example": "0x1234567890abcdef1234567890abcdef" } ] }, "order": { "type": "object", "properties": { "a": { "type": "integer", "minimum": 0, "description": "Asset index. Perps use the index in the `meta` universe; spot uses `10000 + index` from `spotMeta`. This is an INDEX, not a ticker — resolve it from the info endpoint, and note that an index built against the wrong universe places a valid order in the wrong market.", "example": 0 }, "b": { "type": "boolean", "description": "Buy (`true`) or sell (`false`).", "example": true }, "p": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Limit price. Must satisfy Hyperliquid's tick rules — at most 5 significant figures and at most `6 - szDecimals` decimals for a perp — and is refused there, not here.\n\nThis price is fixed when you sign, and an intent that bridges to HyperCore takes ~30s to deliver. Price it to still cross after that move, or the order is refused with your funds already delivered.", "example": "64250.5" }, "s": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Size in units of the asset, to at most the asset's `szDecimals`. Hyperliquid refuses an order worth under ~$10.", "example": "0.0002" }, "r": { "type": "boolean", "description": "Reduce-only. `true` is how a position is CLOSED — pair it with a tokenless intent, since closing needs no delivered collateral.", "example": false }, "t": { "oneOf": [ { "type": "object", "properties": { "limit": { "type": "object", "properties": { "tif": { "type": "string", "enum": [ "Alo", "Ioc", "Gtc" ], "description": "Time in force. `Ioc` fills what it can and cancels the rest, which is how a market order is expressed here — there is no market order type. `Alo` is post-only. `Gtc` rests on the book.\n\nPrefer `Ioc` for anything an intent delivers funds for: a resting order leaves the account holding USDC and no position, and the agent that could have cancelled it is already spent.", "example": "Ioc" } }, "required": [ "tif" ], "additionalProperties": false } }, "required": [ "limit" ], "additionalProperties": false }, { "type": "object", "properties": { "trigger": { "type": "object", "properties": { "isMarket": { "type": "boolean" }, "triggerPx": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, "tpsl": { "type": "string", "enum": [ "tp", "sl" ], "description": "Take-profit or stop-loss.", "example": "sl" } }, "required": [ "isMarket", "triggerPx", "tpsl" ], "additionalProperties": false } }, "required": [ "trigger" ], "additionalProperties": false } ], "description": "Either `{ limit: { tif } }` or `{ trigger: { isMarket, triggerPx, tpsl } }`." }, "c": { "type": "string", "pattern": "^0x[0-9a-fA-F]{32}$", "description": "Optional client order id — 128-bit hex. Your handle on the order afterwards: the exchange echoes it back, so it is the only way to correlate a fill with the intent that placed it without polling by asset.", "example": "0x1234567890abcdef1234567890abcdef" } }, "required": [ "a", "b", "p", "s", "r", "t" ], "additionalProperties": false }, "a": { "type": "boolean", "enum": [ true ], "description": "Place the replacement even if the cancel failed. Omit it entirely for the default — Hyperliquid rejects an action hashed with `a: false`, so `false` is not a legal value." } }, "required": [ "type", "oid", "order" ], "additionalProperties": false, "description": "Replace one resting order." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "batchModify" ] }, "modifies": { "type": "array", "items": { "type": "object", "properties": { "oid": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{32}$", "description": "Optional client order id — 128-bit hex. Your handle on the order afterwards: the exchange echoes it back, so it is the only way to correlate a fill with the intent that placed it without polling by asset.", "example": "0x1234567890abcdef1234567890abcdef" } ] }, "order": { "type": "object", "properties": { "a": { "type": "integer", "minimum": 0, "description": "Asset index. Perps use the index in the `meta` universe; spot uses `10000 + index` from `spotMeta`. This is an INDEX, not a ticker — resolve it from the info endpoint, and note that an index built against the wrong universe places a valid order in the wrong market.", "example": 0 }, "b": { "type": "boolean", "description": "Buy (`true`) or sell (`false`).", "example": true }, "p": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Limit price. Must satisfy Hyperliquid's tick rules — at most 5 significant figures and at most `6 - szDecimals` decimals for a perp — and is refused there, not here.\n\nThis price is fixed when you sign, and an intent that bridges to HyperCore takes ~30s to deliver. Price it to still cross after that move, or the order is refused with your funds already delivered.", "example": "64250.5" }, "s": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Size in units of the asset, to at most the asset's `szDecimals`. Hyperliquid refuses an order worth under ~$10.", "example": "0.0002" }, "r": { "type": "boolean", "description": "Reduce-only. `true` is how a position is CLOSED — pair it with a tokenless intent, since closing needs no delivered collateral.", "example": false }, "t": { "oneOf": [ { "type": "object", "properties": { "limit": { "type": "object", "properties": { "tif": { "type": "string", "enum": [ "Alo", "Ioc", "Gtc" ], "description": "Time in force. `Ioc` fills what it can and cancels the rest, which is how a market order is expressed here — there is no market order type. `Alo` is post-only. `Gtc` rests on the book.\n\nPrefer `Ioc` for anything an intent delivers funds for: a resting order leaves the account holding USDC and no position, and the agent that could have cancelled it is already spent.", "example": "Ioc" } }, "required": [ "tif" ], "additionalProperties": false } }, "required": [ "limit" ], "additionalProperties": false }, { "type": "object", "properties": { "trigger": { "type": "object", "properties": { "isMarket": { "type": "boolean" }, "triggerPx": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, "tpsl": { "type": "string", "enum": [ "tp", "sl" ], "description": "Take-profit or stop-loss.", "example": "sl" } }, "required": [ "isMarket", "triggerPx", "tpsl" ], "additionalProperties": false } }, "required": [ "trigger" ], "additionalProperties": false } ], "description": "Either `{ limit: { tif } }` or `{ trigger: { isMarket, triggerPx, tpsl } }`." }, "c": { "type": "string", "pattern": "^0x[0-9a-fA-F]{32}$", "description": "Optional client order id — 128-bit hex. Your handle on the order afterwards: the exchange echoes it back, so it is the only way to correlate a fill with the intent that placed it without polling by asset.", "example": "0x1234567890abcdef1234567890abcdef" } }, "required": [ "a", "b", "p", "s", "r", "t" ], "additionalProperties": false } }, "required": [ "oid", "order" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "a": { "type": "boolean", "enum": [ true ], "description": "Place the replacement even if the cancel failed. Omit it entirely for the default — Hyperliquid rejects an action hashed with `a: false`, so `false` is not a legal value." } }, "required": [ "type", "modifies" ], "additionalProperties": false, "description": "Replace several resting orders." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "updateLeverage" ] }, "asset": { "type": "integer", "minimum": 0 }, "isCross": { "type": "boolean", "description": "Cross margin (`true`) or isolated (`false`).", "example": true }, "leverage": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "New leverage, capped by the asset's own maximum. Set it BEFORE the intent that opens the position: leverage applied afterwards does not resize an existing one.", "example": 5 } }, "required": [ "type", "asset", "isCross", "leverage" ], "additionalProperties": false, "description": "Change the leverage used for an asset. Needs no delivered funds." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "updateIsolatedMargin" ] }, "asset": { "type": "integer", "minimum": 0 }, "isBuy": { "type": "boolean" }, "ntli": { "type": "integer", "description": "Margin to add (positive) or remove (negative), in USDC with 6 decimals — `1000000` is 1 USD.", "example": 1000000 } }, "required": [ "type", "asset", "isBuy", "ntli" ], "additionalProperties": false, "description": "Add or remove margin on an isolated position." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "twapOrder" ] }, "twap": { "type": "object", "properties": { "a": { "type": "integer", "minimum": 0, "description": "Asset index, as for an order.", "example": 0 }, "b": { "type": "boolean", "description": "Buy (`true`) or sell (`false`).", "example": true }, "s": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Total size to work, in units of the asset.", "example": "0.01" }, "r": { "type": "boolean", "description": "Reduce-only.", "example": false }, "m": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "Duration in MINUTES. Hyperliquid enforces its own bounds and refuses a duration outside them (\"Invalid TWAP duration\"), so none are imposed here.", "example": 30 }, "t": { "type": "boolean", "description": "Randomize the timing of the sub-orders rather than spacing them evenly.", "example": true } }, "required": [ "a", "b", "s", "r", "m", "t" ], "additionalProperties": false } }, "required": [ "type", "twap" ], "additionalProperties": false, "description": "Work a position in over `m` minutes rather than in one fill.\n\nCarries NO limit price, which is what makes it the shape to reach for when the bridge delay is the risk: an `Ioc` order is priced at quote time and refused if the book has moved past it by the time the funds land, whereas a TWAP cannot be refused for not crossing.\n\nThe intent completes when Hyperliquid ACCEPTS the TWAP, not when it finishes — the sub-orders run for `m` minutes afterwards, with no further intent and nothing on our side watching them." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "twapCancel" ] }, "a": { "type": "integer", "minimum": 0, "description": "Asset index of the running TWAP.", "example": 0 }, "t": { "type": "integer", "minimum": 0, "description": "The TWAP id, which Hyperliquid returns when it accepts the `twapOrder` and is not echoed on the intent. Read it back from the exchange — the agent that placed the TWAP authorised only that one action, so cancelling is a second intent.", "example": 12345 } }, "required": [ "type", "a", "t" ], "additionalProperties": false, "description": "Stop a running TWAP. Needs no delivered funds." } ], "description": "A single Hyperliquid action to authorise. Shorthand for a one-element `actions`; give one or the other, not both." }, "actions": { "type": "array", "items": { "discriminator": { "propertyName": "type" }, "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "orders": { "type": "array", "items": { "type": "object", "properties": { "a": { "type": "integer", "minimum": 0, "description": "Asset index. Perps use the index in the `meta` universe; spot uses `10000 + index` from `spotMeta`. This is an INDEX, not a ticker — resolve it from the info endpoint, and note that an index built against the wrong universe places a valid order in the wrong market.", "example": 0 }, "b": { "type": "boolean", "description": "Buy (`true`) or sell (`false`).", "example": true }, "p": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Limit price. Must satisfy Hyperliquid's tick rules — at most 5 significant figures and at most `6 - szDecimals` decimals for a perp — and is refused there, not here.\n\nThis price is fixed when you sign, and an intent that bridges to HyperCore takes ~30s to deliver. Price it to still cross after that move, or the order is refused with your funds already delivered.", "example": "64250.5" }, "s": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Size in units of the asset, to at most the asset's `szDecimals`. Hyperliquid refuses an order worth under ~$10.", "example": "0.0002" }, "r": { "type": "boolean", "description": "Reduce-only. `true` is how a position is CLOSED — pair it with a tokenless intent, since closing needs no delivered collateral.", "example": false }, "t": { "oneOf": [ { "type": "object", "properties": { "limit": { "type": "object", "properties": { "tif": { "type": "string", "enum": [ "Alo", "Ioc", "Gtc" ], "description": "Time in force. `Ioc` fills what it can and cancels the rest, which is how a market order is expressed here — there is no market order type. `Alo` is post-only. `Gtc` rests on the book.\n\nPrefer `Ioc` for anything an intent delivers funds for: a resting order leaves the account holding USDC and no position, and the agent that could have cancelled it is already spent.", "example": "Ioc" } }, "required": [ "tif" ], "additionalProperties": false } }, "required": [ "limit" ], "additionalProperties": false }, { "type": "object", "properties": { "trigger": { "type": "object", "properties": { "isMarket": { "type": "boolean" }, "triggerPx": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, "tpsl": { "type": "string", "enum": [ "tp", "sl" ], "description": "Take-profit or stop-loss.", "example": "sl" } }, "required": [ "isMarket", "triggerPx", "tpsl" ], "additionalProperties": false } }, "required": [ "trigger" ], "additionalProperties": false } ], "description": "Either `{ limit: { tif } }` or `{ trigger: { isMarket, triggerPx, tpsl } }`." }, "c": { "type": "string", "pattern": "^0x[0-9a-fA-F]{32}$", "description": "Optional client order id — 128-bit hex. Your handle on the order afterwards: the exchange echoes it back, so it is the only way to correlate a fill with the intent that placed it without polling by asset.", "example": "0x1234567890abcdef1234567890abcdef" } }, "required": [ "a", "b", "p", "s", "r", "t" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "grouping": { "type": "string", "enum": [ "na", "normalTpsl", "positionTpsl" ], "description": "`na` for a plain order. The TP/SL groupings attach the orders as a bracket around a position.", "example": "na" }, "builder": { "type": "object", "properties": { "b": { "type": "string", "pattern": "^0x[0-9a-fA-F]{40}$", "description": "Address receiving the builder fee." }, "f": { "type": "integer", "minimum": 0, "description": "Builder fee in TENTHS of a basis point — `10` is 1bp of order notional.", "example": 10 } }, "required": [ "b", "f" ], "additionalProperties": false } }, "required": [ "type", "orders", "grouping" ], "additionalProperties": false, "description": "Place one or more orders. Opening a position needs an intent that delivers USDC; a reduce-only close does not." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cancel" ] }, "cancels": { "type": "array", "items": { "type": "object", "properties": { "a": { "type": "integer", "minimum": 0, "description": "Asset index." }, "o": { "type": "integer", "minimum": 0, "description": "Order id." } }, "required": [ "a", "o" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "f": { "type": "boolean", "description": "Fast cancel." } }, "required": [ "type", "cancels" ], "additionalProperties": false, "description": "Cancel resting orders by order id. Needs no delivered funds, so it rides a tokenless intent." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "cancelByCloid" ] }, "cancels": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "integer", "minimum": 0 }, "cloid": { "type": "string", "pattern": "^0x[0-9a-fA-F]{32}$", "description": "Optional client order id — 128-bit hex. Your handle on the order afterwards: the exchange echoes it back, so it is the only way to correlate a fill with the intent that placed it without polling by asset.", "example": "0x1234567890abcdef1234567890abcdef" } }, "required": [ "asset", "cloid" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "f": { "type": "boolean" } }, "required": [ "type", "cancels" ], "additionalProperties": false, "description": "Cancel resting orders by client order id." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "modify" ] }, "oid": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{32}$", "description": "Optional client order id — 128-bit hex. Your handle on the order afterwards: the exchange echoes it back, so it is the only way to correlate a fill with the intent that placed it without polling by asset.", "example": "0x1234567890abcdef1234567890abcdef" } ] }, "order": { "type": "object", "properties": { "a": { "type": "integer", "minimum": 0, "description": "Asset index. Perps use the index in the `meta` universe; spot uses `10000 + index` from `spotMeta`. This is an INDEX, not a ticker — resolve it from the info endpoint, and note that an index built against the wrong universe places a valid order in the wrong market.", "example": 0 }, "b": { "type": "boolean", "description": "Buy (`true`) or sell (`false`).", "example": true }, "p": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Limit price. Must satisfy Hyperliquid's tick rules — at most 5 significant figures and at most `6 - szDecimals` decimals for a perp — and is refused there, not here.\n\nThis price is fixed when you sign, and an intent that bridges to HyperCore takes ~30s to deliver. Price it to still cross after that move, or the order is refused with your funds already delivered.", "example": "64250.5" }, "s": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Size in units of the asset, to at most the asset's `szDecimals`. Hyperliquid refuses an order worth under ~$10.", "example": "0.0002" }, "r": { "type": "boolean", "description": "Reduce-only. `true` is how a position is CLOSED — pair it with a tokenless intent, since closing needs no delivered collateral.", "example": false }, "t": { "oneOf": [ { "type": "object", "properties": { "limit": { "type": "object", "properties": { "tif": { "type": "string", "enum": [ "Alo", "Ioc", "Gtc" ], "description": "Time in force. `Ioc` fills what it can and cancels the rest, which is how a market order is expressed here — there is no market order type. `Alo` is post-only. `Gtc` rests on the book.\n\nPrefer `Ioc` for anything an intent delivers funds for: a resting order leaves the account holding USDC and no position, and the agent that could have cancelled it is already spent.", "example": "Ioc" } }, "required": [ "tif" ], "additionalProperties": false } }, "required": [ "limit" ], "additionalProperties": false }, { "type": "object", "properties": { "trigger": { "type": "object", "properties": { "isMarket": { "type": "boolean" }, "triggerPx": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, "tpsl": { "type": "string", "enum": [ "tp", "sl" ], "description": "Take-profit or stop-loss.", "example": "sl" } }, "required": [ "isMarket", "triggerPx", "tpsl" ], "additionalProperties": false } }, "required": [ "trigger" ], "additionalProperties": false } ], "description": "Either `{ limit: { tif } }` or `{ trigger: { isMarket, triggerPx, tpsl } }`." }, "c": { "type": "string", "pattern": "^0x[0-9a-fA-F]{32}$", "description": "Optional client order id — 128-bit hex. Your handle on the order afterwards: the exchange echoes it back, so it is the only way to correlate a fill with the intent that placed it without polling by asset.", "example": "0x1234567890abcdef1234567890abcdef" } }, "required": [ "a", "b", "p", "s", "r", "t" ], "additionalProperties": false }, "a": { "type": "boolean", "enum": [ true ], "description": "Place the replacement even if the cancel failed. Omit it entirely for the default — Hyperliquid rejects an action hashed with `a: false`, so `false` is not a legal value." } }, "required": [ "type", "oid", "order" ], "additionalProperties": false, "description": "Replace one resting order." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "batchModify" ] }, "modifies": { "type": "array", "items": { "type": "object", "properties": { "oid": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{32}$", "description": "Optional client order id — 128-bit hex. Your handle on the order afterwards: the exchange echoes it back, so it is the only way to correlate a fill with the intent that placed it without polling by asset.", "example": "0x1234567890abcdef1234567890abcdef" } ] }, "order": { "type": "object", "properties": { "a": { "type": "integer", "minimum": 0, "description": "Asset index. Perps use the index in the `meta` universe; spot uses `10000 + index` from `spotMeta`. This is an INDEX, not a ticker — resolve it from the info endpoint, and note that an index built against the wrong universe places a valid order in the wrong market.", "example": 0 }, "b": { "type": "boolean", "description": "Buy (`true`) or sell (`false`).", "example": true }, "p": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Limit price. Must satisfy Hyperliquid's tick rules — at most 5 significant figures and at most `6 - szDecimals` decimals for a perp — and is refused there, not here.\n\nThis price is fixed when you sign, and an intent that bridges to HyperCore takes ~30s to deliver. Price it to still cross after that move, or the order is refused with your funds already delivered.", "example": "64250.5" }, "s": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Size in units of the asset, to at most the asset's `szDecimals`. Hyperliquid refuses an order worth under ~$10.", "example": "0.0002" }, "r": { "type": "boolean", "description": "Reduce-only. `true` is how a position is CLOSED — pair it with a tokenless intent, since closing needs no delivered collateral.", "example": false }, "t": { "oneOf": [ { "type": "object", "properties": { "limit": { "type": "object", "properties": { "tif": { "type": "string", "enum": [ "Alo", "Ioc", "Gtc" ], "description": "Time in force. `Ioc` fills what it can and cancels the rest, which is how a market order is expressed here — there is no market order type. `Alo` is post-only. `Gtc` rests on the book.\n\nPrefer `Ioc` for anything an intent delivers funds for: a resting order leaves the account holding USDC and no position, and the agent that could have cancelled it is already spent.", "example": "Ioc" } }, "required": [ "tif" ], "additionalProperties": false } }, "required": [ "limit" ], "additionalProperties": false }, { "type": "object", "properties": { "trigger": { "type": "object", "properties": { "isMarket": { "type": "boolean" }, "triggerPx": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, "tpsl": { "type": "string", "enum": [ "tp", "sl" ], "description": "Take-profit or stop-loss.", "example": "sl" } }, "required": [ "isMarket", "triggerPx", "tpsl" ], "additionalProperties": false } }, "required": [ "trigger" ], "additionalProperties": false } ], "description": "Either `{ limit: { tif } }` or `{ trigger: { isMarket, triggerPx, tpsl } }`." }, "c": { "type": "string", "pattern": "^0x[0-9a-fA-F]{32}$", "description": "Optional client order id — 128-bit hex. Your handle on the order afterwards: the exchange echoes it back, so it is the only way to correlate a fill with the intent that placed it without polling by asset.", "example": "0x1234567890abcdef1234567890abcdef" } }, "required": [ "a", "b", "p", "s", "r", "t" ], "additionalProperties": false } }, "required": [ "oid", "order" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "a": { "type": "boolean", "enum": [ true ], "description": "Place the replacement even if the cancel failed. Omit it entirely for the default — Hyperliquid rejects an action hashed with `a: false`, so `false` is not a legal value." } }, "required": [ "type", "modifies" ], "additionalProperties": false, "description": "Replace several resting orders." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "updateLeverage" ] }, "asset": { "type": "integer", "minimum": 0 }, "isCross": { "type": "boolean", "description": "Cross margin (`true`) or isolated (`false`).", "example": true }, "leverage": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "New leverage, capped by the asset's own maximum. Set it BEFORE the intent that opens the position: leverage applied afterwards does not resize an existing one.", "example": 5 } }, "required": [ "type", "asset", "isCross", "leverage" ], "additionalProperties": false, "description": "Change the leverage used for an asset. Needs no delivered funds." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "updateIsolatedMargin" ] }, "asset": { "type": "integer", "minimum": 0 }, "isBuy": { "type": "boolean" }, "ntli": { "type": "integer", "description": "Margin to add (positive) or remove (negative), in USDC with 6 decimals — `1000000` is 1 USD.", "example": 1000000 } }, "required": [ "type", "asset", "isBuy", "ntli" ], "additionalProperties": false, "description": "Add or remove margin on an isolated position." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "twapOrder" ] }, "twap": { "type": "object", "properties": { "a": { "type": "integer", "minimum": 0, "description": "Asset index, as for an order.", "example": 0 }, "b": { "type": "boolean", "description": "Buy (`true`) or sell (`false`).", "example": true }, "s": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Total size to work, in units of the asset.", "example": "0.01" }, "r": { "type": "boolean", "description": "Reduce-only.", "example": false }, "m": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "Duration in MINUTES. Hyperliquid enforces its own bounds and refuses a duration outside them (\"Invalid TWAP duration\"), so none are imposed here.", "example": 30 }, "t": { "type": "boolean", "description": "Randomize the timing of the sub-orders rather than spacing them evenly.", "example": true } }, "required": [ "a", "b", "s", "r", "m", "t" ], "additionalProperties": false } }, "required": [ "type", "twap" ], "additionalProperties": false, "description": "Work a position in over `m` minutes rather than in one fill.\n\nCarries NO limit price, which is what makes it the shape to reach for when the bridge delay is the risk: an `Ioc` order is priced at quote time and refused if the book has moved past it by the time the funds land, whereas a TWAP cannot be refused for not crossing.\n\nThe intent completes when Hyperliquid ACCEPTS the TWAP, not when it finishes — the sub-orders run for `m` minutes afterwards, with no further intent and nothing on our side watching them." }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "twapCancel" ] }, "a": { "type": "integer", "minimum": 0, "description": "Asset index of the running TWAP.", "example": 0 }, "t": { "type": "integer", "minimum": 0, "description": "The TWAP id, which Hyperliquid returns when it accepts the `twapOrder` and is not echoed on the intent. Read it back from the exchange — the agent that placed the TWAP authorised only that one action, so cancelling is a second intent.", "example": 12345 } }, "required": [ "type", "a", "t" ], "additionalProperties": false, "description": "Stop a running TWAP. Needs no delivered funds." } ], "description": "A Hyperliquid L1 action, passed through as they define it. Keys are re-emitted in their canonical order before the action is hashed, so the order you send them in does not matter." }, "minItems": 1, "maxItems": 3, "description": "The Hyperliquid actions to authorise, IN ORDER. Each gets its own agent in its own API-wallet slot, registered ONE AT A TIME and some seconds apart, and they are sent to the exchange in the order given once every agent is live — the first refusal stops the rest, so a later action never runs against a state an earlier one failed to reach.\n\nOrder is what makes this more than a batch: `updateLeverage` has to land before the order it applies to, since leverage applied afterwards does not resize an open position. So opening a leveraged position is `[updateLeverage, order]` in ONE intent rather than two.\n\nCapped at three, which is Hyperliquid's: an account has three NAMED API-wallet slots and the unnamed one belongs to the account holder. More than one action requires `tokenRequests`: HyperCore refuses a registration while the eviction the previous one queued is still pending, so each rides a dispatch stage of its own, released a few seconds after the one before it landed, and an intent that delivers nothing has only the one. An action that needs collateral must be paired with `tokenRequests` anyway; one that does not (a reduce-only close, a cancel, a leverage change) rides a tokenless intent, one at a time — a few seconds after the previous intent's last registration, or it is refused as `HYPERCORE_TRADE_IN_FLIGHT`." } } } }, "description": "Intent options", "example": { "settlementLayers": { "include": [ "ECO" ] }, "sponsorSettings": { "gas": true, "bridgeFees": true, "swapFees": true } } }, "accountAccessList": { "type": "object", "properties": { "chainIds": { "type": "array", "items": { "type": "string", "pattern": "^(eip155|solana|tron|hypercore|stellar):[-_a-zA-Z0-9]{1,32}$", "description": "CAIP-2 chain identifier (e.g. `eip155:8453`, `solana:…`, `tron:…`, or a HyperCore delivery venue `hypercore:spot` / `hypercore:perp`)", "example": "eip155:8453" } }, "tokens": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "string" }, { "type": "string", "enum": [ "ETH", "USDC", "WETH", "USDT", "USDT0", "BNB", "WBNB", "XDAI", "WXDAI", "POL", "WPOL", "MON", "WMON", "S", "WS", "OKB", "WOKB", "HYPE", "WHYPE", "RON", "WRON", "USDG", "XPL", "WXPL", "AVAX", "WAVAX", "MockUSD", "USDC_TEST", "XLM", "ensUSDC", "ensUSDC2", "ensUSDC3", "TRX", "WTRX", "SOL", "WSOL" ] } ] } }, "chainTokens": { "type": "object", "additionalProperties": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "string" }, { "type": "string", "enum": [ "ETH", "USDC", "WETH", "USDT", "USDT0", "BNB", "WBNB", "XDAI", "WXDAI", "POL", "WPOL", "MON", "WMON", "S", "WS", "OKB", "WOKB", "HYPE", "WHYPE", "RON", "WRON", "USDG", "XPL", "WXPL", "AVAX", "WAVAX", "MockUSD", "USDC_TEST", "XLM", "ensUSDC", "ensUSDC2", "ensUSDC3", "TRX", "WTRX", "SOL", "WSOL" ] } ] } }, "description": "Tokens keyed by CAIP-2 chain ID.", "example": { "eip155:8453": [ "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" ] } }, "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": { "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913": "1000000" } } }, "exclude": { "type": "object", "properties": { "chainIds": { "type": "array", "items": { "type": "string", "pattern": "^(eip155|solana|tron|hypercore|stellar):[-_a-zA-Z0-9]{1,32}$", "description": "CAIP-2 chain identifier (e.g. `eip155:8453`, `solana:…`, `tron:…`, or a HyperCore delivery venue `hypercore:spot` / `hypercore:perp`)", "example": "eip155:8453" } }, "tokens": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "string" }, { "type": "string", "enum": [ "ETH", "USDC", "WETH", "USDT", "USDT0", "BNB", "WBNB", "XDAI", "WXDAI", "POL", "WPOL", "MON", "WMON", "S", "WS", "OKB", "WOKB", "HYPE", "WHYPE", "RON", "WRON", "USDG", "XPL", "WXPL", "AVAX", "WAVAX", "MockUSD", "USDC_TEST", "XLM", "ensUSDC", "ensUSDC2", "ensUSDC3", "TRX", "WTRX", "SOL", "WSOL" ] } ] } }, "chainTokens": { "type": "object", "additionalProperties": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "string" }, { "type": "string", "enum": [ "ETH", "USDC", "WETH", "USDT", "USDT0", "BNB", "WBNB", "XDAI", "WXDAI", "POL", "WPOL", "MON", "WMON", "S", "WS", "OKB", "WOKB", "HYPE", "WHYPE", "RON", "WRON", "USDG", "XPL", "WXPL", "AVAX", "WAVAX", "MockUSD", "USDC_TEST", "XLM", "ensUSDC", "ensUSDC2", "ensUSDC3", "TRX", "WTRX", "SOL", "WSOL" ] } ] } }, "description": "Tokens keyed by CAIP-2 chain ID.", "example": { "eip155:8453": [ "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" ] } } } } }, "description": "Account access list specifying which CAIP-2 chains and tokens an account may access" } }, "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." } ], "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", "LZ" ], "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|solana|tron|hypercore|stellar):[-_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 debited token (EVM 0x or non-EVM base58)", "example": "0xaf88d065e77c8cc2239327c5edb3a432268e5831" }, "symbol": { "type": "string", "nullable": true, "description": "Token symbol, from the internal token registry or, for a token it has no entry for, read on-chain while planning. `null` when neither resolved one.", "example": "USDC" }, "decimals": { "type": "integer", "nullable": true, "description": "Token decimals, from the internal token registry or, for a token it has no entry for, read on-chain while planning. `null` when neither resolved one.", "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 neither the price oracle nor this quote priced the 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|stellar):[-_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, from the internal token registry or, for a token it has no entry for, read on-chain while planning. `null` when neither resolved one.", "example": "USDC" }, "decimals": { "type": "integer", "nullable": true, "description": "Token decimals, from the internal token registry or, for a token it has no entry for, read on-chain while planning. `null` when neither resolved one.", "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 neither the price oracle nor this quote priced the 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" ] } ] } } } }, "422": { "description": "Sponsorship or a request option refuses the route", "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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "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|solana|tron|hypercore|stellar):[-_a-zA-Z0-9]{1,32}$", "description": "Source chain id (CAIP-2): EVM (`eip155:*`), or `solana:…` where this deployment spends from a Solana origin.", "example": "eip155:8453" }, "sourceToken": { "type": "string", "minLength": 1, "description": "Source token address — EVM `0x…`, or a Solana base58 mint.", "example": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" }, "destinationChainId": { "type": "string", "pattern": "^(eip155|solana|tron|hypercore|stellar):[-_a-zA-Z0-9]{1,32}$", "description": "Destination chain id (CAIP-2), matching the destinations `POST /quotes` accepts: EVM (`eip155:*`), a virtual HyperCore delivery venue (`hypercore:spot` or `hypercore:perp`), 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" }, "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 and for a Solana source.", "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", "LZ" ] } } }, "required": [ "include" ], "additionalProperties": false }, { "type": "object", "properties": { "exclude": { "type": "array", "items": { "type": "string", "enum": [ "ACROSS", "ECO", "RELAY", "OFT", "NEAR", "RHINO", "CCTP", "LZ" ] } } }, "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. For an integrator enabled for it, this also sponsors the VALUE of an eligible same-chain swap, so the user trades at par: the user contributes the 1:1 amount and the sponsor pays whatever the market is short. That applies only to pairs where par is a meaningful rate (both sides USD-pegged) and only up to a configured per-swap ceiling; outside those bounds the swap is priced at market." }, "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. The estimator prices every swap at market, so a same-chain swap `POST /quotes` sponsors to par under `swapFees` is estimated below what it delivers (RHI-7069).", "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" }, "balance": { "readOnly": true } }, "required": [ "direction", "sourceChainId", "sourceToken", "destinationChainId", "destinationToken" ], "description": "Indicative-quote request. Chain ids are 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." } ], "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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "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." } ], "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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "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." } ], "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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "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." } ], "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" ] }, "grossUsd": { "type": "number", "nullable": true }, "cutBps": { "type": "integer", "nullable": true }, "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", "grossUsd", "cutBps", "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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "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": "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" ] }, "grossUsd": { "type": "number", "nullable": true }, "cutBps": { "type": "integer", "nullable": true }, "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", "grossUsd", "cutBps", "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" ] } ] } } } } }, "security": [ { "apiKeyAuth": [] }, { "bearerAuth": [] } ], "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" ] } } } }