{ "openapi": "3.0.0", "paths": { "/v3/swap/quote": { "get": { "operationId": "V3SwapController_quote", "parameters": [ { "name": "userOps", "required": true, "in": "query", "description": "Requested user operation types. Use a comma-separated value or repeat the query param. Allowed values: tx, deposit, cex-withdraw.", "schema": { "example": [ "tx", "deposit" ], "type": "array", "items": { "type": "string", "enum": [ "tx", "deposit", "cex-withdraw" ] }, "default": [ "tx" ] }, "example": [ "tx" ] }, { "name": "destinationChainId", "required": true, "in": "query", "description": "Destination chain ID.", "schema": { "example": "8453", "type": "string", "default": "8453" } }, { "name": "inputToken", "required": true, "in": "query", "description": "Input token address on originChainId, or token symbol when userOps is cex-withdraw and originChainId is omitted.", "schema": { "example": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "type": "string", "default": "0xaf88d065e77c8cc2239327c5edb3a432268e5831" } }, { "name": "inputAmount", "required": true, "in": "query", "description": "Input amount in token base units. HyperCore origins accept decimal strings.", "schema": { "example": "1000000", "type": "string", "default": "1000000" } }, { "name": "outputToken", "required": true, "in": "query", "description": "Output token address on destinationChainId.", "schema": { "example": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "type": "string", "default": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" } }, { "name": "receiverAddress", "required": true, "in": "query", "description": "Destination receiver address. Final recipient for plain routes; executor/contract receiver when destinationPayload is set.", "schema": { "example": "0x3e8cB4bd04d81498aB4b94a392c334F5328b237b", "type": "string", "default": "0x3e8cB4bd04d81498aB4b94a392c334F5328b237b" } }, { "name": "originChainId", "required": true, "in": "query", "description": "Origin chain ID. Required for tx and deposit userOps; optional for cex-withdraw.", "schema": { "example": "42161", "type": "string", "default": "42161" } }, { "name": "userAddress", "required": true, "in": "query", "description": "Origin wallet address. Required for tx userOp. Used as the default refund address unless refundAddress is set.", "schema": { "example": "0x3e8cB4bd04d81498aB4b94a392c334F5328b237b", "type": "string", "default": "0x3e8cB4bd04d81498aB4b94a392c334F5328b237b" } }, { "name": "slippage", "required": false, "in": "query", "description": "Slippage tolerance percentage.", "schema": { "type": "string" } }, { "name": "refundAddress", "required": false, "in": "query", "description": "Address to refund funds to. Required for deposit and cex-withdraw userOps.", "schema": { "type": "string" } }, { "name": "contractCaller", "required": false, "in": "query", "description": "Intermediate contract that will call AllowanceHolder.exec on behalf of userAddress (e.g. an integrator bridge contract), for direct tx routes. userAddress remains the default refund address unless refundAddress is set. Pass this only when a contract — not the user's own wallet — is the AllowanceHolder caller, otherwise the transaction reverts (CallerNotSignedUser).", "schema": { "type": "string" } }, { "name": "feeBps", "required": false, "in": "query", "description": "Affiliate fee in basis points. Must be provided together with feeTakerAddress.", "schema": { "type": "string" } }, { "name": "feeTakerAddress", "required": false, "in": "query", "description": "Address that receives the affiliate fee. Must be provided together with feeBps.", "schema": { "type": "string" } }, { "name": "refuel", "required": false, "in": "query", "description": "Whether to request gas refuel. Must be exactly true or false.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "destinationPayload", "required": false, "in": "query", "description": "Hex payload to execute on the destination receiver. Requires destinationGasLimit when set.", "schema": { "type": "string" } }, { "name": "destinationGasLimit", "required": false, "in": "query", "description": "Gas limit for destination payload execution. Requires destinationPayload when set.", "schema": { "type": "string" } }, { "name": "includeProvider", "required": false, "in": "query", "description": "Comma-separated provider IDs to include. Same-chain routes treat these as DEX IDs; cross-chain routes treat these as public bridge IDs.", "schema": { "type": "string" } }, { "name": "excludeProvider", "required": false, "in": "query", "description": "Comma-separated provider IDs to exclude. Same-chain routes treat these as DEX IDs; cross-chain routes treat these as public bridge IDs.", "schema": { "type": "string" } }, { "name": "exchange", "required": false, "in": "query", "description": "CEX exchange ID. Required for cex-withdraw userOp.", "schema": { "type": "string" } }, { "name": "includeQuoteRejections", "required": false, "in": "query", "description": "When true, include per-provider rejection reasons for cross-chain tx quotes that returned no route.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "private", "required": false, "in": "query", "description": "When true, only privacy-capable direct tx providers are quoted.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "simulatedQuotesRequired", "required": false, "in": "query", "description": "When true, return only same-chain DEX routes that passed on-chain simulation, with output amounts replaced by simulated values.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "solanaSponsorAddress", "required": false, "in": "query", "description": "Solana sponsor address for gasless same-chain swaps. When set, the sponsor pays tx fees and ATA rent (DFlow sponsored swap). Solana origin only.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "V3 swap quote routes.", "content": { "application/json": { "examples": { "sameChainTx": { "summary": "Same-chain tx route", "value": { "success": true, "statusCode": 200, "result": { "originChainId": 42161, "destinationChainId": 42161, "userAddress": "0x3e8cb4bd04d81498ab4b94a392c334f5328b237b", "receiverAddress": "0x3e8cb4bd04d81498ab4b94a392c334f5328b237b", "input": { "token": { "chainId": 42161, "address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "name": "USDC", "symbol": "USDC", "decimals": 6, "logoURI": "https://assets.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "icon": "https://assets.coingecko.com/coins/images/6319/large/USDC.png?1769615602" }, "amount": "100000", "priceInUsd": 1, "valueInUsd": 0.1 }, "routes": [ { "userOp": "tx", "quoteId": "0x759a82929538535f6186da129b49e42f3fa22539cde911a2f394bf9d1e3732b4", "expiresAt": 1781000089, "output": { "token": { "chainId": 42161, "address": "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9", "name": "USDT0", "symbol": "USDT0", "decimals": 6, "logoURI": "https://assets.coingecko.com/coins/images/53705/large/usdt0.jpg?1737086183", "icon": "https://assets.coingecko.com/coins/images/53705/large/usdt0.jpg?1737086183" }, "amount": "100023", "minAmountOut": "99022", "priceInUsd": 0.999872, "valueInUsd": 0.1000101971 }, "estimatedTime": 1, "slippage": 1, "suggestedSlippage": 1, "routeTags": [ "FASTEST", "MAX_OUTPUT", "SUGGESTED" ], "routeDetails": { "dexDetails": { "protocol": { "name": "zeroxv2", "displayName": "0x", "icon": "https://media.socket.tech/dexes/zerox.svg" }, "inputTokenAddress": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "outputTokenAddress": "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9", "amountIn": "100000", "amountOut": "100023", "minAmountOut": "99022", "slippage": 1 }, "bridgeDetails": null, "feeDetails": null }, "approval": { "spenderAddress": "0x0000000000001fF3684f28c67538d4D072C22734", "amount": "100000", "tokenAddress": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "userAddress": "0x3e8cb4bd04d81498ab4b94a392c334f5328b237b" }, "txData": { "kind": "evm_tx", "object": { "chainId": 42161, "to": "0x0000000000001fF3684f28c67538d4D072C22734", "data": "0x2213bc0b...", "value": "0" } }, "gasFee": { "gasToken": { "chainId": 42161, "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "name": "Arbitrum Ether", "symbol": "ETH", "decimals": 18, "logoURI": "https://media.socket.tech/networks/ethereum.svg", "icon": "https://media.socket.tech/networks/ethereum.svg" }, "gasLimit": "237034", "gasPrice": "20066000", "estimatedFee": "4756324244000", "feeInUsd": 0.0079402077 }, "statusCheck": { "endpoint": "https://public-backend.socket.tech/v3/swap/status?quoteId=0x759a82929538535f6186da129b49e42f3fa22539cde911a2f394bf9d1e3732b4", "method": "GET", "intervalSec": 5, "maxDurationSec": 600 } } ] }, "message": null } } } } } } }, "summary": "Get quotes", "tags": [ "Swap" ] } }, "/v3/swap/status": { "get": { "operationId": "V3SwapController_status", "parameters": [ { "name": "quoteId", "required": false, "in": "query", "description": "Quote ID returned by /v3/swap/quote.", "schema": { "example": "0x6bfa9f6a45f1a0d5a7a71a4f4f97d9a7", "type": "string", "default": "0x6bfa9f6a45f1a0d5a7a71a4f4f97d9a7" } }, { "name": "srcTxHash", "required": false, "in": "query", "description": "Source transaction hash for direct-route status lookup. Does not resolve deposit routes.", "schema": { "type": "string" } }, { "name": "includeQuoteDetails", "required": false, "in": "query", "description": "Whether to include stored quote row details in the response.", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "V3 swap route status.", "content": { "application/json": { "examples": { "pendingTx": { "summary": "Pending tx route", "value": { "success": true, "statusCode": 200, "result": { "quoteId": "0x759a82929538535f6186da129b49e42f3fa22539cde911a2f394bf9d1e3732b4", "userOp": "tx", "status": "PENDING", "statusCode": "PENDING", "origin": { "chainId": 42161, "status": "PENDING", "txHash": null, "timestamp": null, "userAddress": "0x3e8cb4bd04d81498ab4b94a392c334f5328b237b", "input": [ { "token": { "chainId": 42161, "address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "name": "USDC", "symbol": "USDC", "decimals": 6, "logoURI": "https://assets.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "icon": "https://assets.coingecko.com/coins/images/6319/large/USDC.png?1769615602" }, "amount": "100000", "priceInUsd": 1, "valueInUsd": 0.1 } ] }, "destination": { "chainId": 42161, "status": "PENDING", "txHash": null, "timestamp": null, "receiverAddress": "0x3e8cb4bd04d81498ab4b94a392c334f5328b237b", "output": [ { "token": { "chainId": 42161, "address": "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9", "name": "USDT0", "symbol": "USDT0", "decimals": 6, "logoURI": "https://assets.coingecko.com/coins/images/53705/large/usdt0.jpg?1737086183", "icon": "https://assets.coingecko.com/coins/images/53705/large/usdt0.jpg?1737086183" }, "amount": "100023", "minAmountOut": "100023", "priceInUsd": 0.999872, "valueInUsd": 0.1000101971 } ] }, "routeDetails": { "name": "0x", "logoURI": "https://media.socket.tech/dexes/zerox.svg" }, "refund": null }, "message": null } } } } } } }, "summary": "Get status", "tags": [ "Swap" ] } }, "/v3/swap/supported-chains": { "get": { "operationId": "V3SwapMetadataController_supportedChains", "parameters": [], "responses": { "200": { "description": "Supported chains and providers for v3 swap.", "content": { "application/json": { "examples": { "supportedChains": { "summary": "Supported chains", "value": { "success": true, "statusCode": 200, "result": [ { "chainId": 42161, "name": "Arbitrum", "icon": "https://media.socket.tech/networks/arbitrum.svg", "currency": { "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "name": "Arbitrum Ether", "symbol": "ETH", "decimals": 18, "icon": "https://media.socket.tech/networks/ethereum.svg", "minNativeCurrencyForGas": "900000000000000" }, "explorers": [ "https://arbiscan.io" ], "sendingEnabled": true, "receivingEnabled": true, "isAutoEnabled": true, "isManualEnabled": true, "isDepositEnabled": true, "dexes": [ "zeroxv2", "openocean", "kyberswap" ], "bridges": [ "across", "relay", "cctp-v2-slow" ] } ], "message": null } } } } } } }, "summary": "Get supported chains", "tags": [ "Supported Chains & Token List" ] } }, "/v3/swap/tokens/list": { "get": { "operationId": "V3SwapMetadataController_tokenList", "parameters": [ { "name": "userAddress", "required": false, "in": "query", "description": "User wallet address", "schema": { "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "type": "string", "default": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } }, { "name": "chainIds", "required": false, "in": "query", "description": "Comma-separated chain IDs to include.", "schema": { "example": "42161,8453", "type": "string", "default": "42161,8453" } }, { "name": "list", "required": false, "in": "query", "description": "Set the list type you want: full or trending", "schema": { "default": "trending", "example": "trending", "type": "string", "enum": [ "full", "trending" ] } } ], "responses": { "200": { "description": "V3 swap tokens grouped by chain ID.", "content": { "application/json": { "examples": { "tokenList": { "summary": "Token list", "value": { "success": true, "statusCode": 200, "result": { "8453": [ { "chainId": 8453, "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "name": "USDC", "symbol": "USDC", "decimals": 6, "logoURI": "https://assets.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "isShortListed": false, "tags": [], "trendingRank": 4, "marketCap": 75987436982, "totalVolume": 14895044788, "balance": "0", "balanceInUsd": 0, "isVerified": true } ], "42161": [ { "chainId": 42161, "address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "name": "USDC", "symbol": "USDC", "decimals": 6, "logoURI": "https://assets.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "icon": "https://assets.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "isShortListed": false, "tags": [], "trendingRank": 4, "marketCap": 75987436982, "totalVolume": 14895044788, "balance": "0", "balanceInUsd": 0, "isVerified": true } ] }, "message": null } } } } } } }, "summary": "Get token list", "tags": [ "Supported Chains & Token List" ] } }, "/v3/swap/tokens/search": { "get": { "operationId": "V3SwapMetadataController_searchToken", "parameters": [ { "name": "q", "required": true, "in": "query", "description": "Search query for token address, name or symbol. Does partial matching too", "schema": { "example": "ETH", "type": "string", "default": "ETH" } }, { "name": "userAddress", "required": false, "in": "query", "description": "User wallet address", "schema": { "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "type": "string", "default": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } }, { "name": "address", "required": false, "in": "query", "description": "Alias for userAddress. Kept for clients that pass the wallet address as address.", "schema": { "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "type": "string", "default": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } } ], "responses": { "200": { "description": "V3 swap token search results grouped by chain ID.", "content": { "application/json": { "examples": { "tokenSearch": { "summary": "Token search", "value": { "success": true, "statusCode": 200, "result": { "tokens": { "8453": [ { "chainId": 8453, "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "name": "USDC", "symbol": "USDC", "decimals": 6, "logoURI": "https://assets.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "isShortListed": false, "tags": [], "trendingRank": 4, "marketCap": 75987436982, "totalVolume": 14895044788, "balance": "0", "balanceInUsd": 0, "isVerified": true } ], "42161": [ { "chainId": 42161, "address": "0xaf88d065e77c8cc2239327c5edb3a432268e5831", "name": "USDC", "symbol": "USDC", "decimals": 6, "logoURI": "https://assets.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "icon": "https://assets.coingecko.com/coins/images/6319/large/USDC.png?1769615602", "isShortListed": false, "tags": [], "trendingRank": 4, "marketCap": 75987436982, "totalVolume": 14895044788, "balance": "0", "balanceInUsd": 0, "isVerified": true } ] } }, "message": null } } } } } } }, "summary": "Search tokens", "tags": [ "Supported Chains & Token List" ] } } }, "info": { "title": "Socket V3 Swap API Explorer", "description": "V3 swap quote, status, and metadata endpoints", "version": "1.0", "contact": {} }, "tags": [], "servers": [ { "url": "https://public-backend.socket.tech", "description": "Production" } ], "components": { "schemas": { "SuccessResponseDto": { "type": "object", "properties": { "success": { "type": "boolean", "description": "flag indicating whether the req was successful", "default": true }, "statusCode": { "type": "number", "description": "Http status code", "default": 200 }, "message": { "type": "string", "description": "error message if request failed", "nullable": true } }, "required": [ "success", "statusCode" ] } } } }