curl https://api.stateset.com/v1/stablecoin/balance/stateset1abc... \
-H "Authorization: Bearer sk_test_..."
// Get balance across all chains
const balance = await stateset.stablecoin.balance({
address: 'stateset1abc...',
chains: ['stateset', 'base', 'solana'],
include_pending: true,
include_locked: true
});
console.log('Total balance:', balance.balances.total);
console.log('Available:', balance.balances.available);
// Check balance by chain
balance.chains.forEach(chain => {
console.log(`${chain.chain}: ${chain.balance} ssUSD`);
});
# Query balance at specific time
from datetime import datetime, timedelta
# Balance 30 days ago
past_date = datetime.now() - timedelta(days=30)
historical = stateset.stablecoin.balance(
address='stateset1abc...',
at_timestamp=past_date.isoformat()
)
print(f"Balance 30 days ago: {historical['balances']['total']}")
# Calculate balance change
current = stateset.stablecoin.balance(address='stateset1abc...')
change = float(current['balances']['total']) - float(historical['balances']['total'])
print(f"30-day change: ${change:,.2f}")
// Check multiple addresses efficiently
const addresses = [
'stateset1abc...',
'stateset1def...',
'stateset1ghi...'
];
const balances = await Promise.all(
addresses.map(addr =>
stateset.stablecoin.balance({ address: addr })
)
);
// Calculate total holdings
const totalHoldings = balances.reduce((sum, b) =>
sum + parseFloat(b.balances.total), 0
);
console.log(`Total ssUSD across all addresses: $${totalHoldings.toFixed(2)}`);
{
"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"
}
}
{
"address": "stateset1newuser...",
"balances": {
"available": "0.00",
"pending": "0.00",
"locked": "0.00",
"total": "0.00"
},
"chains": [],
"metadata": {
"first_transaction": null,
"transaction_count": 0,
"account_type": "new"
}
}
Get ssUSD Balance
Query ssUSD balance and detailed holdings information across all supported chains
GET
/
v1
/
stablecoin
/
balance
/
:address
curl https://api.stateset.com/v1/stablecoin/balance/stateset1abc... \
-H "Authorization: Bearer sk_test_..."
// Get balance across all chains
const balance = await stateset.stablecoin.balance({
address: 'stateset1abc...',
chains: ['stateset', 'base', 'solana'],
include_pending: true,
include_locked: true
});
console.log('Total balance:', balance.balances.total);
console.log('Available:', balance.balances.available);
// Check balance by chain
balance.chains.forEach(chain => {
console.log(`${chain.chain}: ${chain.balance} ssUSD`);
});
# Query balance at specific time
from datetime import datetime, timedelta
# Balance 30 days ago
past_date = datetime.now() - timedelta(days=30)
historical = stateset.stablecoin.balance(
address='stateset1abc...',
at_timestamp=past_date.isoformat()
)
print(f"Balance 30 days ago: {historical['balances']['total']}")
# Calculate balance change
current = stateset.stablecoin.balance(address='stateset1abc...')
change = float(current['balances']['total']) - float(historical['balances']['total'])
print(f"30-day change: ${change:,.2f}")
// Check multiple addresses efficiently
const addresses = [
'stateset1abc...',
'stateset1def...',
'stateset1ghi...'
];
const balances = await Promise.all(
addresses.map(addr =>
stateset.stablecoin.balance({ address: addr })
)
);
// Calculate total holdings
const totalHoldings = balances.reduce((sum, b) =>
sum + parseFloat(b.balances.total), 0
);
console.log(`Total ssUSD across all addresses: $${totalHoldings.toFixed(2)}`);
{
"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"
}
}
{
"address": "stateset1newuser...",
"balances": {
"available": "0.00",
"pending": "0.00",
"locked": "0.00",
"total": "0.00"
},
"chains": [],
"metadata": {
"first_transaction": null,
"transaction_count": 0,
"account_type": "new"
}
}
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_..."
const balance = await stateset.stablecoin.balance({
address: 'stateset1abc...'
});
balance = stateset.stablecoin.balance(
address='stateset1abc...'
)
📋 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 balanceInclude pending transactions in balance calculationUseful for showing “available” vs “total” balance
Include locked/vesting balances in response
Query historical balance at specific block heightExample:
1542389Query 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 in other currencies (if requested)
curl https://api.stateset.com/v1/stablecoin/balance/stateset1abc... \
-H "Authorization: Bearer sk_test_..."
// Get balance across all chains
const balance = await stateset.stablecoin.balance({
address: 'stateset1abc...',
chains: ['stateset', 'base', 'solana'],
include_pending: true,
include_locked: true
});
console.log('Total balance:', balance.balances.total);
console.log('Available:', balance.balances.available);
// Check balance by chain
balance.chains.forEach(chain => {
console.log(`${chain.chain}: ${chain.balance} ssUSD`);
});
# Query balance at specific time
from datetime import datetime, timedelta
# Balance 30 days ago
past_date = datetime.now() - timedelta(days=30)
historical = stateset.stablecoin.balance(
address='stateset1abc...',
at_timestamp=past_date.isoformat()
)
print(f"Balance 30 days ago: {historical['balances']['total']}")
# Calculate balance change
current = stateset.stablecoin.balance(address='stateset1abc...')
change = float(current['balances']['total']) - float(historical['balances']['total'])
print(f"30-day change: ${change:,.2f}")
// Check multiple addresses efficiently
const addresses = [
'stateset1abc...',
'stateset1def...',
'stateset1ghi...'
];
const balances = await Promise.all(
addresses.map(addr =>
stateset.stablecoin.balance({ address: addr })
)
);
// Calculate total holdings
const totalHoldings = balances.reduce((sum, b) =>
sum + parseFloat(b.balances.total), 0
);
console.log(`Total ssUSD across all addresses: $${totalHoldings.toFixed(2)}`);
{
"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"
}
}
{
"address": "stateset1newuser...",
"balances": {
"available": "0.00",
"pending": "0.00",
"locked": "0.00",
"total": "0.00"
},
"chains": [],
"metadata": {
"first_transaction": null,
"transaction_count": 0,
"account_type": "new"
}
}
💡 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);
}
}
📊 Related Endpoints
Transfer ssUSD
Send ssUSD to another address
Transaction History
View transaction history
Analytics
Balance analytics and insights
Reserves
View backing reserves
⌘I