Blockchain Address

Generate a permanent, dedicated blockchain wallet address for a specific customer. Unlike payment collection addresses (which are one-time), these addresses are persistent — the same customer always gets the same address on a given blockchain and token combination.

Base path: /v1/blockchain-accounts Authentication: API Key (Authorization: <secret-key>)

---

When to Use This

Use this endpoint when you want to assign a dedicated deposit address to a customer — for example, to enable top-ups, recurring deposits, or on-chain identity tracking. The address is unique per customer × blockchain × token combination and is reused across calls (idempotent).

For one-time checkout payments, use POST /v1/transactions instead.

---

Endpoint

Method	Path	Auth	Description
POST	/v1/blockchain-accounts/create	API Key	Generate or retrieve a customer's wallet address

---

POST /v1/blockchain-accounts/create

Creates a permanent blockchain wallet address for a customer on the specified network and token. If an address already exists for that customer × blockchain × token combination in your current environment, the existing address is returned — no duplicate is created.

Request

Headers

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

Body

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[e-mail]",
  "blockchain": "BSC_TESTNET",
  "token": "USDT"
}

Field	Type	Required	Description
firstName	string	Yes	Customer's first name.
lastName	string	Yes	Customer's last name.
email	string	Yes	Customer's email address. Used to identify and create the customer record.
blockchain	string	Yes	Target blockchain network. See supported values.
token	string	Yes	Cryptocurrency token for the address. See supported values.
phoneNumber	string	No	Customer's phone number. Optional.

Response

{
  "success": true,
  "message": "Blockchain account created",
  "data": {
    "uuid": "1f5c2fb0-9e37-43bd-b591-468a2997b9d4",
    "address": "0xC3C8096293f65D6B33b726E48F87814F557Ca2b8",
    "normalizedAddress": "0xc3c8096293f65d6b33b726e48f87814f557ca2b8",
    "customerId": "5752ba49-b1fe-4852-a26d-2d83f4ef58b5",
    "businessId": "6764b503-d497-4b5f-8083-6819a569a60c",
    "environment": "TEST",
    "token": "USDT",
    "blockchain": "BSC_TESTNET",
    "subscriptionId": null,
    "isActive": true,
    "createdAt": "2026-02-20T08:29:28.057Z",
    "updatedAt": "2026-02-20T08:29:28.057Z"
  }
}

Response fields

Field	Type	Description
uuid	string	Unique ID of this blockchain address record.
address	string	The generated blockchain wallet address. Display this to your customer.
normalizedAddress	string	Lowercase version of the address used internally for matching.
blockchain	string	The blockchain network this address belongs to.
token	string	The token this address is configured for.
customerId	string	ID of the customer profile created or matched in your business.
businessId	string	Your business ID.
isActive	boolean	Whether this address is currently active and usable.
environment	string	TEST or LIVE — matches your API key's environment.
subscriptionId	string	Internal subscription ID for on-chain monitoring. null until assigned.
createdAt	string	ISO timestamp when the address was first generated.
updatedAt	string	ISO timestamp of the last update to this record.

Error Responses

Status	Message	Cause
400	<token> is not supported on <blockchain>	The token–blockchain combination is not supported.
400	Unable to generate blockchain address	External wallet generation failed.
401	Unauthorized	Missing or invalid API key.

---

Supported Values

blockchain

Value	Network Name	Standard
BSC_MAINNET	Binance Smart Chain	BEP-20
POLYGON	Polygon (Matic Network)	ERC-20

Use BSC_TESTNET when testing with a TEST API key.

token

Value	Name
USDT	Tether USD
USDC	USD Coin

---

Idempotency

This endpoint is idempotent. Calling it multiple times with the same customer email, blockchain, and token returns the same address every time — no duplicate addresses are generated.

First call  →  address generated + saved  →  { address: "0xAbc..." }
Second call →  existing address returned  →  { address: "0xAbc..." }  (same)

This means it is safe to call this endpoint on every customer session or page load without worrying about creating duplicates.

---

Code Examples

Node.js

const axios = require('axios');

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

const response = await axios.post(
  `${BASE_URL}/blockchain-accounts/create`,
  {
    firstName: 'John',
    lastName: 'Doe',
    email: '[e-mail]',
    blockchain: 'BSC_TESTNET',
    token: 'USDT',
  },
  {
    headers: {
      Authorization: process.env.IVORYPAY_SECRET_KEY,
      'Content-Type': 'application/json',
    },
  },
);

const { address, blockchain, token } = response.data.data;
console.log(`Customer deposit address: ${address} on ${blockchain} (${token})`);

cURL

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

curl -X POST $BASE_URL/blockchain-accounts/create \
  -H "Authorization: live_sk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[e-mail]",
    "blockchain": "BSC_TESTNET",
    "token": "USDT"
  }'

Python

import requests

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

response = requests.post(
    f'{BASE_URL}/blockchain-accounts/create',
    json={
        'firstName': 'John',
        'lastName': 'Doe',
        'email': '[e-mail]',
        'blockchain': 'BSC_TESTNET',
        'token': 'USDT',
    },
    headers={
        'Authorization': 'live_sk_xxxxxxxxxxxx',
        'Content-Type': 'application/json',
    }
)

data = response.json()['data']
print(f"Customer deposit address: {data['address']} on {data['blockchain']}")