> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitliva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.bitliva.com/api-reference/rates-crypto.md) 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`](https://docs.bitliva.com/api-reference/quotes-sell) | Crypto `amount`, up to 8 decimal places | Naira you would receive |
| Purchase | [`POST /quotes/buy`](https://docs.bitliva.com/api-reference/quotes-buy) | Naira `amount`, up to 2 decimal places | Crypto you would get |

```bash theme={null}
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"}'
```

```json theme={null}
{
  "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`](https://docs.bitliva.com/api-reference/crypto-sell) sells crypto that the customer already holds. The minimum sale is ₦1,500.00.

```bash theme={null}
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`](https://docs.bitliva.com/api-reference/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.

```bash theme={null}
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](https://docs.bitliva.com/guides/customers-and-wallets.md) and retry. |

Trades finish with a [`transaction.successful` or `transaction.failed` webhook](https://docs.bitliva.com/guides/webhooks). If a trade fails, any money held for it is returned.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.