Account Balances

Manage and monitor your cryptocurrency balances across all wallets.

Get Account Balances

GET

/user/balances/

Get aggregated cryptocurrency balances across all your wallets.

Authentication

Requires OAuth 2.0 authentication with read scope.

Example Request

curl -X GET https://api.cryptofuse.io/user/balances/ \
  -H "Authorization: Bearer your_access_token"

Response

Success Response (200 OK)

{
  "balances": [
    {
      "currency": "USDTERC20",
      "currency_name": "Tether USD",
      "network": "ETH",
      "total_balance": "5000.000000",
      "available_balance": "4500.000000",
      "pending_balance": "500.000000",
      "total_deposited": "10000.000000",
      "total_withdrawn": "5000.000000",
      "total_fees_paid": "50.000000",
      "usd_value": "4999.50",
      "last_transaction": "2025-01-15T09:30:00Z",
      "wallets": [
        {
          "wallet_id": "550e8400-e29b-41d4-a716-446655440000",
          "wallet_name": "Default Wallet",
          "balance": "3000.000000",
          "pending": "300.000000"
        },
        {
          "wallet_id": "660e8400-e29b-41d4-a716-446655440001",
          "wallet_name": "Online Store",
          "balance": "1500.000000",
          "pending": "200.000000"
        }
      ]
    },
    {
      "currency": "USDCERC20",
      "currency_name": "USD Coin",
      "network": "ETH",
      "total_balance": "2500.000000",
      "available_balance": "2500.000000",
      "pending_balance": "0.000000",
      "total_deposited": "5000.000000",
      "total_withdrawn": "2500.000000",
      "total_fees_paid": "25.000000",
      "usd_value": "2500.25",
      "last_transaction": "2025-01-14T15:20:00Z",
      "wallets": [
        {
          "wallet_id": "550e8400-e29b-41d4-a716-446655440000",
          "wallet_name": "Default Wallet",
          "balance": "2500.000000",
          "pending": "0.000000"
        }
      ]
    },
    {
      "currency": "ETH",
      "currency_name": "Ethereum",
      "network": "ETH",
      "total_balance": "5.123456789000000000",
      "available_balance": "5.123456789000000000",
      "pending_balance": "0.000000000000000000",
      "total_deposited": "10.000000000000000000",
      "total_withdrawn": "4.876543211000000000",
      "total_fees_paid": "0.050000000000000000",
      "usd_value": "12015.83",
      "last_transaction": "2025-01-13T10:00:00Z",
      "wallets": [
        {
          "wallet_id": "550e8400-e29b-41d4-a716-446655440000",
          "wallet_name": "Default Wallet",
          "balance": "5.123456789000000000",
          "pending": "0.000000000000000000"
        }
      ]
    }
  ],
  "summary": {
    "total_usd_value": "19515.58",
    "total_currencies": 3,
    "total_wallets": 2,
    "last_update": "2025-01-15T10:00:00Z"
  }
}

Response Fields

Field	Type	Description
currency	string	Currency code
total_balance	string	Total balance across all wallets
available_balance	string	Available for withdrawal
pending_balance	string	Awaiting confirmations
total_deposited	string	All-time deposits
total_withdrawn	string	All-time withdrawals
total_fees_paid	string	All-time fees paid
usd_value	string	Current USD value
wallets	array	Breakdown by wallet

Balance States

• Available: Confirmed and ready for withdrawal
• Pending: Received but awaiting confirmations
• Total: Available + Pending

Get Balance History

GET

/user/balances/history/

Get historical balance data and transaction volume for analytics.

Query Parameters

Parameter	Type	Required	Description
currency	string	No	Filter by currency (e.g., "USDTERC20")
period	string	No	Time period: 24h, 7d, 30d (default: 7d)
interval	string	No	Data interval: hourly, daily (default: daily)

Example Request

curl -X GET "https://api.cryptofuse.io/user/balances/history/?currency=USDTERC20&period=7d" \
  -H "Authorization: Bearer your_access_token"

Response

Success Response (200 OK)

{
  "currency": "USDTERC20",
  "period": "7d",
  "interval": "daily",
  "history": [
    {
      "timestamp": "2025-01-09T00:00:00Z",
      "balance": "4200.000000",
      "deposits": "500.000000",
      "withdrawals": "0.000000",
      "deposit_count": 5,
      "withdrawal_count": 0,
      "usd_value": "4199.58"
    },
    {
      "timestamp": "2025-01-10T00:00:00Z",
      "balance": "4700.000000",
      "deposits": "600.000000",
      "withdrawals": "100.000000",
      "deposit_count": 8,
      "withdrawal_count": 1,
      "usd_value": "4699.53"
    },
    {
      "timestamp": "2025-01-11T00:00:00Z",
      "balance": "4500.000000",
      "deposits": "300.000000",
      "withdrawals": "500.000000",
      "deposit_count": 3,
      "withdrawal_count": 2,
      "usd_value": "4499.55"
    }
  ],
  "summary": {
    "starting_balance": "4200.000000",
    "ending_balance": "5000.000000",
    "total_deposits": "3500.000000",
    "total_withdrawals": "2700.000000",
    "net_change": "800.000000",
    "total_deposit_count": 35,
    "total_withdrawal_count": 12,
    "average_daily_deposits": "500.000000",
    "average_daily_withdrawals": "385.714286"
  }
}

Usage Examples

Balance Chart Data

async function getBalanceChartData(currency = 'USDTERC20', period = '7d') {
  const response = await fetch(
    `https://api.cryptofuse.io/user/balances/history/?currency=${currency}&period=${period}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );
  
  const data = await response.json();
  
  // Prepare chart data
  const chartData = {
    labels: data.history.map(h => new Date(h.timestamp).toLocaleDateString()),
    datasets: [
      {
        label: 'Balance',
        data: data.history.map(h => parseFloat(h.balance)),
        borderColor: 'rgb(75, 192, 192)',
        tension: 0.1
      },
      {
        label: 'Deposits',
        data: data.history.map(h => parseFloat(h.deposits)),
        borderColor: 'rgb(54, 162, 235)',
        backgroundColor: 'rgba(54, 162, 235, 0.2)',
        type: 'bar'
      },
      {
        label: 'Withdrawals',
        data: data.history.map(h => -parseFloat(h.withdrawals)),
        borderColor: 'rgb(255, 99, 132)',
        backgroundColor: 'rgba(255, 99, 132, 0.2)',
        type: 'bar'
      }
    ]
  };
  
  return chartData;
}

Transaction Volume Analysis

import pandas as pd
from datetime import datetime, timedelta

async def analyze_transaction_volume():
    """Analyze transaction patterns across currencies."""
    
    currencies = ['USDTERC20', 'USDCERC20', 'DAIERC20']
    all_data = {}
    
    for currency in currencies:
        response = requests.get(
            f'https://api.cryptofuse.io/user/balances/history/',
            params={'currency': currency, 'period': '30d'},
            headers={'Authorization': f'Bearer {access_token}'}
        )
        
        if response.status_code == 200:
            data = response.json()
            all_data[currency] = pd.DataFrame(data['history'])
    
    # Calculate metrics
    for currency, df in all_data.items():
        df['timestamp'] = pd.to_datetime(df['timestamp'])
        df['deposits'] = df['deposits'].astype(float)
        df['withdrawals'] = df['withdrawals'].astype(float)
        
        print(f"\n{currency} Analysis:")
        print(f"Total Volume: ${df['deposits'].sum() + df['withdrawals'].sum():,.2f}")
        print(f"Average Daily Deposits: ${df['deposits'].mean():,.2f}")
        print(f"Peak Day: {df.loc[df['deposits'].idxmax(), 'timestamp'].date()}")
        print(f"Deposit/Withdrawal Ratio: {df['deposits'].sum() / df['withdrawals'].sum():.2f}")

Balance Notifications

Low Balance Alerts

Configure webhooks to receive notifications when balances fall below thresholds. This helps prevent failed withdrawals and ensures smooth operations.

Best Practices

1. Balance Management

• Monitor Pending Balances: Large pending amounts may indicate confirmation delays
• Set Balance Alerts: Configure notifications for low balances
• Regular Reconciliation: Compare balance history with your records

2. Multi-Wallet Strategy

// Distribute risk across wallets
async function distributeBalance(currency, totalAmount) {
  const wallets = await getWallets();
  const amountPerWallet = totalAmount / wallets.length;
  
  for (const wallet of wallets) {
    await createPayment({
      amount: amountPerWallet,
      currency: currency,
      wallet_id: wallet.id
    });
  }
}

3. Balance Caching

class BalanceCache:
    def __init__(self, ttl=300):  # 5 minute cache
        self.cache = {}
        self.ttl = ttl
    
    async def get_balance(self, currency=None):
        cache_key = currency or 'all'
        cached = self.cache.get(cache_key)
        
        if cached and cached['expires'] > time.time():
            return cached['data']
        
        # Fetch fresh data
        params = {'currency': currency} if currency else {}
        response = await fetch_balances(params)
        
        self.cache[cache_key] = {
            'data': response,
            'expires': time.time() + self.ttl
        }
        
        return response

Error Handling

Negative Balance Protection

The system prevents operations that would result in negative balances:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance for operation",
    "details": {
      "available": "100.00",
      "required": "150.00",
      "currency": "USDTERC20"
    }
  }
}

Balance Sync Issues

If balances appear incorrect:

1. Check for pending transactions
2. Verify recent deposits/withdrawals
3. Allow time for blockchain confirmations
4. Contact support if discrepancies persist

Next Steps

• Create a payment
• Create a withdrawal
• View transaction history