Skip to main content
POST
Python (SDK)

Authorizations

x-api-key
string
header
required

Your Compass API Key. Get your key here.

Body

application/json

Swap one token held in the Credit Account for another, in a single atomic transaction, at a firm quote where one covers the pair and at market rate otherwise.

token_in
string
default:USDC
required

Token to sell (input). Provide a token symbol from a limited set (e.g., 'USDC') or any token address.

Examples:

"USDC"

"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"

token_out
string
default:USDT
required

Token to buy (output). Provide a token symbol from a limited set (e.g., 'USDT') or any token address.

Examples:

"USDT"

"0xdAC17F958D2ee523a2206206994597C13D831ec7"

amount_in
default:0.01
required

Human-readable amount of token_in to swap (token units, not wei).

Required range: x > 0
Example:

1.5

owner
string
default:0x06A9aF046187895AcFc7258450B15397CAc67400
required

The owner's wallet address. Their Credit Account must already exist (create it with /v2/credit/create_account) and hold token_in (deposit with /v2/credit/transfer).

Example:

"0x06A9aF046187895AcFc7258450B15397CAc67400"

chain
enum<string>
default:base
required

Target blockchain network where the swap will execute.

Available options:
arbitrum,
base,
bsc,
ethereum,
hyperevm,
tempo
Example:

"base"

action_type
string
default:V2_SWAP

Action type identifier for swap operations.

Allowed value: "V2_SWAP"
slippage
default:0.5

Maximum slippage tolerance as a percentage (e.g., 0.5 = 0.5%). Bounds the market route only; a firm quote fills exactly and ignores it.

Required range: 0 <= x <= 10
Example:

0.5

gas_sponsorship
boolean
default:false

Optionally request gas sponsorship. If true, EIP-712 typed data will be returned that must be signed by the owner and submitted to the 'Prepare gas-sponsored transaction' endpoint (/gas_sponsorship/prepare). Gas-sponsored builds always execute at market rate.

Example:

false

preview
boolean
default:false

If true, build a display ESTIMATE: no firm RFQ quote is ever requested (quote_expires_at stays null). NOTE that this guarantees only that no firm quote was spent — it does not guarantee an absent payload: under 'auto' when the firm provider does not cover or cannot currently price the pair, and always under pricing=market, the call falls through to the aggregator and returns a signable market build (an unsigned transaction, or EIP-712 typed data when gas_sponsorship=true), without requiring the account to hold token_in yet. How the estimate is priced follows pricing: on a firm-covered pair whose size the firm provider's live price levels can serve, 'auto' and 'firm' price it from those levels (indicative, transaction stays null — re-call with preview=false for the signable build); otherwise it comes from the market build above (pricing='firm' instead refuses with a typed error). Set it on every call made while a user is exploring parameters, and leave it false only for the build they actually intend to sign — firm quotes are single-use maker commitments, and requesting them for displays that are never executed degrades the pricing this API is offered.

pricing
enum<string>
default:auto

Swap routing policy. 'auto': a firm zero-slippage quote when a firm venue covers the pair, transparent fallback to the market aggregator otherwise. 'firm': never price on the market route; an uncovered pair fails with a typed error instead of silently substituting market pricing — previews included: a preview the firm provider's live price levels cannot price returns the same typed error rather than market numbers. 'market': never route through the firm venue; the swap is priced by the aggregator and bounded by slippage (which firm fills ignore). 'firm' is incompatible with gas_sponsorship (sponsored swaps force market routing).

Available options:
auto,
firm,
market
Example:

"auto"

Response

Successful Response

The swap transaction to sign, plus which route priced it and how long that price holds.

estimated_amount_out
string
required

Estimated amount of output token received from the swap. Exact on executable firm builds (a firm quote fills at this amount or reverts). On market builds it is a quote-time estimate, and slippage sets how far below it the transaction's enforced minimum output sits. On preview=true responses reporting 'firm' it is INDICATIVE — computed from the firm provider's live price levels without spending a quote.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
transaction
UnsignedTransaction · object | null

Unsigned transaction for direct execution. Present when gas_sponsorship=false — except firm-priced previews (preview=true responses reporting swap_provider='firm'), which carry the estimate only: the firm quote is fetched at execution time, so there is no payload to sign yet. A preview whose response reports swap_provider='market' does carry this signable payload.

Example:
eip_712
BatchedSafeOperationsResponse · object | null

EIP-712 typed data for gas-sponsored execution. Present when gas_sponsorship=true.

Example:
swap_provider
enum<string>
default:market

Identifies which route priced the swap. 'market': a DEX aggregator, slippage-bounded. 'firm': a zero-slippage quote that fills exactly or reverts. On preview=true responses 'firm' means the estimate is INDICATIVE, computed from live maker price levels without spending any quote; execution fetches the firm quote at signing time. Always present. This is the authoritative firm-vs-market signal and clients do need to read it: pricing is only what was REQUESTED, and under 'auto' a firm build can fall back to market transparently.

Available options:
market,
firm
quote_expires_at
string<date-time> | null

Deadline of the firm swap quote. Sign and broadcast before it or the transaction reverts on-chain; refresh by re-calling this endpoint (discard the previous payload). Null on market builds and on every preview (a preview never holds a firm quote).