Deposits

Deposits are the core of the Crypto Deposits Platform — enabling you to accept cryptocurrency payments from your users across multiple blockchain networks. On this page, we'll dive into the different deposit endpoints you can use to create deposit addresses, retrieve deposit history, and track incoming payments.

The deposit model

The deposit model contains all the information about incoming cryptocurrency payments, including the transaction hash, amount, token, sender address, and associated user.

Properties

Name
chainId
Type
string
Description
The blockchain network in CAIP-2 format (e.g., eip155:1 for Ethereum mainnet).
Name
txnHash
Type
string
Description
The transaction hash on the blockchain.
Name
tokenId
Type
string
Description
The token identifier in CAIP-19 format (e.g., eip155:1/erc20:0xa0b86991... for USDC on Ethereum).
Name
amount
Type
string
Description
The deposit amount in base units (e.g., "100000000" = 100 USDC with 6 decimals).
Name
accountChainId
Type
string
Description
The deposit account chain ID.
Name
externalUserId
Type
string
Description
Your internal user identifier.
Name
senderAddress
Type
string
Description
The blockchain address that sent the deposit.
Name
Token
Type
object
Description
Token details including name, symbol, decimals, and contract address.
Name
createdAt
Type
timestamp
Description
Timestamp of when the deposit was detected.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the deposit was last updated.

GET/payments

List all deposits

This endpoint allows you to retrieve a list of all deposits for your organization across all chains and users. You can optionally filter by user ID.

Query parameters

Name
userId
Type
string
Description
Optional. Filter deposits by external user ID.

Request

GET

/payments

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

Response

{
  "payments": [
    {
      "chainId": "eip155:1",
      "txnHash": "0x1234567890abcdef...",
      "tokenId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "amount": "100000000",
      "accountChainId": "eip155:1",
      "externalUserId": "customer_789",
      "senderAddress": "0xabcdef...",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "Token": {
        "id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      }
    }
  ]
}

GET/payments/:userId/deposits

Get deposits for a user

Retrieve all deposits for a specific user. This is useful for showing a user their deposit history.

Path parameters

Name
userId
Type
string
Description
The external user ID to get deposits for.

Request

GET

/payments/:userId/deposits

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

Response

{
  "deposits": [
    {
      "chainId": "eip155:1",
      "txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "tokenId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "amount": "100000000",
      "accountChainId": "eip155:1",
      "externalUserId": "customer_789",
      "senderAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "Token": {
        "id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      }
    },
    {
      "chainId": "eip155:137",
      "txnHash": "0xfedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
      "tokenId": "eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
      "amount": "50000000",
      "accountChainId": "eip155:137",
      "externalUserId": "customer_789",
      "senderAddress": "0x9876543210abcdef9876543210abcdef98765432",
      "createdAt": "2025-01-14T15:20:00.000Z",
      "updatedAt": "2025-01-14T15:20:00.000Z",
      "Token": {
        "id": "eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "address": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174"
      }
    }
  ]
}

GET/payments/deposit-address

Get deposit address

This endpoint allows you to get or create a deposit address for a specific user on a specific chain. If an address doesn't exist, it will be created automatically.

Required parameters

Name
chainId
Type
string
Description
The blockchain network in CAIP-2 format (e.g., eip155:1).
Name
tokenId
Type
string
Description
The token identifier in CAIP-19 format.
Name
userId
Type
string
Description
Your internal user identifier.

Request

GET

/payments/deposit-address

curl -G https://api.coinspayd.io/payments/deposit-address \
  -H "x-api-key: {your-api-key}" \
  -d chainId=eip155:1 \
  -d tokenId=eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 \
  -d userId=customer_789

Response (EVM chains)

{
  "address": {
    "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"
  }
}

Response (XRP with destination tag)

{
  "address": {
    "orgId": "org_456",
    "chainId": "xrpl:mainnet",
    "externalUserId": "customer_789",
    "orgDepositAccountId": "acc_456",
    "properties": {
      "address": "rN7n7otQDd6FczFgLdlqtyMVrn3HMtthca",
      "destinationTag": "12345"
    },
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  }
}

GET/payments/:userId/deposits

Get user deposit history

This endpoint allows you to retrieve all deposits for a specific user across all chains.

Request

GET

/payments/customer_789/deposits

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

Response

{
  "deposits": [
    {
      "chainId": "eip155:1",
      "txnHash": "0x1234...",
      "tokenId": "eip155:1/erc20:0xa0b86991...",
      "amount": "100000000",
      "accountChainId": "eip155:1",
      "externalUserId": "customer_789",
      "senderAddress": "0xabcdef...",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

Common errors

When working with deposits, you may encounter these errors:

Error Code	Description
`INVALID_CHAIN`	The specified chain ID was not found or is invalid
`CHAIN_NOT_ENABLED`	The chain exists but is disabled for your organization
`INVALID_TOKEN`	The specified token ID was not found
`TOKEN_NOT_ENABLED`	The token exists but is disabled
`FAILED_TO_CREATE_DEPOSIT_ACCOUNT`	Failed to create a deposit address for the user

Chain ID formats (CAIP-2)

Common chain IDs you'll use:

Ethereum: eip155:1
Polygon: eip155:137
BSC: eip155:56
Ethereum Sepolia (testnet): eip155:11155111
Bitcoin: bip122:000000000019d6689c085ae165831e93
Tron: tron:0x00000000000000000000000000000000
XRP: xrpl:mainnet

Token ID formats (CAIP-19)

Token IDs combine chain ID with token type and address:

USDC on Ethereum: eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
USDT on Ethereum: eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7
Native ETH: eip155:1/slip44:60
Native BTC: bip122:000000000019d6689c085ae165831e93/slip44:0