Bitcoin Swap Reference › REST API
Conventions
| Base URL | https://btcw.tech — the same API is served at https://app.btcw.tech |
|---|---|
| Authentication | no API key required |
| Format | JSON, UTF-8; GET only. CORS open (Access-Control-Allow-Origin: *) — callable directly from the browser |
| Token amounts | in the quote API (/api/v2/swap/*): integer strings, base units (18 decimals) — never parse them as floats.
In the stats endpoints: floats, human units (BTCw, USD) |
| Time | /api/* and the ts, t, expiresAt fields: Unix seconds. The updated field of /api/v2/*: Unix milliseconds |
| Caching | per the cache-control header listed for each endpoint; polling faster than that returns no new data |
| Rate limit | 20 requests/second per IP, shared across /api/*, /api/v2/* and the explorer API — see Limits & error codes |
| Prices | all USD prices come from on-chain oracles (BtcwPriceFeed, PriceHub) |
Prices
/api/pricemax-age=5BTCw price and OracleAMM status. No parameters.
| Field | Type | Description |
|---|---|---|
price_usd | number | oracle BTC/USD price × peg ratio |
bid_usd / ask_usd | number | actual OracleAMM buy / sell price for BTCw (spread included) |
spread_pct | number | spread per side, % (0.3) |
updated_at, age_seconds, max_age_seconds | number | when the price was written, price age, staleness threshold (300) |
stale, paused, tradable | bool | price is stale; OracleAMM is paused; orders can be filled (not stale, not paused, liquidity available) |
liquidity | object | btcw, usdw held in OracleAMM; max_trade_btcw |
oracle | object | round, answer_btc_usd, decimals, address, sources |
contracts | object | amm, usdw, feed addresses |
usdw_total_supply, block | number | USDw total supply; block at read time |
curl -s https://btcw.tech/api/price/api/tokensmax-age=5BTCw and USDw in a compact wallet format: symbol, name, address (null for native BTCw), native, decimals,
price_usd, logo. The 200 price-tracker tokens are at /api/v2/swap/assets.
/api/v2/poolsmax-age=5The 201 ClpPools pools. Returns { updated, pools: [...] }.
| Field | Description |
|---|---|
address, symbol, name, logo | the pool's token (logo is a path relative to btcw.tech) |
class | crypto · stock (US equities) · stable (USDw) |
oracleUsd / poolUsd / devBps | oracle price, pool price, deviation (bps, positive = pool is more expensive) |
depthBtcw / depthAsset | pool depth on each side |
tvlUsd, vol24hUsd, fees24hUsd, swaps24h, feeTvlPct24h | stats, valued at the oracle price at indexing time; includes Treasury trades |
priceAgeS | age of the token's oracle price, seconds |
Swap
/api/v2/swap/assetsmax-age=30The 202 swappable assets: { chainId, updated, assets: [{ address, native, symbol, name, decimals, logoURI, priceUsd, poolDepthBtcw }] }.
Native BTCw has address = 0xEeee…EEeE and native: true.
/api/v2/swap/quoteno-storeQuote + prebuilt transaction. Full guide and example response: Wallet swap integration.
| Parameter | Description | |
|---|---|---|
from, to | required | token address or native |
amount | required | integer, base units |
sender | when set, returns tx, approval and simulates the transaction | |
recipient | receiver; if different from sender, only the ClpPools route remains | |
slippage_bps | 100 | 1–5000 → minAmountOut |
route | best | best · clp · amm (BTCw ⇄ USDw) · amm-eth (ETHw ⇄ USDw) · router (multi-hop through SwapRouter in one transaction) |
Status codes: 200 quote returned · 400 invalid input ({ error }) · 422 no route can fill the order (routes[].error still included) · 502 RPC read error.
Stats
/api/v2/statsmax-age=5Chain-wide figures used by the Dashboard: block, validators, btcw_usd, tvl_usd (split into tvl_clp_usd / tvl_oracleamm_usd),
volume_24h, swaps_24h, fees_24h_usd, total_swaps, wallets, oracle_assets_fresh (e.g. "100/100"),
network, status (per-component health), treasury_addresses.
Volume includes of_which_treasury… fields — the share traded by the Treasury wallets (treasury_addresses) to keep pool prices close to the oracle.
/api/v2/history?hours=48max-age=5Hourly series, hours up to 720. Each entry: t (start of hour), volClp, volAmm, volTreasury, swaps, swapsTreasury, fees (USD).
/api/v2/swaps?limit=50max-age=5Latest swaps (limit up to 300) and the 10 largest swaps in 24 hours: { latest, top24h }. Each swap: venue, from, to,
amountIn, amountOut, usd, fee, trader, treasury (bool), block, tx, ts.
Health
/api/healthmax-age=5Price API: { ok, block, age_seconds }.
/api/v2/healthmax-age=5Indexer: { ok, lastBlock, builtAgoS }. Returns 503 until indexing has finished (after a restart) — as do all other /api/v2/* endpoints.
Static files
| Path | Contents |
|---|---|
/developers/contracts.json | addresses + ABIs of all contracts, chain info, API description · CORS open |
/chain.json | network info, ethereum-lists format |
/swap/sdk/btcw-swap.js | SDK — can be imported directly from any domain (CORS open) · see JavaScript SDK |
/logo.svg, /logo.png, /usdw.png | BTCw, USDw logos |
The explorer has its own API (Blockscout): https://explorer.btcw.tech/api/v2/… — see the Blockscout docs.