curl -X POST https://api.stateset.com/v1/stablecoin/issue \
-H "Authorization: Bearer sk_live_issuer_..." \
-H "X-Issuer-Certificate: cert_..." \
-H "Content-Type: application/json" \
-d '{
"recipient": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
"amount": "50000.00",
"reference_id": "ISS-2024-001234",
"source_funds": {
"type": "bank_wire",
"reference": "FEDREF20240115ABC123",
"amount_usd": "50000.00",
"sending_institution": "Chase Bank",
"received_at": "2024-01-15T09:30:00Z",
"verified": true
},
"compliance": {
"kyc_status": "verified",
"kyc_provider": "jumio",
"kyc_id": "KYC-ABC-123456",
"aml_status": "clear",
"aml_provider": "chainalysis",
"jurisdiction": "US",
"sanctions_check": true
},
"purpose": "merchant_settlement",
"metadata": {
"customer_id": "cust_123456",
"batch": "SETTLE-2024-01-15"
}
}'
{
"issuance": {
"id": "iss_1a2b3c4d5e6f7g8h",
"status": "completed",
"recipient": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
"amount": {
"value": "50000.00",
"denom": "ssusd",
"usd_value": "50000.00"
},
"reference_id": "ISS-2024-001234",
"created_at": "2024-01-15T10:30:05Z"
},
"transaction": {
"hash": "B5E7A2D9F3C8E1A4D6B9C3F7E2A5D8B1E4C7F9A2",
"block_height": 1234567,
"gas_used": "125000",
"explorer_url": "https://explorer.stateset.com/tx/B5E7A2D9F3C8E1A4D6B9C3F7E2A5D8B1E4C7F9A2"
},
"reserve_update": {
"total_supply": "125000000.00",
"total_reserves": "125500000.00",
"reserve_ratio": "1.0040"
}
}
{
"error": {
"type": "invalid_request_error",
"code": "insufficient_reserve_verification",
"message": "Source funds have not been verified. Please contact operations team.",
"param": "source_funds.verified",
"details": {
"wire_reference": "FEDREF20240115ABC123",
"expected_amount": "50000.00",
"verification_status": "pending"
}
}
}
Issue ssUSD
Mint new StateSet USD (ssUSD) stablecoins upon receipt of USD reserves
POST
/
v1
/
stablecoin
/
issue
curl -X POST https://api.stateset.com/v1/stablecoin/issue \
-H "Authorization: Bearer sk_live_issuer_..." \
-H "X-Issuer-Certificate: cert_..." \
-H "Content-Type: application/json" \
-d '{
"recipient": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
"amount": "50000.00",
"reference_id": "ISS-2024-001234",
"source_funds": {
"type": "bank_wire",
"reference": "FEDREF20240115ABC123",
"amount_usd": "50000.00",
"sending_institution": "Chase Bank",
"received_at": "2024-01-15T09:30:00Z",
"verified": true
},
"compliance": {
"kyc_status": "verified",
"kyc_provider": "jumio",
"kyc_id": "KYC-ABC-123456",
"aml_status": "clear",
"aml_provider": "chainalysis",
"jurisdiction": "US",
"sanctions_check": true
},
"purpose": "merchant_settlement",
"metadata": {
"customer_id": "cust_123456",
"batch": "SETTLE-2024-01-15"
}
}'
{
"issuance": {
"id": "iss_1a2b3c4d5e6f7g8h",
"status": "completed",
"recipient": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
"amount": {
"value": "50000.00",
"denom": "ssusd",
"usd_value": "50000.00"
},
"reference_id": "ISS-2024-001234",
"created_at": "2024-01-15T10:30:05Z"
},
"transaction": {
"hash": "B5E7A2D9F3C8E1A4D6B9C3F7E2A5D8B1E4C7F9A2",
"block_height": 1234567,
"gas_used": "125000",
"explorer_url": "https://explorer.stateset.com/tx/B5E7A2D9F3C8E1A4D6B9C3F7E2A5D8B1E4C7F9A2"
},
"reserve_update": {
"total_supply": "125000000.00",
"total_reserves": "125500000.00",
"reserve_ratio": "1.0040"
}
}
{
"error": {
"type": "invalid_request_error",
"code": "insufficient_reserve_verification",
"message": "Source funds have not been verified. Please contact operations team.",
"param": "source_funds.verified",
"details": {
"wire_reference": "FEDREF20240115ABC123",
"expected_amount": "50000.00",
"verification_status": "pending"
}
}
}
Legacy contract: confirm deployment before use. This page does not establish a
provisioned public service. Check the dated host report and obtain
a supported host and API version. New integrations should begin with the
API directory or local commerce walkthrough.
Issuer Access Only: This endpoint requires verified issuer status under the GENIUS Act. Contact sales@stateset.com for issuer onboarding.
Overview
The issue endpoint allows authorized entities to mint new ssUSD tokens when USD funds are received and verified. Every ssUSD issued is backed 1:1 by USD reserves held in segregated accounts.Key Requirements
Issuer Verification
Must be approved as a Federal Qualified Nonbank Payment Stablecoin Issuer
KYC/AML Compliance
All issuances require completed KYC and passed AML checks
Reserve Verification
USD funds must be received and verified before issuance
API Permissions
API key must have
stablecoin:issue scopeAuthentication
curl -X POST https://api.stateset.com/v1/stablecoin/issue \
-H "Authorization: Bearer sk_live_issuer_..." \
-H "X-Issuer-Certificate: cert_..."
const headers = {
'Authorization': 'Bearer sk_live_issuer_...',
'X-Issuer-Certificate': 'cert_...'
};
Required Headers
| Header | Description |
|---|---|
Authorization | Bearer token with issuer permissions |
X-Issuer-Certificate | Issuer certificate for additional verification |
Request Parameters
The StateSet address to receive the issued ssUSDFormat:
stateset1 followed by 39 charactersExample: stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xuAmount of ssUSD to issue in standard units (not micro units)Format: Decimal string with up to 2 decimal placesExamples:
"1000.00"- Issue 1,000 ssUSD"50000.50"- Issue 50,000.50 ssUSD
- Minimum: $100.00
- Maximum: $10,000,000.00 per transaction
Unique identifier for this issuance. Used for idempotency.Format: Any unique string up to 64 charactersExample:
"ISS-2024-001234"Reusing a reference_id will return the original transaction instead of creating a new one.
Details about the USD funds backing this issuance
Show properties
Show properties
How the USD was receivedOptions:
bank_wire- Fedwire transferach- ACH transferswift- International SWIFT wirecheck- Cashier’s check
Reference number from the payment systemExamples:
- Wire:
"FEDREF20240115ABC123" - ACH:
"ACH-TRACE-123456" - SWIFT:
"SWIFT-MT103-REF"
Compliance verification details
Show properties
Show properties
Purpose code for the issuanceOptions:
general- General business operationsmerchant_settlement- E-commerce merchant payoutspayroll- Employee salary paymentsvendor_payment- B2B vendor paymentstreasury- Corporate treasury operations
Additional metadata for record keepingExample:
{
"customer_id": "cust_123",
"internal_ref": "MINT-2024-001",
"notes": "Monthly merchant settlement"
}
Response
The issuance details
Show properties
Show properties
Errors
Succeeds with201. Failures return 400, 401, 403, 422 or 429 with an error body, per the platform status-code contract.
curl -X POST https://api.stateset.com/v1/stablecoin/issue \
-H "Authorization: Bearer sk_live_issuer_..." \
-H "X-Issuer-Certificate: cert_..." \
-H "Content-Type: application/json" \
-d '{
"recipient": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
"amount": "50000.00",
"reference_id": "ISS-2024-001234",
"source_funds": {
"type": "bank_wire",
"reference": "FEDREF20240115ABC123",
"amount_usd": "50000.00",
"sending_institution": "Chase Bank",
"received_at": "2024-01-15T09:30:00Z",
"verified": true
},
"compliance": {
"kyc_status": "verified",
"kyc_provider": "jumio",
"kyc_id": "KYC-ABC-123456",
"aml_status": "clear",
"aml_provider": "chainalysis",
"jurisdiction": "US",
"sanctions_check": true
},
"purpose": "merchant_settlement",
"metadata": {
"customer_id": "cust_123456",
"batch": "SETTLE-2024-01-15"
}
}'
{
"issuance": {
"id": "iss_1a2b3c4d5e6f7g8h",
"status": "completed",
"recipient": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
"amount": {
"value": "50000.00",
"denom": "ssusd",
"usd_value": "50000.00"
},
"reference_id": "ISS-2024-001234",
"created_at": "2024-01-15T10:30:05Z"
},
"transaction": {
"hash": "B5E7A2D9F3C8E1A4D6B9C3F7E2A5D8B1E4C7F9A2",
"block_height": 1234567,
"gas_used": "125000",
"explorer_url": "https://explorer.stateset.com/tx/B5E7A2D9F3C8E1A4D6B9C3F7E2A5D8B1E4C7F9A2"
},
"reserve_update": {
"total_supply": "125000000.00",
"total_reserves": "125500000.00",
"reserve_ratio": "1.0040"
}
}
{
"error": {
"type": "invalid_request_error",
"code": "insufficient_reserve_verification",
"message": "Source funds have not been verified. Please contact operations team.",
"param": "source_funds.verified",
"details": {
"wire_reference": "FEDREF20240115ABC123",
"expected_amount": "50000.00",
"verification_status": "pending"
}
}
}
Error Codes
| Code | Description | Resolution |
|---|---|---|
unauthorized_issuer | Not authorized to issue ssUSD | Contact sales for issuer onboarding |
insufficient_permissions | API key lacks issue permissions | Use an issuer API key |
duplicate_reference | Reference ID already used | Use a unique reference ID |
insufficient_reserve_verification | USD funds not verified | Wait for operations to verify wire |
compliance_check_failed | KYC/AML check failed | Resolve compliance issues |
invalid_recipient | Invalid StateSet address | Check address format |
amount_mismatch | Source funds don’t match issuance | Ensure amounts match exactly |
rate_limit_exceeded | Too many requests | Implement exponential backoff |
Compliance & Regulations
All issuances must comply with GENIUS Act requirements. Failure to maintain proper reserves or accurate reporting may result in criminal penalties.
Monthly Attestation Impact
Each issuance updates the reserve balance that must be attested monthly:- Increases total ssUSD supply
- Must be backed by verified USD reserves
- Included in monthly CPA audit
- Subject to regulatory review
Record Keeping
All issuance records are maintained for 7 years including:- Source fund documentation
- KYC/AML verification records
- Transaction details
- Reserve balance updates
Best Practices
Verify Funds First
Verify Funds First
Always ensure USD funds are received and verified before attempting issuance. The API will reject issuances without verified backing funds.
Use Idempotency
Use Idempotency
Always provide a unique
reference_id. This prevents accidental duplicate issuances and allows safe retries.Monitor Reserve Ratio
Monitor Reserve Ratio
After each issuance, verify the
reserve_ratio remains at or above 1.0000. This ensures full backing.Implement Webhooks
Implement Webhooks
Set up webhooks to receive real-time notifications about issuance status, especially for large amounts.
Related Endpoints
Redeem ssUSD
Burn ssUSD and withdraw USD reserves
View Reserves
Check current reserve composition
Transfer ssUSD
Transfer between addresses
Attestations
View monthly reserve reports
Last modified on September 21, 2026