# Redeem

<mark style="color:green;">`POST`</mark> `/redeem`

This endpoint initiates a token redemption process by generating an unsigned redeem transaction. It performs several checks: validating input parameters, verifying the recipient's token [allowance](/integrations/publish-your-docs-2/token-approval.md), resolving the bank account details, and sending a notification email. The unsigned transaction details are then returned to the client for signing and broadcasting.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <api_key>` |

**Body**

<table><thead><tr><th width="190">Name</th><th width="143">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>recipient</code></td><td>string</td><td>The wallet address of the user (must be a valid EVM address).</td></tr><tr><td><code>amount</code></td><td>number</td><td>The amount of tokens to redeem.</td></tr><tr><td><code>assetType</code></td><td>string</td><td>The type of asset to redeem. Must be one of the enums (e.g., <code>"ENSC"</code>, <code>"USDC"</code>, <code>"USDT"</code>, <code>"LSK"</code>).</td></tr><tr><td><code>payoutEmail</code></td><td>string</td><td>Email address to which the payout reference <code>pvRef</code> will be sent (Required <strong>only if</strong> <code>assetType</code> is <code>ENSC</code>. For non‑ENSC assets, this field is omitted.).</td></tr><tr><td><code>bank</code></td><td>string</td><td>The local Nigerian bank code gotten from the get-banks endpoint (<strong>Conditionally Required:</strong> Required <strong>only if</strong> <code>assetType</code> is <code>ENSC</code> (e.g., <code>'058'</code>, <code>'044'</code>).</td></tr><tr><td><code>accountNumber</code></td><td>string</td><td>The bank account number (Required <strong>only if</strong> <code>assetType</code> is <code>ENSC</code> (e.g., <code>'0123456789'</code>, <code>'0690000032'</code>).</td></tr></tbody></table>

**Example 1**

{% tabs %}
{% tab title="ENSC Redemption (Cash-To-Bank)" %}

```json
{
  "recipient": "0xRecipientAddressABC123",
  "amount": 100,
  "assetType": "ENSC",
  "payoutEmail": "user@example.com",
  "bank": "058",
  "accountNumber": "0123456789"
}
```

{% endtab %}

{% tab title="Response (200) Ok" %}

```json
{
  "status": 200,
  "message": "Transaction processed successfully",
  "data": {
    "to": "0xDexContractAddressDEF456",
    "value": 0,
    "gasLimit": "0x186a0",
    "gasPrice": "0x4a817c800",
    "nonce": "5",
    "data": "0xEncodedRedeemFunctionCallForENSC",
    "pvRef": "PV-ABCD1234",
    "txStatus": "PENDING",
    "payout": {
      "accountName": "Resolved Account Name",
      "bank": "058",
      "accountNumber": "0123456789"
    }
  }
}
```

{% endtab %}
{% endtabs %}

**Example 2**

{% tabs %}
{% tab title="USDC Redemption (Crypto)" %}

```json
{
  "recipient": "0xRecipientAddressABC123",
  "amount": 50,
  "assetType": "USDC"
}
```

{% endtab %}

{% tab title="Response (200) Ok" %}

```json
{
  "status": 200,
  "message": "Transaction processed successfully",
  "data": {
    "to": "0xDexContractAddressDEF456",
    "value": 0,
    "gasLimit": "0x186a0",
    "gasPrice": "0x4a817c800",
    "nonce": "8",
    "data": "0xEncodedRedeemFunctionCallForUSDC"
  }
}
```

{% endtab %}
{% endtabs %}

**Common Error Responses**

{% tabs %}
{% tab title="Missing Entity Data (Unauthorized):" %}

```json
{
  "status": 401,
  "error": "Unauthorized",
  "message": "Unauthorized: Missing entity data"
}
```

{% endtab %}

{% tab title="Missing payoutEmail (when assetType is ENSC):" %}

```json
{
  "status": 400,
  "error": "Invalid Request",
  "message": "payoutEmail is required"
}
```

{% endtab %}

{% tab title="Invalid Recipient Address:" %}

```json
{
  "status": 400,
  "error": "Invalid Request",
  "message": "Invalid recipient address"
}
```

{% endtab %}

{% tab title="Asset Not Supported:" %}

```json
{
  "status": 400,
  "error": "Invalid Asset",
  "message": "Provided asset type is not whitelisted"
}
```

{% endtab %}

{% tab title="Insufficient Allowance:" %}

```json
{
  "status": 400,
  "error": "Invalid Request",
  "message": "Insufficient allowance to spend from user token balance"
}
```

{% endtab %}

{% tab title="Bank Account Resolution Failure (for ENSC):" %}

```json
{
  "status": 400,
  "error": "Bank Account Resolution Failed",
  "message": "Unable to resolve bank account details"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.prosperavest.com/integrations/publish-your-docs-2/redeem.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.