Same-chain swaps

When both tokens are on the same chain, a swap is one transaction the user sends. Tern finds the best route across DEX aggregators and builds the transaction. The user receives at least the quoted minimum, or the transaction reverts and nothing moves. There’s no secret, no deposit address, and no waiting on a solver. This guide swaps 0.01 ETH for USDC on Base. The Quickstart runs the same flow as a script.

Before you start

The user’s address, which sends the swap and pays the gas.
The user’s wallet, to sign the transaction.
An API key, for production. You can build and test without one.

Get a price

Send the two tokens and the amount. Use native for the chain’s native token.

curl https://api.ternswap.xyz/v1/quote \
  -H "content-type: application/json" \
  -d '{
    "from": { "chain": "base", "asset": "native", "amount": "10000000000000000" },
    "to":   { "chain": "base", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" }
  }'

{
  "route": "swap",
  "from": { "chain": "base", "asset": "native", "amount": "10000000000000000", "usd": "20.49" },
  "to":   { "chain": "base", "asset": "0x8335…2913", "amount": "20501034", "minAmount": "20398528", "usd": "20.49" },
  "expiresAt": 1794404868,
  "fees": { "totalUsd": "0.01", "items": [ { "kind": "protocol", "usd": "0.00" }, { "kind": "network", "usd": "0.01" } ] },
  "priceImpactBps": 0,
  "costBps": 5,
  "etaSecs": 8,
  "sourceGas": { "amount": "3722988000000", "usd": "0.01" }
}

route: "swap" means it happens on one chain.
to.amount is what the user should receive after Tern’s fee, and to.minAmount the least they’ll receive.
fees breaks down the cost: see Fees and pricing.
sourceGas is the gas the user will pay. Include sender in the request and it only counts the approval that address actually needs.
etaSecs is how long the chain takes to confirm.

Wallets set aside extra gas while a transaction is pending. If the user is selling their entire balance of the native token, leave about three times sourceGas unsold.

Get the transaction

When the user confirms, ask again with sender (who sends and pays) and recipient (who receives). You can also set slippageBps: how far below the expected amount the swap may land before it reverts. It’s 50 (0.5%) by default and at most 300 (3%).

curl https://api.ternswap.xyz/v1/quote \
  -H "content-type: application/json" \
  -H "x-api-key: $TERN_API_KEY" \
  -d '{
    "from": { "chain": "base", "asset": "native", "amount": "10000000000000000" },
    "to":   { "chain": "base", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913" },
    "sender": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
    "recipient": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
    "slippageBps": 50
  }'

{
  "id": "q_01M5Y2Z4APRNZWK2FQWZY1GAQ8",
  "route": "swap",
  "from": { "chain": "base", "asset": "native", "amount": "10000000000000000", "usd": "20.49" },
  "to":   { "chain": "base", "asset": "0x8335…2913", "amount": "20501034", "minAmount": "20398528", "usd": "20.49" },
  "expiresAt": 1794404914,
  "execute": {
    "transactions": [
      { "to": "0x294bde9a3c13962fd06a42c123ac56152dd1dd7b", "data": "0x…", "value": "10000000000000000" }
    ]
  }
}

Send it right away

From sender’s wallet:

EVM chains: send execute.transactions in order. An approval comes first when it’s needed, and USDT on Ethereum may get an extra approval of zero before it. When selling the native token, the amount travels as the transaction’s value.
Starknet: send execute.calls together, as a single transaction.

Before the user signs, check that the transactions only approve the token being sold to Tern’s swap contract and then call it. Hard-code its address from Contract addresses.The quote lasts about 60 seconds, because prices move quickly. After expiresAt the contract refuses the swap, so get a new quote rather than sending late.

Track it

GET /v1/quote/{id} shows awaiting_deposit until the transaction confirms, then completed. A swap that isn’t sent in time becomes expired.Both source.txHash and destination.txHash are the swap’s one transaction. source.amount is what it spent and destination.amount is what the user received.

If something goes wrong

What happened	What to do
`422 no_route`	No aggregator has a route for this pair and amount. Try a different amount or pair.
`400 invalid_request`	`detail` says why: for example the same token on both sides, `recipient` without `sender`, or `slippageBps` above 300.
The transaction reverts	The swap would have delivered less than the minimum, or the quote expired. Nothing moved except gas. Get a new quote.
Status `expired`	The swap wasn’t sent in time. Get a new quote.

How it differs from a cross-chain swap

No secret, no reveal step, and no deposit address: only sender can send the swap.
If the minimum can’t be met, the transaction reverts and nothing moves. There’s never a refund to wait for.
The quote lasts about a minute, not 30 minutes.

Get started

Concepts

Guides

Protocol

Same-chain swaps

Before you start

If something goes wrong

How it differs from a cross-chain swap

Next steps

Private swaps

TernSwap

​Before you start

​If something goes wrong

​How it differs from a cross-chain swap

​Next steps

Private swaps

TernSwap

Before you start

If something goes wrong

How it differs from a cross-chain swap

Next steps