Get swap quote

Get an exchange rate quote for a currency pair. The rate is Bitania's live mid-market price (the median of several exchanges, refreshed every 10 seconds); the quoted output already has the service fee taken off and nothing else is deducted — the network fee of the payout is paid by Bitania. 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 to your users is final.

Rate types:

• float — 0.25 % fee. The output is an estimate: the deposit is converted at the market rate of the moment it confirms, and the response's slippage on the swap shows the difference afterwards.
• fixed — 0.5 % fee. The output is guaranteed for the payment window (guaranteedAmount) as long as the user sends the quoted amount (±0.5 %). Requires fixed_rate_enabled on your API key.

Direction:

• from — specify how much the user sends (e.g. 0.5 BTC), the API returns how much they receive
• to — specify how much the user wants to receive (e.g. 10000 USDT), the API returns how much they must send. A quote by receive amount is always fixed-rate (the user asked for an exact amount), so it needs fixed rate enabled on your key.

Authentication: HMAC-signed (v2) request — X-API-KEY, X-API-SIGN, X-API-TIMESTAMP, X-API-NONCE headers. See the Swap Aggregator Guide for the signing scheme.

Request

Request Body (required)

Content-Type: application/json

{
  type: string, enum: float|fixed, default "float" — Rate type
  from: string, required, e.g. "BTC" — Source currency code (see /swap/currencies)
  to: string, required, e.g. "USDTTRC" — Destination currency code
  direction: string, enum: from|to, default "from" — 'from' (send amount) or 'to' (receive amount)
  amount: number, required, e.g. 0.5 — Amount in the direction currency (a numeric string is accepted too)
}

Response 200

Success

{
  code: integer, e.g. 0 — 0 = success, 1 = error
  msg: string, e.g. "" — Error message (empty on success)
  data: object — Quote details
    {
      from: object — Source currency — what the user sends
        {
          code: string, e.g. "BTC" — Currency code
          coin: string, e.g. "BTC" — Coin ticker
          network: string, e.g. "BTC" — Chain
          name: string, e.g. "Bitcoin" — Display name
          amount: number, e.g. 0.5 — Amount in this currency
          rate: number, e.g. 87150.42 — How much `to` you get per 1 unit of `from`
          precision: integer, e.g. 8 — Decimal precision for amounts in this currency
          min: number, e.g. 0.001 — Minimum send amount for this pair
          max: number, e.g. 2.5 — Maximum send amount right now: the liquidity we make available for the pair (0 = no limit)
          usd: number, e.g. 43575.21 — USD value of the amount at current prices
        }
      to: object — Destination currency — what the user receives
        {
          code, coin, network, name, precision — as in from
          amount: number, e.g. 43466.28 — Output amount after the service fee
          rate: number, e.g. 0.0000114744 — The inverse rate (`from` per 1 `to`)
          min: number — Output of the minimum send amount
          max: number — Output of the maximum send amount (0 = no limit)
          usd: number — USD value of the output
        }
      fee: object — Fee breakdown
        {
          percent: number, e.g. 0.25 — Total percentage deducted: service fee (0.25 float, 0.5 fixed) plus your volume share, if your agreement has one
          partnerPercent: number, e.g. 0 — The part of "percent" that is your own volume share (0 on a fee-share agreement)
          amount: number, e.g. 108.94 — Absolute fee amount in the destination currency
        }
      errors: array, e.g. [] — Always empty: a quote that violates a rule is a 400 with the reason in msg
      slippage: number, e.g. 0 — Always 0: there is no order book to walk
      rateType: string, enum: float|fixed — Rate type used for this quote
      bufferPercent: number, e.g. 0 — Always 0: the fixed-rate margin is in the fee, not in the rate
      guaranteedAmount: number|null — Guaranteed output amount for fixed-rate quotes, null for float
      expiresIn: integer, e.g. 3600 — Payment window a swap created now would get, in seconds
    }
}

Response 400

Validation or business error, for example: Minimum is 100 TRX, Maximum right now is 2.1 BTC (limited by our USDT liquidity), 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

{
  code: integer, e.g. 1 — Error code (1)
  msg: string, e.g. "Missing required fields: from, to, amount" — Error message
  data: null
}

Response 401

Authentication failed: unknown or disabled key, IP not whitelisted (Invalid credentials), or a bad signature, stale timestamp or reused nonce (Invalid signature)

{
  code: integer, e.g. 1
  msg: string, e.g. "Invalid credentials"
  data: null
}

Response 429

Rate limit of this endpoint exhausted; wait retry_after seconds (also sent as the Retry-After header)

{
  code: integer, e.g. 1
  msg: string, e.g. "Rate limit exceeded. Please retry after 12 seconds."
  data: null
  retry_after: integer, e.g. 12
}