Accounts

Accounts represent unique deposit addresses generated for users on specific blockchain networks. Each user gets a dedicated address per chain to receive cryptocurrency deposits.

The account model

Each account is a unique deposit address for a specific user on a specific blockchain.

Properties

Name
orgId
Type
string
Description
Organization ID that owns this account.
Name
chainId
Type
string
Description
Blockchain network in CAIP-2 format (e.g., eip155:1).
Name
externalUserId
Type
string
Description
Your internal user identifier.
Name
orgDepositAccountId
Type
string
Description
Unique account identifier within your organization.
Name
properties
Type
object
Description
Chain-specific properties (address, destination tag, etc.).
Name
createdAt
Type
timestamp
Description
Timestamp of when the account was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the account was last updated.

GET/accounts

List all accounts

Retrieve all deposit accounts for your organization across all users and chains.

Request

GET

/accounts

curl https://api.coinspayd.io/accounts \
  -H "x-api-key: {your-api-key}"

Response

{
  "accounts": [
    {
      "orgId": "org_456",
      "chainId": "eip155:1",
      "externalUserId": "customer_789",
      "orgDepositAccountId": "acc_123",
      "properties": {
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"
      },
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z"
    },
    {
      "orgId": "org_456",
      "chainId": "eip155:137",
      "externalUserId": "customer_789",
      "orgDepositAccountId": "acc_124",
      "properties": {
        "address": "0x8b9e3e5a6d1c4f2b0a7c8d9e1f3a5b7c9d2e4f6a"
      },
      "createdAt": "2025-01-16T10:00:00.000Z",
      "updatedAt": "2025-01-16T10:00:00.000Z"
    },
    {
      "orgId": "org_456",
      "chainId": "xrpl:mainnet",
      "externalUserId": "customer_123",
      "orgDepositAccountId": "acc_125",
      "properties": {
        "address": "rN7n7otQDd6FczFgLdlqtyMVrn3HMtthca",
        "destinationTag": "12345"
      },
      "createdAt": "2025-01-17T10:00:00.000Z",
      "updatedAt": "2025-01-17T10:00:00.000Z"
    }
  ]
}

Understanding account properties

Different blockchain networks have different account property structures:

EVM Chains (Ethereum, Polygon, BSC)

{
  "properties": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7"
  }
}

Users send deposits to this Ethereum-compatible address.

Bitcoin

{
  "properties": {
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
  }
}

Users send BTC to this native Bitcoin address.

Tron

{
  "properties": {
    "address": "TXYZabcdef1234567890abcdef1234567890"
  }
}

Users send TRX or TRC-20 tokens to this Tron address.

XRP Ledger

{
  "properties": {
    "address": "rN7n7otQDd6FczFgLdlqtyMVrn3HMtthca",
    "destinationTag": "12345"
  }
}

Users must include the destination tag when sending XRP to differentiate between users sharing the same base address.

Filter accounts by user

Find all deposit addresses for a specific user:

const userId = 'customer_789'

const response = await fetch(
  'https://api.coinspayd.io/accounts',
  {
    headers: { 'x-api-key': 'your-api-key' }
  }
)
const { accounts } = await response.json()

// Filter by user
const userAccounts = accounts.filter(acc => acc.externalUserId === userId)

console.log(`User ${userId} has ${userAccounts.length} deposit addresses:`)
userAccounts.forEach(acc => {
  console.log(`- ${acc.chainId}: ${acc.properties.address}`)
})

user_id = 'customer_789'

response = requests.get(
    'https://api.coinspayd.io/accounts',
    headers={'x-api-key': 'your-api-key'}
)
accounts = response.json()['accounts']

# Filter by user
user_accounts = [acc for acc in accounts if acc['externalUserId'] == user_id]

print(f"User {user_id} has {len(user_accounts)} deposit addresses:")
for acc in user_accounts:
    print(f"- {acc['chainId']}: {acc['properties']['address']}")

Account lifecycle

Creation

Accounts are created automatically when you request a deposit address via:

GET /payments/deposit-address?chainId={chain}&tokenId={token}&userId={user}

If an account doesn't exist for that user on that chain, one is created.

Reuse

The same account address is reused for all tokens on the same chain:

User customer_123 on Ethereum (eip155:1)
- USDC deposits → 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7
- USDT deposits → 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7 (same address)
- DAI deposits → 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7 (same address)

Security

Each user gets unique addresses per chain
Addresses are deterministically generated using CREATE2 (EVM) or HD wallets
Private keys are encrypted at rest
Deposits are automatically swept to settlement accounts

Account statistics

Generate statistics about your deposit accounts:

const { accounts } = await getAccounts()

// Count by chain
const byChain = {}
accounts.forEach(acc => {
  byChain[acc.chainId] = (byChain[acc.chainId] || 0) + 1
})

console.log('Accounts by chain:')
Object.entries(byChain).forEach(([chain, count]) => {
  console.log(`${chain}: ${count} accounts`)
})

// Count unique users
const uniqueUsers = new Set(accounts.map(acc => acc.externalUserId))
console.log(`\nTotal unique users: ${uniqueUsers.size}`)

// Average accounts per user
const avgPerUser = accounts.length / uniqueUsers.size
console.log(`Average accounts per user: ${avgPerUser.toFixed(2)}`)

Example Output:

Accounts by chain:
eip155:1: 150 accounts
eip155:137: 120 accounts
eip155:56: 80 accounts
bip122:000000000019d6689c085ae165831e93: 50 accounts
tron:0x00000000000000000000000000000000: 40 accounts
xrpl:mainnet: 30 accounts

Total unique users: 200
Average accounts per user: 2.35

Display addresses to users

When showing deposit addresses to users, include clear instructions:

EVM Chains

Send USDC to this Ethereum address:
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7

⚠️ Only send USDC on Ethereum network
⚠️ Do not send tokens on other networks

XRP with Destination Tag

Send XRP to:
Address: rN7n7otQDd6FczFgLdlqtyMVrn3HMtthca
Destination Tag: 12345

⚠️ You MUST include the destination tag
⚠️ Missing tag will result in lost funds

Bitcoin

Send BTC to this address:
bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

⚠️ Only send Bitcoin (BTC)
⚠️ Do not send other cryptocurrencies

Best practices

User communication

Clearly label which network each address is for
Warn users about sending to wrong networks
For XRP, emphasize the importance of destination tags
Provide QR codes for easier mobile deposits

Monitoring

Track which users have created accounts on which chains
Monitor account creation trends
Alert users when new deposit addresses are generated

Security

Never expose private keys
Validate addresses before displaying to users
Log all account access for audit trails