Every swap on Tern is a quote. You ask for a price to show the user, ask again for a firm quote when they confirm, and then follow that quote until the swap is done.

​
Prices and firm quotes

Both come from the same request, POST /v1/quote. What you include decides which one you get. A firm cross-chain quote asks solvers to compete and commit to a price, so request one only when the user confirms. Send an Idempotency-Key with it, so a retried request gets the same quote back instead of a new one.

​
Amounts

  • from.amount: exactly what the user sends.
  • to.amount: what the user should receive.
  • to.minAmount: the least the user will receive, when the quote has one.
Amounts are whole numbers in the token’s smallest unit, sent as strings. For USDC, which has 6 decimals, "1000000" is 1 USDC. Same-chain swaps always have a minimum: below it, the swap reverts. Cross-chain swaps have one when the solver has to buy the destination token as it fills, because that price can move. The solver commits to the minimum and passes on everything its purchase yields, so the user usually gets about to.amount. When a cross-chain quote has no minimum, such as USDC for USDC, to.amount is itself the commitment. slippageBps sets the gap between the expected amount and the minimum, in basis points (1 bps = 0.01%). It’s 50 (0.5%) by default and at most 300 (3%). Show the user both amounts, with the minimum labeled “Minimum received”.

​
Deadlines

Every quote has an expiresAt, a Unix time. What it means depends on the quote: Always read expiresAt from the quote rather than assuming these values. After it passes, get a new quote.

​
Statuses

GET /v1/quote/{id} tells you where a swap stands. A cross-chain swap moves like this: Same-chain and private swaps are a single transaction, so they go straight from awaiting_deposit to completed once it confirms, or to expired if it’s never sent. Stop checking once a status is final. Track a swap shows how to follow statuses in your app, and webhooks can push them to you instead.

Fees and pricing

What a swap costs, line by line.

Refunds

When and how users get their deposit back.