# 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"`).


---

# 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.dexpal.io/for-partners/endpoints/dex-earn.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.