GET
/
v1
/
stablecoin
/
balance
/
:address
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"
  }
}
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

address
string
required
The blockchain address to query. Supports multiple formats:
  • StateSet: stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu
  • Ethereum/Base: 0x742d35Cc6634C0532925a3b844Bc9e7595f6E321
  • Solana: DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

🔍 Query Parameters

chains
array
Filter by specific chains or query all chainsOptions: ["stateset", "base", "solana", "cosmos"]Default: All chains where address has balance
include_pending
boolean
default:false
Include pending transactions in balance calculationUseful for showing “available” vs “total” balance
include_locked
boolean
default:true
Include locked/vesting balances in response
at_height
integer
Query historical balance at specific block heightExample: 1542389
at_timestamp
string
Query historical balance at specific timeFormat: ISO 8601 (e.g., 2024-06-25T12:00:00Z)
convert_to
string
Convert balance to another currencyOptions: USD, EUR, GBP, JPY, etc.

📤 Response

address
string
The queried blockchain address
balances
object
Balance breakdown by type and chain
chains
array
Balance breakdown by blockchain
conversions
object
Balance in other currencies (if requested)
metadata
object
Additional account information
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);
  }
}