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"
}
}
Legacy contract: confirm deployment before use. This page does not establish a
provisioned public service. Check the dated host report and obtain
a supported host and API version. New integrations should begin with the
API directory or local commerce walkthrough.
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
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
π€ Response
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 September 21, 2026