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

What is ssUSD?

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

Is ssUSD safe?

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 and reserve reports.

What can I do with ssUSD?

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

Technical Questions

Which blockchains support ssUSD?

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 to move between chains.

What are the transaction limits?

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 →

How fast are transfers?

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

What are the fees?

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.

Compliance Questions

Do I need KYC?

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 →

Which countries are supported?

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

Are transactions reported to tax authorities?

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.

🔧 Troubleshooting Guide

Common Errors

Error: Insufficient funds

Problem: Transaction fails with insufficient funds error

Solutions:

1. Check your balance including pending transactions:

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:

console.log('Available:', balance.balances.available);
console.log('Locked:', balance.balances.locked);

Error: Invalid address format

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:

const isValid = stateset.utils.validateAddress(
  address,
  'stateset' // or 'ethereum', 'solana'
);

3. Check for typos or extra spaces

Error: KYC required

Problem: Transaction blocked due to KYC requirements

Solutions:

1. Complete KYC verification:

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

2. Check KYC status:

const status = await stateset.compliance.getKYCStatus();
console.log('KYC Status:', status); // pending, approved, rejected

3. For business accounts, ensure all beneficial owners are verified

Error: Rate limit exceeded

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:

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

Error: Compliance block

Problem: Transaction blocked for compliance reasons

Solutions:

1. Check transaction details for flags:

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: [e-mail]
   • Include transaction ID and context

Integration Issues

Webhooks not receiving events

Problem: Webhook endpoint not receiving events

Solutions:

1. Verify webhook signature:

const isValid = stateset.webhooks.verifySignature(
  payload,
  headers['x-stateset-signature'],
  webhookSecret
);

2. Check webhook status:

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)

Balance not updating

Problem: Balance appears incorrect or not updating

Solutions:

1. Check if including pending transactions:

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

2. Subscribe to real-time updates:

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

🎯 Best Practices

Security

API Key Management

• Never expose secret keys in client code
• Use environment variables
• Rotate keys regularly
• Use restricted keys with minimal permissions

Transaction Security

• Always verify recipient addresses
• Use idempotency keys for retries
• Implement transaction limits
• Monitor for unusual patterns

Performance

Optimize API Calls

• Use batch operations when possible
• Implement caching for read operations
• Use webhooks instead of polling
• Parallelize independent operations

Error Handling

• Implement proper retry logic
• Log all errors with context
• Have fallback mechanisms
• Monitor error rates

🆘 Getting Help

Support Channels

Discord

Real-time help from community and team

GitHub Issues

Report bugs and request features

Email Support

For sensitive or account-specific issues

Emergency Contacts

• Compliance Issues: [e-mail]
• Security Issues: [e-mail] (PGP available)
• API Emergencies: +1-888-STATESET (24/7)

Debug Information

When contacting support, include:

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

Video Tutorials

Step-by-step video guides

Sample Apps

Full example applications

API Status

Real-time system status

Blog

Updates and best practices