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

# ssUSD FAQ & Troubleshooting

> Frequently asked questions and troubleshooting guide for StateSet USD

# ssUSD FAQ & Troubleshooting

Find answers to common questions and solutions to typical issues when working with StateSet USD.

## ❓ Frequently Asked Questions

### General Questions

<AccordionGroup>
  <Accordion title="What is ssUSD?" icon="circle-question">
    **StateSet USD (ssUSD)** is a fully-backed, regulatory-compliant stablecoin pegged 1:1 to the US Dollar. It's a stablecoin issued under the GENIUS Act, featuring:

    * 1:1 USD backing with audited reserves
    * Monthly CPA attestations published on-chain
    * Criminal penalties for reserve misreporting
    * Instant settlement on StateSet Network
    * Multi-chain support (Base, Solana, Cosmos)
    * Full KYC/AML compliance
  </Accordion>

  <Accordion title="Is ssUSD safe?" icon="shield-check">
    **Yes, ssUSD has multiple safety layers:**

    1. **Regulatory Safety**: Federal oversight by OCC
    2. **Reserve Safety**: 100% backed by US Dollars and T-Bills
    3. **Legal Safety**: Criminal penalties for misreporting
    4. **Technical Safety**: Audited smart contracts
    5. **Operational Safety**: Segregated customer assets

    See our [security audits](/security/audits) and [reserve reports](/stablecoin/reserves).
  </Accordion>

  <Accordion title="What can I do with ssUSD?" icon="rocket">
    **ssUSD Use Cases:**

    * **Payments**: Instant, low-cost transactions globally
    * **E-commerce**: Accept payments without chargebacks
    * **Payroll**: Pay employees instantly worldwide
    * **Treasury**: Hold stable, liquid reserves
    * **Cross-border**: Send money internationally
  </Accordion>
</AccordionGroup>

### Technical Questions

<AccordionGroup>
  <Accordion title="Which blockchains support ssUSD?" icon="link">
    **Supported Chains:**

    1. **StateSet** (Native): Instant, \$0.01 fees
    2. **Base**: Coinbase's L2, low fees
    3. **Solana**: High-speed DeFi
    4. **Cosmos IBC**: 50+ connected chains
    5. **Ethereum** (Coming Q2 2024)
    6. **Polygon** (Coming Q2 2024)

    Use our [bridge](/stablecoin/bridge) to move between chains.
  </Accordion>

  <Accordion title="What are the transaction limits?" icon="gauge">
    **Limits by Account Type:**

    | Account Type | Daily       | Monthly      | Per Transaction |
    | ------------ | ----------- | ------------ | --------------- |
    | Basic        | \$10,000    | \$50,000     | \$5,000         |
    | Verified     | \$100,000   | \$500,000    | \$50,000        |
    | Premium      | \$1,000,000 | \$10,000,000 | \$500,000       |
    | Business     | Custom      | Custom       | Custom          |

    [Request limit increase →](/compliance/limits)
  </Accordion>

  <Accordion title="How fast are transfers?" icon="bolt">
    **Transfer Speeds:**

    * **On StateSet**: \< 1 second finality
    * **To Base**: \~2 seconds
    * **To Solana**: \~3 seconds
    * **Cross-chain**: 1-5 minutes (via bridge)
    * **Bank redemption**: T+1 business day
  </Accordion>

  <Accordion title="What are the fees?" icon="dollar-sign">
    **Fee Structure:**

    * **Transfers on StateSet**: \$0.01 flat
    * **Cross-chain bridge**: 0.1% (min $1, max $100)
    * **Issuance**: 0% (no fees)
    * **Redemption**: 0% (no fees)
    * **Inactive account**: \$0/month

    No hidden fees, no minimum balance requirements.
  </Accordion>
</AccordionGroup>

### Compliance Questions

<AccordionGroup>
  <Accordion title="Do I need KYC?" icon="id-card">
    **KYC Requirements:**

    * **Required for**: Issuance, redemption, > \$1,000 daily volume
    * **Not required for**: Transfers between verified users \< \$1,000
    * **Process time**: 5-10 minutes automated
    * **Documents needed**: Government ID, proof of address
    * **Business accounts**: Additional docs (formation, tax ID)

    [Start KYC →](/kyc/start)
  </Accordion>

  <Accordion title="Which countries are supported?" icon="globe">
    **Supported Regions:**

    ✅ **Fully Supported**: USA, Canada, UK, EU, Singapore, Japan, Australia

    ⚠️ **Limited Support**: China, India, Brazil (transfers only)

    ❌ **Not Supported**: North Korea, Iran, Syria, Cuba, Russia (sanctioned)

    See [full country list](/compliance/countries)
  </Accordion>

  <Accordion title="Are transactions reported to tax authorities?" icon="file-invoice">
    **Tax Reporting:**

    * **US Persons**: 1099 forms for > \$600 annual volume
    * **Non-US**: Comply with local regulations
    * **API Access**: Download transaction history anytime
    * **Export Formats**: CSV, PDF, JSON

    ssUSD transactions may be taxable events. Consult your tax advisor.
  </Accordion>
</AccordionGroup>

## 🔧 Troubleshooting Guide

### Common Errors

<AccordionGroup>
  <Accordion title="Error: Insufficient funds" icon="x-circle">
    **Problem**: Transaction fails with insufficient funds error

    **Solutions:**

    1. Check your balance including pending transactions:

    ```javascript theme={null}
    const balance = await stateset.stablecoin.balance({
      address: yourAddress,
      include_pending: true
    });
    ```

    2. Ensure you're accounting for fees (\$0.01 per transaction)

    3. Check if funds are locked or vesting:

    ```javascript theme={null}
    console.log('Available:', balance.balances.available);
    console.log('Locked:', balance.balances.locked);
    ```
  </Accordion>

  <Accordion title="Error: Invalid address format" icon="map-marker">
    **Problem**: Address validation fails

    **Solutions:**

    1. Verify address format for the chain:
       * StateSet: `stateset1...` (45 chars)
       * Ethereum/Base: `0x...` (42 chars)
       * Solana: `base58...` (44 chars)
    2. Use address validation:

    ```javascript theme={null}
    const isValid = stateset.utils.validateAddress(
      address,
      'stateset' // or 'ethereum', 'solana'
    );
    ```

    3. Check for typos or extra spaces
  </Accordion>

  <Accordion title="Error: KYC required" icon="shield-x">
    **Problem**: Transaction blocked due to KYC requirements

    **Solutions:**

    1. Complete KYC verification:

    ```javascript theme={null}
    const kycUrl = await stateset.compliance.getKYCUrl({
      redirect_url: 'https://yourapp.com/kyc-complete'
    });
    window.location.href = kycUrl;
    ```

    2. Check KYC status:

    ```javascript theme={null}
    const status = await stateset.compliance.getKYCStatus();
    console.log('KYC Status:', status); // pending, approved, rejected
    ```

    3. For business accounts, ensure all beneficial owners are verified
  </Accordion>

  <Accordion title="Error: Rate limit exceeded" icon="gauge-high">
    **Problem**: Too many API requests

    **Solutions:**

    1. Check rate limit headers:

    ```
    X-RateLimit-Limit: 100
    X-RateLimit-Remaining: 0
    X-RateLimit-Reset: 1640995200
    ```

    2. Implement exponential backoff:

    ```javascript theme={null}
    async function retryWithBackoff(fn, maxRetries = 3) {
      for (let i = 0; i < maxRetries; i++) {
        try {
          return await fn();
        } catch (error) {
          if (error.code === 'rate_limit' && i < maxRetries - 1) {
            await sleep(Math.pow(2, i) * 1000);
          } else {
            throw error;
          }
        }
      }
    }
    ```

    3. Use batch operations when possible
    4. Upgrade to higher tier for increased limits
  </Accordion>

  <Accordion title="Error: Compliance block" icon="ban">
    **Problem**: Transaction blocked for compliance reasons

    **Solutions:**

    1. Check transaction details for flags:

    ```javascript theme={null}
    const screening = await stateset.compliance.getScreening(transactionId);
    console.log('Risk factors:', screening.risk_factors);
    ```

    2. Common causes:
       * Sanctioned entity involvement
       * Unusual transaction pattern
       * Missing Travel Rule info (> \$3,000)
       * Exceeding velocity limits
    3. Contact compliance team:
       * Email: [compliance@stateset.com](mailto:compliance@stateset.com)
       * Include transaction ID and context
  </Accordion>
</AccordionGroup>

### Integration Issues

<AccordionGroup>
  <Accordion title="Webhooks not receiving events" icon="webhook">
    **Problem**: Webhook endpoint not receiving events

    **Solutions:**

    1. Verify webhook signature:

    ```javascript theme={null}
    const isValid = stateset.webhooks.verifySignature(
      payload,
      headers['x-stateset-signature'],
      webhookSecret
    );
    ```

    2. Check webhook status:

    ```javascript theme={null}
    const webhooks = await stateset.webhooks.list();
    webhooks.forEach(w => {
      console.log(`${w.url}: ${w.status}, last error: ${w.last_error}`);
    });
    ```

    3. Common issues:
       * Firewall blocking StateSet IPs
       * SSL certificate problems
       * Timeout (must respond in 20s)
       * Wrong content-type (expects JSON)
  </Accordion>

  <Accordion title="Balance not updating" icon="sync">
    **Problem**: Balance appears incorrect or not updating

    **Solutions:**

    1. Check if including pending transactions:

    ```javascript theme={null}
    const balance = await stateset.stablecoin.balance({
      address: yourAddress,
      include_pending: true,
      chains: ['stateset', 'base', 'solana'] // Check all chains
    });
    ```

    2. Subscribe to real-time updates:

    ```javascript theme={null}
    const ws = stateset.subscriptions.connect();
    ws.subscribe('balance.updated', (event) => {
      console.log('New balance:', event.balance);
    });
    ```

    3. Clear cache if using one
    4. Verify transaction actually completed on-chain
  </Accordion>
</AccordionGroup>

## 🎯 Best Practices

### Security

<CardGroup cols={2}>
  <Card title="API Key Management" icon="key">
    * Never expose secret keys in client code
    * Use environment variables
    * Rotate keys regularly
    * Use restricted keys with minimal permissions
  </Card>

  <Card title="Transaction Security" icon="lock">
    * Always verify recipient addresses
    * Use idempotency keys for retries
    * Implement transaction limits
    * Monitor for unusual patterns
  </Card>
</CardGroup>

### Performance

<CardGroup cols={2}>
  <Card title="Optimize API Calls" icon="gauge">
    * Use batch operations when possible
    * Implement caching for read operations
    * Use webhooks instead of polling
    * Parallelize independent operations
  </Card>

  <Card title="Error Handling" icon="shield-check">
    * Implement proper retry logic
    * Log all errors with context
    * Have fallback mechanisms
    * Monitor error rates
  </Card>
</CardGroup>

## 🆘 Getting Help

### Support Channels

<CardGroup cols={3}>
  <Card title="Discord" icon="discord" href="https://discord.gg/stateset">
    Real-time help from community and team
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/stateset/issues">
    Report bugs and request features
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:support@stateset.com">
    For sensitive or account-specific issues
  </Card>
</CardGroup>

### Emergency Contacts

* **Compliance Issues**: [compliance@stateset.com](mailto:compliance@stateset.com)
* **Security Issues**: [security@stateset.com](mailto:security@stateset.com) (PGP available)
* **API Emergencies**: +1-888-STATESET (24/7)

### Debug Information

When contacting support, include:

```javascript theme={null}
const debugInfo = {
  sdk_version: stateset.version,
  api_endpoint: stateset.apiEndpoint,
  timestamp: new Date().toISOString(),
  request_id: response.headers['x-request-id'],
  error_code: error.code,
  error_message: error.message,
  stack_trace: error.stack
};
```

## 📚 Additional Resources

<CardGroup cols={2}>
  <Card title="Video Tutorials" icon="video" href="https://youtube.com/stateset">
    Step-by-step video guides
  </Card>

  <Card title="Sample Apps" icon="code" href="https://github.com/stateset/examples">
    Full example applications
  </Card>

  <Card title="API Status" icon="signal" href="https://status.stateset.com">
    Real-time system status
  </Card>

  <Card title="Blog" icon="newspaper" href="https://blog.stateset.com">
    Updates and best practices
  </Card>
</CardGroup>