List Addresses

Retrieve all derived blockchain addresses for a customer's wallet with pagination and filtering options.

Endpoint

GET /api/v1/wallet/customer/:customerID/addresses

Authentication

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

Path Parameters

Parameter	Type	Description
customerID	string	Customer identifier

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Results per page (default: 20, max: 100)
network	string	No	Filter by network (BTC, ETH, BSC, etc.)

Example Request

JavaScript

// Get all addresses
const response = await fetch(
  'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/addresses?page=1&limit=50',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const data = await response.json();
console.log(`Total addresses: ${data.total}`);
console.log('Addresses:', data.addresses);

// Filter by network
const ethResponse = await fetch(
  'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/addresses?network=ETH',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

Python

import requests

# Get all addresses with pagination
response = requests.get(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/addresses',
    headers={'X-API-Key': 'your-api-key'},
    params={'page': 1, 'limit': 50}
)

data = response.json()
print(f"Total: {data['total']}")
for addr in data['addresses']:
    print(f"{addr['network']}: {addr['address']}")

# Filter by network
eth_response = requests.get(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/addresses',
    headers={'X-API-Key': 'your-api-key'},
    params={'network': 'ETH'}
)

cURL

# Get all addresses
curl "https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/addresses?page=1&limit=50" \
  -H "X-API-Key: your-api-key"

# Filter by network
curl "https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/addresses?network=BTC" \
  -H "X-API-Key: your-api-key"

Response

Success Response (200 OK)

Field	Type	Description
customer_id	string	Customer identifier
addresses	array	Array of derived address objects
total	integer	Total number of addresses

Address Object

Field	Type	Description
id	integer	Address database ID
customer_wallet_id	integer	Parent wallet ID
network	string	Blockchain network
address	string	Blockchain address
address_index	integer	Derivation index
derivation_path	string	BIP-44 path
is_testnet	boolean	Testnet address flag
monitored	boolean	Deposit monitoring enabled
total_received	string	Total amount received (if monitored)
last_checked_at	string	Last monitoring check timestamp

{
  "customer_id": "user_12345",
  "addresses": [
    {
      "id": 101,
      "customer_wallet_id": 42,
      "network": "BTC",
      "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "address_index": 0,
      "derivation_path": "m/84'/0'/0'/0/0",
      "is_testnet": false,
      "monitored": true,
      "total_received": "0.00150000",
      "last_checked_at": "2026-01-03T04:15:00Z"
    },
    {
      "id": 102,
      "customer_wallet_id": 42,
      "network": "ETH",
      "address": "0x8B3192f2f0f0D7E4F5C3A1B9E2D7A6C5B4D3E2F1",
      "address_index": 0,
      "derivation_path": "m/44'/60'/0'/0/0",
      "is_testnet": false,
      "monitored": true,
      "total_received": "0.5",
      "last_checked_at": "2026-01-03T04:15:00Z"
    },
    {
      "id": 103,
      "customer_wallet_id": 42,
      "network": "BSC",
      "address": "0x8B3192f2f0f0D7E4F5C3A1B9E2D7A6C5B4D3E2F1",
      "address_index": 0,
      "derivation_path": "m/44'/60'/0'/0/0",
      "is_testnet": false,
      "monitored": false,
      "total_received": "0",
      "last_checked_at": null
    }
  ],
  "total": 3
}

Error Responses

404 Not Found

{
  "error": "Wallet not found"
}

500 Internal Server Error

{
  "error": "Failed to fetch addresses"
}

Use Cases

Display Deposit Addresses

Show all deposit addresses to user:

async function loadDepositAddresses(customerId) {
  const response = await fetch(
    `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${customerId}/addresses`,
    {
      headers: { 'X-API-Key': process.env.API_KEY }
    }
  );
  
  const data = await response.json();
  
  // Group by network
  const byNetwork = data.addresses.reduce((acc, addr) => {
    if (!acc[addr.network]) acc[addr.network] = [];
    acc[addr.network].push(addr);
    return acc;
  }, {});
  
  return byNetwork;
}

Balance Summary

Calculate total balance across all addresses:

async function getTotalBalance(customerId) {
  const response = await fetch(
    `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${customerId}/addresses?limit=100`,
    {
      headers: { 'X-API-Key': process.env.API_KEY }
    }
  );
  
  const data = await response.json();
  
  // Sum total_received by network
  const balances = {};
  data.addresses.forEach(addr => {
    if (!balances[addr.network]) balances[addr.network] = 0;
    balances[addr.network] += parseFloat(addr.total_received || 0);
  });
  
  return balances;
}

Pagination

For wallets with many addresses, use pagination:

async function getAllAddresses(customerId) {
  let page = 1;
  let allAddresses = [];
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${customerId}/addresses?page=${page}&limit=100`,
      {
        headers: { 'X-API-Key': process.env.API_KEY }
      }
    );
    
    const data = await response.json();
    allAddresses = allAddresses.concat(data.addresses);
    
    hasMore = data.addresses.length === 100;
    page++;
  }
  
  return allAddresses;
}

Related Endpoints

• Derive Address - Create new addresses
• Get Transactions - View transaction history
• Export Private Key - Export address keys