Redeem Stablecoin

Redeem stablecoins for fiat currency

POST /v1/stablecoin/redeem

Redeem Stablecoin

cURL

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": {}
}
'

Example Request

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

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

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

Example Request

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

Node.js

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);
  }
}