Redeem

If this entity information is missing, the endpoint returns a 401 Unauthorized error.

POST /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, 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

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

Example 1

ENSC Redemption (Cash-To-Bank)

{
  "recipient": "0xRecipientAddressABC123",
  "amount": 100,
  "assetType": "ENSC",
  "payoutEmail": "[e-mail]",
  "bank": "058",
  "accountNumber": "0123456789"
}

Response (200) Ok

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

Example 2

USDC Redemption (Crypto)

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

Response (200) Ok

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

Common Error Responses

Missing Entity Data (Unauthorized):

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

Missing payoutEmail (when assetType is ENSC):

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

Invalid Recipient Address:

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

Asset Not Supported:

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

Insufficient Allowance:

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

Bank Account Resolution Failure (for ENSC):

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