Cross-chain swaps

This guide walks through a swap of 100 USDC on Base for USDC on Starknet, from quote to completion. Your app creates a secret, the user deposits, a solver locks the user’s tokens on Starknet, and your app reveals the secret so the user is paid. How Tern works explains why each step is there.

Before you start

Somewhere to store one secret per swap, encrypted, on your server or in the user’s app. Without the secret, a swap can’t complete and only refunds.
A connection to each destination chain you support (an RPC endpoint), so you can check the solver’s tokens yourself.
The user’s address on both chains. Refunds go to the source-chain address, so it must be one the user controls.
An API key, for production. You can build and test without one: see Authentication and limits.

Create a secret

Generate 32 random bytes with a secure random generator. This secret is what completes the swap. Tern’s API calls it the fulfillment.Its SHA-256 hash is what you share with Tern up front. The API calls it the executionCondition.

import { randomBytes, createHash } from "node:crypto";

const secret = randomBytes(32);
const executionCondition = "0x" + createHash("sha256").update(secret).digest("hex");
// Store `secret`, encrypted, before you request the quote.

import hashlib, secrets

secret = secrets.token_bytes(32)
execution_condition = "0x" + hashlib.sha256(secret).hexdigest()
# Store `secret`, encrypted, before you request the quote.

Use a new secret for every swap. Tern refuses a hash that any earlier quote used (409 condition_reused), because one revealed secret would unlock every swap that shared it.

Get a firm quote

When the user confirms the price, ask for a firm quote. It’s the same request as a price, plus three fields:

sender: the user’s address on the source chain, where any refund goes.
recipient: the user’s address on the destination chain.
executionCondition: the hash from step 1.

You can also set slippageBps: how far below the expected amount the user accepts, in case the solver has to buy the token they want. It’s 50 (0.5%) by default and at most 300 (3%). Add an Idempotency-Key header so a retried request returns the same quote.

curl https://api.ternswap.xyz/v1/quote \
  -H "content-type: application/json" \
  -H "x-api-key: $TERN_API_KEY" \
  -H "Idempotency-Key: order-8412" \
  -d '{
    "from": { "chain": "base", "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "amount": "100000000" },
    "to":   { "chain": "starknet", "asset": "0x033068f6539f8e6e6b131e6b2b814e6c34a5224bc66947c47dab9dfee93b35fb" },
    "sender": "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
    "recipient": "0x04a7c1e8f2d5b6a39e0c7d18b2f4e6a5c3d9b8a7f6e5d4c3b2a1908f7e6d5c4b",
    "executionCondition": "0x0d8d122cdf33761dd3693836dd7b4c9d633a4fb37d151e0c8de1b42fe6738fb9"
  }'

{
  "id": "q_01JB8Z5W3F6V9Q2X4K7M1N0P8R",
  "route": "escrow",
  "from": { "chain": "base", "asset": "0x8335…2913", "amount": "100000000", "usd": "100.00" },
  "to":   { "chain": "starknet", "asset": "0x0330…35fb", "amount": "99880000", "usd": "99.88" },
  "expiresAt": 1793085830,
  "fees": { "totalUsd": "0.13", "items": [ { "kind": "network", "usd": "0.06" }, { "kind": "solver", "usd": "0.07" } ] },
  "costBps": 13,
  "etaSecs": 40,
  "execute": {
    "depositAddress": "0x3c1f0e0a9b7d6c5e4f3a2b1c0d9e8f7a6b5c4d3e",
    "transactions": [
      { "to": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "data": "0x095ea7b3…", "value": "0" },
      { "to": "0x0133271eca590460acad93c14167bbdc1a8b1dea", "data": "0x…", "value": "0" }
    ]
  }
}

id identifies this swap from now on. Store it with the secret.
to.amount is what the user should receive. If the quote also has to.minAmount, that’s the least they’ll receive: show both. See Amounts.
expiresAt is the deadline to deposit, 30 minutes from now.
execute is how the user deposits, in the next step.

For what to show about cost, see Fees and pricing.

Take the deposit

Before expiresAt, the user deposits in one of two ways.

From the user's wallet
To a deposit address

EVM chains: send execute.transactions in order from sender. An approval is included only when it’s needed. USDT on Ethereum may get an extra approval of zero first, because that token requires it.
Starknet: send execute.calls together, as a single transaction, from sender.

Before the user signs, check that the transactions only approve the token being sold to Tern’s contract and then call it. Hard-code the address from Contract addresses.

The user sends exactly from.amount of the token to execute.depositAddress, from any wallet or straight from an exchange. The address belongs to this swap alone, and Tern moves whatever arrives into the swap.If the user sends a different amount, a different token, or sends too late, the funds go back to them, or the swap may refund. See Deposit addresses.

Once you have the deposit’s transaction hash, you can send it to POST /v1/index so the status updates sooner. Tern finds the deposit either way.

Wait for the solver

Check the swap’s status with GET /v1/quote/{id}, or receive it through webhooks. It moves from awaiting_deposit to deposit_confirmed once the deposit is confirmed, then to in_progress once the solver has locked the user’s tokens on the destination chain.

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

At in_progress, move to the next step. If the status becomes refunded or expired instead, the swap is over: see If something goes wrong. Track a swap covers how often to check and what each field means.

Check the solver's tokens

Before you reveal the secret, confirm on the destination chain that the solver has really locked the user’s tokens. Use your own connection to the chain, not Tern’s status or a webhook: this check is what makes revealing safe.The solver locks the tokens in Tern’s escrow contract, in one or more locks tied to your hash. Check that:

Every lock you count is still open, pays recipient, holds to.asset, and has at least 30 minutes before it expires.
Together they hold at least to.minAmount, or to.amount if the quote has no minimum.

To find the locks, look for the escrow contract’s Prepared events that carry your hash. On EVM chains the hash is the event’s third indexed field (topics[3]), and escrows(escrowId) returns each lock’s amount and state (1 means still open). On Starknet the hash is a key of the Prepared event, and get_escrow(escrow_id) returns the same. The exact event formats are in the specification.If the solver locked less than the minimum, don’t reveal. Wait a few minutes for it to add the rest; if it doesn’t, the swap refunds.

Reveal the secret

Send the secret from step 1 to Tern, with an Idempotency-Key:

curl https://api.ternswap.xyz/v1/quote/q_01JB8Z5W3F6V9Q2X4K7M1N0P8R/fulfill \
  -H "content-type: application/json" \
  -H "x-api-key: $TERN_API_KEY" \
  -H "Idempotency-Key: fulfill-8412" \
  -d '{ "fulfillment": "0x8f3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b" }'

Tern answers 202 Accepted and pays the user on the destination chain. It runs the same checks first. If the solver’s tokens aren’t ready yet, it answers 409 destination_not_ready and does nothing: wait a few seconds and try again with the same key.Keep checking the status until it’s completed. destination.txHash is the transaction that paid the user.

Once revealed, the secret is public. Reveal it only after the checks in the previous step pass.

If something goes wrong

What happened	What to do
`409 condition_reused` when quoting	Create a new secret and request a new quote.
`422 no_route` when quoting	No solver offered a price for this swap. Try a different amount or pair, or try again later.
Status `expired`	No deposit arrived before the deadline. Request a new quote. Anything sent late goes back to the user.
Status `refunded`	The swap didn’t complete and the user got their deposit back. Show them `source.refundTxHash`. See Refunds.
The solver locked less than the minimum	Don’t reveal. The solver may add the rest; otherwise the swap refunds.
`409 destination_not_ready` when revealing	Wait a few seconds and try again with the same `Idempotency-Key`.
A timeout or `5xx` when revealing	You can’t tell whether it went through. Try again with the same `Idempotency-Key` until you get an answer.

Next steps

Track a swap

Follow statuses and show users their swap history.

Webhooks

Get every status change sent to your server.

Refunds

Every way a swap can end without completing.

Errors

Every error and what to do about it.

Get started

Concepts

Guides

Protocol

Cross-chain swaps

Before you start

If something goes wrong

Next steps

Track a swap

Webhooks

Refunds

Errors

​Before you start

​If something goes wrong

​Next steps

Track a swap

Webhooks

Refunds

Errors

Before you start

If something goes wrong

Next steps