We offer Monero staking! Contact support.
Bitania API

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.

Base URLhttps://bitania.com Prefix/v1 MethodPOST on every endpoint AuthHMAC-SHA256 (v2) LiquidityBitania's own hot wallets (No AML swap)

Architecture overview

Partners only

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.

This is the No AML swap: our own hot wallet

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.

Your aggregatorBitania
Get quote
POST /swap/pricerate + amounts
Price at the live market rate, apply the service fee, check limits and liquidity.
Show to userCreate swap
POST /swap/createdeposit address
Generate a fresh deposit address, start the payment window.
User sends cryptoPoll status
POST /swap/statusDONE + tx hash
Detect and confirm the deposit, credit it at the applicable rate, send the output to the destination.
  1. Call /swap/price with the pair, the amount and the direction.
  2. Show the quote, including the output amount and the service fee.
  3. Call /swap/create with the destination address and a refund address.
  4. Show the deposit address and the time left in the payment window.
  5. Poll /swap/status every 10 to 30 seconds.
  6. Handle the terminal states: DONE, EXPIRED, REFUNDED.
  7. 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.

CodeCoinNetworkConfirmationsMinimumStatus
BTCBTCBitcoin network10.001 BTCavailable
LTCLTCLitecoin network20.1 LTCavailable
XMRXMRMonero network50.05 XMRavailable
ZECZECZcash network60.02 ZECtemporarily disabled
TRXTRXTron network20100 TRXavailable
ETHETHEthereum network120.01 ETHavailable
SOLSOLSolana network10.5 SOLavailable
AVAXAVAXAvalanche C-Chain301 AVAXavailable
USDTTRCUSDTTron (TRC20)2020 USDTavailable
USDTERCUSDTEthereum (ERC20)1250 USDTavailable
USDCERCUSDCEthereum (ERC20)1250 USDCavailable
USDCSOLUSDCSolana (SPL)120 USDCavailable
POST/v1/swap/currencies120/min

Returns 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.

POST/v1/swap/pairs120/min

Every 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   }
]
FieldTypeMeaning
from / tostringCurrency codes for the pair.
typestringAlways direct; kept for compatibility with older integrations.
viaarrayAlways empty.
availablebooleanFalse while the pair, or one of its coins, is under maintenance.
fixedbooleanWhether you may request fixed-rate quotes on it (your key's fixed_rate_enabled, and the pair available).
minnumberMinimum 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.

HeaderValue
X-API-KEYYour API key, in the form btn_…
X-API-SIGNThe signature, lowercase hex
X-API-TIMESTAMPUnix seconds, within 60 s of server time
X-API-NONCEUnique per request, never reused within 120 s
X-API-VERSIONOptional. 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)}
  • timestamp is the same value sent in X-API-TIMESTAMP.
  • METHOD is uppercase. Every endpoint is POST.
  • path includes the /v1 prefix, 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.

Three things reject a request
  • A clock more than 60 seconds out. Keep the machine NTP-synced; this is the usual cause of intermittent Invalid signature errors.
  • 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=, never json=).

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.

POST/v1/swap/price600/min

A 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.

FieldTypeMeaning
typestringoptionalfloat (default) or fixed; fixed needs fixed_rate_enabled on your key
fromstringrequiredSource currency code
tostringrequiredDestination currency code
amountnumberrequiredAmount in the direction currency (a numeric string is accepted too)
directionstringoptionalfrom (default) fixes the send amount, to fixes the receive amount and is always a fixed-rate quote
splitintegeroptionalQuote 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.min and from.max are the live limits; max follows Bitania's liquidity in the destination coin, so it moves (0 = no limit). to.min / to.max are their outputs.
  • fee is already deducted from to.amount. Display it from the response rather than hard-coding it.
  • guaranteedAmount is set on fixed-rate quotes; expiresIn is the payment window a swap created now would get, in seconds. slippage and bufferPercent are 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.
POST/v1/swap/create60/min201 Created

Creates 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.

FieldTypeMeaning
typestringoptionalfloat (default) or fixed
fromstringrequiredSource currency code
tostringrequiredDestination currency code
amountnumberrequiredAmount in the direction currency
directionstringoptionalfrom (default) or to; a to order is always fixed-rate
toAddressstringrequiredWhere the output goes; validated for the destination chain
refundAddressstringrecommendedWhere 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
dryrunbooleanoptionaltrue simulates the swap (DR-prefixed id, no chain interaction). Needs the dryrun_enabled permission
splitintegeroptionalSplit 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
addressesstring[]with splitThe 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 id and token. 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.left in seconds rather than hard-coding it; Bitania can tune it.
  • url is 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.
POST/v1/swap/status600/min

Where 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.

FieldTypeMeaning
idstringrequiredSwap id (10 characters; dry-run ids start with DR)
tokenstringoptionalPer-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-----..." } ]
  }
}
FieldWhen it appears
from.tx.id, from.tx.confirmationsOnce the deposit is detected
to.tx.idOnce the payout is sent; to.tx.confirmations keeps refreshing while you poll, to.tx.txKey on Monero is the payment proof
rateActualOn DONE, the rate actually applied
slippageOnce the deposit is credited: applied rate vs quoted rate in percent (0 on a fixed-rate swap honoured as quoted)
issue.typeOn a problem: LESS, MORE, LATE, BELOW_MINIMUM, NO_LIQUIDITY
issue.reasonWhile 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.needsRefundAddressWhen no refund address is on file and one is needed
proposed.amount, proposed.rateOn RATE_CHANGED, the re-quote
refund.tx.idOnce a refund is sent
time.leftWhile the payment window is still open
guaranteeOne PGP-clearsigned letter per step reached (created, deposit, paid, refunded)
deletedtrue 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
splitnull 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
dryrunOn simulated swaps

An unknown id and a swap you may not see both return 404 Swap not found.

POST/v1/swap/emergency30/minalias /v1/swap/resolve

Takes 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.

FieldTypeMeaning
idstringrequiredSwap id
choicestringrequiredEXCHANGE continues the swap at the current rate (proposed.rate) for the deposited amount, moving it to EXCHANGING; REFUND sends the full deposit back
addressstringconditionalRefund 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
tokenstringoptionalPer-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.

POST/v1/swap/advance120/mindry-run only

Steps 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
StatusMeaning
NEWCreated, waiting for the deposit; time.left counts down.
PENDINGDeposit seen, no confirmations yet.
CONFIRMINGConfirming on chain: from.tx.confirmations against from.reqConfirmations.
EXCHANGINGConfirmed and credited at the applicable rate; payout being prepared.
SENDINGPayout 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.
DONEFinished. to.tx.id and rateActual are set; on Ethereum, Avalanche and Zcash the payout has at least one confirmation.
EXPIREDWindow 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_CHANGEDFixed-rate deposit outside the ±0.5 % tolerance (LESS / MORE) or late (LATE). Needs EXCHANGE or REFUND.
REFUNDING / REFUNDEDSending 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.
FAILEDIn 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.

Enabled per key

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.

EndpointLimitBodyReturns
POST /v1/normal/currencies120/minnoneThe coins the partner lists (fewer than /swap/currencies); every one can be sent and received.
POST /v1/normal/pairs120/minnoneEvery 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/price600/minas /swap/priceThe partner's quote: from.amount, to.amount, rate (fee inside), rateType, refundAddressRequired, quoteValidFor.
POST /v1/normal/create60/minas /swap/create, no dryrun201 with the Normal swap object; from.address (and from.extraId when the chain needs a memo) is where the customer sends.
POST /v1/normal/status600/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 (refundAddressRequired in the quote), and a HOLD that 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_CHANGED state: a mismatching or late deposit is re-priced by the partner.
  • Normal swaps are not in /swap/status and classic swaps are not in /normal/status; keep the kind with 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: 0 is success, with HTTP 200, or 201 when a swap was created.
  • code: 1 is an error with the reason in msg and data: 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

FeeAmountWho pays
ServiceInside the rateAlready 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 sharePer API key: a share of the service fee, or a share of the volumeCredited to your partner account in USD when a swap completes; withdraw it in any supported coin at market rate, without a fee
Payout network feeWhatever the chain costsBitania. The amount quoted is the amount sent
RefundFreeThe 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.

EndpointLimit
/swap/currencies120/min
/swap/pairs120/min (one call returns every pair)
/swap/price600/min
/swap/create60/min
/swap/status600/min
/swap/advance120/min
/swap/emergency30/min

On a 429, back off exponentially and respect Retry-After.

Error handling

MessageHTTPCauseWhat to do
Invalid signature401Wrong signing string, body hash mismatch, clock skew over 60 s, or a reused or missing nonceCheck the canonical format, sync the clock, generate a fresh nonce per request
Invalid credentials401Unknown key, disabled key, or an IP outside the whitelist. Deliberately indistinguishableCheck the key is active and the source IP is allowed
Missing required fields: …400Body incomplete or a field has the wrong typeValidate the payload before sending
Minimum is 100 TRX400Amount below the pair minimumShow from.min from the quote or from /swap/pairs
Maximum right now is …400Output larger than Bitania's current liquidity in the destination coinOffer a smaller amount or retry later
This pair is under maintenance400Pair or coin disabledHide the pair and refresh /swap/pairs
USDT payouts are temporarily unavailable400Our 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 unavailable400Price feed staleRetry after a few seconds
That is not a valid USDT address400Bad destination or refund address for that chainValidate addresses client-side and check the network
Fixed rate is not enabled for your API key400Fixed quote, or direction: "to", without the permissionUse floating with direction: "from", or ask support for the permission
Swap not found404Wrong id, or another key's swap without its tokenCheck the stored id, and send the token
Rate limit exceeded. Please retry after 12 seconds.429The endpoint's budget for your key is used upWait 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_enabled on your key, then pass "dryrun": true to /swap/create, alongside real swaps with the same credentials.
  • Dry-run swap ids start with DR; data.dryrun is true in every response.
  • Nothing moves on its own: /swap/advance steps the swap forward one stage per call, NEW → PENDING → CONFIRMING → EXCHANGING → SENDING → DONE, filling in a fake deposit txid, confirmations, a fake output txid and rateActual. Advancing a DONE swap returns a 400.
  • There is no RATE_CHANGED, REFUNDING or EXPIRED, 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

  1. Get credentials. Ask support for a btn_ key, a bts_ secret and a panel login.
  2. Turn on dry-run. Request dryrun_enabled on the key.
  3. Implement HMAC v2 signing. Canonical string, fresh nonce, synced clock, data= not json=.
  4. Test with dry-run swaps. Create, advance through every stage, check the final state.
  5. Cache currencies and pairs. Load them on startup, refresh every few hours and on maintenance errors.
  6. Build the quote flow. Show the output amount, the fee and the limits from the response.
  7. Build swap creation. Always send a refund address; store id and token.
  8. Build status polling. Every 10 to 30 seconds, with the countdown from time.left; show url to the user if you like.
  9. Handle RATE_CHANGED and REFUNDING. Give the user the choice with proposed, collect a refund address when issue.needsRefundAddress is true, or ask for auto_execute_on_mismatch.
  10. Go live. Remove "dryrun": true.
Need a key?

Contact support through the button in the header, on Telegram or over SimpleX, and ask for API credentials.