Introduction

The Tern API is built around one thing: the quote. You get a price, turn it into a firm quote, have the user deposit or send the swap, track its status, and for a cross-chain swap, reveal the secret that completes it.

Base URL

https://api.ternswap.xyz

Every path starts with /v1. Requests and responses are JSON over HTTPS.

Endpoints

Endpoint	What it does
`GET /v1/chains`	Lists the supported chains, their contracts, and the tokens solvers support.
`POST /v1/quote`	Gets a price, or a firm quote with the transactions to send.
`GET /v1/quote/{id}`	Shows where a swap stands.
`GET /v1/quotes`	Finds swaps by address or transaction hash.
`POST /v1/quote/{id}/fulfill`	Reveals the secret that completes a cross-chain swap.
`POST /v1/quote/{id}/submit`	Submits a prepared private swap.
`POST /v1/index`	Tells Tern about a transaction so a status updates sooner. Optional.

Formats

What	Format
Chains	Lowercase names, such as `base` or `starknet`. See Supported chains.
Tokens	The token’s contract address, or `native` for an EVM chain’s native token.
Amounts	Whole numbers in the token’s smallest unit, as strings. Never decimals.
Dollar values	Strings with two decimals, rounded down: `"99.88"`.
Times	Unix time, in seconds.
Field names	camelCase.
Request size	Up to 64 KiB, or 1 MiB when submitting a private swap.
Timeouts	Requests that take longer than 10 seconds return `503 timeout`.

New fields, error codes, and values may be added to v1 over time. Ignore fields you don’t recognize, and handle an unfamiliar error code by its HTTP status.

Calling from a browser

The API accepts requests from any website, so a web app can call it directly. Browsers can send the x-api-key, Idempotency-Key, and x-request-id headers, and read the x-request-id and Retry-After headers in responses.

Rules for every request

Authentication and limits

API keys, rate limits, and request IDs.

Idempotency

Retry safely without creating anything twice.

Errors

What each error means and how to handle it.

Overview

Quotes

Chains

Indexing

Introduction

Base URL

Endpoints

Formats

Calling from a browser

Rules for every request

Authentication and limits

Idempotency

Errors

​Base URL

​Endpoints

​Formats

​Calling from a browser

​Rules for every request

Authentication and limits

Idempotency

Errors

Base URL

Endpoints

Formats

Calling from a browser

Rules for every request