Portfolio

Portfolio endpoints allow you to track real-time cryptocurrency balances across all chains and tokens for your organization. Monitor settlement accounts, gas accounts, and aggregate portfolio values.

The portfolio model

The portfolio model tracks balances for each token across all blockchain networks, providing real-time visibility into your organization's cryptocurrency holdings.

Properties

Name
id
Type
string
Description
Unique identifier for the portfolio entry.
Name
orgId
Type
string
Description
The organization ID that owns this portfolio.
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
accountId
Type
string
Description
The blockchain address or account identifier.
Name
balance
Type
string
Description
Current balance in base units (e.g., "10000000000" = 10,000 USDC with 6 decimals).
Name
lastUpdated
Type
timestamp
Description
Timestamp of when the balance was last updated.
Name
createdAt
Type
timestamp
Description
Timestamp of when the portfolio entry was created.
Name
updatedAt
Type
timestamp
Description
Timestamp of when the portfolio entry was last modified.

GET/portfolio

Get organization portfolio

This endpoint retrieves all portfolio balances for your organization across all chains and tokens.

Request

GET

/portfolio

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

Response

{
  "portfolio": [
    {
      "id": "portfolio_123",
      "orgId": "org_456",
      "chainId": "eip155:1",
      "tokenId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "accountId": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb7",
      "balance": "10000000000",
      "lastUpdated": "2025-01-15T12:00:00.000Z",
      "createdAt": "2025-01-10T00:00:00.000Z",
      "updatedAt": "2025-01-15T12:00:00.000Z"
    },
    {
      "id": "portfolio_124",
      "orgId": "org_456",
      "chainId": "eip155:137",
      "tokenId": "eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
      "accountId": "0x8b9e3e5a6d1c4f2b0a7c8d9e1f3a5b7c9d2e4f6a",
      "balance": "5000000000",
      "lastUpdated": "2025-01-15T11:30:00.000Z",
      "createdAt": "2025-01-10T00:00:00.000Z",
      "updatedAt": "2025-01-15T11:30:00.000Z"
    }
  ]
}

GET/portfolio/settlement

Get settlement account balances

This endpoint retrieves balances for your organization's settlement accounts—the main accounts where collected funds are aggregated.

Request

GET

/portfolio/settlement

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

Response

{
  "settlement": [
    {
      "chainId": "eip155:1",
      "tokenId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "accountId": "0x1234567890abcdef1234567890abcdef12345678",
      "balance": "100000000000",
      "Token": {
        "id": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
      }
    }
  ]
}

Understanding account types

Your organization has different types of accounts for managing cryptocurrency:

Deposit Accounts

Individual deposit addresses generated for each user on each chain. Funds sent to these addresses are automatically swept to settlement accounts.

Settlement Accounts

Main treasury accounts where collected funds are aggregated. These are the accounts that hold the majority of your organization's cryptocurrency holdings.

Gas Accounts

Accounts that hold native tokens (ETH, MATIC, BNB, etc.) used to pay for transaction fees when sweeping deposits or processing withdrawals.

Portfolio aggregation

To calculate your total holdings across all chains:

// Example: Sum USDC holdings across all chains
const totalUSDC = portfolio
  .filter(entry => entry.tokenId.includes('usdc'))
  .reduce((sum, entry) => {
    const decimals = 6 // USDC has 6 decimals
    return sum + parseInt(entry.balance) / Math.pow(10, decimals)
  }, 0)

console.log(`Total USDC: $${totalUSDC.toFixed(2)}`)

# Example: Sum USDC holdings across all chains
total_usdc = sum(
    int(entry['balance']) / 10**6  # USDC has 6 decimals
    for entry in portfolio['portfolio']
    if 'usdc' in entry['tokenId'].lower()
)

print(f"Total USDC: ${total_usdc:,.2f}")

Real-time updates

Portfolio balances are updated in real-time as:

Deposits are detected via QuickNode Streams
Withdrawals are processed and confirmed on-chain
Sweeps complete moving funds to settlement accounts

For the most up-to-date balances, query the portfolio endpoint after receiving webhook notifications for deposit or withdrawal events.

Multi-chain portfolio example

Here's an example response showing holdings across multiple chains:

{
  "portfolio": [
    {
      "chainId": "eip155:1",
      "tokenId": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "balance": "50000000000",
      "Token": { "symbol": "USDC", "decimals": 6 }
    },
    {
      "chainId": "eip155:137",
      "tokenId": "eip155:137/erc20:0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
      "balance": "25000000000",
      "Token": { "symbol": "USDC", "decimals": 6 }
    },
    {
      "chainId": "bip122:000000000019d6689c085ae165831e93",
      "tokenId": "bip122:000000000019d6689c085ae165831e93/slip44:0",
      "balance": "100000000",
      "Token": { "symbol": "BTC", "decimals": 8 }
    }
  ]
}

Interpretation:

Ethereum: 50,000 USDC
Polygon: 25,000 USDC
Bitcoin: 1.0 BTC