# Bitnob API Documentation

> Bitnob provides APIs for Bitcoin, stablecoin (USDT/USDC), and fiat payment infrastructure across Africa. Build payouts, trading, virtual accounts, virtual cards, lightning payments, and wallet management into your applications.

## Documentation Sections

- [Getting Started](https://docs.bitnob.co/docs/genesis): Overview, quickstart, and authentication
- [Quickstart](https://docs.bitnob.co/docs/quickstart): Get from zero to first API call
- [Authentication](https://docs.bitnob.co/docs/authentication): HMAC-SHA256 request signing and API credentials
- [Stablecoins](https://docs.bitnob.co/docs/stablecoins): USDT and USDC deposits and withdrawals
- [Payouts](https://docs.bitnob.co/docs/payouts): Send payments to bank accounts, mobile money, and crypto addresses
- [Card Issuing](https://docs.bitnob.co/docs/card-issuing): Virtual card creation and management
- [Trading](https://docs.bitnob.co/docs/trading): Convert between USDT, USDC, BTC, and NGN
- [Virtual Accounts](https://docs.bitnob.co/docs/virtual-accounts): Nigerian bank account numbers that fund your NGN balance
- [Developer Resources](https://docs.bitnob.co/docs/developer-resources): Postman collection, OpenAPI spec, tools, and guides

## API Reference

- [Authentication](https://docs.bitnob.co/api-reference/authentication): HMAC request signing, Who Am I
- [Webhook Verification](https://docs.bitnob.co/api-reference/authentication/webhook-verification): Verify x-bitnob-signature (HMAC-SHA512 over the raw body), retries, de-duplication, Node/Python/Go examples
- [Wallets](https://docs.bitnob.co/api-reference/wallets): Get Balances, Get Balance By Currency
- [Transactions](https://docs.bitnob.co/api-reference/transactions): Get Transactions, Get Transaction By ID Or Reference
- [Addresses](https://docs.bitnob.co/api-reference/addresses): Generate, List, Get, Validate Addresses, Supported Chains
- [Withdrawal](https://docs.bitnob.co/api-reference/withdrawal): Create Withdrawal (single step)
- [Exchange Rates](https://docs.bitnob.co/api-reference/exchange-rates): Get Rate, List Rates, Convert Amount
- [Trading](https://docs.bitnob.co/api-reference/trading): Get Prices, Create Quote, Get Quote, Create Order, Get Orders, Get Order, Cancel Order
- [Virtual Accounts](https://docs.bitnob.co/api-reference/virtual-accounts): Create, List, Get, Transactions, Update Alias, Simulate Deposit
- [Customers](https://docs.bitnob.co/api-reference/customers): Create, List, Get, Update Customers
- [Virtual Cards](https://docs.bitnob.co/api-reference/virtual-cards): Create Card, Fund or Withdraw, Freeze/Unfreeze, Terminate, Card Transactions
- [Payouts](https://docs.bitnob.co/api-reference/payouts): Quote, Initialize, Finalize, Get Payouts, Supported Countries
- [Bulk Transfers](https://docs.bitnob.co/api-reference/bulk-transfers): Create, Confirm, Retry Batches
- [Lightning](https://docs.bitnob.co/api-reference/lightning): Create Invoice, Decode, Preview, Pay
- [Beneficiary](https://docs.bitnob.co/api-reference/beneficiary): Beneficiary management

## Base URLs

- Sandbox: https://api.bitnob.com
- Production: https://api.bitnob.com

The host is the same for both. The environment is selected by which client secret signs the request; the client ID is the same in both.

## Authentication

All requests require HMAC-SHA256 signature authentication with four headers:
- `x-auth-client`: Your Client ID
- `x-auth-timestamp`: Unix timestamp in seconds
- `x-auth-nonce`: Unique random value per request (16-byte hex or UUID)
- `x-auth-signature`: Hex-encoded HMAC-SHA256 of `CLIENT_ID:TIMESTAMP:NONCE:BODY`, keyed with your client secret

`BODY` is the exact request body string, or empty for GET requests. There is no single API-key header.

## Amount units

- Trading `quantity` is a string in major units of the base currency: "0.001" BTC, "100" USDT, "5000" naira.
- Balances, transactions, withdrawals and webhooks use base units as integer strings: 6-decimal units for USDT/USDC (1 USDT = 1000000), satoshis for BTC, kobo for NGN.

## Webhooks

Webhooks are signed with HMAC-SHA512 over the raw request body, sent in the `x-bitnob-signature` header and keyed with your webhook secret.

## Errors and rate limits

- Errors are RFC 7807 objects (`type`, `title`, `status`, `detail`, `code`, `correlation_id`, `request_id`); request-shape validation errors return `{"success": false, "error": {"code", "message", "details"}}`.
- Rate limit: 500 requests per minute per client IP address. Responses carry `X-Ratelimit-Limit`, `X-Ratelimit-Remaining`, `X-Ratelimit-Reset`.

## OpenAPI Specification

Available at: https://docs.bitnob.co/api-collections/swagger/bitnob-api-v2.openapi.json