Derive Address

Derive a blockchain address from a customer's HD wallet for a specific network. Supports 9 blockchain networks including Bitcoin, Ethereum, BSC, Polygon, Tron, Solana, and more.

Endpoint

POST /api/v1/wallet/customer/:customerID/derive

Authentication

Requires API key authentication via X-API-Key header.

Path Parameters

Parameter	Type	Description
customerID	string	Customer identifier

Request Body

Field	Type	Required	Description
network	string	Yes	Blockchain network (BTC, BCH, LTC, ETH, BSC, POL, TRX, SOL, XRP)
index	integer	No	Address derivation index (default: 0)
is_testnet	boolean	No	Use testnet address (default: false)
enable_monitoring	boolean	No	Enable deposit monitoring/webhooks (default: false)

Supported Networks

Network	Code	Description	Address Format
Bitcoin	BTC	Bitcoin mainnet	bc1... (SegWit)
Bitcoin Cash	BCH	Bitcoin Cash	bitcoincash:...
Litecoin	LTC	Litecoin	ltc1... (SegWit)
Ethereum	ETH	Ethereum mainnet	0x... (40 hex chars)
BSC	BSC	Binance Smart Chain	0x... (40 hex chars)
Polygon	POL	Polygon (Matic)	0x... (40 hex chars)
Tron	TRX	Tron network	T... (base58)
Solana	SOL	Solana	base58 (44 chars)
Ripple	XRP	XRP Ledger	r... (base58)

Example Request

JavaScript

// Derive Bitcoin address
const response = await fetch(
  'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/derive',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      network: 'BTC',
      index: 0,
      is_testnet: false,
      enable_monitoring: true
    })
  }
);

const address = await response.json();
console.log('Bitcoin Address:', address.address);
console.log('Derivation Path:', address.derivation_path);

Python

import requests

# Derive Ethereum address
response = requests.post(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/derive',
    headers={
        'X-API-Key': 'your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'network': 'ETH',
        'index': 0,
        'is_testnet': False,
        'enable_monitoring': True
    }
)

address = response.json()
print(f"Ethereum Address: {address['address']}")

cURL

curl -X POST https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/derive \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "BSC",
    "index": 0,
    "is_testnet": false,
    "enable_monitoring": true
  }'

Response

Success Response (200 OK)

Field	Type	Description
customer_id	string	Customer identifier
network	string	Blockchain network
address	string	Derived blockchain address
index	integer	Derivation index used
derivation_path	string	BIP-44 derivation path
is_testnet	boolean	Whether address is for testnet
monitored	boolean	Whether deposit monitoring is enabled

{
  "customer_id": "user_12345",
  "network": "BTC",
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "index": 0,
  "derivation_path": "m/84'/0'/0'/0/0",
  "is_testnet": false,
  "monitored": true
}

Error Responses

400 Bad Request

{
  "error": "Key: 'DeriveAddressRequest.Network' Error:Field validation for 'Network' failed on the 'oneof' tag"
}

404 Not Found

{
  "error": "wallet not found for customer user_12345"
}

500 Internal Server Error

{
  "error": "failed to derive address: unsupported network"
}

Derivation Paths

The service uses standard BIP-44 derivation paths:

Network	Path	Standard
Bitcoin	m/84'/0'/0'/0/{index}	BIP-84 (SegWit)
Bitcoin Cash	m/44'/145'/0'/0/{index}	BIP-44
Litecoin	m/84'/2'/0'/0/{index}	BIP-84 (SegWit)
Ethereum	m/44'/60'/0'/0/{index}	BIP-44
BSC	m/44'/60'/0'/0/{index}	BIP-44 (same as ETH)
Polygon	m/44'/60'/0'/0/{index}	BIP-44 (same as ETH)
Tron	m/44'/195'/0'/0/{index}	BIP-44
Solana	m/44'/501'/0'/0/{index}	BIP-44
Ripple	m/44'/144'/0'/0/{index}	BIP-44

Multiple Addresses

You can derive multiple addresses per network by incrementing the index:

// Derive 5 Bitcoin addresses
const addresses = [];
for (let i = 0; i < 5; i++) {
  const response = await fetch(url, {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      network: 'BTC',
      index: i,
      is_testnet: false
    })
  });
  addresses.push(await response.json());
}

Deposit Monitoring

When enable_monitoring is true, the service will:

• Monitor the blockchain for incoming transactions to this address
• Send webhook notifications when deposits are detected
• Track total received amount

See Deposit Monitoring Guide for webhook setup.

Best Practices

Address Management

• Reuse addresses: Derived addresses are deterministic and can be re-derived
• Index 0 for primary: Use index 0 for main deposit address
• Multiple addresses: Use different indices for privacy or accounting
• Testnet first: Always test with is_testnet: true before mainnet
• Enable monitoring: Set enable_monitoring: true for deposit addresses

Related Endpoints

• List Addresses - View all derived addresses
• Export Private Key - Export address private key
• Transfer - Send funds from derived address