# 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.

> **🔒 Affiliate-code gating (applies to every user-level endpoint below)**
>
> User-level endpoints **must only return data for users who have DexPal's affiliate code set on their account** at the DEX. If an address is not attributed to the DexPal affiliate code at query time, respond as if the address has no data:
>
> * `/users/{address}/accounts` → `404 "Address not found"`
> * `/users/positions` | `/users/orders` | `/users/history` | `/users/holdings` | `/users/lp-holdings` → `200` with `"data": []`

| 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.


---

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