> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Redeem Stablecoin

> Redeem stablecoins for fiat currency

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

## Authentication

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

<ParamField body="sender" type="string" required>
  The blockchain address holding the stablecoins to redeem

  Example: `stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu`
</ParamField>

<ParamField body="amount" type="object" required>
  The amount and denomination of stablecoins to redeem

  <Expandable title="Amount Object">
    <ParamField body="denom" type="string" required>
      The denomination of the stablecoin (e.g., "ssusd")
    </ParamField>

    <ParamField body="amount" type="string" required>
      The amount to redeem in the smallest unit (e.g., "1000000" for 1 ssUSD with 6 decimals)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="destination" type="object" required>
  Destination for the fiat funds

  <Expandable title="Destination Object">
    <ParamField body="type" type="string" required>
      Type of destination: "bank\_wire", "ach", "swift", "sepa"
    </ParamField>

    <ParamField body="account_number" type="string" required>
      Destination account number
    </ParamField>

    <ParamField body="routing_number" type="string">
      Routing number (required for ACH)
    </ParamField>

    <ParamField body="swift_code" type="string">
      SWIFT/BIC code (required for SWIFT transfers)
    </ParamField>

    <ParamField body="iban" type="string">
      IBAN (required for SEPA transfers)
    </ParamField>

    <ParamField body="bank_name" type="string">
      Name of the receiving bank
    </ParamField>

    <ParamField body="beneficiary_name" type="string" required>
      Name of the account holder
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="reference_id" type="string" required>
  Unique reference ID for this redemption transaction
</ParamField>

<ParamField body="compliance" type="object">
  Compliance information

  <Expandable title="Compliance Object">
    <ParamField body="purpose" type="string">
      Purpose of redemption
    </ParamField>

    <ParamField body="source_of_funds" type="string">
      Source of the stablecoins being redeemed
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata for the redemption
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the redemption transaction
</ResponseField>

<ResponseField name="object" type="string">
  Object type, always "stablecoin\_redemption"
</ResponseField>

<ResponseField name="sender" type="string">
  The sender address
</ResponseField>

<ResponseField name="amount" type="object">
  The redeemed amount

  <Expandable title="Amount Object">
    <ResponseField name="denom" type="string">
      The denomination of the stablecoin
    </ResponseField>

    <ResponseField name="amount" type="string">
      The amount redeemed
    </ResponseField>

    <ResponseField name="display_amount" type="string">
      Human-readable amount (e.g., "1000.00 ssUSD")
    </ResponseField>

    <ResponseField name="fiat_amount" type="string">
      Equivalent fiat amount
    </ResponseField>

    <ResponseField name="fiat_currency" type="string">
      Fiat currency code (e.g., "USD")
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="transaction_hash" type="string">
  Blockchain transaction hash for the burn
</ResponseField>

<ResponseField name="status" type="string">
  Status: "pending", "processing", "completed", "failed", "cancelled"
</ResponseField>

<ResponseField name="estimated_arrival" type="string">
  Estimated arrival date for fiat funds
</ResponseField>

<ResponseField name="fees" type="object">
  Fee breakdown

  <Expandable title="Fees Object">
    <ResponseField name="network_fee" type="string">
      Blockchain network fee
    </ResponseField>

    <ResponseField name="processing_fee" type="string">
      Processing fee
    </ResponseField>

    <ResponseField name="total_fee" type="string">
      Total fees
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of creation
</ResponseField>

<ResponseField name="completed_at" type="string">
  ISO 8601 timestamp of completion
</ResponseField>

<ResponseExample>
  ```json Example Request theme={null}
  {
    "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"
    }
  }
  ```

  ```json Example Response theme={null}
  {
    "id": "red_9h8g7f6e5d4c3b2a",
    "object": "stablecoin_redemption",
    "sender": "stateset1qypqxpq9qcrsszg2pvxq6rs0zqg3yyc5lzv7xu",
    "amount": {
      "denom": "ssusd",
      "amount": "1000000000",
      "display_amount": "1000.00 ssUSD",
      "fiat_amount": "1000.00",
      "fiat_currency": "USD"
    },
    "transaction_hash": "A7F4C1B8E5D2A9F7C3B1E8D5A2F9C7E1B4A7D2F5E8B1C4A7F9D2E5B8C1F4A7D2",
    "status": "processing",
    "estimated_arrival": "2024-01-17T16:00:00Z",
    "fees": {
      "network_fee": "0.50",
      "processing_fee": "5.00",
      "total_fee": "5.50"
    },
    "created_at": "2024-01-15T10:45:00Z",
    "completed_at": null
  }
  ```
</ResponseExample>

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

```json theme={null}
{
  "event": "stablecoin.redeemed",
  "data": {
    "id": "red_9h8g7f6e5d4c3b2a",
    "status": "completed",
    "amount": {
      "denom": "ssusd",
      "amount": "1000000000"
    }
  }
}
```

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  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);
    }
  }
  ```

  ```python Python theme={null}
  import requests

  def redeem_stablecoin():
      url = "https://api.stateset.com/v1/stablecoin/redeem"
      
      headers = {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      }
      
      data = {
          "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"
          }
      }
      
      try:
          response = requests.post(url, json=data, headers=headers)
          response.raise_for_status()
          print("Redemption initiated:", response.json())
      except requests.exceptions.RequestException as e:
          print("Redemption failed:", e)
  ```

  ```curl cURL theme={null}
  curl -X POST https://api.stateset.com/v1/stablecoin/redeem \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "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"
    }'
  ```
</CodeGroup>