Swap integration
Everything needed to quote, create and track a swap from your own aggregator or shop. Three calls do the work: price it, create it, poll it. The /v1/swap endpoints are the No AML swap: Bitania's own liquidity, from our own hot wallets, no AML check on the deposit, so the amount quoted is the amount sent. The Normal swap endpoints under /v1/normal are a separate add-on.
Architecture overview
Access to the Swap API is restricted to verified aggregator partners. To apply for credentials, contact Bitania support (Telegram or SimpleX via the Support button). You receive an API key, an API secret and a login to the partner panel, where you follow your swaps, earnings and payouts.
Every swap created through /v1/swap is executed by Bitania itself. The deposit address belongs to Bitania's hot wallet, the payout is sent from Bitania's hot wallet, and the deposit is not run through any AML check: we accept any coins. No third party sits between your user and Bitania. The only alternative is the Normal swap add-on, which is executed by a liquidity partner and has to be enabled for a key separately.
Bitania does instant cross-chain swaps paid from its own liquidity. Prices come from the median of several major exchanges and refresh every 10 seconds. There is no order book to slip against: the amount quoted is the amount sent, and Bitania covers the on-chain cost of the payout. Swaps are stateless: your users never interact with Bitania directly, unless you hand them the public status page of their swap.
An integration is three calls. Quote with /swap/price, create with /swap/create and get a fresh deposit address back, then poll /swap/status until it is done.
- Call
/swap/pricewith the pair, the amount and the direction. - Show the quote, including the output amount and the service fee.
- Call
/swap/createwith the destination address and a refund address. - Show the deposit address and the time left in the payment window.
- Poll
/swap/statusevery 10 to 30 seconds. - Handle the terminal states:
DONE,EXPIRED,REFUNDED. - Handle the states that need the user:
RATE_CHANGED,REFUNDING.
Supported currencies
12 currencies across 8 chains. These are the only codes that can take a deposit or receive a payout; the figures are live, what Bitania has configured right now. Cache the list rather than requesting it per page view, and mind the network on USDT and USDC.
| Code | Coin | Network | Confirmations | Minimum | Status |
|---|---|---|---|---|---|
BTC | BTC | Bitcoin network | 1 | 0.001 BTC | available |
LTC | LTC | Litecoin network | 2 | 0.1 LTC | available |
XMR | XMR | Monero network | 5 | 0.05 XMR | available |
ZEC | ZEC | Zcash network | 6 | 0.02 ZEC | temporarily disabled |
TRX | TRX | Tron network | 20 | 100 TRX | available |
ETH | ETH | Ethereum network | 12 | 0.01 ETH | available |
SOL | SOL | Solana network | 1 | 0.5 SOL | available |
AVAX | AVAX | Avalanche C-Chain | 30 | 1 AVAX | available |
USDTTRC | USDT | Tron (TRC20) | 20 | 20 USDT | available |
USDTERC | USDT | Ethereum (ERC20) | 12 | 50 USDT | available |
USDCERC | USDC | Ethereum (ERC20) | 12 | 50 USDC | available |
USDCSOL | USDC | Solana (SPL) | 1 | 20 USDC | available |
/v1/swap/currencies120/minReturns the live list. Each entry carries code, coin, network, name, recv and send (whether Bitania can take / pay the coin right now), precision, reqConfirmations and min. Trust it over the table above: a currency can be switched off for node maintenance, and confirmation counts or minimums can be tuned. GET is accepted as well (sign it with GET as the method and an empty body).
{ "code": 0, "msg": "", "data": [
{ "code": "BTC", "coin": "BTC", "network": "BTC", "name": "Bitcoin", "recv": true, "send": true, "precision": 8, "reqConfirmations": 1, "min": 0.001 },
{ "code": "LTC", "coin": "LTC", "network": "LTC", "name": "Litecoin", "recv": true, "send": true, "precision": 8, "reqConfirmations": 2, "min": 0.1 },
{ "code": "XMR", "coin": "XMR", "network": "XMR", "name": "Monero", "recv": true, "send": true, "precision": 8, "reqConfirmations": 5, "min": 0.05 },
{ "code": "ZEC", "coin": "ZEC", "network": "ZEC", "name": "Zcash", "recv": false, "send": false, "precision": 8, "reqConfirmations": 6, "min": 0.02 },
{ "code": "TRX", "coin": "TRX", "network": "TRX", "name": "Tron", "recv": true, "send": true, "precision": 6, "reqConfirmations": 20, "min": 100 },
{ "code": "ETH", "coin": "ETH", "network": "ETH", "name": "Ethereum", "recv": true, "send": true, "precision": 8, "reqConfirmations": 12, "min": 0.01 },
{ "code": "SOL", "coin": "SOL", "network": "SOL", "name": "Solana", "recv": true, "send": true, "precision": 8, "reqConfirmations": 1, "min": 0.5 },
{ "code": "AVAX", "coin": "AVAX", "network": "AVAX", "name": "Avalanche", "recv": true, "send": true, "precision": 8, "reqConfirmations": 30, "min": 1 },
{ "code": "USDTTRC", "coin": "USDT", "network": "TRX", "name": "Tether", "recv": true, "send": true, "precision": 6, "reqConfirmations": 20, "min": 20 },
{ "code": "USDTERC", "coin": "USDT", "network": "ETH", "name": "Tether", "recv": true, "send": true, "precision": 6, "reqConfirmations": 12, "min": 50 },
{ "code": "USDCERC", "coin": "USDC", "network": "ETH", "name": "USD Coin", "recv": true, "send": true, "precision": 6, "reqConfirmations": 12, "min": 50 },
{ "code": "USDCSOL", "coin": "USDC", "network": "SOL", "name": "USD Coin", "recv": true, "send": true, "precision": 6, "reqConfirmations": 1, "min": 20 }
] }
A /swap/price or /swap/create request naming any other code is rejected with Unknown currency code. Codes are case-insensitive and the spellings USDT-TRC20, USDT-ERC20, USDC-ERC20 and USDC-SOL are accepted as aliases, but always send the codes above.
Supported pairs
Every permutation of the currencies is swappable, in both directions. There is no routing: Bitania holds every coin and pays the output from its own wallet, so each pair is direct.
/v1/swap/pairs120/minEvery pair that can be swapped right now, with its per-pair minimum. Refresh it when a swap is refused with a maintenance error, and hide pairs where available is false. GET is accepted as well.
[
{ "from": "BTC", "to": "USDTTRC", "type": "direct", "via": [], "available": true, "fixed": true, "min": 0.001 },
{ "from": "XMR", "to": "LTC", "type": "direct", "via": [], "available": true, "fixed": true, "min": 0.05 },
{ "from": "TRX", "to": "XMR", "type": "direct", "via": [], "available": true, "fixed": true, "min": 100 }
]
| Field | Type | Meaning |
|---|---|---|
from / to | string | Currency codes for the pair. |
type | string | Always direct; kept for compatibility with older integrations. |
via | array | Always empty. |
available | boolean | False while the pair, or one of its coins, is under maintenance. |
fixed | boolean | Whether you may request fixed-rate quotes on it (your key's fixed_rate_enabled, and the pair available). |
min | number | Minimum send amount for this pair. |
A pair can be put under maintenance (available: false) or be limited by Bitania's liquidity in the destination coin; the quote's from.max tells you the largest amount that can be swapped right now.
Authentication
Every request is signed with HMAC-SHA256 over a canonical string (the v2 scheme). No JWT tokens or user accounts are involved. Ask support for a key, a secret and a panel login.
| Header | Value |
|---|---|
X-API-KEY | Your API key, in the form btn_… |
X-API-SIGN | The signature, lowercase hex |
X-API-TIMESTAMP | Unix seconds, within 60 s of server time |
X-API-NONCE | Unique per request, never reused within 120 s |
X-API-VERSION | Optional. If sent it must be exactly 2 |
The canonical string
The signature is not over the raw body. Build a canonical signing string from four newline-joined fields, then HMAC it with your API secret:
{timestamp}\n{METHOD}\n{path}\n{sha256_hex(body)}
timestampis the same value sent inX-API-TIMESTAMP.METHODis uppercase. Every endpoint isPOST.pathincludes the/v1prefix, for example/v1/swap/price, with no host and no query string.sha256_hex(body)is the hex SHA-256 of the exact request body bytes. For an empty body, hash the empty string.
Sign that string with your API secret and send the lowercase hex digest as X-API-SIGN. The joining is exactly three \n (LF) characters, in the order above.
- A clock more than 60 seconds out. Keep the machine NTP-synced; this is the usual cause of intermittent
Invalid signatureerrors. - A reused nonce within 120 seconds. Generate a fresh one on every request, retries included.
- A body hash that does not match the bytes actually sent. Serialise once and send that exact string (in Python's requests,
data=, neverjson=).
Signing examples
API_KEY="btn_your_key"
API_SECRET="bts_your_secret"
HOST="https://bitania.com"
REQ_PATH="/v1/swap/price"
BODY='{"from":"BTC","to":"USDTTRC","amount":0.1,"direction":"from","type":"float"}'
TS=$(date +%s)
NONCE=$(cat /proc/sys/kernel/random/uuid)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 | awk '{print $NF}')
SIGNING_STRING=$(printf '%s\nPOST\n%s\n%s' "$TS" "$REQ_PATH" "$BODY_HASH")
SIGN=$(printf '%s' "$SIGNING_STRING" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $NF}')
curl -X POST "$HOST$REQ_PATH" \
-H "Content-Type: application/json" \
-H "X-API-KEY: $API_KEY" \
-H "X-API-SIGN: $SIGN" \
-H "X-API-TIMESTAMP: $TS" \
-H "X-API-NONCE: $NONCE" \
-d "$BODY"
import hmac, hashlib, json, time, uuid, requests
API_KEY = "btn_your_key"
API_SECRET = "bts_your_secret"
HOST = "https://bitania.com"
def swap_request(endpoint, payload):
path = f"/v1/swap/{endpoint}"
body = json.dumps(payload)
ts = str(int(time.time()))
nonce = uuid.uuid4().hex
body_hash = hashlib.sha256(body.encode()).hexdigest()
signing_string = f"{ts}\nPOST\n{path}\n{body_hash}"
signature = hmac.new(
API_SECRET.encode(), signing_string.encode(), hashlib.sha256
).hexdigest()
return requests.post(
HOST + path,
headers={
"X-API-KEY": API_KEY,
"X-API-SIGN": signature,
"X-API-TIMESTAMP": ts,
"X-API-NONCE": nonce,
"Content-Type": "application/json",
},
data=body, # data=, not json=, so the hash matches the bytes
).json()
const crypto = require("crypto");
const axios = require("axios");
const API_KEY = "btn_your_key";
const API_SECRET = "bts_your_secret";
const HOST = "https://bitania.com";
async function swapRequest(endpoint, payload) {
const path = `/v1/swap/${endpoint}`;
const body = JSON.stringify(payload);
const ts = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomUUID();
const bodyHash = crypto.createHash("sha256").update(body).digest("hex");
const signingString = `${ts}\nPOST\n${path}\n${bodyHash}`;
const signature = crypto
.createHmac("sha256", API_SECRET)
.update(signingString)
.digest("hex");
const { data } = await axios.post(HOST + path, body, {
headers: {
"X-API-KEY": API_KEY,
"X-API-SIGN": signature,
"X-API-TIMESTAMP": ts,
"X-API-NONCE": nonce,
"Content-Type": "application/json",
},
validateStatus: () => true,
});
return data;
}
If an IP whitelist is set on the key, requests from anywhere else fail with Invalid credentials, the same error an unknown key returns. Integrations written against the original v1 scheme, which signs the raw body only (HMAC-SHA256(api_secret, body)) and sends just X-API-KEY and X-API-SIGN, keep working unchanged, but they have no replay protection: new integrations should use v2.
Endpoints
All under /v1/swap/, JSON bodies, signed as above. Every response is the standard envelope; create, status, advance and emergency return the swap object in data.
/v1/swap/price600/minA quote. Nothing is reserved and no address is generated. The rate is Bitania's live mid-market price with the service fee already taken off the output; nothing else is deducted. Partners on a volume-share agreement: your share is added to the fee and already included in every quote and swap made with your key or referral link (fee.partnerPercent shows it), so the output you display is final.
| Field | Type | Meaning | |
|---|---|---|---|
type | string | optional | float (default) or fixed; fixed needs fixed_rate_enabled on your key |
from | string | required | Source currency code |
to | string | required | Destination currency code |
amount | number | required | Amount in the direction currency (a numeric string is accepted too) |
direction | string | optional | from (default) fixes the send amount, to fixes the receive amount and is always a fixed-rate quote |
split | integer | optional | Quote a Split transactions payout in this many parts (2 to 20; needs the split permission). The answer gains split: outputs, about (the size of one part), minPerOutput and minTotal (each part is at least the destination coin's minimum swap amount) and minAddresses |
{"from":"BTC","to":"USDTTRC","amount":0.1,"direction":"from","type":"float"}
{
"code": 0,
"msg": "",
"data": {
"from": { "code": "BTC", "coin": "BTC", "network": "BTC", "name": "Bitcoin", "amount": 0.1, "rate": 87150.42, "precision": 8, "min": 0.001, "max": 2.5, "usd": 8715.04 },
"to": { "code": "USDTTRC", "coin": "USDT", "network": "TRX", "name": "Tether", "amount": 8693.25, "rate": 0.0000114744, "precision": 6, "min": 87.15, "max": 217876.05, "usd": 8693.25 },
"fee": { "percent": …, "partnerPercent": 0, "amount": … },
"errors": [],
"slippage": 0,
"rateType": "float",
"bufferPercent": 0,
"guaranteedAmount": null,
"expiresIn": 3600
}
}
from.minandfrom.maxare the live limits;maxfollows Bitania's liquidity in the destination coin, so it moves (0 = no limit).to.min/to.maxare their outputs.feeis already deducted fromto.amount. Display it from the response rather than hard-coding it.guaranteedAmountis set on fixed-rate quotes;expiresInis the payment window a swap created now would get, in seconds.slippageandbufferPercentare always 0 on a quote: there is no order book to walk and the fixed-rate margin is in the fee, not the rate.- Errors: Minimum is 100 TRX, Maximum right now is 2.1 BTC, Unknown currency code "DOGE", Fixed rate is not enabled for your API key, This pair is under maintenance, Pricing is temporarily unavailable, please try again in a moment.
/v1/swap/create60/min201 CreatedCreates the swap, returns a fresh deposit address and starts the payment window. The swap is processed automatically once the deposit confirms: the deposit is credited, the payout is sent to toAddress, and nothing needs a call from you.
| Field | Type | Meaning | |
|---|---|---|---|
type | string | optional | float (default) or fixed |
from | string | required | Source currency code |
to | string | required | Destination currency code |
amount | number | required | Amount in the direction currency |
direction | string | optional | from (default) or to; a to order is always fixed-rate |
toAddress | string | required | Where the output goes; validated for the destination chain |
refundAddress | string | recommended | Where the deposit goes if the swap cannot complete. Without it a swap that must be refunded waits (REFUNDING, issue.needsRefundAddress) until you send an address via /swap/emergency |
dryrun | boolean | optional | true simulates the swap (DR-prefixed id, no chain interaction). Needs the dryrun_enabled permission |
split | integer | optional | Split transactions: the payout leaves as this many separate transactions (2 to 20) of different sizes, adding up to to.amount, over the payout addresses taken in turns. Needs the split permission on your key (ask Bitania support); each part must be at least the destination coin's minimum swap amount, so the quote may ask for a larger amount or fewer parts. Not available with dryrun |
addresses | string[] | with split | The other payout addresses of a split, toAddress being the first: at least two different addresses in all, never more than split, every one validated for the destination chain |
{
"type": "float",
"from": "BTC",
"to": "USDTTRC",
"amount": 0.1,
"direction": "from",
"toAddress": "TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr",
"refundAddress": "bc1q..."
}
{
"code": 0,
"msg": "",
"data": {
"id": "k7m3px9qw2",
"token": "uYx9j2k3Lm4nOp5qRs6tUw",
"status": "NEW",
"from": { "code": "BTC", "address": "bc1q...", "amount": "0.1", "reqConfirmations": 1, "tx": null },
"to": { "code": "USDTTRC", "address": "TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr", "amount": "8693.25", "tx": null },
"fee": { "percent": …, "amount": … },
"time": { "reg": 1761822000, "expiration": 1761825600, "left": 3600 },
"url": "https://bitania.com/swap/k7m3px9qw2?t=uYx9j2k3Lm4nOp5qRs6tUw"
}
}
- Store both
idandtoken. The token is explained under cross-aggregator views; treat it as a secret. - The payment window is 60 minutes for both rate types today. Drive your countdown from
time.leftin seconds rather than hard-coding it; Bitania can tune it. urlis the public status page you can hand to the user; the link carries the token, so it opens on any device.- Errors: That is not a valid USDT address, The refund address is not a valid BTC address, Minimum is 0.001 BTC, Dry-run mode is not enabled for your API key, BTC deposits are temporarily unavailable, please try again later.
/v1/swap/status600/minWhere the swap stands. Poll it every 10 to 30 seconds until a terminal status. By default the swap must belong to your key (created with it, or through your referral link); pass the optional token to read a swap another key created.
| Field | Type | Meaning | |
|---|---|---|---|
id | string | required | Swap id (10 characters; dry-run ids start with DR) |
token | string | optional | Per-swap token from /swap/create; authorizes the call from a different API key |
{"id": "k7m3px9qw2"}
{
"code": 0,
"msg": "",
"data": {
"id": "k7m3px9qw2",
"status": "DONE",
"from": { "address": "bc1q...", "amount": "0.1", "amountDeposited": "0.1", "reqConfirmations": 1,
"tx": { "id": "deposit_tx_hash", "amount": "0.1", "confirmations": 3 } },
"to": { "address": "TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr", "amount": "8701.10",
"tx": { "id": "output_tx_hash", "fee": "1.1", "feeCurrency": "TRX", "confirmations": 20 } },
"rate": "87150.42",
"rateActual": "87229.33",
"slippage": 0.09,
"fee": { "percent": …, "amount": … },
"guarantee": [ { "step": "created", "title": "...", "signedAt": "...", "text": "-----BEGIN PGP SIGNED MESSAGE-----..." } ]
}
}
| Field | When it appears |
|---|---|
from.tx.id, from.tx.confirmations | Once the deposit is detected |
to.tx.id | Once the payout is sent; to.tx.confirmations keeps refreshing while you poll, to.tx.txKey on Monero is the payment proof |
rateActual | On DONE, the rate actually applied |
slippage | Once the deposit is credited: applied rate vs quoted rate in percent (0 on a fixed-rate swap honoured as quoted) |
issue.type | On a problem: LESS, MORE, LATE, BELOW_MINIMUM, NO_LIQUIDITY |
issue.reason | While RATE_CHANGED, REFUNDING or FAILED: the explanation. Also while EXCHANGING with issue.type NO_LIQUIDITY: our wallet of the payout coin is short, the swap is paid as soon as it is topped up, and issue.choice is REFUND because you may take the deposit back instead through /swap/emergency |
issue.needsRefundAddress | When no refund address is on file and one is needed |
proposed.amount, proposed.rate | On RATE_CHANGED, the re-quote |
refund.tx.id | Once a refund is sent |
time.left | While the payment window is still open |
guarantee | One PGP-clearsigned letter per step reached (created, deposit, paid, refunded) |
deleted | true once the customer deleted the swap from its page. The swap itself continues and the status keeps updating, but from then on from.address, to.address, refund.address are null and guarantee is empty. Same field on /v1/normal/status |
split | null for an ordinary swap. For a swap created with split: outputs (the number of transactions), addresses (every payout address, to.address first), sent (how many parts are out) and parts[], one entry per transaction already broadcast: id, amount, address, confirmations, timeReg. The swap is SENDING from the first part on and DONE with the last one; to.tx is then the last part |
dryrun | On simulated swaps |
An unknown id and a swap you may not see both return 404 Swap not found.
/v1/swap/emergency30/minalias /v1/swap/resolveTakes a decision on a swap that cannot simply execute. Two situations need you: a RATE_CHANGED swap (a fixed-rate deposit outside the ±0.5 % tolerance, or one that arrived after the swap had expired), where proposed holds the re-quote; and a REFUNDING swap with issue.needsRefundAddress true, where the deposit will be sent back but no refund address is known.
| Field | Type | Meaning | |
|---|---|---|---|
id | string | required | Swap id |
choice | string | required | EXCHANGE continues the swap at the current rate (proposed.rate) for the deposited amount, moving it to EXCHANGING; REFUND sends the full deposit back |
address | string | conditional | Refund address, required for REFUND when none was given at creation; validated for the source chain. An address that is already set is not changed through the API |
token | string | optional | Per-swap token |
{"id": "k7m3px9qw2", "choice": "EXCHANGE"}
{"id": "k7m3px9qw2", "choice": "REFUND", "address": "bc1q..."}
The response is the updated swap, in the same shape as /swap/status: EXCHANGING after EXCHANGE, REFUNDING (with issue.choice REFUND) after REFUND. Deposits below the pair minimum never wait for you: they are refunded automatically as soon as a refund address is known, which is why we recommend always passing refundAddress on create. A deposit whose payout is larger than our available balance is held (EXCHANGING, issue.type NO_LIQUIDITY, issue.choice REFUND) until we top the wallet up, usually within hours; REFUND returns the full deposit at any point of that wait. Swaps in FAILED (manual review) cannot be resolved this way.
Errors: EXCHANGE is only possible while the swap is RATE_CHANGED, REFUND is only possible while the swap is RATE_CHANGED, or REFUNDING without a refund address, A refund address is required, The refund address is not a valid TRX address, A refund address is already set for this swap; contact support to change it, This swap is under manual review; Bitania support resolves it, Dry-run swaps never need a decision.
/v1/swap/advance120/mindry-run onlySteps a simulated swap forward one stage and fills in realistic data (fake transaction hashes, confirmation counts, timestamps). Calling it on a real swap returns an error: real swaps move on their own. See dry-run mode.
{"id": "DRk7m3px9q"}
Errors: Only dry-run swaps can be advanced; real swaps move on their own, Dry-run swap DRk7m3px9q is already DONE and cannot be advanced.
The swap object
Returned in data by create (201), status, advance and emergency. Amounts are strings at full precision; times are UNIX seconds.
{
id: string 10 characters; dry-run swaps "DR" + 8
token: string per-swap access token, 22 characters; treat it as a secret
type: "float" | "fixed"
status: NEW | PENDING | CONFIRMING | RATE_CHANGED | EXCHANGING | SENDING | REFUNDING | DONE | EXPIRED | REFUNDED | FAILED
time: { reg, start, finish, update, expiration, left }
creation, first deposit seen, ended, last change, end of the window,
seconds left (null once a deposit was seen or the swap ended)
from: { code, coin, network, name, amount, amountDeposited, address, reqConfirmations,
tx: null | { id, amount, fee, feeCurrency, timeReg, timeBlock, confirmations } }
to: { code, coin, network, name, amount, address,
tx: null | { id, amount, fee, feeCurrency, timeReg, confirmations, txKey } }
to.amount is the quote until the deposit is confirmed, the final amount after
refund: { address: string | null, tx: null | { ... } }
guarantee: [ { step: created | deposit | paid | refunded, title, signedAt, text } ]
PGP-clearsigned letters; verify against https://bitania.com/pgp.txt
issue: { type: null | LESS | MORE | LATE | BELOW_MINIMUM | NO_LIQUIDITY,
reason: string | null, needsRefundAddress: boolean, choice: NONE | EXCHANGE | REFUND }
rate: string to-coin per 1 from-coin at creation
rateActual: string | null the rate actually applied, set on DONE
fee: { percent: number, amount: string }
slippage: number | null applied rate vs quoted rate, in percent
proposed: null | { rate, amount } the re-quote while RATE_CHANGED
dryrun: boolean
url: string | null the public status page (null for dry-run swaps)
}
Swap lifecycle
The payment window is 60 minutes for both rate types today. Read the real value from time.left rather than assuming it. A deposit that is broadcast inside the window but confirms slowly is still honoured: once the transaction has been seen (PENDING) the swap no longer expires.
NEW → PENDING → CONFIRMING → EXCHANGING → SENDING → DONE
↓ (fixed rate, deposit ≠ order) ↓ (below minimum / more than we hold)
RATE_CHANGED REFUNDING → REFUNDED
↙ ↘
EXCHANGING REFUNDING → REFUNDED
↓
DONE
| Status | Meaning |
|---|---|
NEW | Created, waiting for the deposit; time.left counts down. |
PENDING | Deposit seen, no confirmations yet. |
CONFIRMING | Confirming on chain: from.tx.confirmations against from.reqConfirmations. |
EXCHANGING | Confirmed and credited at the applicable rate; payout being prepared. |
SENDING | Payout being sent. On Ethereum, Avalanche and Zcash (ETH, AVAX, their tokens and ZEC) the broadcast transaction waits here for its first confirmation: to.tx.id is already set and to.tx.confirmations counts up; a transaction the network drops before that is resent under a new to.tx.id. |
DONE | Finished. to.tx.id and rateActual are set; on Ethereum, Avalanche and Zcash the payout has at least one confirmation. |
EXPIRED | Window closed with no deposit. A deposit that still reaches the address within 24 hours of the deadline revives the swap: it goes back to NEW and continues. A floating swap then executes at the current rate; a fixed swap enters RATE_CHANGED with issue.type LATE. Later than that the money is kept aside and returned by hand. |
RATE_CHANGED | Fixed-rate deposit outside the ±0.5 % tolerance (LESS / MORE) or late (LATE). Needs EXCHANGE or REFUND. |
REFUNDING / REFUNDED | Sending the deposit back, then sent (refund.tx): the user's choice, or automatic for a deposit below the minimum (BELOW_MINIMUM) or beyond available liquidity (NO_LIQUIDITY); may be waiting for a refund address. |
FAILED | In manual review by Bitania, for example a payout that failed on-chain; issue.reason says why. It resolves to DONE or REFUNDED without your involvement: show a neutral "processing" state and keep polling. |
Floating-rate swaps never enter RATE_CHANGED: whatever arrives is converted at the market rate of its confirmation, and additional deposits to the same address while the swap is open are credited the same way. If you prefer that for fixed-rate swaps too, ask for auto_execute_on_mismatch on your key: mismatches then execute at the current rate without the acceptance step (slippage shows the difference). Coins under the dust limit, worth a few dollars, cannot be refunded because the network fee exceeds them.
import time
while True:
status = swap_request("status", {"id": "k7m3px9qw2"})
state = status["data"]["status"]
if state == "DONE":
print("Complete! Output tx:", status["data"]["to"]["tx"]["id"])
break
elif state in ("EXPIRED", "REFUNDED"):
print("Terminal:", state)
break
elif state == "FAILED":
print("Under review:", status["data"]["issue"]["reason"]) # keep polling, slower is fine
elif state == "RATE_CHANGED":
break # offer EXCHANGE or REFUND, see /swap/emergency
elif state == "REFUNDING" and status["data"]["issue"]["needsRefundAddress"]:
break # collect a refund address and send it with REFUND
time.sleep(15)
Cross-aggregator status views
Every created swap returns a token, a URL-safe per-swap secret of 22 characters and 128 bits of entropy. Any API key that presents it can call /swap/status, /swap/emergency and /swap/advance for that swap, whoever created it (constant-time compare). Without the token the usual ownership check applies and someone else's swap comes back as Swap not found, so swap ids cannot be probed.
This is what lets a user follow one swap across two aggregators, or on the public status page (url, which carries the token; a visitor without it is asked for the swap's receive address first). Store the token next to the id.
# Your aggregator polling its own swap: no token needed
swap_request("status", {"id": "k7m3px9qw2"})
# Another key (e.g. a second integration of yours) reading the same swap
swap_request("status", {"id": "k7m3px9qw2", "token": "uYx9j2k3Lm4nOp5qRs6tUw"})
Normal swaps (partner liquidity)
Everything above is Bitania's own liquidity: the deposit comes to our wallet, the payout leaves it, and we accept any coins without an AML check. That is what the website calls a No AML swap, and the /v1/swap endpoints stay exactly as they are.
Next to it, a key can be enabled for Normal swaps, an add-on under /v1/normal. A Normal swap is executed by Bitania's liquidity partner: the partner issues the deposit address, receives the coins and pays the output straight to the destination. Its rate already contains every fee (it sits roughly 1–3 % below the market mid, nothing is deducted on top), and the partner runs an automatic AML check on the deposit. A deposit that scores too high puts the swap on HOLD: the swap's public page (url) tells the customer to contact Bitania support, which offers a refund or a No AML swap set up by hand for 2–3 % extra. Same HMAC signing, same envelope, same rate-limit budgets as the classic counterparts; no dry-run and no emergency call.
Ask support to switch Normal swaps on for your key. Until then the three write endpoints answer Normal swaps are not enabled for your API key. Bitania can also pause Normal swaps for everyone at once; /normal/status keeps working for swaps already placed.
| Endpoint | Limit | Body | Returns |
|---|---|---|---|
POST /v1/normal/currencies | 120/min | none | The coins the partner lists (fewer than /swap/currencies); every one can be sent and received. |
POST /v1/normal/pairs | 120/min | none | Every pair of those coins with available (both coins open on our side and listed by the partner right now, refreshed every 10 minutes), fixed and the min send amount. Your partner panel shows the same list as a matrix. |
POST /v1/normal/price | 600/min | as /swap/price | The partner's quote: from.amount, to.amount, rate (fee inside), rateType, refundAddressRequired, quoteValidFor. |
POST /v1/normal/create | 60/min | as /swap/create, no dryrun | 201 with the Normal swap object; from.address (and from.extraId when the chain needs a memo) is where the customer sends. |
POST /v1/normal/status | 600/min | {"id", "token"?} | The Normal swap object as last read from the partner (every 30 seconds). |
{"from":"BTC","to":"USDTTRC","amount":0.1,"direction":"from","type":"float"}
{"type":"float","from":"BTC","to":"USDTTRC","amount":0.1,"direction":"from","toAddress":"TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr","refundAddress":"bc1q..."}
{
id: string 10 characters, shares the id space with classic swaps
token: string per-swap access token; /normal/status accepts it from any key
kind: "normal"
type: "float" | "fixed"
status: NEW | CONFIRMING | EXCHANGING | SENDING | HOLD | DONE | EXPIRED | REFUNDED | FAILED
hold: boolean the partner's AML check paused the swap (status HOLD)
time: { reg, start, finish, update, expiration, left }
from: { code, coin, network, name, amount, amountDeposited, address, extraId, tx: null | { id, url } }
to: { code, coin, network, name, amount, address, tx: null | { id, url } }
refund: { address, tx: null | { id, url } }
rate: string to-coin per 1 from-coin, every fee inside
guarantee: [ { step, title, signedAt, text } ] PGP-clearsigned letters, signed by Bitania, as on classic swaps
note: string | null why it is on hold, refunded, failed or expired
url: string the public status page, token included
}
- Always send
refundAddress: the partner needs one on some pairs (refundAddressRequiredin the quote), and aHOLDthat ends in a refund goes there. - A floating Normal swap converts at the partner's rate of the moment the deposit confirms; a fixed one holds the quoted amount when the exact amount arrives in time. There is no
RATE_CHANGEDstate: a mismatching or late deposit is re-priced by the partner. - Normal swaps are not in
/swap/statusand classic swaps are not in/normal/status; keep thekindwith the id. - Your earnings: a completed Normal swap credits your partner balance with a share of its volume (the percentage is set by Bitania), and it shows in your partner panel next to your other swaps. Swaps started from your referral link work the same way, whichever kind the visitor picks.
Response format
Every endpoint answers in the same envelope.
{
"code": 0,
"msg": "",
"data": { }
}
code: 0is success, with HTTP 200, or 201 when a swap was created.code: 1is an error with the reason inmsganddata: null. The HTTP status says what kind: 400 validation or business rule, 401 authentication, 404 unknown swap, 429 rate limit.
Every response also carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix time). A 429 adds a Retry-After header and retry_after in the body.
Rate types
Floating
The default. The output is an estimate: the deposit converts at the market rate once it has the required confirmations, and slippage shows the difference to the quote afterwards. A mismatched deposit never causes an emergency state, so there is nothing for the user to resolve.
Fixed
The rate locks when the swap is created and holds for deposits within ±0.5% of the ordered amount, sent within the window. Outside that, the swap goes to RATE_CHANGED and the user picks EXCHANGE or REFUND. Fixed rate needs the fixed_rate_enabled permission on your key.
A quote with "direction": "to" is always fixed rate, because the user asked for an exact amount. If you would rather not put the choice to the user, ask support for auto_execute_on_mismatch on your key.
Fees
| Fee | Amount | Who pays |
|---|---|---|
| Service | Inside the rate | Already reflected in the quote: to.amount is what is paid out, nothing is deducted afterwards. The fee object in each response reports what that quote contained; Bitania does not publish a fixed percentage |
| Partner revenue share | Per API key: a share of the service fee, or a share of the volume | Credited to your partner account in USD when a swap completes; withdraw it in any supported coin at market rate, without a fee |
| Payout network fee | Whatever the chain costs | Bitania. The amount quoted is the amount sent |
| Refund | Free | The full deposit goes back, nothing is withheld, and Bitania pays the on-chain cost of the refund. refund.tx shows the transaction |
Show fees from the quote response. Do not hard-code them.
Rate limits
Per API key, per endpoint.
| Endpoint | Limit |
|---|---|
/swap/currencies | 120/min |
/swap/pairs | 120/min (one call returns every pair) |
/swap/price | 600/min |
/swap/create | 60/min |
/swap/status | 600/min |
/swap/advance | 120/min |
/swap/emergency | 30/min |
On a 429, back off exponentially and respect Retry-After.
Error handling
| Message | HTTP | Cause | What to do |
|---|---|---|---|
| Invalid signature | 401 | Wrong signing string, body hash mismatch, clock skew over 60 s, or a reused or missing nonce | Check the canonical format, sync the clock, generate a fresh nonce per request |
| Invalid credentials | 401 | Unknown key, disabled key, or an IP outside the whitelist. Deliberately indistinguishable | Check the key is active and the source IP is allowed |
| Missing required fields: … | 400 | Body incomplete or a field has the wrong type | Validate the payload before sending |
| Minimum is 100 TRX | 400 | Amount below the pair minimum | Show from.min from the quote or from /swap/pairs |
| Maximum right now is … | 400 | Output larger than Bitania's current liquidity in the destination coin | Offer a smaller amount or retry later |
| This pair is under maintenance | 400 | Pair or coin disabled | Hide the pair and refresh /swap/pairs |
| USDT payouts are temporarily unavailable | 400 | Our wallet for the destination coin is empty or unreachable; every pair paying it out closes automatically (available: false) | Hide the pair, refresh /swap/pairs and retry later |
| Pricing is temporarily unavailable | 400 | Price feed stale | Retry after a few seconds |
| That is not a valid USDT address | 400 | Bad destination or refund address for that chain | Validate addresses client-side and check the network |
| Fixed rate is not enabled for your API key | 400 | Fixed quote, or direction: "to", without the permission | Use floating with direction: "from", or ask support for the permission |
| Swap not found | 404 | Wrong id, or another key's swap without its token | Check the stored id, and send the token |
| Rate limit exceeded. Please retry after 12 seconds. | 429 | The endpoint's budget for your key is used up | Wait retry_after seconds, back off exponentially |
Dry-run mode
A full integration test against the live API with no blockchain involved. Dry-run swaps are quoted with the real market price and validated like real orders, but the deposit address is a dummy, nothing is watched and nothing is sent. Use it as your first step: it validates your signing, request format, response parsing and status-polling UI before you touch real crypto.
- Ask support for
dryrun_enabledon your key, then pass"dryrun": trueto/swap/create, alongside real swaps with the same credentials. - Dry-run swap ids start with
DR;data.dryrunis true in every response. - Nothing moves on its own:
/swap/advancesteps the swap forward one stage per call,NEW → PENDING → CONFIRMING → EXCHANGING → SENDING → DONE, filling in a fake deposit txid, confirmations, a fake output txid andrateActual. Advancing aDONEswap returns a 400. - There is no
RATE_CHANGED,REFUNDINGorEXPIRED, and nothing lands in your stats, volumes, earnings or in the partner panel. - Going live is removing
"dryrun": true.
# 1. Create dry-run swap
swap = swap_request("create", {
"type": "float",
"from": "BTC",
"to": "USDTTRC",
"amount": 0.1,
"direction": "from",
"toAddress": "TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr",
"dryrun": True,
})
swap_id = swap["data"]["id"]
assert swap["data"]["dryrun"] is True
assert swap_id.startswith("DR")
# 2. Advance through all stages
for expected in ["PENDING", "CONFIRMING", "EXCHANGING", "SENDING", "DONE"]:
result = swap_request("advance", {"id": swap_id})
assert result["data"]["status"] == expected
# 3. Verify final state
final = swap_request("status", {"id": swap_id})
assert final["data"]["status"] == "DONE"
assert final["data"]["to"]["tx"]["id"] is not None
print(f"Dry-run swap {swap_id} completed successfully")
Referral links
If you would rather send people to the site than call the API, link them with your ref code, shown in the partner panel.
https://bitania.com/?ref=your_refcode
Attribution is remembered in the visitor's browser for 30 days. Referred swaps show up in the same partner panel as API swaps, and earnings are credited when a swap completes.
Integration checklist
- Get credentials. Ask support for a
btn_key, abts_secret and a panel login. - Turn on dry-run. Request
dryrun_enabledon the key. - Implement HMAC v2 signing. Canonical string, fresh nonce, synced clock,
data=notjson=. - Test with dry-run swaps. Create, advance through every stage, check the final state.
- Cache currencies and pairs. Load them on startup, refresh every few hours and on maintenance errors.
- Build the quote flow. Show the output amount, the fee and the limits from the response.
- Build swap creation. Always send a refund address; store
idandtoken. - Build status polling. Every 10 to 30 seconds, with the countdown from
time.left; showurlto the user if you like. - Handle
RATE_CHANGEDandREFUNDING. Give the user the choice withproposed, collect a refund address whenissue.needsRefundAddressis true, or ask forauto_execute_on_mismatch. - Go live. Remove
"dryrun": true.
Contact support through the button in the header, on Telegram or over SimpleX, and ask for API credentials.