REST API Guide

The Atomiq REST API is an HTTP interface for the Atomiq cross-chain DEX, covering trustless swaps between Bitcoin / Lightning and smart chains (Starknet, Solana, Botanix, Citrea, Alpen, Goat).

You can either self-host the REST API on your own infrastructure using Docker (refer to Run REST API Locally), or use the public API provided by Atomiq:

• Mainnet: https://mainnet.swaps-api.atomiq.exchange/
• Testnet4: https://testnet4.swaps-api.atomiq.exchange/

warning

By using the REST API you fully trust the backend to correctly validate swap data and serve properly constructed transactions to the clients. A compromised backend might drain your user's funds.

Prefer the Atomiq SDK, which verifies everything locally and doesn't rely on trusted external APIs. Use the REST API only when you cannot use the SDK: non-JS runtimes or environments without local persistence.

The API is non-custodial: it never holds user keys. All signing happens in the client wallet — the API builds unsigned transactions and submits signed ones.

tip

• Looking for exact request / response shapes? → REST API Reference
• Machine-readable OpenAPI 3.1 spec: /rest-api-reference/openapi.json — for code generators, AI agents, and tooling.

Conventions used throughout

• Base URL — examples use https://mainnet.swaps-api.atomiq.exchange (the hosted public API). Replace with https://testnet4.swaps-api.atomiq.exchange for testnet, or with http://localhost:3000 when running the self-hosted container.
• GET vs POST — GET endpoints read parameters from the query string, POST endpoints from a JSON body.

The rest of this guide assumes you're familiar with the shared vocabulary described here.

Token identifiers

Tokens are identified by a single string in the form <network>-<ticker>. Typical values:

Token ID	Meaning
BITCOIN-BTC	On-chain Bitcoin
LIGHTNING-BTC	Bitcoin over the Lightning Network
STARKNET-STRK, STARKNET-ETH, STARKNET-<erc20-address>	Starknet native and ERC-20 tokens
SOLANA-SOL, SOLANA-<spl-mint>	Solana native and SPL tokens
CITREA-CBTC, BOTANIX-BTC, ALPEN-BTC, GOAT-BTC	Supported EVM chains

You don't need to hard-code this list. Use GET /getSupportedTokens and GET /getSwapCounterTokens to enumerate what the current LP network supports — see Quoting Swaps.

Amounts and BigInt-as-string

Numerical integer values (like TypeScript's bigint) appear in this API as BigIntString (e.g. "150000", "1500000000000000000"), because JSON cannot safely encode arbitrary-precision integers as native numbers.

info

The SDK accepts human-readable values as strings and base unit values as bigints, since the REST API cannot differentiate between these types (both would be string-serialized) only base unit amounts are supported by the API!

Every monetary amount returned by the API uses the ApiAmount shape:

{
  "amount":    "0.00003",                   // decimal-formatted for display
  "rawAmount": "3000",                      // base units as a decimal string
  "decimals":  8,                           // token decimals
  "symbol":    "BTC",                       // ticker
  "chain":     "BITCOIN"                    // chain identifier
}

When sending amounts to the API, for example when creating a swap with POST /createSwap, always pass the raw base-unit string — not a decimal, not a number. "150000" for 0.0015 BTC, not 0.0015.

Error shape

All errors are JSON. For 4xx responses the body is { "error": "<message>" }. Transient 5xx errors should be retried with backoff.

Rate-limit (429) responses may include additional fields depending on how the API is deployed — the self-hosted container returns retryAfter in seconds inside the body, while hosted deployments typically expose Retry-After only as a standard HTTP header. Treat both as advisory and back off accordingly.

What this guide covers

Section	What you'll learn
Creating & Executing a Swap	Create a swap, poll currentAction, sign PSBTs or smart-chain transactions, submit signed payloads, render execution steps, and stop at terminal states.
Quoting Swaps	Build the pre-swap form: list supported tokens, narrow compatible counter-tokens, estimate spendable balance, validate limits, and parse recipient addresses.
Listing Swaps	Restore pending swaps after restart, list signer history, resume polling from list results, and handle refunds.
Bitcoin & Lightning Specifics	Handle Bitcoin PSBT variants, Lightning HTLC-based hashes and swap secret reveal, BOLT11 invoices, LNURLs, and gas drops.
Run REST API Locally	Self-host atomiq-api-docker with Docker Compose and configure chains, LP connectivity, storage, rate limits, and server settings.