> 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-rewards.md). # DEX Rewards Returns per-user affiliate trading activity for users attributed to the DexPal affiliate code. This endpoint is the foundation of the DexPal rewards system — accuracy directly impacts user cashback, credits, and leaderboard rankings. ## Overview | | | | ------------------ | -------------- | | **Method** | GET | | **Poll frequency** | On demand | | **Auth** | Bearer API key | | **Rate limit** | 60 req/min | ## Request ### Query Parameters | Param | Type | Required | Description | | -------- | ------- | -------- | ----------------------------------------- | | `from` | ISO8601 | yes | Start of the time range (inclusive). | | `to` | ISO8601 | yes | End of the time range (inclusive). | | `limit` | integer | no | Items per page. Default `100`, max `500`. | | `offset` | integer | no | Items to skip. Default `0`. | ### Headers | Header | Required | Description | | --------------- | -------- | ------------------ | | `Authorization` | yes | `Bearer ` | ## Response Returns a paginated `data` array of user reward records, plus a `summary` object with aggregate totals for the requested time range. ### Fields — User Reward Object | Field | Type | Required | Description | | ----------------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | string | yes | Primary wallet address of the user. | | `volumeUsd` | number | yes | Total trading volume in USD (notional) for the time range. | | `feesUsd` | number | yes | Total fees paid by the user in USD for the time range. | | `affiliateRevenueUsd` | number | yes | Gross affiliate revenue generated by this user in USD. This is the most critical field — it represents the gross amount the DEX attributes to DexPal's affiliate code and is used for cashback, credits, and leaderboard rankings. | | `associatedAddresses` | array\[string] | no | Other addresses (subaccounts, linked wallets) whose activity is included in this user's totals. | | `tradeCount` | integer | no | Number of trades executed in the time range. | | `firstTradeAt` | ISO8601 | no | Timestamp of the user's first trade in the time range. | | `lastTradeAt` | ISO8601 | no | Timestamp of the user's most recent trade in the time range. | | `realizedPnlUsd` | number | no | Total realized PnL in USD for the time range. | | `feeTierLabel` | string | no | Human-readable fee tier label e.g. `"VIP 2"`, `"Gold"`. | | `effectiveMakerFeeRate` | number | no | Effective maker fee rate applied to this user as a decimal percentage. | | `effectiveTakerFeeRate` | number | no | Effective taker fee rate applied to this user as a decimal percentage. | | `affiliateRateApplied` | number | no | Effective affiliate revenue share rate applied as a decimal. | | `affiliateRevenueL1Usd` | number | no | Direct (L1) referral affiliate revenue in USD. | | `affiliateRevenueL2Usd` | number | no | Sub-referral (L2) affiliate revenue in USD. | | `makerVolumeUsd` | number | no | Maker-side trading volume in USD for the time range. | | `takerVolumeUsd` | number | no | Taker-side trading volume in USD for the time range. | ### Fields — Summary Object | Field | Type | Description | | -------------------------- | ------ | -------------------------------------------------------------- | | `totalVolumeUsd` | number | Sum of `volumeUsd` across all users in the response. | | `totalFeesUsd` | number | Sum of `feesUsd` across all users in the response. | | `totalAffiliateRevenueUsd` | number | Sum of `affiliateRevenueUsd` across all users in the response. | ## Example Response ```json { "success": true, "data": [ { "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12", "volumeUsd": 125000.5, "feesUsd": 62.5, "affiliateRevenueUsd": 31.25, "associatedAddresses": ["0xfed...a09"], "tradeCount": 47, "firstTradeAt": "2026-02-01T03:22:00Z", "lastTradeAt": "2026-02-01T19:45:00Z", "realizedPnlUsd": 3200.0 }, { "address": "0x9876543210abcdef9876543210abcdef98765432", "volumeUsd": 8500.0, "feesUsd": 4.25, "affiliateRevenueUsd": 2.13 } ], "summary": { "totalVolumeUsd": 133500.5, "totalFeesUsd": 66.75, "totalAffiliateRevenueUsd": 33.38 }, "pagination": { "limit": 500, "offset": 0, "total": 87, "hasMore": false }, "timestamp": "2026-02-02T00:15:00Z" } ``` ## Error Responses | Status | Error | When | | ------ | ------------------------------------------- | ------------------------- | | `400` | `"Missing required parameter: from"` | `from` or `to` absent | | `400` | `"Invalid date format for parameter: from"` | Not valid ISO8601 | | `400` | `"Parameter 'from' must be before 'to'"` | Inverted range | | `401` | `"Invalid or missing API key"` | Bad or absent auth header | | `500` | `"Internal server error"` | Unexpected failure | ## Notes * Only include users who have traded under DexPal's affiliate code in the given time range. Do not include users with zero activity. * `affiliateRevenueUsd` must be the **gross** amount attributed to DexPal's code — before any cashback or rebate distributions. * `summary` totals should match the full result set for the time range, not just the current page. When paginating, the `summary` is consistent across all pages. * If a user trades across multiple subaccounts or linked wallets, consolidate into a single record under the primary address and list the others in `associatedAddresses`.