Track a swap

Every firm quote has a status you can check at GET /v1/quote/{id}. Check it until the swap is done, or have changes sent to you with webhooks. What each status means is in Quotes and statuses.

Check the status

curl https://api.ternswap.xyz/v1/quote/q_01JB8Z5W3F6V9Q2X4K7M1N0P8R

{
  "id": "q_01JB8Z5W3F6V9Q2X4K7M1N0P8R",
  "status": "completed",
  "createdAt": 1793084030,
  "expiresAt": 1793085830,
  "depositAddress": "0x3c1f0e0a9b7d6c5e4f3a2b1c0d9e8f7a6b5c4d3e",
  "source":      { "chain": "base", "asset": "0x8335…2913", "amount": "100000000", "usd": "100.00", "txHash": "0x9a1e…40c2" },
  "destination": { "chain": "starknet", "asset": "0x0330…35fb", "amount": "99880000", "usd": "99.88", "txHash": "0x05d2…7b19" },
  "fees": { "totalUsd": "0.13", "items": [ { "kind": "network", "usd": "0.06" }, { "kind": "solver", "usd": "0.07" } ] },
  "costBps": 13,
  "etaSecs": 40,
  "sourceConfirmedAt": 1793084112,
  "destinationSeenAt": 1793084139
}

Field	What it tells you
`status`	Where the swap stands. `completed`, `refunded`, and `expired` are final.
`source.txHash`	The user’s deposit, or the swap’s transaction on a single chain.
`source.refundTxHash`	The transaction that returned the deposit, if the swap was refunded.
`destination.txHash`	The transaction that paid the user. On a single chain, it’s the same as `source.txHash`.
`source.amount`, `destination.amount`	The quoted amounts at first, then the actual amounts once the transactions are seen.
`expiresAt`, `depositAddress`	The same as in the firm quote, so you can still show the deadline and the deposit address after a page reload.
`fees`, `costBps`, `etaSecs`	The numbers from when it was quoted. See Fees and pricing.
`sourceConfirmedAt`, `destinationSeenAt`	Cross-chain only: when the deposit was confirmed, and when the solver’s tokens were first seen, as Unix times.

How often to check: every 2 to 5 seconds while the user is watching, and stop once the status is final. etaSecs gives a rough idea of how long it’ll take. If you’re tracking many swaps at once, use webhooks instead: every check counts toward your rate limit.

Get updates sooner

Tern finds every deposit and swap on its own. If you send a transaction’s hash as soon as it’s mined, the status updates a little sooner:

curl https://api.ternswap.xyz/v1/index \
  -H "content-type: application/json" \
  -d '{ "chain": "base", "txHash": "0x9a1e…40c2" }'

Tern answers 202 Accepted with an empty body. See POST /v1/index.

Show a user’s swap history

GET /v1/quotes finds firm quotes, newest first. Search by one of:

address: swaps that address sent or received;
txHash: the swap a transaction belongs to, whether it’s a deposit, a payment, a refund, or a same-chain swap.

curl "https://api.ternswap.xyz/v1/quotes?address=0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266&limit=20"

{
  "quotes": [ { "id": "q_01JB8Z5W3F6V9Q2X4K7M1N0P8R", "status": "completed", "…": "…" } ],
  "next": "q_01JB7T2K9D4C8B6A5Z3Y1X0W9V"
}

Each result has the same fields as a status. You get 20 results by default and up to 100 with limit. For the next page, pass next as before. The last page has no next. Private swaps don’t name any address, so searching by address won’t find them. Keep their quote IDs yourself.

Measure how fast swaps fill

On a cross-chain swap, destinationSeenAt minus sourceConfirmedAt is how long the solver took to lock the user’s tokens once the deposit was confirmed. Each time appears once that step has happened.

Get started

Concepts

Guides

Protocol

Track a swap

Check the status

Get updates sooner

Show a user’s swap history

Measure how fast swaps fill

​Check the status

​Get updates sooner

​Show a user’s swap history

​Measure how fast swaps fill

Check the status

Get updates sooner

Show a user’s swap history

Measure how fast swaps fill