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 Earn Account for another, in a single atomic transaction.

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.

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%).

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). Firm-priced builds may be sponsored: the sponsor must broadcast before quote_expires_at.

Example:

false

pricing
enum<string>
default:auto

Swap routing policy. 'auto': on chains with a market route the swap is priced by the market aggregator and bounded by slippage (the default behaviour); on HyperEVM, where only firm pricing is available, it is a firm zero-slippage quote that fills exactly or reverts. 'firm': always a firm quote; refused with a typed 409 when no firm quote covers the pair right now, never silently priced at market. 'market': always the market route; refused with 422 on HyperEVM. Read swap_provider on the response for the route that actually priced the build, and quote_expires_at for a firm quote's deadline.

Available options:
auto,
firm,
market
Example:

"auto"

Response

Successful Response

estimated_amount_out
string
required

Estimated amount of output token received from the swap. Exact on firm builds (a firm quote fills at this amount or reverts); a quote-time estimate on market builds, where slippage sets how far below it the enforced minimum output sits.

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

Unsigned transaction for direct execution. Present when gas_sponsorship=false.

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

Which route priced the swap. 'market': a DEX aggregator, slippage-bounded. 'firm': a zero-slippage quote that fills exactly or reverts. Always present; this is the authoritative signal, since pricing is only what was requested.

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

Deadline of the firm swap quote. The transaction (or the sponsor's broadcast of the signed typed data) must be included before it or the swap reverts on-chain; refresh by re-calling this endpoint and discarding the previous payload. Null on market builds.