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
Field | Type | Description |
---|---|---|
btcBalance | decimal | Bitcoin balance |
ltcBalance | decimal | Litecoin balance |
bscusdBalance | decimal | USDT balance on Binance Smart Chain |
bnbBalance | decimal | BNB balance on Binance Smart Chain |
ethBalance | decimal | Ethereum balance |
usdtBalance | decimal | USDT balance on Ethereum |
trxBalance | decimal | TRON balance |
trxusdBalance | decimal | USDT balance on TRON |
optusdBalance | decimal | USDT balance on Optimism |
optethBalance | decimal | ETH balance on Optimism |
ethusdcBalance | decimal | USDC balance on Ethereum |
bscusdcBalance | decimal | USDC balance on Binance Smart Chain |
All balance values are returned in their native cryptocurrency units. For example, BTC balance is in Bitcoin units, ETH balance is in Ethereum units, etc.
Supported Currencies
Paybin supports the following cryptocurrencies for balance tracking:
Native Cryptocurrencies
Symbol | Name | Network | Field Name |
---|---|---|---|
BTC | Bitcoin | Bitcoin Mainnet | btcBalance |
ETH | Ethereum | Ethereum Mainnet | ethBalance |
LTC | Litecoin | Litecoin Mainnet | ltcBalance |
BNB | Binance Coin | Binance Smart Chain | bnbBalance |
Stablecoins
Symbol | Name | Supported Networks | Field Name |
---|---|---|---|
USDT | Tether | Ethereum, BSC, TRON, Optimism | usdtBalance , bscusdBalance , trxusdBalance , optusdBalance |
USDC | USD Coin | Ethereum, BSC | ethusdcBalance , 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
)
Each network maintains separate balances. For example, USDT on Ethereum and USDT on Binance Smart Chain are tracked separately.
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 Code | Description | Recommended Action |
---|---|---|
Z503 | Invalid API key | Check your secret key and ensure it's correct |
Z400 | Bad request | Verify request format |
Z429 | Rate limit exceeded | Implement exponential backoff |
Z500 | Internal server error | Retry 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));
}
}
}
Always implement proper error handling and retry logic to ensure reliable balance updates for your application.