Product · Digital Assets

Crypto Trading

Programmatically buy and sell Bitcoin, Ethereum, USDT, and USDC with institutional liquidity, real-time rate feeds, multi-network settlement, and webhook trade callbacks.

Base Path/api/v1/partner/crypto

Authx-api-key (+ x-signature on buy/sell)

Supported AssetsBTC, ETH, USDT (TRC20, ERC20, BEP20), USDC

Webhookscrypto.purchase.success · crypto.sale.approved · crypto.sale.declined

1. Asset Catalog & Rates

List supported cryptocurrencies

GET /partner/crypto

API Key only

cURL

curl https://api.billpadi.com/api/v1/partner/crypto \
  -H "x-api-key: $API_KEY"

Example response — 200 OK

{
  "success": true,
  "message": "Cryptocurrencies retrieved successfully",
  "data": [
    {
      "id": "665f3a019e1b2c0012a4ec01",
      "name": "Tether USD",
      "symbol": "USDT",
      "networks": [
        { "id": "net_trc20", "name": "TRC20 (Tron)", "fee": 1.0 },
        { "id": "net_bep20", "name": "BEP20 (BNB Smart Chain)", "fee": 0.5 },
        { "id": "net_erc20", "name": "ERC20 (Ethereum)", "fee": 5.0 }
      ],
      "minBuy": 10,
      "maxBuy": 50000,
      "minSell": 10,
      "maxSell": 50000
    }
  ],
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/crypto"
}

Get real-time exchange rates

GET /partner/crypto/rates

API Key only

cURL

curl https://api.billpadi.com/api/v1/partner/crypto/rates \
  -H "x-api-key: $API_KEY"

Example response — 200 OK

{
  "success": true,
  "message": "Crypto rates retrieved successfully",
  "data": [
    {
      "cryptoId": "665f3a019e1b2c0012a4ec01",
      "symbol": "USDT",
      "buyRate": 1580.50,
      "sellRate": 1565.00,
      "currency": "NGN"
    }
  ],
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/crypto/rates"
}

2. Calculate Trade Breakdown

Preview exact costs, network fees, and conversion amounts before placing a live order:

Calculate rate & fee breakdown

POST /partner/crypto/breakdown

API Key only

Field	Type	Required	Description
cryptoId	string (ObjectId)	required	24-character hexadecimal ID of the cryptocurrency
tradeType	string	required	`buy` or `sell`
networkId	string	required	Selected blockchain network (e.g. `net_trc20`)
cryptoAmount	number	either/or	Amount in crypto units (e.g. `100`)
amount	number	either/or	Amount in NGN fiat (alternative to cryptoAmount)

cURL

curl -X POST https://api.billpadi.com/api/v1/partner/crypto/breakdown \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{
    "cryptoId": "665f3a019e1b2c0012a4ec01",
    "tradeType": "buy",
    "networkId": "net_trc20",
    "cryptoAmount": 100
  }'

Example response — 200 OK

{
  "success": true,
  "message": "Breakdown calculated successfully",
  "data": {
    "cryptoAmount": 100,
    "fiatAmount": 158050.00,
    "rate": 1580.50,
    "networkFee": 1.0,
    "totalCost": 159630.50
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/crypto/breakdown"
}

3. Buy Crypto

Purchase crypto using your partner NGN wallet balance and disburse it to an external destination blockchain address:

Execute crypto purchase

POST /partner/crypto/buy

Signature required

Field	Type	Required	Description
cryptoId	string (ObjectId)	required	24-character hexadecimal ID
networkId	string	required	Blockchain network ID
walletAddress	string	required	Destination blockchain wallet address
cryptoAmount	number	either/or	Crypto units to buy
amount	number	either/or	Equivalent NGN fiat to spend
partnerReference	string	required	Unique reference for idempotency

cURL

curl -X POST https://api.billpadi.com/api/v1/partner/crypto/buy \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "cryptoId": "665f3a019e1b2c0012a4ec01",
    "networkId": "net_trc20",
    "walletAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "cryptoAmount": 100,
    "partnerReference": "CRYPTO-BUY-9921"
  }'

Example response — 200 OK

{
  "success": true,
  "message": "Crypto purchase initiated successfully",
  "data": {
    "reference": "CRYPTO_1720603200000_AA1",
    "partnerReference": "CRYPTO-BUY-9921",
    "status": "pending",
    "cryptoAmount": 100,
    "fiatAmount": 158050.00,
    "walletAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "network": "TRC20"
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/crypto/buy"
}

4. Sell Crypto

Initiate a sell order to receive a dedicated deposit address. Once the crypto arrives on-chain and confirms, your NGN wallet is automatically credited:

Initiate crypto sale

POST /partner/crypto/sell

Signature required

Field	Type	Required	Description
cryptoId	string (ObjectId)	required	24-character hexadecimal ID
networkId	string	required	Deposit blockchain network
cryptoAmount	number	either/or	Crypto units to sell
amount	number	either/or	Equivalent NGN fiat expected
bankAccountId	string	optional	Optional saved payout account (if disbursing directly to bank)
partnerReference	string	required	Unique reference for idempotency

cURL

curl -X POST https://api.billpadi.com/api/v1/partner/crypto/sell \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d '{
    "cryptoId": "665f3a019e1b2c0012a4ec01",
    "networkId": "net_trc20",
    "cryptoAmount": 250,
    "partnerReference": "CRYPTO-SELL-7712"
  }'

Example response — 200 OK

{
  "success": true,
  "message": "Crypto sale initiated. Send crypto to the provided deposit address.",
  "data": {
    "reference": "CRYPTO_1720603200000_BB2",
    "partnerReference": "CRYPTO-SELL-7712",
    "status": "pending",
    "depositAddress": "TJYeK2khEsLJW1ChVWFMSMeRDow5KcbXYZ",
    "cryptoAmount": 250,
    "fiatAmount": 391250.00,
    "rate": 1565.00
  },
  "timestamp": "2026-07-10T09:20:03.000Z",
  "path": "/api/v1/partner/crypto/sell"
}

5. Crypto Transaction Status & Listing

Get crypto trade status

GET /partner/crypto/transactions/:reference

API Key only

List crypto transactions

GET /partner/crypto/transactions

API Key only

← PreviousGift Cards Next →International Top-Up