Api Reference

Balances

Endpoint to check your cryptocurrency balances

Get Your Balances

Retrieves your balances for all assets, including their USD value.

Endpoint

GET /api/balances

Headers

Authorization: Bearer {token}
Accept: application/json

Parameters

This endpoint does not accept any parameters.

Example Request

curl -X GET https://api.flow-payments.com/api/balances \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Accept: application/json"

Successful Response

Code: 200 OK

{
  "data": [
    {
        "asset": {
            "id": 1,
            "name": "Bitcoin",
            "symbol": "BTC",
            "chain": "bitcoin",
            "type": "native",
            "decimals": 8,
            "usd_rate": "93037.28254643",
            "network_fee": "0",
            "min_confirmations": 1
        },
        "balance": 0,
        "usd_value": 0
    },
    {
        "asset": {
            "id": 2,
            "name": "Ethereum",
            "symbol": "ETH",
            "chain": "ethereum",
            "type": "native",
            "decimals": 18,
            "usd_rate": "3125.16675365",
            "network_fee": "0.000000042162288",
            "min_confirmations": 5
        },
        "balance": "0.000090074983482468",
        "usd_value": "0.28"
    }
  ]
}

Response Fields

Each element in the data array contains:

Field	Type	Description
`asset`	object	Information about the cryptocurrency
`asset.id`	integer	Unique identifier of the asset
`asset.name`	string	Full name of the cryptocurrency
`asset.symbol`	string	Cryptocurrency symbol
`asset.chain`	string	Asset blockchain
`asset.type`	string	Type: `native` or `token`
`asset.decimals`	integer	Number of decimals
`asset.usd_rate`	string	Current exchange rate in USD
`asset.network_fee`	string	Network fee in standard units
`asset.min_confirmations`	integer	Minimum number of confirmations required for a transaction to be considered valid
`balance`	string	Balance in standard cryptocurrency units
`usd_value`	string	Balance value in USD

Value Calculations

Balance

The balance is expressed in standard units of the cryptocurrency:

For BTC: in bitcoins (e.g., 0.15234567)
For ETH: in ethers (e.g., 2.5)
For USDC: in USDC (e.g., 1000.00)

USD Value

The USD value is calculated automatically:

usd_value = balance × usd_rate

Example:

Balance: 0.15234567 BTC
USD Rate: $45,000.00
USD Value: 0.15234567 × 45000 = $6,855.55

Use Cases

1. Display Total Balance

Calculate your total balance in USD:

const response = await fetch('https://api.flow-payments.com/api/balances', {
  headers: {
    'Authorization': 'Bearer sk_live_abc123...',
    'Accept': 'application/json'
  }
});

const { data: balances } = await response.json();

const totalUSD = balances.reduce((sum, item) => {
  return sum + parseFloat(item.usd_value);
}, 0);

console.log(`Total balance: $${totalUSD.toFixed(2)}`);
// Result: Total balance: $15,355.55

2. Check Balance Before Payout

Verify you have sufficient funds before creating a payout:

<?php

function hasEnoughBalance($balances, $symbol, $amount) {
    foreach ($balances['data'] as $item) {
        if ($item['asset']['symbol'] === $symbol) {
            return floatval($item['balance']) >= $amount;
        }
    }
    return false;
}

// Check before creating a 0.5 ETH payout
if (hasEnoughBalance($balances, 'ETH', 0.5)) {
    // Create the payout
    createPayout('ETH', 0.5, $recipientAddress);
} else {
    echo "Insufficient balance";
}

Balance Updates

Balances are updated automatically when:

✅ An invoice is paid (increases your balance)
✅ A payout is created (decreases your balance)

!NOTE Balances only reflect confirmed transactions. Pending transactions are not included in the balance.

Negative Balances

Balances can never be negative. If you attempt to create a payout with an amount greater than your balance, you will receive a 400 Bad Request error:

{
  "message": "Insufficient balance"
}

Possible Errors

Code	Description
`401`	Missing or invalid authentication token
`429`	Rate limit exceeded
`500`	Internal server error

Important Notes

!IMPORTANT
Balances include all active assets, even those with a balance of 0
USD values are calculated with current exchange rates
Exchange rates may vary, so USD value is indicative

!TIP Call this endpoint regularly to keep your data up to date, especially if you display balances in a real-time dashboard.

Associated Webhooks

The following events can affect your balances:

invoice.paid - Increases your balance when an invoice is paid
payout.completed - Decreases your balance when a payout is completed

See the webhooks documentation for more information.

Assets

Endpoint to retrieve the list of available cryptocurrencies

Invoices

Endpoints to create and manage payment invoices