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

# Quickstart: make your first crypto sale in the sandbox

> Create a customer, generate a USDT address, simulate a deposit and sell the crypto for naira in the Bitliva sandbox with curl, step by step.

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.

> [!NOTE]
>
> 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.

**1. Set your API key**

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

```bash theme={null}
export BITLIVA_API_KEY="your_api_key"
export BITLIVA_URL="https://merchant.bitliva.com/api/v1"
```

**2. Check that your key works**

```bash theme={null}
curl "$BITLIVA_URL/me" \
  -H "Authorization: Bearer $BITLIVA_API_KEY"
```

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

**3. Create a customer**

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

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

```json theme={null}
{
  "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`:

```bash theme={null}
export CUSTOMER_ID="2f6d1c0a-8a3e-4d59-b8a1-71e0c4d5f9a3"
```

**4. Generate a deposit address and simulate a deposit**

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

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

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

**5. Confirm the balance**

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

**6. Quote the sale**

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

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

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

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

## Next steps

> [card] [Handle webhooks](https://docs.bitliva.com/guides/webhooks.md)
>
> Verify signatures and react to transaction events.

> [card] [Buy and sell crypto](https://docs.bitliva.com/guides/buy-and-sell-crypto.md)
>
> Learn how rates, quotes, purchases and sales fit together.


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