> ## 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. # API Reference > Complete reference documentation for all StateSet Commerce APIs # API Reference Complete documentation for all StateSet Commerce Network APIs. All API endpoints are RESTful and return JSON responses. ## ๐ŸŒ Base URLs ``` https://api.stateset.com/v1 ``` ``` https://api-testnet.stateset.com/v1 ``` ## ๐Ÿ”‘ Authentication All requests must include your API key in the Authorization header: ```bash theme={null} Authorization: Bearer ${STATESET_API_KEY} ``` ## ๐Ÿ“š Core APIs Issue, redeem, and transfer ssUSD stablecoins **Key Endpoints:** * `POST /stablecoin/issue` * `POST /stablecoin/redeem` * `POST /stablecoin/transfer` * `GET /stablecoin/balance` Process payments and handle transactions **Key Endpoints:** * `POST /payments/create` * `GET /payments/{id}` * `POST /payments/refund` * `GET /payments/list` Manage e-commerce orders and fulfillment **Key Endpoints:** * `POST /orders/create` * `PATCH /orders/{id}` * `POST /orders/{id}/fulfill` * `GET /orders/list` Trade finance, factoring, and lending **Key Endpoints:** * `POST /finance/invoices/factor` * `POST /finance/po/finance` * `POST /finance/loans/create` * `GET /finance/options` Deploy and manage autonomous agents **Key Endpoints:** * `POST /agents/create` * `POST /agents/{id}/execute` * `GET /agents/{id}/activity` * `PATCH /agents/{id}/config` Cross-border trade and compliance **Key Endpoints:** * `POST /global/orders/create` * `POST /global/compliance/check` * `GET /global/tax/calculate` * `POST /global/shipping/quote` ## ๐Ÿ”ง Common Parameters ### Pagination Most list endpoints support pagination: | Parameter | Type | Description | Default | | ---------------- | ------- | ----------------------------- | ------- | | `limit` | integer | Number of records to return | 10 | | `starting_after` | string | Cursor for pagination | null | | `ending_before` | string | Cursor for reverse pagination | null | **Example:** ```bash theme={null} GET /v1/orders?limit=20&starting_after=ord_123 ``` ### Filtering List endpoints support filtering: ```bash theme={null} GET /v1/orders?status=pending&created[gte]=2024-01-01 ``` ### Expanding Objects Request nested objects in a single call: ```bash theme={null} GET /v1/orders/ord_123?expand[]=customer&expand[]=items.product ``` ## ๐Ÿ“จ Request Format ### Headers | Header | Required | Description | | ----------------- | -------- | ------------------------------------- | | `Authorization` | Yes | Bearer token with your API key | | `Content-Type` | Yes\* | `application/json` for POST/PUT/PATCH | | `Idempotency-Key` | No | Unique key for safe retries | | `X-Account-Id` | No | Act on behalf of a connected account | ### Request Body All POST, PUT, and PATCH requests accept JSON: ```json theme={null} { "amount": 100.00, "currency": "ssusd", "recipient": "stateset1abc...", "metadata": { "order_id": "12345", "customer_email": "user@example.com" } } ``` ## ๐Ÿ“ค Response Format ### Success Response ```json theme={null} { "id": "pay_1a2b3c4d", "object": "payment", "amount": 100.00, "currency": "ssusd", "status": "succeeded", "created": 1640995200, "metadata": { "order_id": "12345" } } ``` ### Error Response ```json theme={null} { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "The 'amount' parameter is required", "param": "amount", "doc_url": "https://docs.stateset.com/errors/parameter_missing" } } ``` ## ๐Ÿ”„ Idempotency Ensure safe retries with idempotency keys: ```bash theme={null} curl -X POST https://api.stateset.com/v1/payments \ -H "Authorization: Bearer sk_test_..." \ -H "Idempotency-Key: unique-key-123" \ -d '{...}' ``` Idempotency keys are valid for 24 hours. ## ๐Ÿ“Š Rate Limits | Plan | Requests/Second | Daily Limit | Burst | | ---------- | --------------- | ----------- | ------ | | Free | 10 | 1,000 | 20 | | Starter | 100 | 100,000 | 200 | | Growth | 1,000 | 10,000,000 | 2,000 | | Enterprise | Custom | Custom | Custom | Rate limit headers: ``` X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1640995200 ``` ## ๐ŸŒ CORS The API supports CORS for browser-based requests: ```javascript theme={null} // Browser request example fetch('https://api.stateset.com/v1/account/balance', { headers: { 'Authorization': 'Bearer pk_test_...' // Public key only } }) .then(response => response.json()) .then(data => console.log(data)); ``` ## ๐Ÿ” Security ### API Key Types | Key Type | Prefix | Usage | | ---------- | ----------------------- | ------------------- | | Secret | `sk_test_` / `sk_live_` | Server-side only | | Public | `pk_test_` / `pk_live_` | Client-side safe | | Restricted | `rk_test_` / `rk_live_` | Limited permissions | ### Best Practices 1. **Never expose secret keys** in client-side code 2. **Use HTTPS** for all requests 3. **Verify webhooks** with signature validation 4. **Implement retry logic** with exponential backoff 5. **Monitor rate limits** and implement caching ## ๐Ÿ“ก Webhooks Register webhooks to receive real-time events: ```bash theme={null} POST /v1/webhooks { "url": "https://yourapp.com/webhook", "events": ["payment.succeeded", "order.created"] } ``` [Learn more about webhooks โ†’](/webhooks) ## ๐Ÿงช Testing ### Test Mode Use test API keys to simulate transactions: * No real money movement * Immediate transaction processing * Special test card numbers available ### Test Data | Resource | Test ID Format | Example | | -------- | -------------- | --------------- | | Customer | `cust_test_*` | `cust_test_123` | | Payment | `pay_test_*` | `pay_test_456` | | Order | `ord_test_*` | `ord_test_789` | ## ๐Ÿ“ฑ SDK Support Official SDKs available for: ```bash theme={null} npm install @stateset/sdk ``` ```bash theme={null} pip install stateset ``` ```bash theme={null} go get github.com/stateset/stateset-go ``` [View all SDKs โ†’](/sdks) ## ๐Ÿ†˜ Support Resources Real-time API status and incidents Import our complete API collection Get help from developers Contact our support team