Buy and sell crypto for your customers

Check rates, request quotes, then buy or sell crypto for a customer. Naira moves through your wallet and the crypto belongs to the customer.

To trade crypto for a customer, you check rates, ask for a quote, and then place a buy or a sell. Naira moves through your wallet, and the crypto belongs to the customer.

Check rates

Crypto rates returns the naira price per US dollar for each coin. buy_rate is what a customer pays, and sell_rate is what they receive. Rates are indicative, so use the quote endpoints when you need exact amounts.

Get a quote

Quotes tell you the result of a trade before you place it.

Quote	Endpoint	You send	You get
Sale	POST /quotes/sell	Crypto amount, up to 8 decimal places	Naira you would receive
Purchase	POST /quotes/buy	Naira amount, up to 2 decimal places	Crypto you would get

curl -X POST https://merchant.bitliva.com/api/v1/quotes/buy \
  -H "Authorization: Bearer $BITLIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency": "btc", "amount": "100000.00"}'

{
  "status": "success",
  "message": "Quotation retrieved successfully.",
  "data": {
    "from_amount": "100000.00",
    "from_currency": "NGN",
    "to_amount": "0.00098019",
    "to_currency": "BTC"
  }
}

Sell crypto

POST /crypto/sell sells crypto that the customer already holds. The minimum sale is ₦1,500.00.

curl -X POST https://merchant.bitliva.com/api/v1/crypto/sell \
  -H "Authorization: Bearer $BITLIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "2f6d1c0a-8a3e-4d59-b8a1-71e0c4d5f9a3",
    "currency": "btc",
    "amount": "0.001",
    "reference": "order-1042"
  }'

Buy crypto

POST /crypto/buy pays naira from your wallet and credits the crypto to the customer. The customer needs an address for that coin first. A purchase can stay pending briefly, and the webhook fires when it completes.

curl -X POST https://merchant.bitliva.com/api/v1/crypto/buy \
  -H "Authorization: Bearer $BITLIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "2f6d1c0a-8a3e-4d59-b8a1-71e0c4d5f9a3",
    "currency": "btc",
    "amount": "100000.00",
    "reference": "order-1043"
  }'

Use a unique reference

Both calls require a reference, up to 64 letters, numbers and . _ : -. Sending the same reference again returns the original trade instead of doing it twice. Reusing a reference for a different request returns reference_conflict.

Common errors

code	When it happens
unsupported_currency	The coin is not one of btc, eth, usdt, sol, trx, bnb, ltc or usdc.
amount_below_minimum	The amount is zero or below the minimum. The message states the minimum.
insufficient_crypto_balance	The customer does not hold enough of that coin for a sale.
sale_not_possible	The sale could not start, usually because the balance is too low or the amount is too small to price.
insufficient_wallet_balance	Your naira wallet cannot cover the purchase. Top up in the dashboard.
address_required	The customer has no address for that coin. Generate one and retry.

Trades finish with a transaction.successful or transaction.failed webhook. If a trade fails, any money held for it is returned.