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?

Is ssUSD safe?

What can I do with ssUSD?

Technical Questions

Which blockchains support ssUSD?

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?

What are the fees?

Compliance Questions

Do I need KYC?

Which countries are supported?

Are transactions reported to tax authorities?

🔧 Troubleshooting Guide

Common Errors

Error: Insufficient funds

Problem: Transaction fails with insufficient funds errorSolutions:

Check your balance including pending transactions:

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

Ensure you’re accounting for fees ($0.01 per transaction)
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 failsSolutions:

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

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

Check for typos or extra spaces

Error: KYC required

Problem: Transaction blocked due to KYC requirementsSolutions:

Complete KYC verification:

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

Check KYC status:

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

For business accounts, ensure all beneficial owners are verified

Error: Rate limit exceeded

Problem: Too many API requestsSolutions:

Check rate limit headers:

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

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

Use batch operations when possible
Upgrade to higher tier for increased limits

Error: Compliance block

Problem: Transaction blocked for compliance reasonsSolutions:

Check transaction details for flags:

const screening = await stateset.compliance.getScreening(transactionId);
console.log('Risk factors:', screening.risk_factors);

Common causes:
- Sanctioned entity involvement
- Unusual transaction pattern
- Missing Travel Rule info (> $3,000)
- Exceeding velocity limits
Contact compliance team:
- Email: compliance@stateset.com
- Include transaction ID and context

Integration Issues

Webhooks not receiving events

Problem: Webhook endpoint not receiving eventsSolutions:

Verify webhook signature:

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

Check webhook status:

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

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

Check if including pending transactions:

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

Subscribe to real-time updates:

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

Clear cache if using one
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: compliance@stateset.com
Security Issues: security@stateset.com (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

StateSet Commerce

​ssUSD FAQ & Troubleshooting

​❓ Frequently Asked Questions

​General Questions

​Technical Questions

​Compliance Questions

​🔧 Troubleshooting Guide

​Common Errors

​Integration Issues

​🎯 Best Practices

​Security