Skip to main content
POST
https://api.stateset.com
/
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"
  }
}
Issuer Access Only: This endpoint requires verified issuer status under the GENIUS Act. Contact [email protected] 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

HeaderDescription
AuthorizationBearer token with issuer permissions
X-Issuer-CertificateIssuer 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
​
compliance
object
required
Compliance verification details
​
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
​
transaction
object
Blockchain transaction details
​
reserve_update
object
Reserve balance update details
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

CodeDescriptionResolution
unauthorized_issuerNot authorized to issue ssUSDContact sales for issuer onboarding
insufficient_permissionsAPI key lacks issue permissionsUse an issuer API key
duplicate_referenceReference ID already usedUse a unique reference ID
insufficient_reserve_verificationUSD funds not verifiedWait for operations to verify wire
compliance_check_failedKYC/AML check failedResolve compliance issues
invalid_recipientInvalid StateSet addressCheck address format
amount_mismatchSource funds don’t match issuanceEnsure amounts match exactly
rate_limit_exceededToo many requestsImplement 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

Always ensure USD funds are received and verified before attempting issuance. The API will reject issuances without verified backing funds.
Always provide a unique reference_id. This prevents accidental duplicate issuances and allows safe retries.
After each issuance, verify the reserve_ratio remains at or above 1.0000. This ensures full backing.
Set up webhooks to receive real-time notifications about issuance status, especially for large amounts.

Redeem ssUSD

Burn ssUSD and withdraw USD reserves

View Reserves

Check current reserve composition

Transfer ssUSD

Transfer between addresses

Attestations

View monthly reserve reports