curl https://api.stateset.com/v1/stablecoin/balance/{address} \
-H "Authorization: Bearer sk_test_..."
# Balance across specific chains, including pending and locked funds
curl "https://api.stateset.com/v1/stablecoin/balance/stateset1abc...?chains=stateset,base,solana&include_pending=true&include_locked=true" \
-H "Authorization: Bearer sk_test_..."
# Balance 30 days ago
curl "https://api.stateset.com/v1/stablecoin/balance/stateset1abc...?at_timestamp=2024-05-26T00:00:00Z" \
-H "Authorization: Bearer sk_test_..."
# Current balance, to compute the 30-day change
curl "https://api.stateset.com/v1/stablecoin/balance/stateset1abc..." \
-H "Authorization: Bearer sk_test_..."
# Check multiple addresses
for addr in stateset1abc... stateset1def... stateset1ghi...; do
curl -s "https://api.stateset.com/v1/stablecoin/balance/$addr" \
-H "Authorization: Bearer sk_test_..." | jq -r '.balances.total'
done
{
"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/{address} \
-H "Authorization: Bearer sk_test_..."
# Balance across specific chains, including pending and locked funds
curl "https://api.stateset.com/v1/stablecoin/balance/stateset1abc...?chains=stateset,base,solana&include_pending=true&include_locked=true" \
-H "Authorization: Bearer sk_test_..."
# Balance 30 days ago
curl "https://api.stateset.com/v1/stablecoin/balance/stateset1abc...?at_timestamp=2024-05-26T00:00:00Z" \
-H "Authorization: Bearer sk_test_..."
# Current balance, to compute the 30-day change
curl "https://api.stateset.com/v1/stablecoin/balance/stateset1abc..." \
-H "Authorization: Bearer sk_test_..."
# Check multiple addresses
for addr in stateset1abc... stateset1def... stateset1ghi...; do
curl -s "https://api.stateset.com/v1/stablecoin/balance/$addr" \
-H "Authorization: Bearer sk_test_..." | jq -r '.balances.total'
done
{
"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/{address} \
-H "Authorization: Bearer sk_test_..."
📋 Path Parameters
string
required
The blockchain address to query. Supports multiple formats:
- StateSet:
stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu - Ethereum/Base:
0x742d35Cc6634C0532925a3b844Bc9e7595f6E321 - Solana:
DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
🔍 Query Parameters
array
Filter by specific chains or query all chainsOptions:
["stateset", "base", "solana", "cosmos"]Default: All chains where address has balanceboolean
default:false
Include pending transactions in balance calculationUseful for showing “available” vs “total” balance
boolean
default:true
Include locked/vesting balances in response
integer
Query historical balance at specific block heightExample:
1542389string
Query historical balance at specific timeFormat: ISO 8601 (e.g.,
2024-06-25T12:00:00Z)string
Convert balance to another currencyOptions:
USD, EUR, GBP, JPY, etc.📤 Response
string
The queried blockchain address
object
array
object
Balance in other currencies (if requested)
object
Errors
Succeeds with200. Failures return 400, 401, 403, 404 or 429 with an error body, per the platform status-code contract.
curl https://api.stateset.com/v1/stablecoin/balance/{address} \
-H "Authorization: Bearer sk_test_..."
# Balance across specific chains, including pending and locked funds
curl "https://api.stateset.com/v1/stablecoin/balance/stateset1abc...?chains=stateset,base,solana&include_pending=true&include_locked=true" \
-H "Authorization: Bearer sk_test_..."
# Balance 30 days ago
curl "https://api.stateset.com/v1/stablecoin/balance/stateset1abc...?at_timestamp=2024-05-26T00:00:00Z" \
-H "Authorization: Bearer sk_test_..."
# Current balance, to compute the 30-day change
curl "https://api.stateset.com/v1/stablecoin/balance/stateset1abc..." \
-H "Authorization: Bearer sk_test_..."
# Check multiple addresses
for addr in stateset1abc... stateset1def... stateset1ghi...; do
curl -s "https://api.stateset.com/v1/stablecoin/balance/$addr" \
-H "Authorization: Bearer sk_test_..." | jq -r '.balances.total'
done
{
"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 res = await fetch(
`https://api.stateset.com/v1/stablecoin/balance/${this.treasuryAddress}?include_pending=true&convert_to=USD,EUR`,
{ headers: { Authorization: `Bearer ${process.env.STATESET_API_KEY}` } }
);
const balance = await res.json();
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 fetch(
`https://api.stateset.com/v1/stablecoin/balance/${merchantWallet}?include_pending=true`,
{ headers: { Authorization: `Bearer ${process.env.STATESET_API_KEY}` } }
).then(r => r.json());
const available = parseFloat(balance.balances.available);
if (available < amount) {
throw new Error(`Insufficient funds. Available: ${available}`);
}
// Process payment
const payment = await fetch('https://api.stateset.com/v1/stablecoin/transfer', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.STATESET_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ to: recipient, amount: amount.toString(), memo: 'Payment processed' })
}).then(r => r.json());
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 fetch(
`https://api.stateset.com/v1/stablecoin/balance/${multiSig.address}?include_pending=true`,
{ headers: { Authorization: `Bearer ${process.env.STATESET_API_KEY}` } }
).then(r => r.json());
// 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
curl -X POST https://api.stateset.com/v1/webhooks \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourapp.com/webhooks/balance",
"events": ["balance.changed"],
"filters": { "address": "stateset1abc...", "minimum_change": 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 res = await fetch(`https://api.stateset.com/v1/stablecoin/balance/${userAddress}`, {
headers: { Authorization: `Bearer ${process.env.STATESET_API_KEY}` }
});
if (!res.ok) {
const { error } = await res.json();
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;
default:
console.error('Unexpected error:', error);
}
}
} catch (networkError) {
console.error('Network issue, retrying...');
// Implement retry logic
}
📊 Related Endpoints
Transfer ssUSD
Send ssUSD to another address
Transaction History
View transaction history
Analytics
Balance analytics and insights
Reserves
View backing reserves
Last modified on August 31, 2026