Quickstart: make your first crypto sale in the sandbox

This quickstart walks through a complete flow with the Bitliva Merchant API: create a customer, generate a USDT address, simulate a deposit in the sandbox, and sell that USDT for naira. Each step is a single curl call.

The deposit helper used in step 4 only exists in the sandbox. The mode field returned by GET /me tells you whether your key is running in test or live mode.

Set your API key

Export your API key and the base URL so the later commands stay short.

export BITLIVA_API_KEY="your_api_key"
export BITLIVA_URL="https://merchant.bitliva.com/api/v1"

Check that your key works

curl "$BITLIVA_URL/me" \
  -H "Authorization: Bearer $BITLIVA_API_KEY"

{
  "status": "success",
  "message": "Merchant retrieved successfully.",
  "data": {
    "merchant_code": "BITLIVA-K3M9X2QA",
    "mode": "test",
    "status": "approved"
  }
}

Create a customer

Send your own id for the user as reference. Sending the same reference again returns the same customer.

curl -X POST "$BITLIVA_URL/customers" \
  -H "Authorization: Bearer $BITLIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference": "user_1042", "first_name": "Ada", "last_name": "Obi"}'

{
  "status": "success",
  "message": "Customer created successfully.",
  "data": {
    "customer": {
      "id": "2f6d1c0a-8a3e-4d59-b8a1-71e0c4d5f9a3",
      "reference": "user_1042",
      "first_name": "Ada",
      "last_name": "Obi",
      "created_at": "2026-10-18T09:00:00+01:00"
    }
  }
}

Save the customer id:

export CUSTOMER_ID="2f6d1c0a-8a3e-4d59-b8a1-71e0c4d5f9a3"

Generate a deposit address and simulate a deposit

USDT needs a network. This creates a TRC20 address for the customer.

curl -X POST "$BITLIVA_URL/customers/$CUSTOMER_ID/wallets" \
  -H "Authorization: Bearer $BITLIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency": "usdt", "network": "trc20"}'

Now credit the customer’s test balance with 25 USDT. This also fires the crypto.deposit.received webhook.

curl -X POST "$BITLIVA_URL/sandbox/customers/$CUSTOMER_ID/deposits" \
  -H "Authorization: Bearer $BITLIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency": "usdt", "network": "trc20", "amount": 25}'

Confirm the balance

curl "$BITLIVA_URL/customers/$CUSTOMER_ID/balances" \
  -H "Authorization: Bearer $BITLIVA_API_KEY"

The balances array now lists usdt with a balance of 25.00000000.

Quote the sale

Ask what 25 USDT is worth in naira before you commit.

curl -X POST "$BITLIVA_URL/quotes/sell" \
  -H "Authorization: Bearer $BITLIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"currency": "usdt", "amount": "25"}'

The response returns from_amount, from_currency, to_amount and to_currency.

Sell the crypto

Send a unique reference for the sale. If you repeat the call with the same reference, you get the original sale back instead of selling twice.

curl -X POST "$BITLIVA_URL/crypto/sell" \
  -H "Authorization: Bearer $BITLIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "'"$CUSTOMER_ID"'",
    "currency": "usdt",
    "amount": "25",
    "reference": "order-1042"
  }'

The 201 response contains a transaction with type set to crypto_sell and status set to successful. The minimum sale is ₦1,500.00.

Get started

Guides

Quickstart: make your first crypto sale in the sandbox

Next steps

Handle webhooks

Buy and sell crypto

​Next steps

Handle webhooks

Buy and sell crypto

Next steps