> ## 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

<Warning>
  **Legacy contract: confirm deployment before use.** This page does not establish a
  provisioned public service. Check the dated [host report](/api-reference/hosts) and obtain
  a supported host and API version. New integrations should begin with the
  [API directory](/api-reference/introduction) or [local commerce walkthrough](/guides/first-operation).
</Warning>

<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/{address} \
    -H "Authorization: Bearer sk_test_..."
  ```
</CodeGroup>

*JS/Python SDK support for this resource has not shipped yet.*

## 📋 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>

### Errors

Succeeds with `200`. Failures return `400`, `401`, `403`, `404` or `429` with an error body, per the [platform status-code contract](/api-reference/errors#http-status-codes).

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

  ```bash Multi-Chain Balance theme={null}
  # 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_..."
  ```

  ```bash Historical Balance theme={null}
  # 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_..."
  ```

  ```bash Batch Balance Query theme={null}
  # 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
  ```
</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 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

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

```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 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:

```bash theme={null}
# 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 }
  }'
```

```json Webhook payload theme={null}
{
  "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 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

<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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.