Balance API

The Paybin Balance API allows you to retrieve account balances for all supported cryptocurrencies. This API provides real-time balance information for your merchant account across multiple blockchain networks.

Get Merchant Balances

This endpoint retrieves the current balances for all cryptocurrencies in your merchant account.

  • Name
    PublicKey
    Type
    string
    Description

    Your Paybin Public Key, used to authenticate the request.

Get Merchant Balances

curl --location 'https://sandbox.paybin.io/v1/merchant/balances' \
--header 'X-Api-Key: {secretKey}' \
--header 'Content-Type: application/json' \
--data '{
  "PublicKey": "{publicKey}"
}'

Response

{
  "apiVersion": "1.0.0.0",
  "data": {
    "btcBalance": 0.01827139,
    "ltcBalance": 4.8155043,
    "bscusdBalance": 124.900335290627,
    "bnbBalance": 0.49766454477400346,
    "ethBalance": 0.2053466266382856,
    "usdtBalance": 0.391465,
    "trxBalance": 4.846484,
    "trxusdBalance": 0.314496,
    "optusdBalance": 0.188525,
    "optethBalance": 0.027137871507939223,
    "ethusdcBalance": 0.0,
    "bscusdcBalance": 0.0
  },
  "code": 200,
  "message": "OK"
}

Exception

{
  "apiVersion": "1.0.0.0",
  "data": null,
  "code": 400,
  "message": "Z503"
}

Balance Response Format

The balance API response provides comprehensive information about your account balances:

Balance Fields

FieldTypeDescription
btcBalancedecimalBitcoin balance
ltcBalancedecimalLitecoin balance
bscusdBalancedecimalUSDT balance on Binance Smart Chain
bnbBalancedecimalBNB balance on Binance Smart Chain
ethBalancedecimalEthereum balance
usdtBalancedecimalUSDT balance on Ethereum
trxBalancedecimalTRON balance
trxusdBalancedecimalUSDT balance on TRON
optusdBalancedecimalUSDT balance on Optimism
optethBalancedecimalETH balance on Optimism
ethusdcBalancedecimalUSDC balance on Ethereum
bscusdcBalancedecimalUSDC balance on Binance Smart Chain

Supported Currencies

Paybin supports the following cryptocurrencies for balance tracking:

Native Cryptocurrencies

SymbolNameNetworkField Name
BTCBitcoinBitcoin MainnetbtcBalance
ETHEthereumEthereum MainnetethBalance
LTCLitecoinLitecoin MainnetltcBalance
BNBBinance CoinBinance Smart ChainbnbBalance

Stablecoins

SymbolNameSupported NetworksField Name
USDTTetherEthereum, BSC, TRON, OptimismusdtBalance, bscusdBalance, trxusdBalance, optusdBalance
USDCUSD CoinEthereum, BSCethusdcBalance, bscusdcBalance

Multi-Network Support

Some cryptocurrencies are available on multiple networks:

  • USDT: Ethereum (usdtBalance), Binance Smart Chain (bscusdBalance), TRON (trxusdBalance), Optimism (optusdBalance)
  • USDC: Ethereum (ethusdcBalance), Binance Smart Chain (bscusdcBalance)
  • ETH: Ethereum (ethBalance), Optimism (optethBalance)

Best Practices

πŸ”„ Regular Updates

  • Poll frequently: Update balances every 30-60 seconds for real-time accuracy
  • Cache responses: Store balance data locally to reduce API calls
  • Handle errors: Implement retry logic for failed requests

πŸ“Š Monitoring

// Example: Regular balance polling
setInterval(async () => {
  try {
    const response = await getMerchantBalances();
    updateBalanceDisplay(response.data);
    
    // Check for significant changes
    const previousTotal = getPreviousTotal();
    const currentTotal = calculateTotalBalance(response.data);
    const change = ((currentTotal - previousTotal) / previousTotal) * 100;
    
    if (Math.abs(change) > 5) { // 5% threshold
      notifyBalanceChange(change);
    }
  } catch (error) {
    console.error('Failed to fetch balances:', error);
  }
}, 30000); // Every 30 seconds

function calculateTotalBalance(balances) {
  // Convert all balances to USD equivalent
  return (
    balances.btcBalance * btcPrice +
    balances.ethBalance * ethPrice +
    balances.usdtBalance * 1 +
    balances.bscusdBalance * 1 +
    // ... other currencies
  );
}

πŸ’° Display Guidelines

  • Show native units: Display balances in their native cryptocurrency units
  • Include network info: Clearly indicate which network each balance belongs to
  • Update timestamps: Show when the balance was last updated
  • Handle zero balances: Don't hide zero balances, show them as 0.00

πŸ” Security Considerations

  • Secure storage: Never log or display API keys
  • HTTPS only: Always use HTTPS for API communications
  • Rate limiting: Respect API rate limits to avoid throttling
  • Error handling: Don't expose sensitive information in error messages

πŸ“ˆ Performance Optimization

// Example: Optimized balance fetching
class BalanceManager {
  constructor() {
    this.cache = new Map();
    this.lastUpdate = 0;
    this.updateInterval = 30000; // 30 seconds
  }

  async getBalances(forceUpdate = false) {
    const now = Date.now();
    
    // Return cached data if recent enough
    if (!forceUpdate && (now - this.lastUpdate) < this.updateInterval) {
      return this.cache.get('balances');
    }

    try {
      const response = await fetchBalances();
      this.cache.set('balances', response.data);
      this.lastUpdate = now;
      return response.data;
    } catch (error) {
      // Return cached data on error if available
      const cached = this.cache.get('balances');
      if (cached) {
        console.warn('Using cached balance data due to API error');
        return cached;
      }
      throw error;
    }
  }
}

🚨 Error Handling

Common error scenarios and how to handle them:

Error CodeDescriptionRecommended Action
Z503Invalid API keyCheck your secret key and ensure it's correct
Z400Bad requestVerify request format
Z429Rate limit exceededImplement exponential backoff
Z500Internal server errorRetry with exponential backoff
// Example: Robust error handling
async function getBalancesWithRetry(maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await getMerchantBalances();
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
      
      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Was this page helpful?