v1

latestOpenAPI 3.1.02026-07-243035381.4 MB

DeFi API

Get best swap rate

/v4/data/defi/swaps/quote

20 credits per API call

Get the single best swap rate across all supported protocols. Compares all protocols and returns the one with the best price: sell orders — highest buyAmount, buy orders — lowest sellAmount. Use this when you just want the best deal without thinking about protocols. For comparing all options, use GET /swaps/quotes instead. **Quotes are cached for up to 15 seconds** (less than one Ethereum block). Each response includes an `expiresAt` field (Unix timestamp) indicating when the underlying quote was originally fetched from the protocol. Always check `expiresAt` against the current time before displaying or acting on a quote — if less than ~10 seconds remain, re-query to get a fresh price.

get/v4/data/defi/swaps/quote

Query parameters

sellTokenstring required

ERC-20 token contract address to sell.

buyTokenstring required

ERC-20 token contract address to buy.

amountstring required

Fixed-side amount in base units. sell order: exact amount of sellToken to spend. buy order: exact amount of buyToken to receive.

fromAddressstring required

Wallet address initiating the swap. Used for CoW fee estimation.

Tatum network slug (e.g. ethereum-mainnet, bsc-mainnet, polygon-mainnet). Matches the networks[].id field in https://blockchains.tatum.io/blockchains2.json.

kind'sell' | 'buy'

Whether this is exact-input (sell) or exact-output (buy).

slippageBpsnumber

Slippage tolerance in basis points (1 bps = 0.01%). Applied to the quoted amount to compute limitAmount.

Response

sellTokenstring required

buyTokenstring required

sellAmountstring required

buyAmountstring required

Best-case expected output (sell orders) or required input (buy orders).

kind'sell' | 'buy' required

Whether this is an exact-input (sell) or exact-output (buy) rate.

estimatedSettlementSecondsnumber required

Estimated time until the swap is settled, in seconds (not minutes). Uniswap / PancakeSwap: ~12-15 s (one Ethereum block — near-instant). CoW Protocol: ≥30 s (one batch auction cycle; illiquid pairs may take longer).

limitAmountstring required

Guaranteed limit amount after applying slippage tolerance. sell order: minimum buyToken output (minBuyAmount) — higher is better. buy order: maximum sellToken input (maxSellAmount) — lower is better.

feestring required

Protocol-level fee in sellToken units. CoW Protocol: the fee amount extracted by solvers from the order surplus. Uniswap / PancakeSwap: always '0' — LP fees are embedded in the quoted amounts (amountOut already reflects the pool fee tier). The pool fee tier is available in payload.protocolData.poolFee.

expiresAtnumber required

Unix timestamp — how long this quote / order is valid. After this time, CoW orders expire and DEX quotes become stale.

protocolstring required

executionModel'instant' | 'batch-auction' required

How this protocol executes swaps.

instant: atomic on-chain tx — guaranteed price (within slippage) or revert
batch-auction: off-chain order book — solver fills within limit price, may take minutes
cross-chain: bridge + swap — settlement depends on destination chain finality

mevProtectedboolean required

Whether this protocol is MEV-protected by design. CoW Protocol: true — batch auction with delegated execution means your intent never enters the public mempool, making sandwich attacks impossible. AMM protocols (Uniswap, PancakeSwap): false — transactions enter the public mempool and are vulnerable without additional measures.