elizaos--eliza/packages/docs/cloud/api/redemptions.mdx

---
title: Redemptions
description: Redeem earnings for elizaOS tokens.
---

# Redemptions

Redeem creator earnings for elizaOS tokens. Earnings balances are tracked in USD; redemption requests use integer `pointsAmount`, where 100 points equals $1.00.

## Get Redemption Balance

<div className="api-endpoint">
  <span className="method-badge method-badge-get">GET</span>
  <span className="path">/api/v1/redemptions/balance</span>
</div>

Get your redeemable earnings balance and eligibility.

### Response

```json
{
  "success": true,
  "balance": {
    "totalEarned": 500,
    "availableBalance": 125.5,
    "pendingBalance": 24,
    "totalRedeemed": 100,
    "totalPending": 24,
    "totalConvertedToCredits": 12.25
  },
  "bySource": [
    { "source": "miniapp", "totalEarned": 300, "count": 42 },
    { "source": "agent", "totalEarned": 200, "count": 10 }
  ],
  "limits": {
    "minRedemptionUsd": 1,
    "maxSingleRedemptionUsd": 1000,
    "userDailyLimitUsd": 1000,
    "userHourlyLimitUsd": 250
  },
  "eligibility": {
    "canRedeem": true,
    "dailyLimitRemaining": 1000
  }
}
```

---

## List Redemptions

<div className="api-endpoint">
  <span className="method-badge method-badge-get">GET</span>
  <span className="path">/api/v1/redemptions</span>
</div>

Get redemption history.

### Query Parameters

| Parameter | Description |
| --------- | ----------- |
| `limit` | Maximum records to return, capped at 100. Default: 20. |

### Response

```json
{
  "success": true,
  "redemptions": [
    {
      "id": "red_abc123",
      "pointsAmount": 10000,
      "usdValue": 100,
      "elizaAmount": 1234.5,
      "elizaPriceUsd": 0.081,
      "network": "base",
      "payoutAddress": "0x1234...abcd",
      "status": "completed",
      "txHash": "0x...",
      "createdAt": "2026-05-05T10:30:00Z",
      "completedAt": "2026-05-05T11:00:00Z",
      "requiresReview": false
    }
  ],
  "paused": false
}
```

---

## Get Redemption Quote

<div className="api-endpoint">
  <span className="method-badge method-badge-get">GET</span>
  <span className="path">/api/v1/redemptions/quote</span>
</div>

Get a token quote before creating a redemption.

### Query Parameters

| Parameter | Required | Description |
| --------- | -------- | ----------- |
| `network` | yes | One of `ethereum`, `base`, `bnb`, `solana`. |
| `pointsAmount` | no | Integer points to redeem. Defaults to 100. |

### Response

```json
{
  "success": true,
  "quote": {
    "network": "base",
    "tokenAddress": "0x...",
    "pointsAmount": 10000,
    "usdValue": 100,
    "twapPriceUsd": 0.081,
    "spotPriceUsd": 0.08,
    "priceMethod": "TWAP",
    "elizaAmount": 1234.5,
    "safetySpreadPercent": 5,
    "validUntil": "2026-05-05T10:35:00Z",
    "validitySeconds": 300,
    "requiresAdminApproval": false
  },
  "canRedeem": true
}
```

---

## Create Redemption

<div className="api-endpoint">
  <span className="method-badge method-badge-post">POST</span>
  <span className="path">/api/v1/redemptions</span>
</div>

Create a redemption request.

### Request

```json
{
  "pointsAmount": 10000,
  "network": "base",
  "payoutAddress": "0x1234567890abcdef1234567890abcdef12345678",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
}
```

| Field | Description |
| ----- | ----------- |
| `appId` | Optional app UUID for attribution. |
| `pointsAmount` | Required integer, 100-100000. 100 points equals $1.00. |
| `network` | Required: `ethereum`, `base`, `bnb`, or `solana`. |
| `payoutAddress` | Required wallet address. |
| `signature` | Optional wallet signature. |
| `idempotencyKey` | Optional UUID for safe retries. |

### Response

```json
{
  "success": true,
  "redemptionId": "red_abc123",
  "quote": {
    "usdValue": 100,
    "elizaAmount": 1234.5,
    "requiresReview": false
  },
  "message": "Redemption created and will be processed shortly."
}
```

---

## Get Redemption Status

<div className="api-endpoint">
  <span className="method-badge method-badge-get">GET</span>
  <span className="path">/api/v1/redemptions/status</span>
</div>

Check payout network availability.

---

## Get Redemption Details

<div className="api-endpoint">
  <span className="method-badge method-badge-get">GET</span>
  <span className="path">/api/v1/redemptions/{"{id}"}</span>
</div>

Get details about a specific redemption.

<Info>
  Large redemptions may require admin approval. Quote and create responses include review flags when applicable.
</Info>