This endpoint provides real-time balance information with multi-chain support and historical querying capabilities.
ssUSD Balance API
Query StateSet USD (ssUSD) balances with comprehensive filtering, multi-chain aggregation, and real-time updates.
🔑 Authentication
curl https://api.stateset.com/v1/stablecoin/balance/stateset1abc... \
-H "Authorization: Bearer sk_test_..."
📋 Path Parameters
The blockchain address to query. Supports multiple formats:
- StateSet:
stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu
- Ethereum/Base:
0x742d35Cc6634C0532925a3b844Bc9e7595f6E321
- Solana:
DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
🔍 Query Parameters
Filter by specific chains or query all chainsOptions: ["stateset", "base", "solana", "cosmos"]
Default: All chains where address has balance
Include pending transactions in balance calculationUseful for showing “available” vs “total” balance
Include locked/vesting balances in response
Query historical balance at specific block heightExample: 1542389
Query historical balance at specific timeFormat: ISO 8601 (e.g., 2024-06-25T12:00:00Z
)
Convert balance to another currencyOptions: USD
, EUR
, GBP
, JPY
, etc.
📤 Response
The queried blockchain address
Balance breakdown by type and chain
Spendable balance (excluding pending and locked)
Balance in pending transactions
Locked or vesting balance
Total balance (available + pending + locked)
Balance breakdown by blockchain
Pending balance on this chain
Last transaction timestamp
Balance in other currencies (if requested)
Additional account information
Timestamp of first ssUSD transaction
Total number of transactions
Account classification: retail
, institutional
, merchant
curl https://api.stateset.com/v1/stablecoin/balance/stateset1abc... \
-H "Authorization: Bearer sk_test_..."
{
"address": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
"balances": {
"available": "10500.50",
"pending": "250.00",
"locked": "5000.00",
"total": "15750.50"
},
"chains": [
{
"chain": "stateset",
"balance": "12500.50",
"pending": "150.00",
"last_activity": "2024-06-25T11:45:00Z"
},
{
"chain": "base",
"balance": "2000.00",
"pending": "100.00",
"last_activity": "2024-06-25T10:30:00Z"
},
{
"chain": "solana",
"balance": "1250.00",
"pending": "0.00",
"last_activity": "2024-06-24T18:00:00Z"
}
],
"conversions": {
"USD": "15750.50",
"EUR": "14525.67",
"GBP": "12456.89"
},
"metadata": {
"first_transaction": "2024-01-15T08:00:00Z",
"transaction_count": 342,
"account_type": "retail",
"risk_score": "low"
}
}
💡 Common Use Cases
Treasury Dashboard
// Real-time treasury monitoring
class TreasuryDashboard {
async getSnapshot() {
const balance = await stateset.stablecoin.balance({
address: this.treasuryAddress,
include_pending: true,
convert_to: ['USD', 'EUR']
});
return {
total_assets: balance.balances.total,
liquid_assets: balance.balances.available,
pending_settlements: balance.balances.pending,
chain_distribution: this.analyzeChainDistribution(balance.chains),
fx_exposure: balance.conversions
};
}
analyzeChainDistribution(chains) {
const total = chains.reduce((sum, c) =>
sum + parseFloat(c.balance), 0
);
return chains.map(c => ({
chain: c.chain,
balance: c.balance,
percentage: (parseFloat(c.balance) / total * 100).toFixed(2)
}));
}
}
Payment Processing
// Check balance before processing payment
async function processPayment(amount, recipient) {
// Get current balance
const balance = await stateset.stablecoin.balance({
address: merchantWallet,
include_pending: true
});
const available = parseFloat(balance.balances.available);
if (available < amount) {
throw new Error(`Insufficient funds. Available: ${available}`);
}
// Process payment
const payment = await stateset.stablecoin.transfer({
to: recipient,
amount: amount.toString(),
memo: 'Payment processed'
});
return payment;
}
Multi-Signature Wallet
// Monitor multi-sig wallet balance
const multiSig = {
address: 'stateset1multisig...',
signers: ['addr1', 'addr2', 'addr3'],
threshold: 2
};
// Get balance and pending transactions
const balance = await stateset.stablecoin.balance({
address: multiSig.address,
include_pending: true
});
// Alert if large pending transaction
if (parseFloat(balance.balances.pending) > 100000) {
await notifySigners({
message: 'Large pending transaction requires approval',
amount: balance.balances.pending,
signers: multiSig.signers
});
}
🔔 Webhooks
Subscribe to balance change events:
// Get notified of balance changes
const webhook = await stateset.webhooks.create({
url: 'https://yourapp.com/webhooks/balance',
events: ['balance.changed'],
filters: {
address: 'stateset1abc...',
minimum_change: 100 // Only notify for changes > $100
}
});
// Webhook payload
{
"event": "balance.changed",
"data": {
"address": "stateset1abc...",
"previous_balance": "10000.00",
"new_balance": "11500.00",
"change": "1500.00",
"transaction_id": "tx_123",
"chain": "stateset"
}
}
🚨 Error Handling
try {
const balance = await stateset.stablecoin.balance({
address: userAddress
});
} catch (error) {
switch(error.code) {
case 'invalid_address':
console.error('Invalid address format');
break;
case 'rate_limit':
console.error('Too many requests, retry after:', error.retry_after);
break;
case 'network_error':
console.error('Network issue, retrying...');
// Implement retry logic
break;
default:
console.error('Unexpected error:', error);
}
}