API Reference

Complete documentation for all StateSet Commerce Network APIs. All API endpoints are RESTful and return JSON responses.

🌐 Base URLs

Production
Testnet

https://api.stateset.com/v1

https://api-testnet.stateset.com/v1

🔑 Authentication

All requests must include your API key in the Authorization header:

Authorization: Bearer ${STATESET_API_KEY}

📚 Core APIs

Stablecoin API

Issue, redeem, and transfer ssUSD stablecoinsKey Endpoints:

POST /stablecoin/issue
POST /stablecoin/redeem
POST /stablecoin/transfer
GET /stablecoin/balance

Payments API

Process payments and handle transactionsKey Endpoints:

POST /payments/create
GET /payments/{id}
POST /payments/refund
GET /payments/list

Orders API

Manage e-commerce orders and fulfillmentKey Endpoints:

POST /orders/create
PATCH /orders/{id}
POST /orders/{id}/fulfill
GET /orders/list

Finance API

Trade finance, factoring, and lendingKey Endpoints:

POST /finance/invoices/factor
POST /finance/po/finance
POST /finance/loans/create
GET /finance/options

AI Agents API

Deploy and manage autonomous agentsKey Endpoints:

POST /agents/create
POST /agents/{id}/execute
GET /agents/{id}/activity
PATCH /agents/{id}/config

Global Commerce API

Cross-border trade and complianceKey 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:

GET /v1/orders?limit=20&starting_after=ord_123

Filtering

List endpoints support filtering:

GET /v1/orders?status=pending&created[gte]=2024-01-01

Expanding Objects

Request nested objects in a single call:

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:

{
  "amount": 100.00,
  "currency": "ssusd",
  "recipient": "stateset1abc...",
  "metadata": {
    "order_id": "12345",
    "customer_email": "user@example.com"
  }
}

📤 Response Format

Success Response

{
  "id": "pay_1a2b3c4d",
  "object": "payment",
  "amount": 100.00,
  "currency": "ssusd",
  "status": "succeeded",
  "created": 1640995200,
  "metadata": {
    "order_id": "12345"
  }
}

Error Response

{
  "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:

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:

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

Never expose secret keys in client-side code
Use HTTPS for all requests
Verify webhooks with signature validation
Implement retry logic with exponential backoff
Monitor rate limits and implement caching

📡 Webhooks

POST /v1/webhooks
{
  "url": "https://yourapp.com/webhook",
  "events": ["payment.succeeded", "order.created"]
}

Learn more about 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:

Node.js

npm install @stateset/sdk

Python

pip install stateset

Go

go get github.com/stateset/stateset-go

View all SDKs →

🆘 Support Resources

API Status

Real-time API status and incidents

Postman Collection

Import our complete API collection

Discord Community

Get help from developers

Support Portal

Contact our support team

Authentication SDKs & Libraries

​API Reference

​🌐 Base URLs

​🔑 Authentication

​📚 Core APIs

Stablecoin API

Payments API

Orders API

Finance API

AI Agents API

Global Commerce API

​🔧 Common Parameters

​Pagination

​Filtering

​Expanding Objects

​📨 Request Format

​Headers

​Request Body

​📤 Response Format

​Success Response

​Error Response

​🔄 Idempotency

​📊 Rate Limits

​🌍 CORS

​🔐 Security

​API Key Types

​Best Practices

​📡 Webhooks

​🧪 Testing

​Test Mode

​Test Data

​📱 SDK Support