Issue ssUSD - StateSet API Docs

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 scope

Authentication

curl -X POST https://api.stateset.com/v1/stablecoin/issue \
  -H "Authorization: Bearer sk_live_issuer_..." \
  -H "X-Issuer-Certificate: cert_..."

Required Headers

Header	Description
`Authorization`	Bearer token with issuer permissions
`X-Issuer-Certificate`	Issuer certificate for additional verification

Request Parameters

recipient

string

required

The StateSet address to receive the issued ssUSDFormat: stateset1 followed by 39 charactersExample: stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu

amount

string

required

Amount 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

Limits:

Minimum: $100.00
Maximum: $10,000,000.00 per transaction

reference_id

string

required

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.

source_funds

object

required

Details about the USD funds backing this issuance

Show properties

type

string

required

How the USD was receivedOptions:

bank_wire - Fedwire transfer
ach - ACH transfer
swift - International SWIFT wire
check - Cashier’s check

reference

string

required

Reference number from the payment systemExamples:

Wire: "FEDREF20240115ABC123"
ACH: "ACH-TRACE-123456"
SWIFT: "SWIFT-MT103-REF"

amount_usd

string

required

USD amount received (must match issuance amount)

sending_institution

string

required

Name of the bank/institution that sent the funds

received_at

string

required

ISO 8601 timestamp when funds were received

verified

boolean

required

Whether the funds have been verified by operations team

compliance

object

required

Compliance verification details

Show properties

kyc_status

string

required

KYC verification statusOptions: verified, pending, rejected

kyc_provider

string

required

KYC provider usedOptions: jumio, onfido, trulioo

kyc_id

string

required

KYC verification ID from provider

aml_status

string

required

AML screening statusOptions: clear, pending_review, flagged

aml_provider

string

required

AML provider usedOptions: chainalysis, elliptic, coinfirm

jurisdiction

string

required

Recipient’s jurisdiction (ISO 3166-1 alpha-2)Example: "US", "GB", "CA"

sanctions_check

boolean

required

Whether OFAC/sanctions screening passed

purpose

string

Purpose code for the issuanceOptions:

general - General business operations
merchant_settlement - E-commerce merchant payouts
payroll - Employee salary payments
vendor_payment - B2B vendor payments
treasury - Corporate treasury operations

metadata

object

Additional metadata for record keepingExample:

{
  "customer_id": "cust_123",
  "internal_ref": "MINT-2024-001",
  "notes": "Monthly merchant settlement"
}

Response

issuance

object

The issuance details

Show properties

string

Unique issuance identifierExample: "iss_1a2b3c4d5e6f7g8h"

status

string

Current status of the issuanceValues: pending, processing, completed, failed

recipient

string

The address that received ssUSD

amount

object

Amount details

Show properties

value

string

Amount in ssUSD

denom

string

Always "ssusd"

usd_value

string

USD equivalent (always matches value for ssUSD)

reference_id

string

Your provided reference ID

created_at

string

ISO 8601 creation timestamp

transaction

object

Blockchain transaction details

Show properties

hash

string

Transaction hash on StateSetExample: "B5E7A2D9F3C8E1A4D6B9C3F7E2A5D8B1E4C7F9A2"

block_height

number

Block number containing the transaction

gas_used

string

Gas consumed by the transaction

explorer_url

string

Link to view on block explorer

reserve_update

object

Reserve balance update details

Show properties

total_supply

string

New total ssUSD supply

total_reserves

string

Total USD reserves after update

reserve_ratio

string

Should always be “1.0000” or higher

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

Use Idempotency

Monitor Reserve Ratio

Implement Webhooks

Redeem ssUSD

Burn ssUSD and withdraw USD reserves

View Reserves

Check current reserve composition

Transfer ssUSD

Transfer between addresses

Attestations

View monthly reserve reports

StateSet Commerce

​Overview

​Key Requirements

Issuer Verification

KYC/AML Compliance

Reserve Verification

API Permissions

​Authentication

​Required Headers

​Request Parameters

​Response

​Error Codes

​Compliance & Regulations

​Monthly Attestation Impact

​Record Keeping

​Best Practices

​Related Endpoints

Redeem ssUSD

View Reserves

Transfer ssUSD

Attestations

Overview

Key Requirements

Authentication

Required Headers

Request Parameters

Response

Error Codes

Compliance & Regulations

Monthly Attestation Impact

Record Keeping

Best Practices

Related Endpoints