> 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/transactions/supported-tokens.md).

# Supported Tokens & Networks

Use these endpoints to discover which tokens and blockchain networks are enabled for your business. Call them before initiating a payment to dynamically populate your token/network selection UI rather than hardcoding values.

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

***

## Endpoints

| Method | Path                                  | Auth    | Description                                            |
| ------ | ------------------------------------- | ------- | ------------------------------------------------------ |
| `GET`  | `/v1/tokens/supported/network-tokens` | API Key | List all tokens and networks enabled for your business |
| `GET`  | `/v1/tokens/networks/:token`          | API Key | Get available networks for a specific token            |

***

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

Returns all token–network combinations currently enabled for your business, grouped by network. The result is scoped to your API key's environment (TEST or LIVE).

Use this to build a dynamic token selector in your checkout UI.

### Request

**Headers**

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

### Example

```http
GET /v1/tokens/supported/network-tokens
Authorization: sk_xxxxxxxxxxxx
```

### Response

```json
{
  "success": true,
  "message": "Default Tokens fetched successfully",
  "data": {
    "Binance Smart Chain": [
      {
        "token": "USDT",
        "tokenId": "uuid",
        "blockchain": "BSC_TESTNET",
        "isActive": true
      },
      {
        "token": "USDC",
        "tokenId": "uuid",
        "blockchain": "BSC_TESTNET",
        "isActive": true
      }
    ],
    "Polygon": [
      {
        "token": "USDT",
        "tokenId": "uuid",
        "blockchain": "POLYGON",
        "isActive": true
      }
    ]
  }
}
```

**Response fields**

| Field        | Type      | Description                                                         |
| ------------ | --------- | ------------------------------------------------------------------- |
| `data`       | `object`  | Keys are network display names. Values are arrays of token objects. |
| `token`      | `string`  | Token symbol (e.g. `USDT`). Pass this as `crypto` in transactions.  |
| `tokenId`    | `string`  | Internal token ID.                                                  |
| `blockchain` | `string`  | Blockchain enum value (e.g. `BSC_TESTNET`). Pass this as `chain`.   |
| `isActive`   | `boolean` | Whether this token is currently active for your business.           |

> Only tokens where `isActive: true` should be presented to your customers.

***

## GET `/v1/tokens/networks/:token`

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

Use this to populate a network dropdown after the user selects a token.

### Request

**Headers**

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

**Path Parameters**

| Parameter | Type     | Description                             |
| --------- | -------- | --------------------------------------- |
| `token`   | `string` | Token symbol in uppercase (e.g. `USDT`) |

### Example

```http
GET /v1/tokens/networks/USDT
Authorization: sk_xxxxxxxxxxxx
```

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

curl $BASE_URL/tokens/networks/USDT \
  -H "Authorization: sk_xxxxxxxxxxxx"
```

### Response

```json
{
  "success": true,
  "message": "Query successful",
  "data": [
    {
      "uuid": "30ea1c20-a7f4-4a9f-81ef-affb15ed625d",
      "createdAt": "2026-02-04T16:24:55.641Z",
      "updatedAt": "2026-02-04T16:24:55.641Z",
      "name": "BSC",
      "network": "BSC_TESTNET",
      "isSupported": true,
      "walletAddress": null,
      "context": "TEST"
    }
  ]
}
```

**Response fields**

| Field           | Type      | Description                                                |
| --------------- | --------- | ---------------------------------------------------------- |
| `uuid`          | `string`  | Unique ID of the network record.                           |
| `name`          | `string`  | Human-readable network name (e.g. `BSC`).                  |
| `network`       | `string`  | Network enum value. Pass this as `chain` in transactions.  |
| `isSupported`   | `boolean` | Whether this network is currently supported for the token. |
| `walletAddress` | `string`  | Pre-assigned wallet address on this network, if any.       |
| `context`       | `string`  | Environment this network belongs to — `TEST` or `LIVE`.    |
| `createdAt`     | `string`  | ISO timestamp when the network record was created.         |

### Error Responses

| Status | Message         | Cause                       |
| ------ | --------------- | --------------------------- |
| `400`  | `Invalid token` | Token symbol not recognised |
| `401`  | `Unauthorized`  | Missing or invalid API key  |

***

## Recommended Integration Pattern

```
1. On page load → GET /v1/tokens/supported/network-tokens
   → Populate token selector with tokens where isActive: true

2. On token selected → GET /v1/tokens/networks/:token
   → Populate network selector with returned networks

3. On confirm → POST /v1/transactions
   → Pass selected token as `crypto` and selected blockchain as `chain`
```

***

## Code Examples

### Node.js

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

const BASE_URL = 'https://api.ivorypay.io/api/v1';
const headers = { Authorization: process.env.IVORYPAY_SECRET_KEY };

// Step 1: Get all supported tokens grouped by network
const { data: tokenData } = await axios.get(
  `${BASE_URL}/tokens/supported/network-tokens`,
  { headers },
);

// tokenData.data is an object keyed by network name
const networks = Object.entries(tokenData.data);
console.log('Supported networks and tokens:', networks);

// Step 2: Get available networks for USDT specifically
const { data: networkData } = await axios.get(
  `${BASE_URL}/tokens/networks/USDT`,
  { headers },
);

console.log('USDT networks:', networkData.data);
// → [{ blockchain: 'BSC_TESTNET', token: 'USDT', isSupported: true, ... }]
```

### cURL

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

# List all supported token–network combinations
curl $BASE_URL/tokens/supported/network-tokens \
  -H "Authorization: sk_xxxxxxxxxxxx"

# Get networks available for USDT
curl $BASE_URL/tokens/networks/USDT \
  -H "Authorization: sk_xxxxxxxxxxxx"
```