StateSet API Docs

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

POST

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

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_..."

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

string

required

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

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

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.

object

required

Details about the USD funds backing this issuance

Show properties

string

required

How the USD was receivedOptions:

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

string

required

Reference number from the payment systemExamples:

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

string

required

USD amount received (must match issuance amount)

string

required

Name of the bank/institution that sent the funds

string

required

ISO 8601 timestamp when funds were received

boolean

required

Whether the funds have been verified by operations team

object

required

Compliance verification details

Show properties

string

required

KYC verification statusOptions: verified, pending, rejected

string

required

KYC provider usedOptions: jumio, onfido, trulioo

string

required

KYC verification ID from provider

string

required

AML screening statusOptions: clear, pending_review, flagged

string

required

AML provider usedOptions: chainalysis, elliptic, coinfirm

string

required

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

boolean

required

Whether OFAC/sanctions screening passed

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

object

Additional metadata for record keepingExample:

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

Response

object

The issuance details

Show properties

string

Unique issuance identifierExample: "iss_1a2b3c4d5e6f7g8h"

string

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

string

The address that received ssUSD

object

Amount details

Show properties

string

Amount in ssUSD

string

Always "ssusd"

string

USD equivalent (always matches value for ssUSD)

string

Your provided reference ID

string

ISO 8601 creation timestamp

object

Blockchain transaction details

Show properties

string

Transaction hash on StateSetExample: "B5E7A2D9F3C8E1A4D6B9C3F7E2A5D8B1E4C7F9A2"

number

Block number containing the transaction

string

Gas consumed by the transaction

string

Link to view on block explorer

object

Reserve balance update details

Show properties

string

New total ssUSD supply

string

Total USD reserves after update

string

Should always be “1.0000” or higher

Errors

Succeeds with 201. 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"
    }
  }'

JS/Python SDK support for this resource has not shipped yet.

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

Always ensure USD funds are received and verified before attempting issuance. The API will reject issuances without verified backing funds.

Use Idempotency

Always provide a unique reference_id. This prevents accidental duplicate issuances and allows safe retries.

Monitor Reserve Ratio

After each issuance, verify the reserve_ratio remains at or above 1.0000. This ensures full backing.

Implement Webhooks

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

Last modified on August 31, 2026

​Overview

​Key Requirements

Issuer Verification

KYC/AML Compliance

Reserve Verification

API Permissions

​Authentication

​Required Headers

​Request Parameters

​Response

​Errors

​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

Errors

Error Codes

Compliance & Regulations

Monthly Attestation Impact

Record Keeping

Best Practices

Related Endpoints