> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get ssUSD Balance

> Query ssUSD balance and detailed holdings information across all supported chains

<Note>
  This endpoint provides real-time balance information with multi-chain support and historical querying capabilities.
</Note>

# ssUSD Balance API

Query StateSet USD (ssUSD) balances with comprehensive filtering, multi-chain aggregation, and real-time updates.

## 🔑 Authentication

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.stateset.com/v1/stablecoin/balance/stateset1abc... \
    -H "Authorization: Bearer sk_test_..."
  ```

  ```javascript JavaScript theme={null}
  const balance = await stateset.stablecoin.balance({
    address: 'stateset1abc...'
  });
  ```

  ```python Python theme={null}
  balance = stateset.stablecoin.balance(
      address='stateset1abc...'
  )
  ```
</CodeGroup>

## 📋 Path Parameters

<ParamField path="address" type="string" required>
  The blockchain address to query. Supports multiple formats:

  * **StateSet**: `stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu`
  * **Ethereum/Base**: `0x742d35Cc6634C0532925a3b844Bc9e7595f6E321`
  * **Solana**: `DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263`
</ParamField>

## 🔍 Query Parameters

<ParamField query="chains" type="array">
  Filter by specific chains or query all chains

  Options: `["stateset", "base", "solana", "cosmos"]`

  Default: All chains where address has balance
</ParamField>

<ParamField query="include_pending" type="boolean" default={false}>
  Include pending transactions in balance calculation

  Useful for showing "available" vs "total" balance
</ParamField>

<ParamField query="include_locked" type="boolean" default={true}>
  Include locked/vesting balances in response
</ParamField>

<ParamField query="at_height" type="integer">
  Query historical balance at specific block height

  Example: `1542389`
</ParamField>

<ParamField query="at_timestamp" type="string">
  Query historical balance at specific time

  Format: ISO 8601 (e.g., `2024-06-25T12:00:00Z`)
</ParamField>

<ParamField query="convert_to" type="string">
  Convert balance to another currency

  Options: `USD`, `EUR`, `GBP`, `JPY`, etc.
</ParamField>

## 📤 Response

<ResponseField name="address" type="string">
  The queried blockchain address
</ResponseField>

<ResponseField name="balances" type="object">
  Balance breakdown by type and chain

  <Expandable title="properties">
    <ResponseField name="available" type="string">
      Spendable balance (excluding pending and locked)
    </ResponseField>

    <ResponseField name="pending" type="string">
      Balance in pending transactions
    </ResponseField>

    <ResponseField name="locked" type="string">
      Locked or vesting balance
    </ResponseField>

    <ResponseField name="total" type="string">
      Total balance (available + pending + locked)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="chains" type="array">
  Balance breakdown by blockchain

  <Expandable title="properties">
    <ResponseField name="chain" type="string">
      Chain identifier
    </ResponseField>

    <ResponseField name="balance" type="string">
      Balance on this chain
    </ResponseField>

    <ResponseField name="pending" type="string">
      Pending balance on this chain
    </ResponseField>

    <ResponseField name="last_activity" type="string">
      Last transaction timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conversions" type="object">
  Balance in other currencies (if requested)
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional account information

  <Expandable title="properties">
    <ResponseField name="first_transaction" type="string">
      Timestamp of first ssUSD transaction
    </ResponseField>

    <ResponseField name="transaction_count" type="integer">
      Total number of transactions
    </ResponseField>

    <ResponseField name="account_type" type="string">
      Account classification: `retail`, `institutional`, `merchant`
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Basic Balance Query theme={null}
  curl https://api.stateset.com/v1/stablecoin/balance/stateset1abc... \
    -H "Authorization: Bearer sk_test_..."
  ```

  ```javascript Multi-Chain Balance theme={null}
  // 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`);
  });
  ```

  ```python Historical Balance theme={null}
  # 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}")
  ```

  ```javascript Batch Balance Query theme={null}
  // 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)}`);
  ```
</RequestExample>

<ResponseExample>
  ```json Standard Response theme={null}
  {
    "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"
    }
  }
  ```

  ```json Empty Balance Response theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

## 💡 Common Use Cases

### Treasury Dashboard

```javascript theme={null}
// 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

```javascript theme={null}
// 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

```javascript theme={null}
// 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:

```javascript theme={null}
// 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

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Transfer ssUSD" icon="arrow-right" href="/stablecoin/transfer">
    Send ssUSD to another address
  </Card>

  <Card title="Transaction History" icon="clock" href="/stablecoin/transactions">
    View transaction history
  </Card>

  <Card title="Analytics" icon="chart-line" href="/stablecoin/analytics">
    Balance analytics and insights
  </Card>

  <Card title="Reserves" icon="shield" href="/stablecoin/reserves">
    View backing reserves
  </Card>
</CardGroup>