{ "openapi": "3.1.0", "info": { "title": "Swaps API", "description": "The Swaps API provides instant cross-chain swap and bridge functionality for decentralized applications.\nIt supports multiple virtual machines (EVM, Solana, Bitcoin) and various DEX protocols and bridge solutions.", "version": "3.0.0", "contact": { "name": "Swaps.xyz", "url": "https://swaps.xyz" } }, "servers": [ { "url": "https://api-v2.swaps.xyz/api", "description": "Production server" } ], "paths": { "/getAction": { "get": { "summary": "Get Action", "servers": [ { "url": "https://api-v2.swaps.xyz/api", "description": "Core Swap API server" } ], "description": "Generates a transaction for cross-chain swaps, bridges, and calls. The action includes transaction data, routing information, and fee calculations for executing the requested operation.", "operationId": "getAction", "parameters": [ { "name": "actionType", "in": "query", "required": true, "description": "Type of action to perform", "schema": { "$ref": "#/components/schemas/ActionType" } }, { "name": "sender", "in": "query", "required": true, "description": "The address of the sender/user", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "srcChainId", "in": "query", "required": true, "description": "Source chain ID", "schema": { "$ref": "#/components/schemas/ChainId" } }, { "name": "srcToken", "in": "query", "required": true, "description": "Source token address", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "dstChainId", "in": "query", "required": true, "description": "Destination chain ID", "schema": { "$ref": "#/components/schemas/ChainId" } }, { "name": "dstToken", "in": "query", "required": true, "description": "Destination token address", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "slippage", "in": "query", "required": true, "description": "Slippage tolerance in bps", "schema": { "type": "number", "format": "float", "minimum": 0, "maximum": 10000 } }, { "name": "amount", "in": "query", "required": false, "description": "The exact in or exact out amount of the swap\n\n**Required:** for `swap-action`\n\n**Required:** for `polymarket` action type", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "swapDirection", "in": "query", "required": false, "description": "Swap direction for the action\n\n**Required:** for `swap-action`\n\nFor `polymarket`, optional — defaults to `exact-amount-in` (recommended).", "schema": { "$ref": "#/components/schemas/SwapDirection" } }, { "name": "recipient", "in": "query", "required": false, "description": "Address to receive the swapped tokens\n\n**Optional:** for `swap-action`\n\n**Required:** for `polymarket` action type (should be the proxy wallet address)", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "to", "in": "query", "required": false, "description": "The EVM address of the target contract (20 bytes hex)\n\n**Required:** for `evm-calldata-tx` action type", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "data", "in": "query", "required": false, "description": "Calldata for the transaction\n\n**Required:** for `evm-calldata-tx` action type", "schema": { "$ref": "#/components/schemas/Hex" } }, { "name": "value", "in": "query", "required": false, "description": "Value to send with transaction\n\n**Optional:** for `evm-calldata-tx` action type", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "erc20Amount", "in": "query", "required": false, "description": "The amount of Erc20 being transferred\n\n**Optional:** for `evm-calldata-tx` action type (use for calls requiring Erc20 transfers)", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "erc20Spender", "in": "query", "required": false, "description": "The Erc20 spender requiring approval for the transaction call\n\n**Optional:** for `evm-calldata-tx` action type (will default to the `to` address)", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "solanaSponsor", "in": "query", "required": false, "description": "Solana address that pays for tx fees and rent (e.g. ATA creation). Only used for Solana same chain swaps. Transaction must be signed by both the user and the sponsor.\n\n**Optional:** When provided, the sponsor covers transaction costs on behalf of the user.", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "bridgeIds", "in": "query", "required": false, "description": "Specific bridge protocols to use\n\n**Optional:** Will default to all available protocols", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BridgeId" } } }, { "name": "refundTo", "in": "query", "required": false, "description": "Alternate address to receive refunds\n\n**Optional:** Will default to the `sender`", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "returnDepositAddress", "in": "query", "required": false, "description": "Return a deposit address for deposit-based flows\n\n**Optional:** Set to `true` to receive a deposit address in the response", "schema": { "type": "boolean", "default": false } }, { "name": "appFees", "in": "query", "required": false, "description": "Application fees configuration as JSON array\n\n**Optional:** Will default to fees configured for the application\n\n **Example:** `[{ \"bps\": 50, \"receiverAddress\": \"0x...\" }]`", "schema": { "type": "string" } }, { "name": "userId", "in": "query", "required": false, "description": "Polymarket user ID - returned from `POST /workflows/polymarket/createOrFetchPolymarketUser`\n\n**Required:** for `polymarket` action type", "schema": { "type": "string" } }, { "name": "side", "in": "query", "required": false, "description": "Order side for Polymarket orders\n\n**Required:** for `polymarket` action type", "schema": { "type": "string", "enum": [ "BUY", "SELL" ] } }, { "name": "tokenID", "in": "query", "required": false, "description": "Polymarket CLOB token ID\n\n**Required:** for `polymarket` action type", "schema": { "type": "string" } }, { "name": "orderType", "in": "query", "required": false, "description": "Polymarket order type\n\n**Required:** for `polymarket` action type\n\n- `FOK`: Fill or Kill (market order)\n- `FAK`: Fill and Kill (market order)", "schema": { "type": "string", "enum": [ "FOK", "FAK" ] } }, { "name": "tickSize", "in": "query", "required": false, "description": "Price tick size for Polymarket orders\n\n**Required:** for `polymarket` action type", "schema": { "type": "string", "enum": [ "0.01", "0.001", "0.0001" ] } }, { "name": "negRisk", "in": "query", "required": false, "description": "Negative risk flag for Polymarket\n\n**Required:** for `polymarket` action type", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "gasless", "in": "query", "required": false, "description": "Request gasless execution. When `true`, the response includes an `executions` array of signed steps to relay through the gasless provider instead of broadcasting a transaction directly.\n\n**Optional:** Only supported on chains with a configured gasless provider (currently Tron). Requires the API key to have gasless enabled.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful response with action data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionResponse" } } } }, "400": { "description": "Bad request due to missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetActionErrorResponse" }, "examples": { "AMOUNT_TOO_HIGH": { "summary": "Amount Too High", "value": { "success": false, "error": { "code": "AMOUNT_TOO_HIGH", "name": "AmountTooHighError", "message": "The specified amount is too high.", "title": "Amount too high", "statusCode": 400, "details": { "srcToken": "0x0000000000000000000000000000000000000000", "dstToken": "0x0000000000000000000000000000000000000000", "srcChainId": 1, "dstChainId": 42161, "maxAmount": 100000000000000000000 }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "AMOUNT_TOO_LOW": { "summary": "Amount Too Low", "value": { "success": false, "error": { "code": "AMOUNT_TOO_LOW", "name": "AmountTooLowError", "message": "The specified amount is too low.", "title": "Amount too low", "statusCode": 400, "details": { "srcToken": "0x0000000000000000000000000000000000000000", "dstToken": "0x0000000000000000000000000000000000000000", "srcChainId": 1, "dstChainId": 42161, "minAmount": 0.000123 }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "CROSS_VM_RECEIVER_REQUIRED": { "summary": "Cross VM Receiver Required", "value": { "success": false, "error": { "code": "CROSS_VM_RECEIVER_REQUIRED", "name": "CrossVmReceiverRequiredError", "message": "Receiver address is required for swaps across different VMs.", "title": "Receiver address required", "statusCode": 400, "details": { "srcChainId": 1, "dstChainId": 1399811149 }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "EXCESSIVE_FEE": { "summary": "Excessive Fee", "value": { "success": false, "error": { "code": "EXCESSIVE_FEE", "name": "ExcessiveFeeError", "message": "The inputted flat fee is too large (over 50% of tx input).", "title": "Excessive fee", "statusCode": 400, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "INSUFFICIENT_LIQUIDITY": { "summary": "Insufficient Liquidity", "value": { "success": false, "error": { "code": "INSUFFICIENT_LIQUIDITY", "name": "InsufficientLiquidityError", "message": "There is insufficient liquidity to complete this transaction.", "title": "Insufficient liquidity", "statusCode": 400, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "INVALID_ADDRESS_FORMAT": { "summary": "Invalid Address Format", "value": { "success": false, "error": { "code": "INVALID_ADDRESS_FORMAT", "name": "InvalidAddressError", "message": "The format of the specified address is invalid.", "title": "Invalid address format", "statusCode": 400, "details": { "field": "sender", "address": "0xinvalid", "reason": "Address must be 40 characters long" }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "INVALID_AMOUNT_ZERO": { "summary": "Invalid Amount Zero", "value": { "success": false, "error": { "code": "INVALID_AMOUNT_ZERO", "name": "InvalidAmountZeroError", "message": "Amount must be greater than zero.", "title": "Zero amount not allowed", "statusCode": 400, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "INVALID_DESTINATION_TOKEN": { "summary": "Invalid Destination Token", "value": { "success": false, "error": { "code": "INVALID_DESTINATION_TOKEN", "name": "InvalidDstTokenError", "message": "Destination token is required.", "title": "Invalid destination token", "statusCode": 400, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "INVALID_PARAMETER": { "summary": "Invalid Parameter", "value": { "success": false, "error": { "code": "INVALID_PARAMETER", "name": "InvalidParameterError", "message": "The request contains an invalid parameter.", "title": "Invalid parameter", "statusCode": 400, "details": { "parameter": "slippage", "value": "15000", "reason": "Slippage must be between 0 and 10000 bps" }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "INVALID_SOURCE_TOKEN": { "summary": "Invalid Source Token", "value": { "success": false, "error": { "code": "INVALID_SOURCE_TOKEN", "name": "InvalidSrcTokenError", "message": "Source token is required.", "title": "Invalid source token", "statusCode": 400, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "MISSING_REQUIRED_FIELD": { "summary": "Missing Required Field", "value": { "success": false, "error": { "code": "MISSING_REQUIRED_FIELD", "name": "MissingRequiredFieldError", "message": "The request is missing a required field.", "title": "Missing required field", "statusCode": 400, "details": { "field": "srcToken", "context": "Source token address is required for swap actions" }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "NO_AVAILABLE_ROUTE": { "summary": "No Available Route", "value": { "success": false, "error": { "code": "NO_AVAILABLE_ROUTE", "name": "NoAvailableRouteError", "message": "No route is available for the specified parameters.", "title": "No available route", "statusCode": 400, "details": { "srcChainId": 1, "dstChainId": 42161, "srcToken": "0x0000000000000000000000000000000000000000", "dstToken": "0x1234567890123456789012345678901234567890" }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "UNSUPPORTED_NETWORK": { "summary": "Unsupported Network", "value": { "success": false, "error": { "code": "UNSUPPORTED_NETWORK", "name": "UnsupportedNetworkError", "message": "The network with the specified chainId is not supported.", "title": "Unsupported network", "statusCode": 400, "details": { "chainId": 999999 }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "UNSUPPORTED_NETWORK_PAIR": { "summary": "Unsupported Network Pair", "value": { "success": false, "error": { "code": "UNSUPPORTED_NETWORK_PAIR", "name": "UnsupportedNetworkPairError", "message": "Routing between the specified networks is not supported.", "title": "Unsupported network pair", "statusCode": 400, "details": { "srcChainId": 1, "dstChainId": 999999 }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "UNSUPPORTED_NETWORK_TOKEN_PAIR": { "summary": "Unsupported Network Token Pair", "value": { "success": false, "error": { "code": "UNSUPPORTED_NETWORK_TOKEN_PAIR", "name": "UnsupportedNetworkAndTokenPairError", "message": "Routing between the specified tokens and networks is not supported.", "title": "Unsupported network and token pair", "statusCode": 400, "details": { "srcChainId": 1, "srcToken": "0x0000000000000000000000000000000000000000", "dstChainId": 42161, "dstToken": "0x1234567890123456789012345678901234567890" }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "UNSUPPORTED_SWAP_DIRECTION": { "summary": "Unsupported Swap Direction", "value": { "success": false, "error": { "code": "UNSUPPORTED_SWAP_DIRECTION", "name": "UnsupportedSwapDirectionError", "message": "The specified swap direction is not supported.", "title": "Unsupported swap direction", "statusCode": 400, "details": { "swapDirection": "exact-amount-out" }, "timestamp": "2024-01-01T00:00:00.000Z" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetActionErrorResponse" }, "examples": { "INVALID_API_KEY": { "summary": "Invalid API Key", "value": { "success": false, "error": { "code": "INVALID_API_KEY", "name": "InvalidApiKeyError", "message": "The provided API key is invalid.", "title": "Invalid API key", "statusCode": 401, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "MISSING_API_KEY": { "summary": "Missing API Key", "value": { "success": false, "error": { "code": "MISSING_API_KEY", "name": "MissingApiKeyError", "message": "API key is required.", "title": "Missing API key", "statusCode": 401, "timestamp": "2024-01-01T00:00:00.000Z" } } } } } } }, "403": { "description": "Forbidden - Access denied due to restrictions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetActionErrorResponse" }, "examples": { "GEO_BLOCKED": { "summary": "Geographic Restriction", "value": { "success": false, "error": { "code": "GEO_BLOCKED", "name": "GeoBlockingError", "message": "Access denied due to geo-blocking restrictions.", "title": "Geo-blocking restriction", "statusCode": 403, "details": { "countryCode": "US", "countryName": "United States", "reason": "Country is on the blocked list", "blockedAt": "2024-01-15T10:30:00.000Z" }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "WALLET_SCREENED": { "summary": "Wallet Screening", "value": { "success": false, "error": { "code": "WALLET_SCREENED", "name": "WalletScreeningError", "message": "Access denied due to wallet screening restrictions.", "title": "Wallet screening restriction", "statusCode": 403, "details": { "walletAddress": "0x1234567890123456789012345678901234567890", "chainId": 1, "riskLevel": "HIGH", "reason": "Wallet flagged by screening service", "screenedAt": "2024-01-15T10:30:00.000Z" }, "timestamp": "2024-01-01T00:00:00.000Z" } } } } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetActionErrorResponse" }, "examples": { "METHOD_NOT_ALLOWED": { "summary": "Method Not Allowed", "value": { "success": false, "error": { "code": "METHOD_NOT_ALLOWED", "name": "MethodNotAllowedError", "message": "The HTTP request method specified is not allowed.", "title": "Method not allowed", "statusCode": 405, "details": { "method": "POST" }, "timestamp": "2024-01-01T00:00:00.000Z" } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetActionErrorResponse" }, "examples": { "INTERNAL_SERVER_ERROR": { "summary": "Internal Server Error", "value": { "success": false, "error": { "code": "INTERNAL_SERVER_ERROR", "name": "InternalServerError", "message": "An internal server error occurred while processing the request.", "title": "Internal Server Error", "statusCode": 500, "timestamp": "2024-01-01T00:00:00.000Z" } } } } } } } } } }, "/registerTxs": { "post": { "summary": "Register Transaction", "servers": [ { "url": "https://api-v2.swaps.xyz/api", "description": "Core Swap API server" } ], "description": "Register transactions for indexing. Mandatory for non EVM transactions.", "operationId": "registerTxs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Single Transaction", "$ref": "#/components/schemas/TxRegistrationEvent" }, { "title": "Multiple Transactions", "type": "array", "items": { "$ref": "#/components/schemas/TxRegistrationEvent" } } ] } } } }, "responses": { "200": { "description": "Transaction registration results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/post_200__webhooks_registerTxsSchema" } } } } } } }, "/getStatus": { "get": { "summary": "Get Status", "servers": [ { "url": "https://api-v2.swaps.xyz/api", "description": "Core Swap API server" } ], "description": "Retrieve the status and details of a transaction by transaction ID.", "operationId": "getTransactionStatus", "parameters": [ { "name": "txHash", "in": "query", "description": "Transaction hash to query (required if txId not provided)", "required": false, "schema": { "type": "string", "example": "0xd56968cf4fede6a0773f3e6dfad7d1088aacd3994bada55d44faee9596dadff2" } }, { "name": "txId", "in": "query", "description": "Transaction ID to query (required if txHash not provided)", "required": false, "schema": { "type": "string", "example": "0x49b1d3d38176e45864fd55500c6c1879ab318609e1ed0c8eb9abd818e6c811fd" } }, { "name": "chainId", "in": "query", "description": "Source chain ID for the transaction (optional but recommended)", "required": false, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Transaction status response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TxDetails" } } } } } } }, "/getTransactions": { "get": { "summary": "Get Transactions", "servers": [ { "url": "https://api-v2.swaps.xyz/api", "description": "Core Swap API server" } ], "description": "Retrieve paginated transaction history with optional filtering.", "operationId": "getTransactions", "parameters": [ { "name": "appIds", "in": "query", "description": "Comma-separated list of your app IDs. By default, a request to this endpoint will return transactions across all appIds in your org. Each API key has a unique app ID. Multiple app IDs can exist within a single org ID.", "schema": { "type": "string", "example": "0x5344e5a7,0x5314e6a7" } }, { "name": "walletAddress", "in": "query", "description": "Wallet address to filter transactions by user", "required": false, "schema": { "type": "string", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } }, { "name": "chainIds", "in": "query", "description": "Comma-separated list of chain IDs to filter by", "required": false, "schema": { "type": "string", "example": "1,42161,10" } }, { "name": "limit", "in": "query", "description": "Number of results per page (max 50)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25, "example": 25 } }, { "name": "period", "in": "query", "description": "Time period filter", "required": false, "schema": { "type": "string", "enum": [ "day", "week", "month" ], "example": "week" } }, { "name": "startDate", "in": "query", "description": "Start date filter (Unix timestamp)", "required": false, "schema": { "type": "string", "example": "1640995200" } }, { "name": "endDate", "in": "query", "description": "End date filter (Unix timestamp)", "required": false, "schema": { "type": "string", "example": "1672531200" } }, { "name": "cursor", "in": "query", "description": "Pagination cursor from previous response. Use the `cursor.next` value from the response to fetch the next page.", "required": false, "schema": { "type": "string", "example": "NjgxNGU5YzQ1ZTJjNjYwMDAxMjM0NTY3XzE3MDY3NDU2MDA=" } } ], "responses": { "200": { "description": "Transaction history response", "content": { "application/json": { "schema": { "type": "object", "properties": { "txs": { "type": "array", "items": { "$ref": "#/components/schemas/TxDetails" } }, "cursor": { "type": "object", "properties": { "next": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page of results. Null if no more pages.", "example": "NjgxNGU5YzQ1ZTJjNjYwMDAxMjM0NTY3XzE3MDY3NDU2MDA=" } } } } } } } } } } }, "/getPaths": { "get": { "summary": "Get Paths", "servers": [ { "url": "https://api-v2.swaps.xyz/api", "description": "Core Swap API server" } ], "description": "Retrieves all available token paths across supported chains with configurable filtering options. It’s recommended to call this endpoint after selecting the source and destination tokens to validate route eligibility.", "operationId": "getPaths", "parameters": [ { "name": "srcChainId", "in": "query", "required": true, "description": "Source chain ID", "schema": { "$ref": "#/components/schemas/ChainId" } }, { "name": "srcToken", "in": "query", "required": true, "description": "Source token address", "schema": { "type": "string" } }, { "name": "dstChainId", "in": "query", "required": false, "description": "Recommended: destination chain ID", "schema": { "$ref": "#/components/schemas/ChainId" } }, { "name": "dstToken", "in": "query", "required": false, "description": "Recommended: destination token address", "schema": { "type": "string" } }, { "name": "excludeBridgeIds", "in": "query", "required": false, "description": "Bridge IDs to exclude from routing", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BridgeId" } } }, { "name": "excludeDexIds", "in": "query", "required": false, "description": "DEX IDs to exclude from routing", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DexId" } } } ], "responses": { "200": { "description": "Paths response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPathsOutput" } } } }, "400": { "description": "Bad request due to missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/getChainList": { "get": { "summary": "Get Chain List", "servers": [ { "url": "https://api-v2.swaps.xyz/api", "description": "Core Swap API server" } ], "description": "Retrieve a list of supported chains, their names, and virtual machine identifiers. Raw data for the [supported chains list](/resources/chain-list).", "operationId": "getChainList", "responses": { "200": { "description": "List of supported chains", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChainListResponse" } } } } } } } }, "/getTokenList": { "get": { "summary": "Get Token List", "servers": [ { "url": "https://api-v2.swaps.xyz/api", "description": "Core Swap API server" } ], "description": "Retrieve the list of supported tokens for a given chain, or for all supported chains if no chainId is specified.", "operationId": "getTokenList", "parameters": [ { "name": "chainId", "in": "query", "required": false, "description": "Chain ID to retrieve tokens for. If omitted, returns token lists for all supported chains, keyed by chain ID.", "schema": { "$ref": "#/components/schemas/ChainId" } } ], "responses": { "200": { "description": "Token list response", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TokenListResponse" }, { "$ref": "#/components/schemas/TokenListByChainResponse" } ] } } } }, "400": { "description": "Bad request due to an unsupported chainId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/submitTx": { "post": { "summary": "Submit Gasless Transaction", "servers": [ { "url": "https://api-v2.swaps.xyz/api", "description": "Core Swap API server" } ], "description": "Submits signed executions obtained from a gasless `GET /getAction` response for relay broadcast. The backend validates each signature, simulates the transactions, then broadcasts them via the configured relay provider.\n\nCall this endpoint only when `executionsType` is `GASLESS` in the `getAction` response. Sign all items in the `executions` array in order before submitting.", "operationId": "submitTx", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitTxRequest" } } } }, "responses": { "200": { "description": "Transaction accepted for relay broadcast", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitTxResponse" } } } }, "400": { "description": "Bad request — invalid signature, unknown txId, or malformed executions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/getQuote": { "get": { "summary": "Get Quote", "servers": [ { "url": "https://api-v2.swaps.xyz/api", "description": "Core Swap API server" } ], "description": "Returns a non-binding reference price for a cross-chain swap. Unlike `GET /getAction`, this endpoint never allocates a deposit address, builds transaction calldata, or triggers wallet-screening checks — it's priced-only, safe to call at high frequency (e.g. to refresh a quote widget), and always uses `swap-action` semantics regardless of any `actionType` you pass.\n\n`sender` and `recipient` are not accepted as inputs — the endpoint prices the route using internal placeholder addresses, since no transaction is produced. If you need a signable transaction, use `GET /getAction` instead.", "operationId": "getQuote", "parameters": [ { "name": "srcChainId", "in": "query", "required": true, "description": "Source chain ID", "schema": { "$ref": "#/components/schemas/ChainId" } }, { "name": "srcToken", "in": "query", "required": true, "description": "Source token address. Use `native` for the chain's native asset.", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "dstChainId", "in": "query", "required": true, "description": "Destination chain ID", "schema": { "$ref": "#/components/schemas/ChainId" } }, { "name": "dstToken", "in": "query", "required": true, "description": "Destination token address. Use `native` for the chain's native asset.", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "amount", "in": "query", "required": true, "description": "The exact in or exact out amount of the swap, in the source or destination token's base units respectively.", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "swapDirection", "in": "query", "required": true, "description": "Whether `amount` is an exact input or exact output amount.", "schema": { "$ref": "#/components/schemas/SwapDirection" } }, { "name": "slippage", "in": "query", "required": false, "description": "Slippage tolerance in bps. **Defaults to `50`** (0.5%) if omitted — unlike `GET /getAction`, where this parameter is required.", "schema": { "type": "number", "format": "float", "minimum": 0, "maximum": 10000, "default": 50 } }, { "name": "bridgeIds", "in": "query", "required": false, "description": "Specific bridge protocols to use\n\n**Optional:** Will default to all available protocols", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BridgeId" } } }, { "name": "refundTo", "in": "query", "required": false, "description": "Alternate address the reference route would refund to\n\n**Optional:** Will default to an internal placeholder address", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "solanaSponsor", "in": "query", "required": false, "description": "Solana address that would pay for tx fees and rent (e.g. ATA creation) if this quote were later executed. Only used for Solana same-chain swaps.", "schema": { "$ref": "#/components/schemas/Address" } }, { "name": "returnDepositAddress", "in": "query", "required": false, "description": "Restrict the priced route universe to deposit-address-based flows\n\n**Optional:** Set to `true` to price against the deposit-address strategy set", "schema": { "type": "boolean", "default": false } }, { "name": "dstGas", "in": "query", "required": false, "description": "Extra gas to deliver on the destination chain, factored into the reference price\n\n**Optional**", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "appFees", "in": "query", "required": false, "description": "Application fees configuration as JSON array\n\n**Optional:** Will default to fees configured for the application\n\n **Example:** `[{ \"bps\": 50, \"receiverAddress\": \"0x...\" }]`", "schema": { "type": "string" } }, { "name": "gasless", "in": "query", "required": false, "description": "Price the route as if gasless execution were requested.\n\n**Optional:** Has limited effect on this endpoint's response — `executions`/`executionsType` are never returned by `getQuote`, so this mainly affects fee computation, not the response shape.", "schema": { "type": "boolean", "default": false } }, { "name": "skipCache", "in": "query", "required": false, "description": "Bypass the internal quote cache and re-price against live routes.\n\n**Optional:** Presence, not value, is checked — passing `skipCache=false` still skips the cache. Omit the parameter entirely to use the cache.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response with a reference-price quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateQuoteResponse" } } } }, "400": { "description": "Bad request due to missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetActionErrorResponse" }, "examples": { "AMOUNT_TOO_HIGH": { "summary": "Amount Too High", "value": { "success": false, "error": { "code": "AMOUNT_TOO_HIGH", "name": "AmountTooHighError", "message": "The specified amount is too high.", "title": "Amount too high", "statusCode": 400, "details": { "srcToken": "0x0000000000000000000000000000000000000000", "dstToken": "0x0000000000000000000000000000000000000000", "srcChainId": 1, "dstChainId": 42161, "maxAmount": 100000000000000000000 }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "AMOUNT_TOO_LOW": { "summary": "Amount Too Low", "value": { "success": false, "error": { "code": "AMOUNT_TOO_LOW", "name": "AmountTooLowError", "message": "The specified amount is too low.", "title": "Amount too low", "statusCode": 400, "details": { "srcToken": "0x0000000000000000000000000000000000000000", "dstToken": "0x0000000000000000000000000000000000000000", "srcChainId": 1, "dstChainId": 42161, "minAmount": 0.000123 }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "CROSS_VM_RECEIVER_REQUIRED": { "summary": "Cross VM Receiver Required", "value": { "success": false, "error": { "code": "CROSS_VM_RECEIVER_REQUIRED", "name": "CrossVmReceiverRequiredError", "message": "Receiver address is required for swaps across different VMs.", "title": "Receiver address required", "statusCode": 400, "details": { "srcChainId": 1, "dstChainId": 1399811149 }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "EXCESSIVE_FEE": { "summary": "Excessive Fee", "value": { "success": false, "error": { "code": "EXCESSIVE_FEE", "name": "ExcessiveFeeError", "message": "The inputted flat fee is too large (over 50% of tx input).", "title": "Excessive fee", "statusCode": 400, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "INSUFFICIENT_LIQUIDITY": { "summary": "Insufficient Liquidity", "value": { "success": false, "error": { "code": "INSUFFICIENT_LIQUIDITY", "name": "InsufficientLiquidityError", "message": "There is insufficient liquidity to complete this transaction.", "title": "Insufficient liquidity", "statusCode": 400, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "INVALID_ADDRESS_FORMAT": { "summary": "Invalid Address Format", "value": { "success": false, "error": { "code": "INVALID_ADDRESS_FORMAT", "name": "InvalidAddressError", "message": "The format of the specified address is invalid.", "title": "Invalid address format", "statusCode": 400, "details": { "field": "sender", "address": "0xinvalid", "reason": "Address must be 40 characters long" }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "INVALID_AMOUNT_ZERO": { "summary": "Invalid Amount Zero", "value": { "success": false, "error": { "code": "INVALID_AMOUNT_ZERO", "name": "InvalidAmountZeroError", "message": "Amount must be greater than zero.", "title": "Zero amount not allowed", "statusCode": 400, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "INVALID_DESTINATION_TOKEN": { "summary": "Invalid Destination Token", "value": { "success": false, "error": { "code": "INVALID_DESTINATION_TOKEN", "name": "InvalidDstTokenError", "message": "Destination token is required.", "title": "Invalid destination token", "statusCode": 400, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "INVALID_PARAMETER": { "summary": "Invalid Parameter", "value": { "success": false, "error": { "code": "INVALID_PARAMETER", "name": "InvalidParameterError", "message": "The request contains an invalid parameter.", "title": "Invalid parameter", "statusCode": 400, "details": { "parameter": "slippage", "value": "15000", "reason": "Slippage must be between 0 and 10000 bps" }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "INVALID_SOURCE_TOKEN": { "summary": "Invalid Source Token", "value": { "success": false, "error": { "code": "INVALID_SOURCE_TOKEN", "name": "InvalidSrcTokenError", "message": "Source token is required.", "title": "Invalid source token", "statusCode": 400, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "MISSING_REQUIRED_FIELD": { "summary": "Missing Required Field", "value": { "success": false, "error": { "code": "MISSING_REQUIRED_FIELD", "name": "MissingRequiredFieldError", "message": "The request is missing a required field.", "title": "Missing required field", "statusCode": 400, "details": { "field": "srcToken", "context": "Source token address is required for swap actions" }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "NO_AVAILABLE_ROUTE": { "summary": "No Available Route", "value": { "success": false, "error": { "code": "NO_AVAILABLE_ROUTE", "name": "NoAvailableRouteError", "message": "No route is available for the specified parameters.", "title": "No available route", "statusCode": 400, "details": { "srcChainId": 1, "dstChainId": 42161, "srcToken": "0x0000000000000000000000000000000000000000", "dstToken": "0x1234567890123456789012345678901234567890" }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "UNSUPPORTED_NETWORK": { "summary": "Unsupported Network", "value": { "success": false, "error": { "code": "UNSUPPORTED_NETWORK", "name": "UnsupportedNetworkError", "message": "The network with the specified chainId is not supported.", "title": "Unsupported network", "statusCode": 400, "details": { "chainId": 999999 }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "UNSUPPORTED_NETWORK_PAIR": { "summary": "Unsupported Network Pair", "value": { "success": false, "error": { "code": "UNSUPPORTED_NETWORK_PAIR", "name": "UnsupportedNetworkPairError", "message": "Routing between the specified networks is not supported.", "title": "Unsupported network pair", "statusCode": 400, "details": { "srcChainId": 1, "dstChainId": 999999 }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "UNSUPPORTED_NETWORK_TOKEN_PAIR": { "summary": "Unsupported Network Token Pair", "value": { "success": false, "error": { "code": "UNSUPPORTED_NETWORK_TOKEN_PAIR", "name": "UnsupportedNetworkAndTokenPairError", "message": "Routing between the specified tokens and networks is not supported.", "title": "Unsupported network and token pair", "statusCode": 400, "details": { "srcChainId": 1, "srcToken": "0x0000000000000000000000000000000000000000", "dstChainId": 42161, "dstToken": "0x1234567890123456789012345678901234567890" }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "UNSUPPORTED_SWAP_DIRECTION": { "summary": "Unsupported Swap Direction", "value": { "success": false, "error": { "code": "UNSUPPORTED_SWAP_DIRECTION", "name": "UnsupportedSwapDirectionError", "message": "The specified swap direction is not supported.", "title": "Unsupported swap direction", "statusCode": 400, "details": { "swapDirection": "exact-amount-out" }, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "AMOUNT_INVALID": { "summary": "Amount Invalid", "value": { "success": false, "error": { "code": "AMOUNT_INVALID", "name": "AmountInvalidError", "message": "The specified amount is invalid.", "title": "Invalid amount", "statusCode": 400, "timestamp": "2024-01-01T00:00:00.000Z" } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetActionErrorResponse" }, "examples": { "INVALID_API_KEY": { "summary": "Invalid API Key", "value": { "success": false, "error": { "code": "INVALID_API_KEY", "name": "InvalidApiKeyError", "message": "The provided API key is invalid.", "title": "Invalid API key", "statusCode": 401, "timestamp": "2024-01-01T00:00:00.000Z" } } }, "MISSING_API_KEY": { "summary": "Missing API Key", "value": { "success": false, "error": { "code": "MISSING_API_KEY", "name": "MissingApiKeyError", "message": "API key is required.", "title": "Missing API key", "statusCode": 401, "timestamp": "2024-01-01T00:00:00.000Z" } } } } } } }, "403": { "description": "Forbidden - Access denied due to restrictions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetActionErrorResponse" }, "examples": { "GEO_BLOCKED": { "summary": "Geographic Restriction", "value": { "success": false, "error": { "code": "GEO_BLOCKED", "name": "GeoBlockingError", "message": "Access denied due to geo-blocking restrictions.", "title": "Geo-blocking restriction", "statusCode": 403, "details": { "countryCode": "US", "countryName": "United States", "reason": "Country is on the blocked list", "blockedAt": "2024-01-15T10:30:00.000Z" }, "timestamp": "2024-01-01T00:00:00.000Z" } } } } } } }, "405": { "description": "Method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetActionErrorResponse" }, "examples": { "METHOD_NOT_ALLOWED": { "summary": "Method Not Allowed", "value": { "success": false, "error": { "code": "METHOD_NOT_ALLOWED", "name": "MethodNotAllowedError", "message": "The HTTP request method specified is not allowed.", "title": "Method not allowed", "statusCode": 405, "details": { "method": "POST" }, "timestamp": "2024-01-01T00:00:00.000Z" } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetActionErrorResponse" }, "examples": { "INTERNAL_SERVER_ERROR": { "summary": "Internal Server Error", "value": { "success": false, "error": { "code": "INTERNAL_SERVER_ERROR", "name": "InternalServerError", "message": "An internal server error occurred while processing the request.", "title": "Internal Server Error", "statusCode": 500, "timestamp": "2024-01-01T00:00:00.000Z" } } } } } } } } } } }, "components": { "schemas": { "EstimateQuoteResponse": { "type": "object", "required": [ "vmId", "amountIn", "amountInMax", "amountOutMin", "amountOut", "protocolFee", "applicationFee", "exchangeRate", "estimatedTxTime", "estimatedPriceImpact", "requiresTokenApproval", "requiresRegisterTransaction" ], "properties": { "vmId": { "type": "string", "enum": [ "evm", "solana", "alt-vm", "hypercore" ], "description": "Virtual machine identifier." }, "amountIn": { "$ref": "#/components/schemas/Payment", "description": "Expected amount to input (exclusive of slippage - recommended value to display in frontend)" }, "amountInMax": { "$ref": "#/components/schemas/Payment", "description": "Maximum amount to input (inclusive of slippage)" }, "amountOut": { "$ref": "#/components/schemas/Payment", "description": "Expected amount delivered to users (exclusive of slippage - recommended value to display in frontend)" }, "amountOutMin": { "$ref": "#/components/schemas/Payment", "description": "Minimum amount delivered to users (inclusive of slippage)" }, "protocolFee": { "$ref": "#/components/schemas/Payment", "description": "Swaps.xyz fee" }, "applicationFee": { "$ref": "#/components/schemas/Payment", "description": "Application fee (your fee!)" }, "bridgeFee": { "$ref": "#/components/schemas/Payment", "description": "Bridge fee (from aggregated providers). Only present when the reference route crosses a bridge." }, "relayerFee": { "$ref": "#/components/schemas/Payment", "description": "Fee charged by a gasless relay provider, denominated in USDT. Rarely populated on this endpoint since `executionsType`/`executions` are not returned here — present mainly for schema parity with `GET /getAction`." }, "exchangeRate": { "type": "number", "format": "float", "description": "Exchange rate for the swap." }, "estimatedTxTime": { "type": "number", "format": "float", "description": "Estimated transaction time in seconds." }, "estimatedPriceImpact": { "type": "number", "format": "float", "description": "Estimated price impact percentage." }, "requiresTokenApproval": { "type": "boolean", "description": "Flag indicating whether executing this route later would require a source token approval check." }, "requiresRegisterTransaction": { "type": "boolean", "description": "Flag indicating whether executing this route later would require registration via the registerTxs endpoint. Mandatory for non-EVM transactions." } } }, "ActionResponse": { "type": "object", "required": [ "tx", "txId", "vmId", "amountIn", "amountInMax", "amountOutMin", "amountOut", "protocolFee", "applicationFee", "exchangeRate", "estimatedTxTime", "estimatedPriceImpact", "allRoutes", "requiresTokenApproval", "requiresRegisterTransaction" ], "properties": { "tx": { "oneOf": [ { "title": "EVM Transaction", "$ref": "#/components/schemas/EvmTransaction" }, { "title": "Solana Transaction", "$ref": "#/components/schemas/SerializedSolTransaction" }, { "title": "Alt VM Transaction", "$ref": "#/components/schemas/AltVmTransaction" }, { "title": "HyperCore Transaction", "$ref": "#/components/schemas/HyperCoreTransaction" }, { "title": "Tron Transaction", "$ref": "#/components/schemas/TronTransaction" }, { "title": "Ton Transaction", "$ref": "#/components/schemas/TonTransaction" } ], "description": "Transaction data for execution" }, "txId": { "$ref": "#/components/schemas/Hex", "description": "Transaction ID" }, "vmId": { "$ref": "#/components/schemas/VmId" }, "amountIn": { "$ref": "#/components/schemas/Payment", "description": "Expected amount to input (exclusive of slippage - recommended value to display in frontend)" }, "amountInMax": { "$ref": "#/components/schemas/Payment", "description": "Maximum amount to input (inclusive of slippage)" }, "amountOut": { "$ref": "#/components/schemas/Payment", "description": "Expected amount delivered to users (exclusive of slippage - recommended value to display in frontend)" }, "amountOutMin": { "$ref": "#/components/schemas/Payment", "description": "Minimum amount delivered to users (inclusive of slippage)" }, "protocolFee": { "$ref": "#/components/schemas/Payment", "description": "Swaps.xyz fee" }, "applicationFee": { "$ref": "#/components/schemas/Payment", "description": "Application fee (your fee!)" }, "bridgeFee": { "$ref": "#/components/schemas/Payment", "description": "Bridge fee (from aggregated providers)" }, "bridgeIds": { "type": "array", "items": { "$ref": "#/components/schemas/BridgeId" }, "description": "Bridge IDs used in the route." }, "bridgeRoute": { "$ref": "#/components/schemas/BridgeRoute", "description": "Bridge route information (src chain + token, dst chain + token, BridgeId)" }, "exchangeRate": { "type": "number", "format": "float", "description": "Exchange rate for the swap." }, "estimatedTxTime": { "type": "number", "format": "float", "description": "Estimated transaction time in seconds." }, "estimatedPriceImpact": { "type": [ "number", "null" ], "format": "float", "description": "Estimated price impact percentage." }, "requiresTokenApproval": { "type": "boolean", "description": "Flag indicating whether the transaction object requires a source token approval check." }, "requiresRegisterTransaction": { "type": "boolean", "description": "Flag indicating whether the transaction requires registration via the registerTxs endpoint. Mandatory for non-EVM transactions." }, "allRoutes": { "type": "array", "items": { "$ref": "#/components/schemas/BaseActionResponse" }, "description": "All available routes for the action." }, "executionsType": { "type": "string", "enum": [ "DEFAULT", "GASLESS" ], "description": "Indicates the execution mode. `GASLESS` when `gasless=true` was requested and a relay provider is available; `DEFAULT` otherwise." }, "executions": { "type": "array", "items": { "$ref": "#/components/schemas/Execution" }, "description": "Ordered list of signing steps the client must complete before calling `POST /submitTx`. Only present when `executionsType` is `GASLESS`." }, "relayerFee": { "$ref": "#/components/schemas/Payment", "description": "Fee charged by the relay provider, denominated in USDT. If non-zero, the user must hold USDT in addition to the source token. Only present when `executionsType` is `GASLESS`." } } }, "BaseActionResponse": { "type": "object", "required": [ "tx", "txId", "amountIn", "vmId", "amountInMax", "amountOutMin", "amountOut", "protocolFee", "applicationFee", "exchangeRate", "estimatedTxTime", "estimatedPriceImpact", "requiresRegisterTransaction" ], "properties": { "tx": { "oneOf": [ { "title": "EVM Transaction", "$ref": "#/components/schemas/EvmTransaction" }, { "title": "Solana Transaction", "$ref": "#/components/schemas/SerializedSolTransaction" }, { "title": "Alt VM Transaction", "$ref": "#/components/schemas/AltVmTransaction" }, { "title": "HyperCore Transaction", "$ref": "#/components/schemas/HyperCoreTransaction" }, { "title": "Tron Transaction", "$ref": "#/components/schemas/TronTransaction" }, { "title": "Ton Transaction", "$ref": "#/components/schemas/TonTransaction" } ], "description": "Transaction data for execution" }, "txId": { "$ref": "#/components/schemas/Hex", "description": "Transaction ID" }, "vmId": { "$ref": "#/components/schemas/VmId" }, "amountIn": { "$ref": "#/components/schemas/Payment", "description": "Expected amount to input (exclusive of slippage - recommended value to display in frontend)" }, "amountInMax": { "$ref": "#/components/schemas/Payment", "description": "Maximum amount to input (inclusive of slippage)" }, "amountOut": { "$ref": "#/components/schemas/Payment", "description": "Expected amount delivered to users (exclusive of slippage - recommended value to display in frontend)" }, "amountOutMin": { "$ref": "#/components/schemas/Payment", "description": "Minimum amount delivered to users (inclusive of slippage)" }, "protocolFee": { "$ref": "#/components/schemas/Payment", "description": "Swaps.xyz fee" }, "applicationFee": { "$ref": "#/components/schemas/Payment", "description": "Application fee (your fee!)" }, "bridgeFee": { "$ref": "#/components/schemas/Payment", "description": "Bridge fee (from aggregated providers)" }, "bridgeIds": { "type": "array", "items": { "$ref": "#/components/schemas/BridgeId" }, "description": "Bridge IDs used in the route." }, "bridgeRoute": { "$ref": "#/components/schemas/BridgeRoute", "description": "Bridge route information (src chain + token, dst chain + token, BridgeId)" }, "exchangeRate": { "type": "number", "format": "float", "description": "Exchange rate for the swap." }, "estimatedTxTime": { "type": "number", "format": "float", "description": "Estimated transaction time in seconds." }, "estimatedPriceImpact": { "type": [ "number", "null" ], "format": "float", "description": "Estimated price impact percentage." }, "requiresRegisterTransaction": { "type": "boolean", "description": "Flag indicating whether the transaction requires registration via the registerTxs endpoint. Mandatory for non-EVM transactions." }, "executionsType": { "type": "string", "enum": [ "DEFAULT", "GASLESS" ], "description": "Indicates the execution mode. `GASLESS` when `gasless=true` was requested and a relay provider is available; `DEFAULT` otherwise." }, "executions": { "type": "array", "items": { "$ref": "#/components/schemas/Execution" }, "description": "Ordered list of signing steps the client must complete before calling `POST /submitTx`. Only present when `executionsType` is `GASLESS`." }, "relayerFee": { "$ref": "#/components/schemas/Payment", "description": "Fee charged by the relay provider, denominated in USDT. If non-zero, the user must hold USDT in addition to the source token. Only present when `executionsType` is `GASLESS`." } } }, "ChainId": { "type": "integer", "description": "Chain ID. Find in the list of supported networks." }, "Eip712Domain": { "type": "object", "required": [ "name", "version", "chainId", "verifyingContract" ], "properties": { "name": { "type": "string", "description": "EIP-712 domain name" }, "version": { "type": "string", "description": "EIP-712 domain version" }, "chainId": { "type": "integer", "description": "Chain ID the typed data is bound to" }, "verifyingContract": { "type": "string", "description": "Address of the contract verifying the signature" } } }, "Eip712Data": { "type": "object", "required": [ "domain", "types", "message" ], "properties": { "domain": { "$ref": "#/components/schemas/Eip712Domain" }, "types": { "type": "object", "description": "EIP-712 type definitions (field name → array of {name, type} pairs)", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } } }, "message": { "type": "object", "description": "The typed data message payload", "additionalProperties": true } } }, "EvmTransactionSignExecution": { "type": "object", "required": [ "txType", "data" ], "properties": { "txType": { "type": "string", "enum": [ "evmTransactionSign" ] }, "data": { "type": "string", "description": "JSON string of an unsigned Tron transaction (TronWeb `raw_data` shape)" }, "signature": { "type": "string", "description": "Hex-encoded signature from TronLink or compatible Tron wallet" } } }, "EvmSignTypedDataExecution": { "type": "object", "required": [ "txType", "data" ], "properties": { "txType": { "type": "string", "enum": [ "evmSignTypedData" ] }, "data": { "description": "EIP-712 typed data to sign. Accepted as either a JSON string (same format returned by `GET /getAction`) or a parsed object — both are equivalent.", "oneOf": [ { "type": "string", "description": "JSON-encoded EIP-712 typed data" }, { "$ref": "#/components/schemas/Eip712Data" } ] }, "signature": { "type": "string", "description": "Hex-encoded EIP-712 signature" } } }, "Execution": { "description": "A single signing step returned in the `executions` array of a gasless `getAction` response. Only available for Tron same-chain swaps. The client must sign each item in order and include the signatures when calling `POST /submitTx`.", "oneOf": [ { "$ref": "#/components/schemas/EvmTransactionSignExecution" }, { "$ref": "#/components/schemas/EvmSignTypedDataExecution" } ], "discriminator": { "propertyName": "txType", "mapping": { "evmTransactionSign": "#/components/schemas/EvmTransactionSignExecution", "evmSignTypedData": "#/components/schemas/EvmSignTypedDataExecution" } } }, "SubmitTxRequest": { "type": "object", "required": [ "txId", "chainId", "executions" ], "properties": { "txId": { "type": "string", "description": "The `txId` from the `GET /getAction` quote response. Used to correlate the signed executions with the original action on the relay." }, "chainId": { "$ref": "#/components/schemas/ChainId", "description": "Source chain ID of the swap." }, "executions": { "type": "array", "description": "All execution steps from the `getAction` response, each with a `signature` field populated by the user's wallet. Must be in the same order as returned by `getAction`.", "items": { "$ref": "#/components/schemas/Execution" } } } }, "SubmitTxResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "description": "Whether the relay broadcast was accepted." }, "txId": { "type": "string", "description": "Internal transaction ID. Pass this to `GET /getStatus` to poll for completion — the status endpoint will return the on-chain transaction hash once the relay broadcast confirms." }, "error": { "type": "string", "description": "Error message when `success` is `false`." } } }, "VmId": { "type": "string", "enum": [ "evm", "solana", "alt-vm", "hypercore", "tron", "ton" ], "description": "Virtual machine identifier." }, "BridgeId": { "type": "string", "description": "Bridge protocol identifier (e.g. \"across\", \"relay\", \"mayan\")." }, "ActionType": { "type": "string", "enum": [ "swap-action", "evm-calldata-tx", "polymarket" ], "description": "Type of action to perform." }, "SwapDirection": { "type": "string", "enum": [ "exact-amount-in", "exact-amount-out" ], "description": "Swap direction for the action." }, "EvmTransaction": { "type": "object", "required": [ "to", "data", "value" ], "properties": { "to": { "$ref": "#/components/schemas/EvmAddress" }, "data": { "$ref": "#/components/schemas/Hex" }, "value": { "type": "string", "pattern": "^[0-9]+$", "description": "Value in wei as string" }, "chainId": { "$ref": "#/components/schemas/ChainId" } } }, "SerializedSolTransaction": { "type": "object", "required": [ "base64Tx", "recentBlockhash", "payer" ], "properties": { "base64Tx": { "type": "string", "description": "Base64-encoded transaction" }, "recentBlockhash": { "type": "string", "description": "Recent blockhash for transaction validity" }, "payer": { "$ref": "#/components/schemas/SolanaAddress", "description": "PublicKey who pays fees" } } }, "AltVmTransaction": { "type": "object", "required": [ "to", "value", "chainId", "chainKey" ], "properties": { "to": { "$ref": "#/components/schemas/ExchangeAddress", "description": "Exchange address" }, "toExtra": { "type": [ "string", "null" ], "description": "Additional address information (e.g., memo, tag). Can be null." }, "value": { "type": "string", "pattern": "^[0-9]+$", "description": "Value as string" }, "chainId": { "$ref": "#/components/schemas/ChainId" }, "chainKey": { "type": "string", "description": "Chain key identifier" } } }, "HyperCoreAction": { "type": "string", "enum": [ "usdSend", "sendAsset" ], "description": "HyperCore action type" }, "HyperCoreUsdSendTransaction": { "type": "object", "required": [ "type", "destination", "amount", "chainId" ], "properties": { "type": { "type": "string", "enum": [ "usdSend" ] }, "destination": { "type": "string", "description": "Destination address" }, "amount": { "type": "string", "description": "Amount to transfer" }, "chainId": { "$ref": "#/components/schemas/ChainId", "description": "Chain ID. 1337 for HyperCore" } } }, "HyperCoreSendAssetTransaction": { "type": "object", "required": [ "type", "destination", "amount", "chainId", "sourceDex", "destinationDex", "token", "fromSubAccount" ], "properties": { "type": { "type": "string", "enum": [ "sendAsset" ] }, "destination": { "type": "string", "description": "Destination address" }, "amount": { "type": "string", "description": "Amount to transfer" }, "chainId": { "$ref": "#/components/schemas/ChainId", "description": "Chain ID. 1337 for HyperCore" }, "sourceDex": { "type": "string", "description": "Source perp dex identifier. Empty string for the default perp dex, \"spot\" for the spot dex." }, "destinationDex": { "type": "string", "description": "Destination perp dex identifier" }, "token": { "type": "string", "description": "Token identifier in \"SYMBOL:ADDRESS\" form" }, "fromSubAccount": { "type": "string", "description": "Sub-account to send from. Empty string for the main account." } } }, "HyperCoreTransaction": { "oneOf": [ { "$ref": "#/components/schemas/HyperCoreUsdSendTransaction" }, { "$ref": "#/components/schemas/HyperCoreSendAssetTransaction" } ] }, "TronTransaction": { "type": "object", "required": [ "to", "data", "value" ], "properties": { "to": { "type": "string", "pattern": "^T[a-zA-Z0-9]{33}$", "description": "Tron address (base58, starts with 'T', 34 chars)" }, "data": { "type": "string", "description": "Hex-encoded calldata" }, "value": { "type": "string", "pattern": "^[0-9]+$", "description": "Value as string" } } }, "Payment": { "allOf": [ { "$ref": "#/components/schemas/TokenInfo" }, { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "string", "pattern": "^[0-9]+$" }, "usdAmount": { "type": [ "number", "null" ], "format": "float", "description": "USD value of the payment amount" } } } ] }, "ExchangeAddress": { "type": "string", "description": "Exchange address format" }, "TokenInfo": { "type": "object", "required": [ "chainId", "address", "name", "symbol", "decimals", "isNative" ], "properties": { "chainId": { "$ref": "#/components/schemas/ChainId", "description": "Chain ID for the token" }, "address": { "$ref": "#/components/schemas/Address", "description": "Token address" }, "name": { "type": "string", "description": "Token name" }, "symbol": { "type": "string", "description": "Token symbol" }, "decimals": { "type": "integer", "description": "Token decimals" }, "isNative": { "type": "boolean", "description": "Boolean flag for whether token is the chain's gas token." }, "logo": { "type": [ "string", "null" ], "description": "URL to the token's logo image. Can be null if logo is not available." }, "swapsXyzCode": { "type": "string", "description": "Internal Swaps.xyz token identifier code." } } }, "TokenListItem": { "type": "object", "required": [ "chainId", "address", "name", "symbol", "decimals", "isNative" ], "properties": { "chainId": { "$ref": "#/components/schemas/ChainId", "description": "Chain ID for the token" }, "address": { "$ref": "#/components/schemas/Address", "description": "Token address" }, "name": { "type": "string", "description": "Token name" }, "symbol": { "type": "string", "description": "Token symbol" }, "decimals": { "type": "integer", "description": "Token decimals" }, "isNative": { "type": "boolean", "description": "Boolean flag for whether token is the chain's gas token." }, "logo": { "type": [ "string", "null" ], "description": "URL to the token's logo image. Can be null if logo is not available." } } }, "TokenListResponse": { "type": "object", "required": [ "tokens" ], "properties": { "tokens": { "type": "array", "description": "List of tokens for the requested chain, with the native token listed first", "items": { "$ref": "#/components/schemas/TokenListItem" } } } }, "TokenListByChainResponse": { "type": "object", "description": "Map of chain ID (as a string) to that chain's token list, returned when no chainId query parameter is provided", "additionalProperties": { "$ref": "#/components/schemas/TokenListResponse" } }, "BridgeStep": { "type": "object", "required": [ "srcChainId", "dstChainId", "srcBridgeToken", "dstBridgeToken", "bridgeId" ], "properties": { "srcChainId": { "$ref": "#/components/schemas/ChainId" }, "dstChainId": { "$ref": "#/components/schemas/ChainId" }, "srcBridgeToken": { "$ref": "#/components/schemas/Address" }, "dstBridgeToken": { "$ref": "#/components/schemas/Address" }, "bridgeId": { "$ref": "#/components/schemas/BridgeId" } } }, "BridgeRoute": { "type": "array", "items": { "$ref": "#/components/schemas/BridgeStep" }, "description": "Array of bridge steps" }, "Address": { "type": "string", "description": "Address type - can be EvmAddress, HyperCoreAddress, SolanaAddress, or AltVmAddress." }, "EvmAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "EVM address (0x prefix + 40 hex characters)" }, "HyperCoreAddress": { "type": "string", "pattern": "^0x([a-fA-F0-9]{32}|[a-fA-F0-9]{40})$", "description": "HyperCore address (0x prefix + 32 or 40 hex characters)" }, "SolanaAddress": { "type": "string", "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$", "description": "Solana public key (base58 encoded, 32-44 characters)" }, "AltVmAddress": { "type": "string", "pattern": "^[a-zA-Z0-9\\-_]{10,200}$", "description": "AltVM address (alphanumeric with dashes/underscores, 10-200 characters)" }, "Hex": { "type": "string", "pattern": "^0x[a-fA-F0-9]*$", "description": "Hex string with 0x prefix" }, "ErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "description": "Always false for error responses", "enum": [ false ], "example": false }, "error": { "type": "object", "required": [ "code", "name", "message", "title", "statusCode", "timestamp" ], "properties": { "code": { "type": "string", "description": "Error type code for programmatic handling" }, "name": { "type": "string", "description": "Error class name" }, "message": { "type": "string", "description": "Detailed error message" }, "title": { "type": "string", "description": "Short, user-friendly error title" }, "statusCode": { "type": "integer", "description": "HTTP status code" }, "details": { "type": "object", "description": "Additional error details", "additionalProperties": true }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp when the error occurred" } } } } }, "GetActionErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "description": "Always false for error responses", "enum": [ false ], "example": false }, "error": { "type": "object", "required": [ "code", "name", "message", "title", "statusCode", "timestamp" ], "properties": { "code": { "type": "string", "description": "Error type code for programmatic handling", "enum": [ "AMOUNT_INVALID", "AMOUNT_TOO_HIGH", "AMOUNT_TOO_LOW", "CROSS_VM_RECEIVER_REQUIRED", "EXCESSIVE_FEE", "GEO_BLOCKED", "INSUFFICIENT_LIQUIDITY", "INVALID_ADDRESS_FORMAT", "INVALID_AMOUNT_ZERO", "INVALID_API_KEY", "INVALID_DESTINATION_TOKEN", "INVALID_PARAMETER", "INVALID_SOURCE_TOKEN", "INTERNAL_SERVER_ERROR", "METHOD_NOT_ALLOWED", "MISSING_API_KEY", "MISSING_REQUIRED_FIELD", "NO_AVAILABLE_ROUTE", "UNSUPPORTED_NETWORK", "UNSUPPORTED_NETWORK_PAIR", "UNSUPPORTED_NETWORK_TOKEN_PAIR", "UNSUPPORTED_SWAP_DIRECTION", "WALLET_SCREENED" ] }, "name": { "type": "string", "description": "Error class name", "example": "InvalidAddressError" }, "message": { "type": "string", "description": "Detailed error message", "example": "The format of the specified address is invalid." }, "title": { "type": "string", "description": "Short, user-friendly error title", "example": "Invalid address format" }, "statusCode": { "type": "integer", "description": "HTTP status code", "example": 400 }, "details": { "type": "object", "description": "Additional context about the error, including invalid values and suggestions", "properties": { "field": { "type": "string", "description": "The field that caused the error" }, "address": { "type": "string", "description": "The invalid address value" }, "reason": { "type": "string", "description": "Explanation of why the value is invalid" } }, "additionalProperties": true, "example": { "field": "srcToken", "address": "0xinvalid", "reason": "Address must be 40 characters long" } }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp when the error occurred", "example": "2024-01-01T00:00:00.000Z" } } } } }, "ChainListResponse": { "type": "object", "properties": { "chainId": { "$ref": "#/components/schemas/ChainId" }, "logo": { "type": [ "string", "null" ], "description": "Chain logo URL" }, "name": { "type": "string", "description": "Human-readable chain name" }, "vmId": { "$ref": "#/components/schemas/VmId" } }, "required": [ "chainId", "logo", "name", "vmId" ] }, "DexId": { "type": "string", "description": "DEX identifier (depends on integration)" }, "AppFee": { "type": "object", "required": [ "bps", "receiverAddress" ], "properties": { "bps": { "type": "number", "description": "Fee in basis points" }, "receiverAddress": { "$ref": "#/components/schemas/EvmAddress", "description": "EVM address to receive the fee" } } }, "TokenInfoWithAmounts": { "allOf": [ { "$ref": "#/components/schemas/TokenInfo" }, { "type": "object", "required": [ "minAmount", "maxAmount" ], "properties": { "minAmount": { "type": [ "string", "null" ], "description": "Minimum amount of source token for exact-out swaps. \n `null` if no min." }, "maxAmount": { "type": [ "string", "null" ], "description": "Maximum amount of source token for exact-out swaps. \n `null` if no max." } } } ] }, "AmountLimits": { "type": "object", "required": [ "minAmount", "maxAmount" ], "properties": { "minAmount": { "type": [ "string", "null" ], "description": "Minimum amount of source token required for exact-in swaps. \n `null` if no min." }, "maxAmount": { "type": [ "string", "null" ], "description": "Maximum amount of source token for exact-in swaps. \n `null` if no max." } } }, "ChainPath": { "type": "object", "properties": { "chainId": { "$ref": "#/components/schemas/ChainId" }, "tokens": { "description": "Available destination tokens for given source token \n `all` indicates all tokens on destination chain are eligible", "oneOf": [ { "title": "Named VM", "type": "string", "enum": [ "all" ] }, { "title": "Token List", "type": "array", "items": { "$ref": "#/components/schemas/TokenInfoWithAmounts" } } ] }, "supportsExactAmountIn": { "type": "boolean" }, "supportsExactAmountOut": { "type": "boolean" }, "amountLimits": { "allOf": [ { "$ref": "#/components/schemas/AmountLimits" }, { "type": "object", "deprecated": true, "description": "⚠️ This field is maintained for backwards compatibility. Use `srcToken.minAmount` and `srcToken.maxAmount` at the top level of the response instead." } ] } }, "required": [ "chainId", "tokens", "supportsExactAmountIn", "supportsExactAmountOut" ] }, "GetPathsOutput": { "type": "object", "properties": { "srcChainId": { "$ref": "#/components/schemas/ChainId", "description": "The source chain ID" }, "srcToken": { "$ref": "#/components/schemas/TokenInfoWithAmounts", "description": "Source token information including amount limits" }, "paths": { "type": "array", "items": { "$ref": "#/components/schemas/ChainPath" } }, "timestamp": { "type": "string", "description": "Response timestamp (ISO string) for cache validation" } }, "required": [ "srcChainId", "srcToken", "paths", "timestamp" ] }, "TxRegistrationEvent": { "type": "object", "properties": { "txId": { "type": "string", "description": "Unique transaction identifier", "example": "0x49b1d3d38176e45864fd55500c6c1879ab318609e1ed0c8eb9abd818e6c811fd" }, "txHash": { "type": "string", "description": "Transaction hash", "example": "0x62d0e13123852791446c6f923c2d0b9247bda10f1eb5eb48ff5b4bc42d22ab42" } }, "required": [ "txId" ] }, "ValidatedTxId": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the transaction registration was successful", "example": true }, "error": { "type": [ "string", "null" ], "description": "Error message if registration failed", "example": null } }, "required": [ "success" ] }, "TxStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success", "pending", "requires refund", "refunded", "failed", "not yet created", "expired", "submitted", "completed" ], "description": "Status of the transaction", "example": "success" }, "sender": { "type": "string", "description": "Sender wallet address", "example": "0x1234567890123456789012345678901234567890" }, "srcChainId": { "type": "integer", "description": "Source chain ID", "example": 1 }, "dstChainId": { "type": [ "integer", "null" ], "description": "Destination chain ID", "example": 42161 }, "srcTxHash": { "type": [ "string", "null" ], "description": "Source transaction hash", "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" }, "dstTxHash": { "type": [ "string", "null" ], "description": "Destination transaction hash", "example": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" }, "bridgeDetails": { "$ref": "#/components/schemas/BridgeDetails" }, "txId": { "type": "string", "description": "Unique transaction identifier", "example": "0x49b1d3d38176e45864fd55500c6c1879ab318609e1ed0c8eb9abd818e6c811fd" }, "actionRequest": { "$ref": "#/components/schemas/ActionRequest", "description": "Original action request parameters" }, "actionResponse": { "$ref": "#/components/schemas/ActionResponse", "description": "Original action response data" }, "usdRates": { "type": [ "object", "null" ], "description": "USD rates at the time of the transaction", "properties": { "srcToken": { "type": [ "number", "null" ] }, "dstToken": { "type": [ "number", "null" ] }, "timestamp": { "type": "integer", "description": "Unix timestamp of the rate snapshot" } }, "required": [ "timestamp" ] }, "workflow": { "anyOf": [ { "$ref": "#/components/schemas/WorkflowData" }, { "type": "null" } ], "description": "Workflow information if transaction is associated with a workflow (only present if the transaction had a workflow)" } }, "required": [ "txId", "status", "sender", "srcChainId", "bridgeDetails" ] }, "TxDetails": { "allOf": [ { "$ref": "#/components/schemas/TxStatus" }, { "type": "object", "properties": { "org": { "anyOf": [ { "$ref": "#/components/schemas/Org" }, { "type": "null" } ] }, "usdValue": { "type": [ "number", "null" ], "description": "USD value of the transaction", "example": 100.5 }, "srcTx": { "anyOf": [ { "$ref": "#/components/schemas/OnchainTx" }, { "type": "null" } ] }, "dstTx": { "anyOf": [ { "$ref": "#/components/schemas/OnchainTx" }, { "type": "null" } ] } } } ] }, "BridgeDetails": { "type": "object", "properties": { "isBridge": { "type": "boolean", "description": "Whether this transaction involves bridging", "example": true }, "bridgeTime": { "type": [ "number", "null" ], "description": "Bridge time in seconds (null if not a bridge)", "example": 420 }, "txPath": { "type": "array", "items": { "$ref": "#/components/schemas/TxNode" }, "description": "Transaction path through different chains" } }, "required": [ "isBridge", "bridgeTime", "txPath" ] }, "TxNode": { "type": "object", "properties": { "chainId": { "type": "integer", "description": "Chain ID for this step", "example": 1 }, "txHash": { "type": [ "string", "null" ], "description": "Transaction hash for this step", "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" }, "timestamp": { "type": [ "integer", "null" ], "example": 1640995200 }, "nextBridge": { "type": [ "string", "null" ], "description": "Bridge type for the next hop", "example": "layerZero" } }, "required": [ "chainId" ] }, "OnchainTx": { "type": "object", "properties": { "toAddress": { "type": [ "string", "null" ], "description": "Recipient address", "example": "0x38630c8ec92494cf96ded12060d8136b75e7a8b5" }, "txHash": { "type": "string", "description": "Transaction hash", "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" }, "chainId": { "type": "integer", "description": "Chain ID", "example": 1 }, "value": { "type": [ "string", "null" ], "description": "Transaction value as string", "example": "0" }, "timestamp": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Unix timestamp in seconds. Integer for recent records; string for records created before the bigint migration.", "example": 1765593607 }, "paymentToken": { "$ref": "#/components/schemas/Token" }, "revertReason": { "type": [ "string", "null" ], "description": "Revert reason if transaction failed, null otherwise" } }, "required": [ "txHash", "chainId", "timestamp" ] }, "Token": { "type": "object", "properties": { "name": { "type": "string", "description": "Token name", "example": "Ethereum" }, "symbol": { "type": "string", "description": "Token symbol", "example": "ETH" }, "decimals": { "type": "integer", "description": "Token decimals", "example": 18 }, "amount": { "type": "string", "description": "Token amount as bigint string", "example": "1000000000000000000" }, "address": { "type": [ "string", "null" ], "description": "Token contract address", "example": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174" }, "chainId": { "type": "integer", "description": "Chain ID for the token", "example": 137 }, "isNative": { "type": "boolean", "description": "Whether the token is the native gas token", "example": false }, "usdAmount": { "type": "number", "description": "USD value of the token amount", "example": 4.00687776 } }, "required": [ "name", "symbol", "decimals", "amount", "chainId" ] }, "Org": { "type": "object", "properties": { "appId": { "type": "string", "description": "Application ID", "example": "0xb38801d6" }, "appName": { "type": "string", "description": "Application name", "example": "Box Examples / Scenarios" }, "affiliateId": { "type": [ "string", "null" ], "description": "Affiliate ID", "example": "0x00000000" } }, "required": [ "appId" ] }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer", "description": "Current page number", "example": 1 }, "limit": { "type": "integer", "description": "Results per page", "example": 25 }, "total": { "type": "integer", "description": "Total number of results", "example": 150 }, "totalPages": { "type": "integer", "description": "Total number of pages", "example": 6 } }, "required": [ "page", "limit", "total", "totalPages" ] }, "get_400__api_getStatusSchema": { "$ref": "#/components/schemas/ErrorResponse" }, "post_200__webhooks_registerTxsSchema": { "type": "array", "items": { "$ref": "#/components/schemas/ValidatedTxId" } }, "ActionRequest": { "type": "object", "properties": { "actionType": { "$ref": "#/components/schemas/ActionType", "description": "Type of action to perform" }, "sender": { "$ref": "#/components/schemas/Address", "description": "The address of the sender/user" }, "srcChainId": { "$ref": "#/components/schemas/ChainId", "description": "Source chain ID" }, "srcToken": { "$ref": "#/components/schemas/Address", "description": "Source token address" }, "dstChainId": { "$ref": "#/components/schemas/ChainId", "description": "Destination chain ID" }, "dstToken": { "$ref": "#/components/schemas/Address", "description": "Destination token address" }, "slippage": { "type": "number", "format": "float", "minimum": 0, "maximum": 10000, "description": "Slippage tolerance in bps" }, "amount": { "type": "string", "pattern": "^[0-9]+$", "description": "The exact in or exact out amount of the swap" }, "swapDirection": { "$ref": "#/components/schemas/SwapDirection", "description": "Swap direction for the action" }, "recipient": { "$ref": "#/components/schemas/Address", "description": "Address to receive the swapped tokens" }, "to": { "$ref": "#/components/schemas/Address", "description": "The EVM address of the target contract (20 bytes hex)" }, "data": { "$ref": "#/components/schemas/Hex", "description": "Calldata for the transaction" }, "value": { "type": "string", "pattern": "^[0-9]+$", "description": "Value to send with transaction" }, "erc20Amount": { "type": "string", "pattern": "^[0-9]+$", "description": "The amount of Erc20 being transferred" }, "erc20Spender": { "$ref": "#/components/schemas/Address", "description": "The Erc20 spender requiring approval for the transaction call" }, "bridgeIds": { "type": "array", "items": { "$ref": "#/components/schemas/BridgeId" }, "description": "Specific bridge protocols to use" }, "refundTo": { "$ref": "#/components/schemas/Address", "description": "Alternate address to receive refunds" }, "appFees": { "type": "array", "items": { "$ref": "#/components/schemas/AppFee" }, "maxItems": 2, "description": "Application fees configuration" } }, "required": [ "actionType", "sender", "srcChainId", "srcToken", "dstChainId", "dstToken", "slippage" ] }, "WorkflowData": { "type": "object", "properties": { "name": { "type": "string", "description": "Workflow name", "example": "polymarket" }, "operation": { "type": "string", "description": "Operation type", "example": "placeOrder" }, "status": { "type": "string", "description": "Workflow status", "example": "success" }, "timestamp": { "type": "integer", "description": "Unix timestamp when workflow was executed", "example": 1763996274 }, "data": { "oneOf": [ { "title": "Polymarket Data", "$ref": "#/components/schemas/PolyMarketWorkflowData" }, { "title": "Generic Workflow Data", "type": "object", "additionalProperties": true } ], "description": "Workflow-specific data" } } }, "PolyMarketWorkflowData": { "type": "object", "required": [ "userId", "orderRequest", "orderResponse" ], "properties": { "userId": { "type": "string", "description": "Polymarket user ID", "example": "0x0797bfec6d2d4f733d461bbee8125805e9e9c892" }, "orderRequest": { "$ref": "#/components/schemas/PolymarketOrderRequest" }, "orderResponse": { "oneOf": [ { "title": "Open Order", "$ref": "#/components/schemas/PolymarketOpenOrder" }, { "title": "Error Response", "type": "object", "required": [ "error", "status" ], "properties": { "error": { "type": "string", "description": "Error message" }, "status": { "type": "string", "description": "Order status" } } } ], "description": "Order response from Polymarket" }, "relayTx": { "type": [ "object", "null" ], "properties": { "txHash": { "type": "string", "description": "Transaction hash of the relay transaction" }, "status": { "type": "string", "description": "Status of the relay transaction" } }, "description": "Relay transaction details (null if not applicable)" } } }, "PolymarketOrderRequest": { "type": "object", "required": [ "side", "tokenID", "orderType", "feeRateBps", "slippage", "tickSize", "negRisk" ], "properties": { "side": { "type": "string", "enum": [ "BUY", "SELL" ], "description": "Order side" }, "tokenID": { "type": "string", "description": "Polymarket CLOB token ID", "example": "110902308091723190012269532299497167125504426554890434343419495764557291673806" }, "orderType": { "type": "string", "enum": [ "FOK", "FAK", "GTC", "GTD" ], "description": "Order type (FOK/FAK are market orders, GTC/GTD are limit orders)" }, "feeRateBps": { "type": "number", "minimum": 0, "description": "Fee rate in basis points", "example": 0 }, "slippage": { "type": "number", "description": "Slippage tolerance in basis points", "example": 100 }, "tickSize": { "type": "string", "enum": [ "0.01", "0.001", "0.0001" ], "description": "Price tick size" }, "negRisk": { "type": "boolean", "description": "Negative risk flag" }, "amount": { "type": "number", "description": "Amount for market orders (FOK/FAK)", "example": 5 }, "price": { "type": "number", "minimum": 0, "maximum": 1, "description": "Price per share (0-1) - required for limit orders, optional for market orders", "example": 0.021 }, "size": { "type": "number", "minimum": 0, "description": "Number of shares for limit orders", "example": 5 } } }, "PolymarketOpenOrder": { "type": "object", "required": [ "id", "status", "owner", "maker_address", "market", "asset_id", "side", "original_size", "size_matched", "price", "outcome", "created_at", "expiration", "order_type", "associate_trades" ], "properties": { "id": { "type": "string", "description": "Order ID", "example": "0xbd2f3c625c1f6f918a74e8645c3afee9e8f2c5adf91f178efa5e1b65f74fb489" }, "status": { "type": "string", "description": "Order status", "example": "MATCHED" }, "owner": { "type": "string", "description": "Owner ID", "example": "258f7485-b93f-52e5-2327-a53c49a299c1" }, "maker_address": { "type": "string", "description": "Maker address", "example": "0xBEDcAD563ddf52391573a016Bc5EC7A334Eec756" }, "market": { "type": "string", "description": "Market ID", "example": "0xb050c89e1e5738c79e117d28da1f057ac2f193511aab87a01b517b466c7265dc" }, "asset_id": { "type": "string", "description": "Asset ID (token ID)", "example": "110902308091723190012269532299497167125504426554890434343419495764557291673806" }, "side": { "type": "string", "enum": [ "BUY", "SELL" ], "description": "Order side" }, "original_size": { "type": "string", "description": "Original order size", "example": "5" }, "size_matched": { "type": "string", "description": "Size matched", "example": "0" }, "price": { "type": "string", "description": "Order price", "example": "0.02" }, "outcome": { "type": "string", "description": "Order outcome", "example": "No" }, "expiration": { "type": "string", "description": "Expiration timestamp", "example": "1763996360" }, "order_type": { "type": "string", "description": "Order type", "example": "GTD" }, "associate_trades": { "type": "array", "items": { "type": "string" }, "description": "Associated trade IDs" }, "created_at": { "type": "integer", "description": "Unix timestamp when order was created", "example": 1763996291 } } }, "TonTransaction": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "description": "Outbound TON messages for the wallet to sign and send, in order. Field names and encodings match TonConnect's `sendTransaction` message shape, so this array can be passed through as-is (add your own `validUntil`).", "items": { "type": "object", "required": [ "address", "amount", "payload" ], "properties": { "address": { "type": "string", "description": "Target contract address (user-friendly base64url, 48 chars)" }, "amount": { "type": "string", "description": "Nanotons to attach to the message — send exactly this, never add value on top. For a native-TON source it covers the swapped amount plus the gas budget; for a jetton source it is gas only (the jetton amount rides inside `payload`)." }, "payload": { "type": "string", "description": "Message body (BoC), base64-encoded" }, "stateInit": { "type": "string", "description": "State init (BoC), base64-encoded; only set when the jetton wallet still needs deploying" } } } } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Limited demo key for API Reference: `5c951bc81da566bbd030ba8e20724063`." } } }, "security": [ { "ApiKeyAuth": [] } ] }