> For the complete documentation index, see [llms.txt](https://ivorypay.gitbook.io/ivorypay-api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ivorypay.gitbook.io/ivorypay-api-documentation/merchant-endpoints/crypto-transfer.md).

# Crypto Transfer

Send cryptocurrency from your IvoryPay business wallet to any external blockchain address.

**Base path:** `/v1/crypto-transfer`\
**Authentication:** API Key (`Authorization: <secret-key>`)

***

## Endpoints

| Method | Path                                           | Description                          |
| ------ | ---------------------------------------------- | ------------------------------------ |
| `POST` | `/v1/crypto-transfer`                          | Initiate a crypto transfer           |
| `GET`  | `/v1/crypto-transfer/:token/networks`          | Get supported networks for a token   |
| `GET`  | `/v1/crypto-transfer/supported/network-tokens` | List all supported tokens & networks |

***

## POST `/v1/crypto-transfer`

Initiates an on-chain crypto transfer from your business wallet to a recipient address.

### Request

**Headers**

```http
Authorization: <your-secret-api-key>
Content-Type: application/json
```

**Body**

```json
{
  "network": "BSC_TESTNET",
  "address": "0xRecipientWalletAddress",
  "amount": 10.5,
  "token": "USDT",
  "reference": "550e8400-e29b-41d4-a716-446655440000"
}
```

| Field       | Type     | Required | Description                                                                  |
| ----------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `network`   | `string` | Yes      | Blockchain network. See [supported networks](#supported-values).             |
| `address`   | `string` | Yes      | Recipient's blockchain wallet address.                                       |
| `amount`    | `number` | Yes      | Amount to send in the specified token. Must be a positive number.            |
| `token`     | `string` | Yes      | Cryptocurrency token to send. See [supported tokens](#supported-values).     |
| `reference` | `string` | Yes      | Your unique identifier for this transfer. Used for idempotency and tracking. |

### Response

```json
{
  "status": true,
  "message": "Your crypto payout request has been initiated",
  "data": {
    "id": "uuid",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 10.5,
    "token": "USDT",
    "network": "BSC_TESTNET",
    "address": "0xRecipientWalletAddress",
    "status": "PENDING",
    "businessId": "uuid",
    "createdAt": "2026-02-19T10:00:00.000Z"
  }
}
```

### Error Responses

| Status | Message                            | Cause                      |
| ------ | ---------------------------------- | -------------------------- |
| `400`  | `Insufficient balance`             | Wallet balance too low     |
| `400`  | `network chain must be one of ...` | Invalid `network` value    |
| `400`  | `token must be one of ...`         | Invalid `token` value      |
| `401`  | `Unauthorized`                     | Missing or invalid API key |

***

## GET `/v1/crypto-transfer/:token/networks`

Returns the list of blockchain networks available for a specific token in your current environment.

### Request

**Headers**

```http
Authorization: <your-secret-api-key>
```

**Path Parameters**

| Parameter | Type     | Description                               |
| --------- | -------- | ----------------------------------------- |
| `token`   | `string` | Token symbol (e.g. `USDT`, `USDC`, `BTC`) |

### Example

```http
GET /v1/crypto-transfer/USDT/networks
Authorization: live_sk_xxxxxxxxxxxx
```

### Response

```json
{
  "status": true,
  "message": "Query successful",
  "data": [
    {
      "network": "BSC_TESTNET",
      "token": "USDT",
      "isSupported": true
    },
    {
      "network": "SOLANA",
      "token": "USDT",
      "isSupported": true
    }
  ]
}
```

***

## GET `/v1/crypto-transfer/supported/network-tokens`

Returns all tokens and their associated blockchain networks that your business can send from. This reflects your business's currently enabled tokens.

### Request

**Headers**

```http
Authorization: <your-secret-api-key>
```

### Response

```json
{
  "status": true,
  "message": "Default Tokens fetched successfully",
  "data": [
    {
      "token": "USDT",
      "network": "BSC_TESTNET",
      "isSupported": true
    },
    {
      "token": "USDC",
      "network": "SOLANA",
      "isSupported": true
    },
    {
      "token": "BTC",
      "network": "BITCOIN",
      "isSupported": true
    }
  ]
}
```

***

## Supported Values

### `token`

| Value  | Name       |
| ------ | ---------- |
| `USDT` | Tether USD |
| `USDC` | USD Coin   |
| `BTC`  | Bitcoin    |
| `ETH`  | Ethereum   |
| `SOL`  | Solana     |

### `network`

| Value         | Chain           |
| ------------- | --------------- |
| `BSC_TESTNET` | BNB Smart Chain |
| `MAINNET`     | Ethereum        |
| `POLYGON`     | Polygon         |
| `SOLANA`      | Solana          |
| `BITCOIN`     | Bitcoin         |

> Use [`GET /v1/crypto-transfer/supported/network-tokens`](#get-v1crypto-transfersupportednetwork-tokens) to see the exact tokens and networks enabled for your account.

***

## Transfer Lifecycle

```
PENDING → PROCESSING → SUCCESS
                    ↘ FAILED
```

| Status       | Description                                            |
| ------------ | ------------------------------------------------------ |
| `PENDING`    | Transfer created, waiting to be sent to the blockchain |
| `PROCESSING` | Broadcast to the blockchain, awaiting confirmation     |
| `SUCCESS`    | Confirmed on-chain, wallet debited                     |
| `FAILED`     | Transfer failed — no funds deducted                    |

Subscribe to [webhook events](/ivorypay-api-documentation/transactions/webhooks.md) to receive real-time status updates.

***

## Code Examples

### Node.js

```javascript
const axios = require('axios');

const BASE_URL = 'https://api.ivorypay.io/api/v1';

const response = await axios.post(`${BASE_URL}/crypto-transfer`, {
  network: 'BSC_TESTNET',
  address: '0xRecipientAddress',
  amount: 10.5,
  token: 'USDT',
  reference: '550e8400-e29b-41d4-a716-446655440000',
}, {
  headers: {
    Authorization: process.env.IVORYPAY_SECRET_KEY,
    'Content-Type': 'application/json',
  },
});

console.log(response.data);
```

### cURL

```bash
BASE_URL="https://api.ivorypay.io/api/v1"

curl -X POST $BASE_URL/crypto-transfer \
  -H "Authorization: live_sk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "BSC_TESTNET",
    "address": "0xRecipientAddress",
    "amount": 10.5,
    "token": "USDT",
    "reference": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

### Python

```python
import requests

BASE_URL = 'https://api.ivorypay.io/api/v1'

response = requests.post(
    f'{BASE_URL}/crypto-transfer',
    json={
        'network': 'BSC_TESTNET',
        'address': '0xRecipientAddress',
        'amount': 10.5,
        'token': 'USDT',
        'reference': '550e8400-e29b-41d4-a716-446655440000',
    },
    headers={
        'Authorization': 'live_sk_xxxxxxxxxxxx',
        'Content-Type': 'application/json',
    }
)

print(response.json())
```