> 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/dex-api-spec.md).

# DEX API Specification

This document defines the API specification that DEX partners must implement to integrate with the DexPal platform.

## Version

`v1` — All endpoints are prefixed with `/dexpal/v1/`.

## Authentication

Endpoints can be secured with an API key provided to DexPal during onboarding.

```
Authorization: Bearer <api_key>
```

## Base URL

Partners host the API at their own domain. DexPal configures the base URL per integration:

```
https://api.yourexchange.com
```

## Response Envelope

All responses follow the same top-level structure:

```json
{
  "success": true,
  "data": { ... },
  "pagination": { ... },
  "timestamp": "2026-01-20T21:00:00Z"
}
```

| Field        | Type            | Always present              | Description                                           |
| ------------ | --------------- | --------------------------- | ----------------------------------------------------- |
| `success`    | boolean         | yes                         | `true` on success, `false` on error                   |
| `data`       | object \| array | yes                         | Response payload                                      |
| `pagination` | object          | only on paginated endpoints | See [Pagination](/for-partners/schemas/pagination.md) |
| `timestamp`  | ISO8601         | yes                         | Server time at response generation                    |

On error:

```json
{
  "success": false,
  "error": "Human-readable error message"
}
```

See [Error Responses](/for-partners/schemas/error.md) for status codes.

## Field Conventions

* All field names use **camelCase**
* All monetary values are in **USD** unless the field name specifies otherwise
* All timestamps use **ISO8601** format (`2026-01-20T21:00:00Z`)
* All rates and percentages are expressed as **decimal numbers** (`0.01` = 1%, not `"1%"`)
* Fees are expressed as **percentage** decimals (`0.05` = 0.05% fee, not 5%)

## Shared Object Schemas

* [AssetObject](/for-partners/schemas/asset-object.md) — used in `markets`
* [TriggerOrder](/for-partners/schemas/trigger-order.md) — used in `positions` and `orders`
* [Pagination](/for-partners/schemas/pagination.md) — used in paginated endpoints
* [Error](/for-partners/schemas/error.md) — error response format

## Endpoints

### DEX-level

These endpoints return platform-wide data and are polled by DexPal on a fixed schedule.

| Endpoint                                                         | Description                                 | Poll Frequency |
| ---------------------------------------------------------------- | ------------------------------------------- | -------------- |
| [GET /dexpal/v1/markets](/for-partners/endpoints/dex-markets.md) | Real-time market data for all trading pairs | Every 30s      |
| [GET /dexpal/v1/metrics](/for-partners/endpoints/dex-metrics.md) | Aggregate DEX-level statistics              | Every 5 min    |
| [GET /dexpal/v1/rewards](/for-partners/endpoints/dex-rewards.md) | Per-user affiliate trading activity         | On demand      |
| [GET /dexpal/v1/token](/for-partners/endpoints/dex-token.md)     | Governance token data                       | Every 5 min    |
| [GET /dexpal/v1/earn](/for-partners/endpoints/dex-earn.md)       | Earn mechanisms (vaults, staking, LP pools) | Every 5 min    |

### User-level

These endpoints return data scoped to specific wallet addresses.

DexPal users can connect multiple wallets to a single account. Since many of our partner DEXes support smart wallets, subaccounts, and one-click trading accounts, we pass **all connected user addresses** in most of our requests. User-level endpoints **must** return cumulative data for all user accounts linked to said addresses.

> **Collection vs. user-facing visibility**
>
> User-level endpoints are **not affiliate-code gated at collection time**. Return data for any requested address the DEX can read, even if the wallet has not used DexPal's affiliate code. This applies to `/users/{address}/accounts`, `/users/positions`, `/users/orders`, `/users/history`, `/users/holdings`, and `/users/lp-holdings`.
>
> DexPal may hide full-data surfaces such as history from end users unless referral attribution is confirmed. That visibility rule is enforced by DexPal, not by partner API responses.

| Endpoint                                                                            | Description                                        |
| ----------------------------------------------------------------------------------- | -------------------------------------------------- |
| [GET /dexpal/v1/users/{address}/accounts](/for-partners/endpoints/user-accounts.md) | Discover all accounts associated with an address   |
| [GET /dexpal/v1/users/positions](/for-partners/endpoints/user-positions.md)         | Open positions across all provided addresses       |
| [GET /dexpal/v1/users/orders](/for-partners/endpoints/user-orders.md)               | Pending limit orders across all provided addresses |
| [GET /dexpal/v1/users/history](/for-partners/endpoints/user-history.md)             | Historical trade events, time-ranged and paginated |
| [GET /dexpal/v1/users/holdings](/for-partners/endpoints/user-holdings.md)           | Wallet and DEX account balances                    |
| [GET /dexpal/v1/users/lp-holdings](/for-partners/endpoints/user-lp-holdings.md)     | LP, vault, and staking positions                   |

## Rate Limiting

Partners should implement rate limiting appropriate to their infrastructure. DexPal will respect the following defaults unless agreed otherwise:

| Endpoint group | Max requests/min |
| -------------- | ---------------- |
| DEX-level      | 60               |
| User-level     | 120              |

Return `429 Too Many Requests` when limits are exceeded.