{"openapi":"3.0.3","info":{"title":"ChainBridge Trading API","version":"1.0.0","description":"Non-custodial DEX aggregator API. Compares 0x (including 0x Gasless), KyberSwap and ParaSwap on Ethereum, Arbitrum, Base, Optimism, Polygon, BNB Chain, Avalanche and Linea; quotes cross-chain swaps via Relay, LI.FI and THORChain (to native BTC, LTC, DOGE, BCH); bridge quotes via LI.FI and Socket. No API key; rate limited per IP. Fee schedule: https://www.chainbridge.trading/about#fees","contact":{"name":"ChainBridge Trading"}},"servers":[{"url":"/api","description":"Local API"}],"tags":[{"name":"SOR","description":"Smart Order Router — swap quotes and execution"},{"name":"Cross-chain","description":"Cross-chain swap quotes and status (Relay, LI.FI, THORChain)"},{"name":"Bridge","description":"Cross-chain bridge quotes, transactions, and status (LI.FI, Socket; API only)"},{"name":"Price","description":"Token USD pricing via CoinGecko"},{"name":"Security","description":"Token safety checks via GoPlus Security"},{"name":"Gasless","description":"Gasless swap submission and status (0x gasless)"},{"name":"Simulation","description":"Pre-swap transaction simulation (Tenderly)"},{"name":"SSE","description":"Server-Sent Events for real-time data"}],"paths":{"/sor/quotes":{"get":{"tags":["SOR"],"summary":"Get swap quotes from all aggregators","description":"Queries 0x (including 0x Gasless), KyberSwap and ParaSwap in parallel (Linea: 0x and KyberSwap) and returns quotes ranked by amount received after gas, with the platform fee included and reported as feeBps.","parameters":[{"name":"chainId","in":"query","required":true,"schema":{"type":"integer","enum":[1,10,42161,8453,137,56,43114,59144]},"description":"Chain ID"},{"name":"sellToken","in":"query","required":true,"schema":{"type":"string"},"description":"Sell token address (0x...)"},{"name":"buyToken","in":"query","required":true,"schema":{"type":"string"},"description":"Buy token address (0x...)"},{"name":"sellAmount","in":"query","required":true,"schema":{"type":"string"},"description":"Sell amount in wei"},{"name":"takerAddress","in":"query","schema":{"type":"string"},"description":"Taker wallet address"},{"name":"slippageBps","in":"query","schema":{"type":"integer","default":100},"description":"Slippage in basis points (100 = 1%)"},{"name":"aggregators","in":"query","schema":{"type":"string"},"description":"Comma-separated aggregator IDs to query"}],"responses":{"200":{"description":"Quotes retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SORQuotesResponse"}}}},"400":{"description":"Validation error"},"500":{"description":"Server error"}}}},"/sor/swap":{"post":{"tags":["SOR"],"summary":"Get swap transaction data","description":"Returns executable calldata. With preferredAggregator + strictAggregator=true the quote comes from that aggregator only (502 if unavailable) so the executed route matches the displayed one; otherwise all sources are ranked by amount received after gas and fees.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sellToken","buyToken","sellAmount","chainId","takerAddress"],"properties":{"preferredAggregator":{"type":"string","enum":["0x","0x-gasless","paraswap","kyber","1inch","uniswapx","balancer","thorchain","cow","openocean","lifi"],"description":"Live by default: 0x, 0x-gasless, paraswap, kyber. lifi only on deployments with a LI.FI API key; the others are disabled and return no quote."},"strictAggregator":{"type":"boolean","default":false},"sellToken":{"type":"string"},"buyToken":{"type":"string"},"sellAmount":{"type":"string"},"sellTokenDecimals":{"type":"integer"},"buyTokenDecimals":{"type":"integer"},"chainId":{"type":"integer"},"takerAddress":{"type":"string"},"slippageBps":{"type":"integer","default":100},"feeRecipient":{"type":"string","description":"Allowlisted partner address"},"feeBps":{"type":"integer","maximum":300}}}}}},"responses":{"200":{"description":"Swap transaction data"},"400":{"description":"Validation error"}}}},"/sor/aggregators":{"get":{"tags":["SOR"],"summary":"List available aggregators","parameters":[{"name":"chainId","in":"query","schema":{"type":"integer"},"description":"Filter by chain ID"}],"responses":{"200":{"description":"List of aggregator configurations"}}}},"/sor/order-status":{"get":{"tags":["SOR"],"summary":"Check UniswapX order fill status (UniswapX is disabled by default)","parameters":[{"name":"orderHash","in":"query","required":true,"schema":{"type":"string"}},{"name":"chainId","in":"query","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Order status"}}}},"/crosschain/quote":{"get":{"tags":["Cross-chain"],"summary":"Get cross-chain swap quotes","description":"Quotes Relay, LI.FI and THORChain in parallel, ranked by net amount received. EVM to EVM via Relay and LI.FI; EVM (Ethereum, Base, BNB Chain, Avalanche) to native BTC, LTC, DOGE or BCH via THORChain; native BTC, LTC, DOGE or BCH to EVM is quote only (executable: false). Each quote lists the steps to sign (exact-amount approval when needed) and any ChainBridge fee as platformFeeBps. Provide exactly one of fromChainId/fromChain and one of toChainId/toChain.","parameters":[{"name":"fromChainId","in":"query","schema":{"type":"integer","enum":[1,42161,8453,10,137,56,43114,59144,324]},"description":"EVM source chain"},{"name":"fromChain","in":"query","schema":{"type":"string","enum":["BTC","LTC","DOGE","BCH"]},"description":"Native source chain (quote only)"},{"name":"toChainId","in":"query","schema":{"type":"integer","enum":[1,42161,8453,10,137,56,43114,59144,324]},"description":"EVM destination chain"},{"name":"toChain","in":"query","schema":{"type":"string","enum":["BTC","LTC","DOGE","BCH"]},"description":"Native destination chain (THORChain)"},{"name":"fromToken","in":"query","required":true,"schema":{"type":"string"},"description":"Source token address"},{"name":"toToken","in":"query","schema":{"type":"string"},"description":"Destination token address (EVM destinations)"},{"name":"fromTokenDecimals","in":"query","required":true,"schema":{"type":"integer"}},{"name":"toTokenDecimals","in":"query","required":true,"schema":{"type":"integer"}},{"name":"amount","in":"query","required":true,"schema":{"type":"string"},"description":"Amount in the smallest unit of the source token"},{"name":"fromAddress","in":"query","schema":{"type":"string"},"description":"Sender wallet (required for EVM sources)"},{"name":"toAddress","in":"query","schema":{"type":"string"},"description":"Recipient; a BTC/LTC/DOGE/BCH address for native destinations"},{"name":"slippageBps","in":"query","schema":{"type":"integer","default":100}},{"name":"providers","in":"query","schema":{"type":"string"},"description":"Comma-separated subset of relay, lifi, thorchain"}],"responses":{"200":{"description":"Quotes ranked by net received, best quote and per-provider errors"},"400":{"description":"Validation error"},"502":{"description":"Upstream failure"}}}},"/crosschain/status":{"get":{"tags":["Cross-chain"],"summary":"Get cross-chain delivery status","parameters":[{"name":"provider","in":"query","required":true,"schema":{"type":"string","enum":["relay","lifi","thorchain"]}},{"name":"srcTxHash","in":"query","required":true,"schema":{"type":"string"}},{"name":"fromChainId","in":"query","required":true,"schema":{"type":"integer"}},{"name":"requestId","in":"query","schema":{"type":"string"},"description":"Required for Relay"},{"name":"toChain","in":"query","schema":{"type":"string","enum":["BTC","LTC","DOGE","BCH"]},"description":"THORChain native destination"},{"name":"toChainId","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Normalized delivery status"},"400":{"description":"Validation error"}}}},"/thorchain/quote":{"get":{"tags":["Cross-chain"],"summary":"Get a raw THORChain quote","description":"Quote only, with a 0.3% affiliate fee included. For executable cross-chain swaps use /crosschain/quote.","parameters":[{"name":"fromAsset","in":"query","required":true,"schema":{"type":"string"},"description":"e.g. ETH.ETH"},{"name":"toAsset","in":"query","required":true,"schema":{"type":"string"},"description":"e.g. BTC.BTC"},{"name":"amount","in":"query","required":true,"schema":{"type":"string"},"description":"Amount in 1e8 units"}],"responses":{"200":{"description":"THORChain quote"},"400":{"description":"Validation error"}}}},"/bridge/quote":{"get":{"tags":["Bridge"],"summary":"Get cross-chain bridge quotes","parameters":[{"name":"fromChainId","in":"query","required":true,"schema":{"type":"integer"}},{"name":"toChainId","in":"query","required":true,"schema":{"type":"integer"}},{"name":"fromToken","in":"query","required":true,"schema":{"type":"string"}},{"name":"toToken","in":"query","required":true,"schema":{"type":"string"}},{"name":"fromAmount","in":"query","required":true,"schema":{"type":"string"}},{"name":"fromAddress","in":"query","required":true,"schema":{"type":"string"}},{"name":"slippageBps","in":"query","schema":{"type":"integer","default":100}},{"name":"providers","in":"query","schema":{"type":"string"},"description":"Comma-separated: lifi,socket"},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["output","time","fees"]}}],"responses":{"200":{"description":"Bridge routes and best route"},"400":{"description":"Validation error"}}}},"/bridge/transaction":{"post":{"tags":["Bridge"],"summary":"Get bridge transaction data","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["provider","routeId","fromAddress"],"properties":{"provider":{"type":"string","enum":["lifi","socket"]},"routeId":{"type":"string"},"fromAddress":{"type":"string"}}}}}},"responses":{"200":{"description":"Transaction data for bridge"}}}},"/bridge/status":{"get":{"tags":["Bridge"],"summary":"Check bridge transaction status","parameters":[{"name":"provider","in":"query","required":true,"schema":{"type":"string"}},{"name":"txHash","in":"query","required":true,"schema":{"type":"string"}},{"name":"fromChainId","in":"query","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Bridge status (pending, completed, failed)"}}}},"/bridge/chains":{"get":{"tags":["Bridge"],"summary":"List supported bridge chains","responses":{"200":{"description":"Supported chains with metadata"}}}},"/price":{"get":{"tags":["Price"],"summary":"Get USD prices for tokens","parameters":[{"name":"chainId","in":"query","required":true,"schema":{"type":"integer"}},{"name":"tokens","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated token addresses (max 100)"}],"responses":{"200":{"description":"Token prices in USD"},"400":{"description":"Validation error"}}}},"/token-safety":{"get":{"tags":["Security"],"summary":"Token safety verdicts (honeypot, taxes, risky permissions)","description":"GoPlus Security checks normalized to safe | caution | danger | unknown. Curated tokens are safe without a lookup; results are cached 6h. Fails open: upstream errors return level unknown with status 200.","parameters":[{"name":"chainId","in":"query","required":true,"schema":{"type":"integer","enum":[1,10,56,137,324,8453,42161,43114,59144]}},{"name":"addresses","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated token addresses (max 20)"}],"responses":{"200":{"description":"Verdicts keyed by lowercase address","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"chainId":{"type":"integer"},"tokens":{"type":"object","additionalProperties":{"type":"object","properties":{"level":{"type":"string","enum":["safe","caution","danger","unknown"]},"reasons":{"type":"array","items":{"type":"string"}},"buyTax":{"type":"number","nullable":true,"description":"Fraction (0.05 = 5%)"},"sellTax":{"type":"number","nullable":true,"description":"Fraction (0.05 = 5%)"}}}}}}}}}}},"400":{"description":"Validation error"},"429":{"description":"Rate limited"}}}},"/gasless/submit":{"post":{"tags":["Gasless"],"summary":"Submit gasless swap order","description":"Submits a signed gasless order (0x gasless; UniswapX is disabled by default) for execution.","responses":{"200":{"description":"Order submitted"}}}},"/gasless/status":{"get":{"tags":["Gasless"],"summary":"Check gasless order status","parameters":[{"name":"tradeHash","in":"query","required":true,"schema":{"type":"string"}},{"name":"chainId","in":"query","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Gasless order status"}}}},"/simulation":{"post":{"tags":["Simulation"],"summary":"Simulate swap transaction","description":"Uses Tenderly to simulate a transaction before execution. Detects reverts and shows expected balance changes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chainId","from","to","data"],"properties":{"chainId":{"type":"integer"},"from":{"type":"string"},"to":{"type":"string"},"data":{"type":"string"},"value":{"type":"string","default":"0"},"gas":{"type":"integer"}}}}}},"responses":{"200":{"description":"Simulation result with balance changes"},"400":{"description":"Validation error"}}}},"/price/stream":{"get":{"tags":["SSE"],"summary":"Real-time price stream (SSE)","description":"Server-Sent Events endpoint for live token price updates.","parameters":[{"name":"chainId","in":"query","required":true,"schema":{"type":"integer"}},{"name":"tokens","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated (max 20)"},{"name":"interval","in":"query","schema":{"type":"integer","default":5000},"description":"Update interval in ms (min 2000)"}],"responses":{"200":{"description":"SSE stream (text/event-stream)"}}}},"/bridge/status/stream":{"get":{"tags":["SSE"],"summary":"Bridge status stream (SSE)","parameters":[{"name":"provider","in":"query","required":true,"schema":{"type":"string"}},{"name":"txHash","in":"query","required":true,"schema":{"type":"string"}},{"name":"fromChainId","in":"query","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"SSE stream with bridge status updates"}}}},"/gasless/status/stream":{"get":{"tags":["SSE"],"summary":"Gasless order status stream (SSE)","parameters":[{"name":"tradeHash","in":"query","required":true,"schema":{"type":"string"}},{"name":"chainId","in":"query","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"SSE stream with order status updates"}}}},"/trade/recent-swaps":{"get":{"tags":["SOR"],"summary":"Get recent swaps for a pair","responses":{"200":{"description":"Recent swap trades"}}}}},"components":{"schemas":{"SORQuotesResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"request":{"type":"object"},"quotes":{"type":"array","items":{"$ref":"#/components/schemas/AggregatorQuote"}},"bestQuote":{"$ref":"#/components/schemas/AggregatorQuote"},"feeBps":{"type":"integer","description":"Fee due on this trade"},"stats":{"type":"object","properties":{"totalAggregators":{"type":"integer"},"successfulQuotes":{"type":"integer"},"timestamp":{"type":"integer"}}}}}}},"AggregatorQuote":{"type":"object","properties":{"aggregator":{"type":"string"},"buyAmount":{"type":"string","description":"Expected output in buy-token wei, net of the platform fee"},"sellAmount":{"type":"string"},"price":{"type":"string"},"gasCostUSD":{"type":"string"},"netBuyAmount":{"type":"string","description":"buyAmount minus estimated gas, in buy-token wei (ranking value)"},"feeBps":{"type":"integer","description":"Fee actually applied by this source (0 for fee-less sources)"},"collectsFees":{"type":"boolean"},"allowanceTarget":{"type":"string","description":"Spender to approve (exact amount)"},"error":{"type":"string","nullable":true}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"},"code":{"type":"string"}}}}}}