> For the complete documentation index, see [llms.txt](https://docs.dexpal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dexpal.io/for-partners/endpoints/dex-earn.md).

# DEX Earn

Returns all earn mechanisms available on the DEX, including vaults, staking pools, and liquidity pools. Each mechanism is a distinct way for users to deposit capital and earn yield.

## Overview

|                    |                 |
| ------------------ | --------------- |
| **Method**         | GET             |
| **Poll frequency** | Every 5 minutes |
| **Auth**           | Bearer API key  |
| **Rate limit**     | 60 req/min      |

## Request

No query parameters.

### Headers

| Header          | Required | Description        |
| --------------- | -------- | ------------------ |
| `Authorization` | yes      | `Bearer <api_key>` |

## Response

Returns a `data` array where each item represents one earn mechanism.

### Fields — Earn Mechanism Object

| Field             | Type           | Required | Description                                                                              |
| ----------------- | -------------- | -------- | ---------------------------------------------------------------------------------------- |
| `name`            | string         | yes      | Human-readable name of the mechanism e.g. `"GNS Staking"`, `"wBTC/USDC Liquidity Pool"`. |
| `type`            | enum           | yes      | Mechanism category. See values below.                                                    |
| `networks`        | array\[string] | yes      | Chain slugs where this mechanism is available e.g. `["arbitrum", "polygon"]`.            |
| `depositCurrency` | string         | yes      | Token symbol required to participate e.g. `"GNS"`, `"USDC"`.                             |
| `description`     | string         | no       | Short description of the mechanism and how it generates yield.                           |
| `autoCompounding` | boolean        | no       | Whether rewards are automatically reinvested.                                            |
| `dexLink`         | string         | no       | Direct URL to the earn mechanism on the DEX.                                             |
| `apy`             | array\[object] | no       | Estimated APY per network. See below.                                                    |
| `tvl`             | array\[object] | no       | Total value locked per network in USD. See below.                                        |

### `type` Values

| Value     | Description                                          |
| --------- | ---------------------------------------------------- |
| `staking` | Single-token staking for governance or revenue share |
| `vault`   | Protocol-managed vault with automated strategy       |
| `lp`      | User-provided liquidity to a trading pair pool       |
| `lending` | Capital lending for borrowing/leverage use           |

### Fields — APY Object (`apy` array items)

| Field     | Type   | Required | Description                                                |
| --------- | ------ | -------- | ---------------------------------------------------------- |
| `network` | string | yes      | Chain slug e.g. `"arbitrum"`.                              |
| `value`   | number | yes      | Estimated APY as a decimal percentage e.g. `6.42` = 6.42%. |

### Fields — TVL Object (`tvl` array items)

| Field     | Type   | Required | Description                   |
| --------- | ------ | -------- | ----------------------------- |
| `network` | string | yes      | Chain slug e.g. `"arbitrum"`. |
| `value`   | number | yes      | Total value locked in USD.    |

## Example Response

```json
{
  "success": true,
  "data": [
    {
      "name": "GNS Staking",
      "type": "staking",
      "networks": ["arbitrum", "polygon", "base"],
      "depositCurrency": "GNS",
      "description": "Stake GNS to earn a share of protocol trading fees.",
      "autoCompounding": false,
      "dexLink": "https://gains.trade/staking",
      "apy": [
        { "network": "arbitrum", "value": 6.42 },
        { "network": "polygon", "value": 9.23 },
        { "network": "base", "value": 5.10 }
      ],
      "tvl": [
        { "network": "arbitrum", "value": 60458378 },
        { "network": "polygon", "value": 4042087 },
        { "network": "base", "value": 1200000 }
      ]
    },
    {
      "name": "DAI Vault",
      "type": "vault",
      "networks": ["arbitrum"],
      "depositCurrency": "DAI",
      "description": "Deposit DAI to act as counterparty liquidity for traders.",
      "autoCompounding": true,
      "dexLink": "https://gains.trade/vaults",
      "apy": [
        { "network": "arbitrum", "value": 14.5 }
      ],
      "tvl": [
        { "network": "arbitrum", "value": 25000000 }
      ]
    }
  ],
  "timestamp": "2026-01-20T21:00:00Z"
}
```

## Error Responses

| Status | Error                          | When                      |
| ------ | ------------------------------ | ------------------------- |
| `401`  | `"Invalid or missing API key"` | Bad or absent auth header |
| `500`  | `"Internal server error"`      | Unexpected failure        |

## Notes

* Return an empty `data` array if the DEX has no earn mechanisms.
* APY values are estimates and should reflect the current rate, not a historical average.
* If a mechanism is temporarily paused or at capacity, still include it in the response — add a `description` note if useful.
* Network slugs should be lowercase and consistent with those used in other endpoints (e.g. `"arbitrum"`, `"base"`, `"polygon"`).