StateSet API Docs

Redeem Stablecoin

curl --request POST \
  --url https://api.stateset.com/v1/stablecoin/redeem \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sender": "<string>",
  "amount": {
    "denom": "<string>",
    "amount": "<string>"
  },
  "destination": {
    "type": "<string>",
    "account_number": "<string>",
    "routing_number": "<string>",
    "swift_code": "<string>",
    "iban": "<string>",
    "bank_name": "<string>",
    "beneficiary_name": "<string>"
  },
  "reference_id": "<string>",
  "compliance": {
    "purpose": "<string>",
    "source_of_funds": "<string>"
  },
  "metadata": {}
}
'

{
  "sender": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
  "amount": {
    "denom": "ssusd",
    "amount": "1000000000"
  },
  "destination": {
    "type": "ach",
    "account_number": "123456789",
    "routing_number": "021000021",
    "bank_name": "JPMorgan Chase",
    "beneficiary_name": "John Doe"
  },
  "reference_id": "RED-2024-001234",
  "compliance": {
    "purpose": "business_operations",
    "source_of_funds": "sales_revenue"
  }
}

POST

stablecoin

redeem

Redeem Stablecoin

curl --request POST \
  --url https://api.stateset.com/v1/stablecoin/redeem \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sender": "<string>",
  "amount": {
    "denom": "<string>",
    "amount": "<string>"
  },
  "destination": {
    "type": "<string>",
    "account_number": "<string>",
    "routing_number": "<string>",
    "swift_code": "<string>",
    "iban": "<string>",
    "bank_name": "<string>",
    "beneficiary_name": "<string>"
  },
  "reference_id": "<string>",
  "compliance": {
    "purpose": "<string>",
    "source_of_funds": "<string>"
  },
  "metadata": {}
}
'

{
  "sender": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
  "amount": {
    "denom": "ssusd",
    "amount": "1000000000"
  },
  "destination": {
    "type": "ach",
    "account_number": "123456789",
    "routing_number": "021000021",
    "bank_name": "JPMorgan Chase",
    "beneficiary_name": "John Doe"
  },
  "reference_id": "RED-2024-001234",
  "compliance": {
    "purpose": "business_operations",
    "source_of_funds": "sales_revenue"
  }
}

This endpoint allows verified users to redeem their stablecoins for fiat currency. Redemptions are subject to KYC/AML verification and minimum/maximum limits.

Authentication

This endpoint requires a valid API key with stablecoin:redeem permissions.

Authorization: Bearer YOUR_API_KEY

Request Body

sender

string

required

The blockchain address holding the stablecoins to redeemExample: stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu

amount

object

required

The amount and denomination of stablecoins to redeem

Show Amount Object

denom

string

required

The denomination of the stablecoin (e.g., “ssusd”)

amount

string

required

The amount to redeem in the smallest unit (e.g., “1000000” for 1 ssUSD with 6 decimals)

destination

object

required

Destination for the fiat funds

Show Destination Object

type

string

required

Type of destination: “bank_wire”, “ach”, “swift”, “sepa”

account_number

string

required

Destination account number

routing_number

string

Routing number (required for ACH)

swift_code

string

SWIFT/BIC code (required for SWIFT transfers)

iban

string

IBAN (required for SEPA transfers)

bank_name

string

Name of the receiving bank

beneficiary_name

string

required

Name of the account holder

reference_id

string

required

Unique reference ID for this redemption transaction

compliance

object

Compliance information

Show Compliance Object

purpose

string

Purpose of redemption

source_of_funds

string

Source of the stablecoins being redeemed

metadata

object

Additional metadata for the redemption

Response

string

Unique identifier for the redemption transaction

object

string

Object type, always “stablecoin_redemption”

sender

string

The sender address

amount

object

The redeemed amount

Show Amount Object

denom

string

The denomination of the stablecoin

amount

string

The amount redeemed

display_amount

string

Human-readable amount (e.g., “1000.00 ssUSD”)

fiat_amount

string

Equivalent fiat amount

fiat_currency

string

Fiat currency code (e.g., “USD”)

transaction_hash

string

Blockchain transaction hash for the burn

status

string

Status: “pending”, “processing”, “completed”, “failed”, “cancelled”

estimated_arrival

string

Estimated arrival date for fiat funds

fees

object

Fee breakdown

Show Fees Object

network_fee

string

Blockchain network fee

processing_fee

string

Processing fee

total_fee

string

Total fees

created_at

string

ISO 8601 timestamp of creation

completed_at

string

ISO 8601 timestamp of completion

{
  "sender": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
  "amount": {
    "denom": "ssusd",
    "amount": "1000000000"
  },
  "destination": {
    "type": "ach",
    "account_number": "123456789",
    "routing_number": "021000021",
    "bank_name": "JPMorgan Chase",
    "beneficiary_name": "John Doe"
  },
  "reference_id": "RED-2024-001234",
  "compliance": {
    "purpose": "business_operations",
    "source_of_funds": "sales_revenue"
  }
}

Error Codes

Code	Description
`400`	Invalid request parameters
`401`	Unauthorized - Invalid API key
`403`	Forbidden - Account not verified for redemptions
`404`	Sender address not found
`409`	Conflict - Duplicate reference_id
`422`	Insufficient balance or invalid amount
`429`	Rate limit exceeded
`500`	Internal server error

Redemption Limits

Minimum: $100 USD equivalent
Maximum: $1,000,000 USD per transaction
Daily Limit: $5,000,000 USD per account
Monthly Limit: Based on account tier

Processing Times

Method	Estimated Time
ACH	1-3 business days
Wire	Same day - 1 business day
SWIFT	1-5 business days
SEPA	1-2 business days

Webhooks

Configure webhooks to receive real-time updates:

{
  "event": "stablecoin.redeemed",
  "data": {
    "id": "red_9h8g7f6e5d4c3b2a",
    "status": "completed",
    "amount": {
      "denom": "ssusd",
      "amount": "1000000000"
    }
  }
}

Code Examples

const axios = require('axios');

async function redeemStablecoin() {
  try {
    const response = await axios.post(
      'https://api.stateset.com/v1/stablecoin/redeem',
      {
        sender: 'stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu',
        amount: {
          denom: 'ssusd',
          amount: '1000000000'
        },
        destination: {
          type: 'ach',
          account_number: '123456789',
          routing_number: '021000021',
          bank_name: 'JPMorgan Chase',
          beneficiary_name: 'John Doe'
        },
        reference_id: 'RED-2024-001234',
        compliance: {
          purpose: 'business_operations',
          source_of_funds: 'sales_revenue'
        }
      },
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );
    
    console.log('Redemption initiated:', response.data);
  } catch (error) {
    console.error('Redemption failed:', error.response.data);
  }
}

Transfer Stablecoin Get ssUSD Balance

​Authentication

​Request Body

​Response

​Error Codes

​Redemption Limits

​Processing Times

​Webhooks

​Code Examples

Authentication

Request Body

Response

Error Codes

Redemption Limits

Processing Times

Webhooks

Code Examples