# Introduction DexPal is a discovery, rewards, and data platform for decentralized exchanges. These docs cover the public user experience, beta access, rewards program, roadmap, and the partner DEX API used to send market, rewards, and user-level data into DexPal. ## For Users | Page | Scope | | ------------------------------------------------- | ------------------------------------------- | | [Users](/for-users/users) | User documentation index | | [Beta Access](/for-users/beta-access) | Beta access and early-user benefits | | [Product & Roadmap](/for-users/product-roadmap) | Product capabilities and roadmap | | [The Degen Club](/for-users/rewards) | Degen Club rewards overview | | [How It Works](/for-users/rewards/how-it-works) | Reward rounds and distribution | | [Credit System](/for-users/rewards/credit-system) | Credits, points, and round-one distribution | | [How to Earn](/for-users/rewards/earning) | Ways to earn | | [Competitions](/for-users/rewards/competitions) | Global and DEX-specific competitions | | [Referrals](/for-users/rewards/referrals) | Referral rules | | [FAQ](/for-users/rewards/faq) | Rewards FAQ | ## For Partner DEXes | Page | Scope | | -------------------------------------------------------------------------------- | ------------------------------------------------------- | | [Partners](/for-partners/partners) | Partner documentation index | | [DEX API Specification](/for-partners/dex-api-spec) | DEX API overview, authentication, envelope, conventions | | [GET /dexpal/v1/markets](/for-partners/endpoints/dex-markets) | Market data | | [GET /dexpal/v1/metrics](/for-partners/endpoints/dex-metrics) | DEX metrics | | [GET /dexpal/v1/rewards](/for-partners/endpoints/dex-rewards) | Rewards | | [GET /dexpal/v1/token](/for-partners/endpoints/dex-token) | Token data | | [GET /dexpal/v1/earn](/for-partners/endpoints/dex-earn) | Earn mechanisms | | [GET /dexpal/v1/users/{address}/accounts](/for-partners/endpoints/user-accounts) | User accounts | | [GET /dexpal/v1/users/positions](/for-partners/endpoints/user-positions) | User positions | | [GET /dexpal/v1/users/orders](/for-partners/endpoints/user-orders) | User orders | | [GET /dexpal/v1/users/history](/for-partners/endpoints/user-history) | User history | | [GET /dexpal/v1/users/holdings](/for-partners/endpoints/user-holdings) | User holdings | | [GET /dexpal/v1/users/lp-holdings](/for-partners/endpoints/user-lp-holdings) | User LP holdings | | [AssetObject](/for-partners/schemas/asset-object) | Asset object schema | | [CollateralBreakdown](/for-partners/schemas/collateral-breakdown) | Collateral breakdown schema | | [LeverageTier](/for-partners/schemas/leverage-tier) | Leverage tier schema | | [TriggerOrder](/for-partners/schemas/trigger-order) | Trigger order schema | | [TradingHours](/for-partners/schemas/trading-hours) | Trading hours schema | | [TwapConfig](/for-partners/schemas/twap-config) | TWAP config schema | | [Pagination](/for-partners/schemas/pagination) | Pagination schema | | [Error Responses](/for-partners/schemas/error) | Error schema | # Users This section explains how to use DexPal as a trader. Start with beta access if you are joining early. Read the rewards pages to understand Degen Club credits, points, competitions, referrals, and earning mechanics. Use the roadmap page for a high-level view of current and planned product areas. ## Contents | Page | Scope | | ------------------------------------------------- | --------------------------------------- | | [Beta Access](/for-users/beta-access) | Beta eligibility, benefits, and support | | [Product & Roadmap](/for-users/product-roadmap) | Current platform features and roadmap | | [The Degen Club](/for-users/rewards) | Rewards overview | | [How It Works](/for-users/rewards/how-it-works) | Reward rounds and prize distribution | | [Credit System](/for-users/rewards/credit-system) | Credits and points | | [How to Earn](/for-users/rewards/earning) | Earning methods | | [Competitions](/for-users/rewards/competitions) | Competitions | | [Referrals](/for-users/rewards/referrals) | Referrals | | [FAQ](/for-users/rewards/faq) | FAQ | # Beta Access Join the DexPal beta program and earn exclusive rewards as an early adopter. ## What are the Beta Benefits? Users whitelisted for the beta earn one-of-a-kind collectibles and points boosters for the duration of the beta period. * Exclusive beta rewards and collectibles * 2× Credits booster on all trading activity * Priority access to new features * Direct feedback channel with the team ## Timeline | Phase | Timing | Description | | --------------------- | ------------ | --------------------------------------------------------------- | | Genesis Beta | January 2026 | Closed beta, limited-access testing with the 2× Credits booster | | Partner Re-engagement | June 2026 | DEX outreach and partner onboarding | | Pre-launch | July 2026 | Public pre-launch | | Official Launch | Fall 2026 | Full platform release and Round 1 rewards competitions | All qualifying trading activity during the beta using DexPal referral codes is credited with the 2× Credits booster. ## Get Started 1. Visit [app.dexpal.io](https://app.dexpal.io) 2. Connect your wallet 3. Start trading on partner DEXs with DexPal referral codes 4. Your activity will be tracked retroactively with 2× Credits ## Participating DEXs The full list of partner DEXs will be announced soon. Follow [@dexpal\_io](https://x.com/dexpal_io) for updates. ## Need Help? * [Discord](https://discord.com/invite/FECs5ct6uk) * [X (Twitter)](https://x.com/dexpal_io) # Product & Roadmap ## Current Platform Features **Pair Screener** — Real-time comparison mechanism across integrated DEXs. Filter trading pairs by asset, exchange, or network while evaluating price, volume, leverage, and funding metrics. **DEX Profiles** — Individual exchange pages combining analytical data with qualitative insights. Evaluate platforms and track incentive offerings. **Competitions & Incentives** — Unified dashboard aggregating trading competitions, promotional campaigns, and reward programs across the DEX ecosystem. **Degen Club Reward Hub** — Exclusive membership program where users gain bonus rewards through affiliate codes on partner exchanges, with all earnings consolidated in one dashboard. ## Development Roadmap ### Phase 1 — Q4 2024–Q1 2025 Foundational infrastructure: * Pair screener * DEX analytics * Rewards tracking * Competition discovery ### Phase 2 — Q1–Q2 2025 Advanced capabilities: * Cross-chain trading history analysis * Asset bridge functionality * Smart notification systems * Collectible NFT achievement badges ### Phase 3 — 2026+ Institutional-grade tooling: * AI-driven market predictions * Worldwide expansion with localized support * Competitive tournament structures ## Vision Become the primary gateway for all decentralized perpetuals trading. # The Degen Club DexPal's universal rewards program for on-chain perpetuals trading. The Degen Club is the world's first universal rewards program for on-chain perpetuals, designed to drive volume and engagement across partner DEXs — while rewarding traders with meaningful incentives. ## Launching Fall 2026 The Universal Rewards Program launches Fall 2026. Trading activity during the beta using DexPal referral codes is credited with a 2× Credits booster. ## How It Works * **Use Referral Codes** — Use DexPal referral codes when trading on partner DEXs. No complex setup required. * **Earn Credits** — Every trade earns Volume Credits based on your activity. All affiliate income goes into a prize pool. * **Win Rewards** — The prize pool is fully redistributed to eligible participants at the end of each round. ## What You Earn | Reward Type | Description | | ------------------ | ------------------------------------------------------ | | DexPal Credits | Temporary points earned during each round from trading | | DexPal Points | Permanent rewards awarded at round end | | Prize Pool Share | Cash rewards from affiliate commissions | | Competition Prizes | Leaderboard rewards and DEX-specific prizes | ## Get Started 1. Connect wallet at [app.dexpal.io](https://app.dexpal.io) 2. Get your referral link or use code **DEXPAL** 3. Start trading on partner DEXs 4. Track progress and earn rewards ## Learn More * [How It Works](/for-users/rewards/how-it-works) — Rounds, prize pool structure, and distribution * [Credit System](/for-users/rewards/credit-system) — Credits vs Points explained * [How to Earn](/for-users/rewards/earning) — All earning methods * [Competitions](/for-users/rewards/competitions) — Leaderboards and fair play mechanics * [Referrals](/for-users/rewards/referrals) — Build a referral network * [FAQ](/for-users/rewards/faq) — Common questions # How It Works ## Phased Reward System (Rounds) The rewards program operates through distinct cycles where participants accumulate rewards. A Round concludes once the base-credit cap is reached or at the Round deadline, whichever comes first. **Round 1:** 150,000 USD baseline prize pool, expandable with DEX and sponsor contributions. Round 1 ends when the 1,500,000 base-credit cap is reached or on December 31, 2026, whichever comes first. ### During a Round * Earn DexPal Credits via trading, quests, and referrals * Build rewards based on trading fees * Compete on leaderboards for additional prizes * Monitor progress on the dashboard in real-time ### Round End * DexPal Points are allocated based on Credits earned * Prize pool distributed to winners * Competition prizes paid out * Credits reset to zero for the next round ### Between Rounds * New quests and challenges announced * Rules refined based on community input * New trading competitions introduced * Bonus incentives can be announced ## Prize Pool The prize pool starts at a 150,000 USD baseline funded from affiliate commissions, then expands with DEX sponsorships and ecosystem contributions, and is fully redistributed to participants. **Funded from:** * Baseline 150,000 USD from affiliate revenue on DexPal referral codes * Expandable with DEX sponsorships * Expandable with ecosystem / third-party contributions ### Distribution at End of Each Round | Category | Allocation | Description | | --------------------- | ---------------- | ----------------------------------------------- | | Cashback | \~70% of credits | Fee rebates paid in USDC through DexPal Credits | | Competitions | \~20% of credits | Global Degen Board + per-DEX leaderboard prizes | | Treasury & Operations | \~10% of credits | Platform maintenance and reserves | Dollar amounts scale with the pool as it expands. DexPal Points — a separate, permanent reward currency — are allocated from their own 1,000,000-point round pool; see [Credit System](/for-users/rewards/credit-system). # Credit System DexPal uses a dual-reward system: Credits (temporary) and Points (permanent). ## DexPal Credits (Temporary) * Earned during each round from trading activity * Reset to zero at the start of every new round * Determine Points allocation at round end * Track performance within the current round ## DexPal Points (Permanent) Points are your core reward currency for long-term value. * Awarded at round end based on Credits earned * Never reset — accumulate forever * Represent long-term contribution to the platform ## Points Distribution — Round One **Total pool: 1,000,000 DexPal Points per round** (with a 10,000,000-point lifetime cap) | Category | Allocation | Distribution Basis | | ------------ | ------------- | -------------------------------------- | | Leaderboards | 50% (500,000) | Degen Board + per-DEX leaderboard rank | | Quests | 35% (350,000) | Completing quests and challenges | | Referrals | 15% (150,000) | Referring active traders | ## Key Differences | Aspect | Credits | Points | | -------- | ------------------------ | ----------------------- | | Duration | Round only | Forever | | Reset | Every round | Never | | Purpose | Track current activity | Long-term rewards | | Value | Determines Points earned | Future benefits & perks | # How to Earn DexPal offers multiple pathways to accumulate Credits and Points. ## Primary Earning Methods ### Trading Volume Every trade earns Volume Credits. Credits scale based on volume across all partner DEXs. Anti-manipulation mechanisms ensure fair distribution and prevent wash trading. ### Paying Fees Fee-based Credits are generated from trading fees, with portions funding competition prize pools. ### Referrals Refer active traders and earn from the referral rewards pool, distributed by your referees' trading activity. You can invite up to 100 wallets, and you must have traded over 10,000 USD through DexPal codes to create an invite code. Referral rewards never deduct from your referees' earnings. ### Quests & Tasks Themed challenges provide bonus Credits throughout each round: * **Volume Quests** — Hit milestones, complete trades, reach thresholds * **Engagement Quests** — Trade across multiple DEXs, maintain login streaks * **Referral Quests** — Successfully refer active traders Quests can award Credits equivalent to millions in trading volume. ## Optimization Tips * Diversify across multiple DEXs * Prioritize quest completion each round * Build a referral network for passive income * Maintain consistent daily activity * Monitor leaderboards and time activity around round cycles # Competitions ## The Degen Board (Global Leaderboard) The Degen Board tracks all traders across DexPal's partner DEXs. * Rankings based on Credits from volume and fees * Top-ranked traders share the competition prize pool (\~20% of credits, funded from the 150,000 USD baseline pool) * Plus a share of the round's leaderboard Points (500,000 — 50% of the 1,000,000-point pool) * Updated daily with real-time standings ## DEX Competitions Each partner DEX has its own dedicated leaderboard. * Top 10 traders per DEX share in the competition prize pool * Distribution based on that DEX's contribution to the prize pool * Some partners add bonus native token rewards * Daily updates for transparency > **Note:** Credits from referrals and quests don't count toward competition rankings — only actual trading activity. ## Competition Summary | Competition | Prize | Who Wins | | ---------------- | -------------------------------------------------- | ------------------ | | Degen Board | Share of the competition pool + leaderboard Points | Top global traders | | DEX Competitions | Share of the competition pool, by DEX contribution | Top 10 per DEX | ## Fair Play Mechanics The rewards framework includes built-in mechanics that keep competition inclusive for all traders: * Volume multipliers that reduce the gap between large and small traders * Encourages consistent participation over burst activity * Dynamic multipliers for fairness * Anti-manipulation algorithms * Wash trading detection and prevention Every trader, regardless of size, has a real chance to climb leaderboards and earn meaningful rewards. # Referrals Build a referral network and earn passive rewards. ## How Referrals Work When you refer someone to DexPal, you earn a bonus on all Credits they generate. ### Eligibility * You must have traded over **10,000 USD** through DexPal codes before you can create an invite code. * You can invite up to **100 wallets**. ### Rewards * Earn from the **referral rewards pool**, distributed pro rata by your referees' trading activity * Rewards are additional, never deducted from your referee's earnings * The more your referees trade, the larger your share Recruit quality traders. Your referral earnings scale with their activity. ## Benefits of a Referral Network | Benefit | Description | | -------------------- | --------------------------------------- | | Passive Income | Earn while they trade | | Scales with Activity | Your share grows as your referees trade | | Long-term Value | Referrals stay active across rounds | | Points Boost | Accelerate your Points accumulation | ## How to Refer 1. Get your unique referral link from [app.dexpal.io](https://app.dexpal.io) 2. Share with friends and fellow traders 3. They sign up and use the link on partner DEXs 4. You earn a share of the referral pool based on their trading ## FAQ **Does my referee lose rewards when I earn referral rewards?** No. Your referee keeps 100% of their own Credits. Referral rewards are additional and come from a separate referral pool. **How many people can I refer?** You can invite up to 100 wallets. **Do referrals carry over between rounds?** Yes. Once someone is your referral, they stay your referral, and their trading continues to contribute to your referral rewards. # FAQ **When do I get my rewards?** All rewards are calculated and distributed at the end of each round. Competition prizes arrive shortly after completion; DexPal Points become permanent account credits. **What are DexPal Points worth?** DexPal Points represent your contribution to the platform's growth and will provide future benefits and exclusive perks. **How long is a round?** Rounds don't have a fixed duration. Round 1 concludes when the 1,500,000 base-credit cap is reached or on December 31, 2026, whichever comes first. **Does my referee lose rewards when I earn referral rewards?** No. Referees keep 100% of their own earnings. Referral rewards are additional and come from a separate referral pool. **Can I win multiple competition prizes?** Yes. You can rank on the Global Degen Board while simultaneously winning a DEX-specific competition. **What about no-fee DEXs?** Credits from no-fee DEX trading don't affect leaderboard rankings, but 90% of referral points from those DEXs are redistributed as bonuses during the DEX's own airdrops. **Do I still earn DEX native rewards?** Yes. You earn both native DEX rewards and DexPal Points simultaneously. DexPal redistributes 90% of referral allocations from those platforms. **What are beta benefits?** During beta: 2× Credits multiplier, performance-based NFTs, and priority waitlist access for uninvited users. **Can whales dominate the leaderboards?** No. DexPal implements volume multipliers and balancing mechanics so consistent smaller traders maintain competitive opportunities. **More questions?** * [Discord](https://discord.com/invite/FECs5ct6uk) * [X (Twitter)](https://x.com/dexpal_io) * # Partners This section is for DEX teams integrating with DexPal. The DEX API specification is the source content for partner ingestion requirements. Start with the overview, then implement the endpoint pages that match the data your DEX can provide. Shared object schemas define the reusable shapes used by those endpoints. ## Contents | Page | Scope | | -------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | [DEX API Specification](/for-partners/dex-api-spec) | API overview, auth, response envelope, conventions, endpoint list | | [GET /dexpal/v1/markets](/for-partners/endpoints/dex-markets) | Market data | | [GET /dexpal/v1/metrics](/for-partners/endpoints/dex-metrics) | DEX metrics | | [GET /dexpal/v1/rewards](/for-partners/endpoints/dex-rewards) | Rewards | | [GET /dexpal/v1/token](/for-partners/endpoints/dex-token) | Token data | | [GET /dexpal/v1/earn](/for-partners/endpoints/dex-earn) | Earn mechanisms | | [GET /dexpal/v1/users/{address}/accounts](/for-partners/endpoints/user-accounts) | User accounts | | [GET /dexpal/v1/users/positions](/for-partners/endpoints/user-positions) | User positions | | [GET /dexpal/v1/users/orders](/for-partners/endpoints/user-orders) | User orders | | [GET /dexpal/v1/users/history](/for-partners/endpoints/user-history) | User history | | [GET /dexpal/v1/users/holdings](/for-partners/endpoints/user-holdings) | User holdings | | [GET /dexpal/v1/users/lp-holdings](/for-partners/endpoints/user-lp-holdings) | User LP holdings | | [AssetObject](/for-partners/schemas/asset-object) | Asset object schema | | [CollateralBreakdown](/for-partners/schemas/collateral-breakdown) | Collateral breakdown schema | | [LeverageTier](/for-partners/schemas/leverage-tier) | Leverage tier schema | | [TriggerOrder](/for-partners/schemas/trigger-order) | Trigger order schema | | [TradingHours](/for-partners/schemas/trading-hours) | Trading hours schema | | [TwapConfig](/for-partners/schemas/twap-config) | TWAP config schema | | [Pagination](/for-partners/schemas/pagination) | Pagination schema | | [Error Responses](/for-partners/schemas/error) | Error schema | # 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 ``` ## 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) | | `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) 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) — used in `markets` * [TriggerOrder](/for-partners/schemas/trigger-order) — used in `positions` and `orders` * [Pagination](/for-partners/schemas/pagination) — used in paginated endpoints * [Error](/for-partners/schemas/error) — 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) | Real-time market data for all trading pairs | Every 30s | | [GET /dexpal/v1/metrics](/for-partners/endpoints/dex-metrics) | Aggregate DEX-level statistics | Every 5 min | | [GET /dexpal/v1/rewards](/for-partners/endpoints/dex-rewards) | Per-user affiliate trading activity | On demand | | [GET /dexpal/v1/token](/for-partners/endpoints/dex-token) | Governance token data | Every 5 min | | [GET /dexpal/v1/earn](/for-partners/endpoints/dex-earn) | 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) | Discover all accounts associated with an address | | [GET /dexpal/v1/users/positions](/for-partners/endpoints/user-positions) | Open positions across all provided addresses | | [GET /dexpal/v1/users/orders](/for-partners/endpoints/user-orders) | Pending limit orders across all provided addresses | | [GET /dexpal/v1/users/history](/for-partners/endpoints/user-history) | Historical trade events, time-ranged and paginated | | [GET /dexpal/v1/users/holdings](/for-partners/endpoints/user-holdings) | Wallet and DEX account balances | | [GET /dexpal/v1/users/lp-holdings](/for-partners/endpoints/user-lp-holdings) | 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. # Endpoints # DEX Markets Returns real-time market data for all trading pairs available on the DEX. ## Overview | | | | ------------------ | ---------------- | | **Method** | GET | | **Poll frequency** | Every 30 seconds | | **Auth** | Bearer API key | | **Rate limit** | 60 req/min | ## Request No query parameters. ### Headers | Header | Required | Description | | --------------- | -------- | ------------------ | | `Authorization` | yes | `Bearer ` | ## Response Returns a top-level `data` array where each item represents one market. A `timestamp` reflects the time the data was generated. ### Fields — Market Object | Field | Type | Required | Description | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | `baseAssets` | array\[[AssetObject](/for-partners/schemas/asset-object)] | yes | Base assets for this market. Single-item array for standard pairs. | | `quoteAssets` | array\[[AssetObject](/for-partners/schemas/asset-object)] | yes | Quote assets for this market. | | `tradeUrl` | string | yes | Direct URL to trade this market on the DEX. | | `price` | number | yes | Current mark/last price in quote currency. | | `volume24h` | number | yes | 24-hour trading volume in USD (pre-calculated). | | `openInterest` | number | yes | Current open interest in USD (pre-calculated). | | `fundingRate` | number | yes | Current funding rate as a decimal percentage. `0.0125` = 0.0125%. | | `indexPrice` | number | no | Oracle/index price in quote currency. | | `change24h` | number | no | 24-hour price change as a decimal percentage. | | `high24h` | number | no | 24-hour high price in quote currency. | | `low24h` | number | no | 24-hour low price in quote currency. | | `maxLeverage` | integer | no | Maximum leverage available for this market. | | `fundingInterval` | integer | no | Funding interval in hours. Defaults to `8` if omitted. | | `nextFunding` | ISO8601 | no | Timestamp of the next funding payment. | | `minOrderSize` | number | no | Minimum order size in base currency. | | `makerFee` | number | no | Base maker/open fee as a decimal percentage. `0.02` = 0.02%. | | `takerFee` | number | no | Base taker/close fee as a decimal percentage. `0.05` = 0.05%. | | `status` | string | no | Market lifecycle state. `active`, `paused`, `delisted`, `settling`, `prelaunch`. | | `fundingIntervalType` | string | no | How the funding interval is determined. `fixed`, `dynamic`, `continuous`, or `velocity`. | | `fundingRateConvention` | string | no | Sign convention for funding rate. `standard` (positive = longs pay shorts), `inverted`, or `apy` (annualised). | | `feeModel` | string | no | How trading fees are charged for this market. `fee`, `spread`, `mixed`, `winFee`, or `zeroFee`. | | `contractType` | string | no | Settlement type. `linear` (USDC-settled), `inverse` (base-settled), or `quanto`. | | `settlementAsset` | string | no | Asset used to settle PnL. e.g. `"BTC"` for inverse, `"USDC"` for linear. | | `openInterestCap` | number | no | Maximum total open interest allowed for this market in USD. | | `openInterestUtilization` | number | no | Current OI as a fraction of the cap (0–1). | | `marketRestriction` | string | no | Current operational trading restriction. `none`, `reduceOnly`, `postOnly`, or `halted`. | | `borrowRate` | number | no | Hourly borrow rate as a decimal. Distinct from `fundingRate`. | | `leverageTiers` | array\[[LeverageTier](https://github.com/dexpal-analytics/dexpal/blob/main/docs/dex-api-spec/schemas/leverage-tier.md)] | no | Leverage tier schedule by notional size. | | `maxPositionSizeUsd` | number | no | Maximum position size in USD for this market. | | `maxOrderSize` | number | no | Maximum single order size in base tokens. | | `makerFeeRebate` | boolean | no | `true` if maker fee is negative (DEX pays the maker). | | `adlActive` | boolean | no | `true` if the auto-deleveraging system is currently active for this market. | | `feeDiscountProgram` | boolean | no | `true` if a volume-based fee discount program applies to this market. | | `maxPnlCap` | number | no | Maximum profit multiplier cap. e.g. `9.0` = 900% max profit. | | `tradingHours` | [TradingHours](https://github.com/dexpal-analytics/dexpal/blob/main/docs/dex-api-spec/schemas/trading-hours.md) | no | Trading hours schedule. `null` for 24/7 markets. | ## Example Response ```json { "success": true, "data": [ { "baseAssets": [{ "symbol": "BTC", "assetType": "crypto" }], "quoteAssets": [{ "symbol": "USD" }], "tradeUrl": "https://app.example.com/trade/BTC-USD", "price": 67543.21, "volume24h": 1234567890.5, "openInterest": 98765432.1, "fundingRate": 0.0125, "indexPrice": 67540.0, "change24h": 2.34, "high24h": 68000.0, "low24h": 66500.0, "maxLeverage": 100, "fundingInterval": 8, "nextFunding": "2026-01-20T22:00:00Z", "minOrderSize": 0.001, "makerFee": 0.02, "takerFee": 0.05 }, { "baseAssets": [{ "symbol": "ETH", "assetType": "crypto" }], "quoteAssets": [{ "symbol": "USD" }], "tradeUrl": "https://app.example.com/trade/ETH-USD", "price": 3456.78, "volume24h": 567890123.45, "openInterest": 45678901.23, "fundingRate": 0.008 } ], "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 **all** active markets in a single response. Do not paginate this endpoint. * Markets with zero volume or open interest should still be included if they are tradeable. * `fundingRate` should reflect the current rate at the time of the response, not a historical average. * For DEXes that charge different fees per user tier, return the base/default rate. * For markets with variable leverage per user, return the platform maximum. # DEX Metrics Returns aggregate DEX-level statistics including volume, fees, open interest, and platform metrics. ## 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 ` | ## Response Returns a single `data` object with platform-wide aggregate statistics. > **RECENTLY UPDATED:** Platform-token staking data (`tokenStakedPct`, `tokenStakingApy`) belongs on the [token](/for-partners/endpoints/dex-token) endpoint — do not duplicate it here. ### Fields — Metrics Object | Field | Type | Required | Description | | ----------------- | ------- | -------- | ------------------------------------------------------------------------------ | | `volume24h` | number | yes | Total trading volume in the last 24 hours, in USD. | | `openInterest24h` | number | yes | Total open interest across all markets, in USD. | | `fees24h` | number | yes | Total fees collected in the last 24 hours, in USD. | | `volume7d` | number | no | Total trading volume over the last 7 days, in USD. | | `volumeAllTime` | number | no | All-time total trading volume, in USD. | | `volumeChange1d` | number | no | 24-hour volume change as a decimal percentage. | | `volumeChange7d` | number | no | 7-day volume change as a decimal percentage. | | `openInterest7d` | number | no | Total open interest over the last 7 days, in USD. | | `fees7d` | number | no | Total fees collected over the last 7 days, in USD. | | `fees30d` | number | no | Total fees collected over the last 30 days, in USD. | | `revenue24h` | number | no | Protocol revenue (after LP/staker distributions) in the last 24 hours, in USD. | | `tvl` | number | no | Total value locked across all vaults and liquidity pools, in USD. | | `traders24h` | integer | no | Number of unique trader addresses active in the last 24 hours. | | `marketsCount` | integer | no | Total number of active markets. | ## Example Response ```json { "success": true, "data": { "volume24h": 1234567890.5, "openInterest24h": 98765432.1, "fees24h": 12345.0, "volume7d": 8765432100.0, "volumeAllTime": 999999999999.0, "volumeChange1d": 5.25, "volumeChange7d": -2.1, "openInterest7d": 105000000.0, "fees7d": 123456.0, "fees30d": 456789.0, "revenue24h": 12345.0, "tvl": 500000000.0, "traders24h": 12500, "marketsCount": 150 }, "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 * All values are point-in-time snapshots at the moment of the response. * Rolling windows (e.g. `volume24h`) should be calculated as the trailing 24 hours from `timestamp`, not calendar-day totals. * `revenue24h` is distinct from `fees24h` — revenue is what the protocol retains after distributing fees to LPs and stakers. * Omit optional fields entirely rather than returning `null` if the data is unavailable. # 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`. # DEX Token Returns data about the DEX's governance or platform token. Omit this endpoint entirely if the DEX has no token. ## 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 ` | ## Response Returns a single `data` object with token market data. ### Fields — Token Object | Field | Type | Required | Description | | ------------------- | ------- | -------- | ------------------------------------------------------------------- | | `ticker` | string | yes | Token ticker symbol e.g. `"GNS"`. | | `marketPrice` | number | yes | Current live market price in USD. | | `marketCap` | number | no | Current market capitalisation in USD (circulating supply × price). | | `fullyDilutedMcap` | number | no | Fully diluted market cap in USD (total supply × price). | | `volume24h` | number | no | 24-hour token trading volume in USD. | | `tvl` | number | no | Total value locked attributed to the token (staking, pools) in USD. | | `circulatingSupply` | number | no | Current circulating supply in token units. | | `totalSupply` | number | no | Total minted supply in token units. | | `maximumSupply` | number | no | Maximum possible supply in token units. `null` if uncapped. | | `priceAth` | object | no | All-time high price record. See below. | | `priceAtl` | object | no | All-time low price record. See below. | | `holdersCount` | integer | no | Number of unique wallet addresses holding the token. | | `tokenStakedPct` | number | no | Percentage of total supply currently staked (0–100). | | `tokenStakingApy` | number | no | Current staking APY as a decimal percentage. | ### Fields — PriceRecord Object (`priceAth`, `priceAtl`) | Field | Type | Required | Description | | ------- | ------- | -------- | --------------------------- | | `value` | number | yes | Price in USD at the record. | | `date` | ISO8601 | yes | Date the record was set. | ## Example Response ```json { "success": true, "data": { "ticker": "GNS", "marketPrice": 1.93, "marketCap": 64661108, "fullyDilutedMcap": 64602278, "volume24h": 2197147, "tvl": 14755122, "circulatingSupply": 33394127, "totalSupply": 33394127, "maximumSupply": null, "priceAth": { "value": 12.45, "date": "2023-02-17T00:00:00Z" }, "priceAtl": { "value": 0.259, "date": "2021-11-29T00:00:00Z" }, "holdersCount": 158296, "tokenStakedPct": 45.5, "tokenStakingApy": 12.5 }, "timestamp": "2026-01-20T21:00:00Z" } ``` ## Error Responses | Status | Error | When | | ------ | ------------------------------------- | ------------------------- | | `401` | `"Invalid or missing API key"` | Bad or absent auth header | | `404` | `"No token associated with this DEX"` | DEX has no platform token | | `500` | `"Internal server error"` | Unexpected failure | ## Notes * If `circulatingSupply` equals `totalSupply`, both fields are still required separately. * `tokenStakedPct` and `tokenStakingApy` should match the values returned in [`metrics`](/for-partners/endpoints/dex-metrics) if both endpoints are implemented. * Return `"maximumSupply": null` explicitly for tokens with no hard cap (do not omit the field). # 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 ` | ## 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"`). # User Accounts Returns all accounts the DEX associates with the given address. DexPal calls this endpoint for each of a user's connected wallets to build a complete picture of their accounts before querying positions, orders, history, or holdings. > **Collection endpoint:** Return accounts for any requested address the DEX can read, even if the wallet has not used DexPal's affiliate code. Return `404 "Address not found"` only when the address is unknown to the DEX. See the [Overview](/for-partners/dex-api-spec). ## Overview | | | | -------------- | -------------- | | **Method** | GET | | **Auth** | Bearer API key | | **Rate limit** | 120 req/min | ## Request ### Path Parameters | Param | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | string | yes | A wallet address in any format supported by the DEX. The DEX handles format detection internally (EVM hex, Solana base58, Cosmos bech32, etc.). | ### Headers | Header | Required | Description | | --------------- | -------- | ------------------ | | `Authorization` | yes | `Bearer ` | ## Response Returns a `data` array of all accounts associated with the given address on this DEX. ### Fields — Account Object | Field | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------------------------------------------------------- | | `address` | string | yes | The account address. May differ from the path `{address}` for subaccounts and smart wallets. | | `label` | string | no | DEX-assigned human-readable label for this account e.g. `"Main Account"`, `"1-Click Trading"`. | ## Account Types DexPal users may have several types of accounts on a given DEX. The DEX handles the distinction internally and returns all of them here. Common account types include: * **Primary wallet** — the main EOA used to sign transactions * **Subaccount** — a DEX-managed account linked to the primary wallet (e.g. dYdX subaccounts) * **Smart wallet** — an ERC-4337 or equivalent smart contract wallet * **One-click trading account** — a session wallet used for fast order execution without per-transaction signing (e.g. Vela one-click trading) All of these are returned as flat entries in the `data` array. DexPal uses the returned addresses to query all other user endpoints. ## Example Response ```json { "success": true, "data": [ { "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12", "label": "Main Account" }, { "address": "0x9c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d", "label": "1-Click Trading" }, { "address": "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef", "label": "Subaccount 1" } ] } ``` ## Error Responses | Status | Error | When | | ------ | ------------------------------ | ----------------------------------- | | `401` | `"Invalid or missing API key"` | Bad or absent auth header | | `404` | `"Address not found"` | Address has no accounts on this DEX | | `500` | `"Internal server error"` | Unexpected failure | ## Notes * Always include the primary wallet itself in the response, not only subaccounts. * Return `404` only when the address is completely unknown to the DEX. A known address with no subaccounts should return a single-item array containing the primary address. * The `address` values returned here are used as input to the `?addr=` parameter on all other user-level endpoints. # User Positions Returns all currently open trading positions for the provided wallet addresses. > **Collection endpoint:** Return open positions for any requested address the DEX can read, even if the wallet has not used DexPal's affiliate code. If none of the provided addresses have open positions, return `200` with `"data": []`. See the [Overview](/for-partners/dex-api-spec). ## Overview | | | | -------------- | -------------- | | **Method** | GET | | **Auth** | Bearer API key | | **Rate limit** | 120 req/min | ## Request ### Query Parameters | Param | Type | Required | Description | | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------ | | `addr` | string | yes | Comma-separated list of wallet addresses to query. Supports all address formats the DEX accepts. | ### Headers | Header | Required | Description | | --------------- | -------- | ------------------ | | `Authorization` | yes | `Bearer ` | ### Example Request ``` GET /dexpal/v1/users/positions?addr=0x1a2b...,0x9c3d...,0xdead... ``` ## Response Returns a `data` array of open position objects. Each item includes the address it belongs to. ### Fields — Position Object | Field | Type | Required | Description | | --------------------- | ------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `positionId` | string | yes | Unique position identifier in the format `exchange:wallet:id` e.g. `"gmx:0x1a2b...:18"`. | | `address` | string | yes | The wallet address that owns this position. Matches one of the `addr` values in the request. | | `exchange` | string | yes | DEX slug e.g. `"gmx"`, `"gains"`, `"vela"`. | | `side` | enum | yes | Position direction. `long` or `short`. | | `baseAsset` | string | yes | Base currency symbol e.g. `"BTC"`. | | `quoteAsset` | string | yes | Quote currency symbol e.g. `"USD"`. | | `assetType` | string | yes | Asset category e.g. `"crypto"`. See [AssetObject](/for-partners/schemas/asset-object) for valid values. | | `avgEntryPrice` | number | yes | Average entry price in quote currency. Reflects the weighted average if the position was scaled in/out. | | `positionSizeUsd` | number | yes | Current position size in USD. | | `positionSizeToken` | number | yes | Current position size in base currency. | | `collateralUsd` | number | yes | Current collateral posted in USD. | | `leverage` | number | yes | Effective leverage at the current position size and collateral. | | `liquidationPrice` | number | yes | Price at which the position would be liquidated, in quote currency. | | `unrealizedPnl` | number | yes | Current unrealized profit/loss in USD. Positive = profit, negative = loss. | | `feeBorrowingUsd` | number | no | Total accrued borrow fees over the life of the position, in USD. | | `feeFundingUsd` | number | no | Total accrued funding fees over the life of the position, in USD. Negative if the position is receiving funding. | | `feeTradingUsd` | number | no | Total accrued trading fees over the life of the position, in USD. | | `feeNetworkUsd` | number | no | Total accrued gas/network fees over the life of the position, in USD. | | `chainId` | integer | no | Wagmi/viem chain ID of the network where the position is held. See [wagmi chains](https://wagmi.sh/core/api/chains). | | `tradeUrl` | string | no | Deep link to this specific position on the DEX. | | `createdAt` | ISO8601 | yes | Timestamp when the position was opened. | | `updatedAt` | ISO8601 | no | Timestamp of the most recent modification to the position (size change, collateral adjustment, etc.). | | `triggerOrders` | array\[[TriggerOrder](/for-partners/schemas/trigger-order)] | no | Associated stop loss and take profit orders. Empty array if none. | | `marginMode` | string | no | Margin isolation mode. `cross`, `isolated`, or `portfolio`. | | `collateralAsset` | string | no | Primary collateral asset symbol e.g. `"USDC"`. | | `collateralAmount` | number | no | Collateral amount in asset units (not USD). | | `collateralFactor` | number | no | Collateral haircut factor (0–1). Lower = less credit per unit of collateral. | | `collateralBreakdown` | array\[[CollateralBreakdown](/for-partners/schemas/collateral-breakdown)] | no | Per-asset collateral breakdown for multi-asset margin accounts. | | `accountId` | string | no | Subaccount or portfolio ID. For DEXes that support subaccounts. | | `adlRiskLevel` | integer | no | ADL risk queue position. `1` = lowest risk, `5` = highest (first in ADL queue). | | `healthFactor` | number | no | Position health ratio. `1.0` = at the liquidation threshold. Higher = healthier. | | `marginHealthStatus` | string | no | Human-readable health status. `healthy`, `warning`, `danger`, or `liquidatable`. | | `hedgeSide` | string | no | For hedge-mode DEXes, which side this position represents. `long` or `short`. | ## Example Response ```json { "success": true, "data": [ { "positionId": "gmx:0x1a2b3c4d5e6f7890abcdef1234567890abcdef12:18", "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12", "exchange": "gmx", "side": "long", "baseAsset": "BTC", "quoteAsset": "USD", "assetType": "crypto", "avgEntryPrice": 61760.20, "positionSizeUsd": 200.0, "positionSizeToken": 0.00319709, "collateralUsd": 20.0, "leverage": 10, "liquidationPrice": 58450.85, "unrealizedPnl": 59.73, "feeBorrowingUsd": 0.12, "feeFundingUsd": 0.08, "feeTradingUsd": 0.20, "feeNetworkUsd": 0.05, "chainId": 42161, "tradeUrl": "https://app.gmx.io/#/trade/BTC-USD", "createdAt": "2024-09-06T22:52:39Z", "updatedAt": "2024-09-09T17:43:57Z", "triggerOrders": [ { "action": "takeProfit", "triggerPrice": 70000.0, "amountPercent": 100.0, "createdAt": "2024-09-06T23:00:00Z" }, { "action": "stopLoss", "triggerPrice": 58000.0, "amountPercent": 100.0, "createdAt": "2024-09-06T23:00:00Z" } ] } ] } ``` ## Error Responses | Status | Error | When | | ------ | ------------------------------------ | ------------------------- | | `400` | `"Missing required parameter: addr"` | `addr` absent | | `401` | `"Invalid or missing API key"` | Bad or absent auth header | | `500` | `"Internal server error"` | Unexpected failure | ## Notes * Only return positions with status `open`. Closed or liquidated positions belong in [`history`](/for-partners/endpoints/user-history). * If none of the provided addresses have open positions, return `"data": []` — not a `404`. * `unrealizedPnl` should be calculated using the current mark price at the time of the response. * For positions that have been partially closed, return the current remaining size — not the original. * `feeFundingUsd` can be negative if the position is on the receiving side of funding. # User Orders Returns all pending limit orders for the provided wallet addresses. > **Collection endpoint:** Return pending orders for any requested address the DEX can read, even if the wallet has not used DexPal's affiliate code. If none of the provided addresses have pending orders, return `200` with `"data": []`. See the [Overview](/for-partners/dex-api-spec). ## Overview | | | | -------------- | -------------- | | **Method** | GET | | **Auth** | Bearer API key | | **Rate limit** | 120 req/min | ## Request ### Query Parameters | Param | Type | Required | Description | | ------ | ------ | -------- | -------------------------------------------------- | | `addr` | string | yes | Comma-separated list of wallet addresses to query. | ### Headers | Header | Required | Description | | --------------- | -------- | ------------------ | | `Authorization` | yes | `Bearer ` | ### Example Request ``` GET /dexpal/v1/users/orders?addr=0x1a2b...,0x9c3d... ``` ## Response Returns a `data` array of pending limit order objects. ### Fields — Order Object | Field | Type | Required | Description | | ------------------- | ----------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `orderId` | string | yes | Unique order identifier in the format `exchange:wallet:id` e.g. `"vela:0x1a2b...:85"`. | | `address` | string | yes | The wallet address that placed this order. | | `exchange` | string | yes | DEX slug e.g. `"vela"`, `"gmx"`. | | `side` | enum | yes | Order direction. `long` or `short`. | | `baseAsset` | string | yes | Base currency symbol e.g. `"BTC"`. | | `quoteAsset` | string | yes | Quote currency symbol e.g. `"USD"`. | | `assetType` | string | yes | Asset category. See [AssetObject](/for-partners/schemas/asset-object) for valid values. | | `limitPrice` | number | yes | Target execution price in quote currency. The order fills when the market reaches this price. | | `positionSizeUsd` | number | yes | Position size that will open at execution, in USD. | | `positionSizeToken` | number | yes | Position size in base currency at the limit price. | | `collateralUsd` | number | yes | Collateral that will be posted at execution, in USD. | | `leverage` | number | yes | Leverage that will be applied at execution. | | `feeFundingUsd` | number | no | Estimated funding fee at time of order creation, in USD. | | `closingFeeUsd` | number | no | Estimated closing fee if the position is closed immediately at execution, in USD. | | `chainId` | integer | no | Wagmi/viem chain ID of the network where the order is placed. | | `createdAt` | ISO8601 | yes | Timestamp when the order was placed. | | `triggerOrders` | array\[[TriggerOrder](/for-partners/schemas/trigger-order)] | no | Associated stop loss and take profit orders that will activate when this order fills. Empty array if none. | | `orderType` | string | no | Order type classification. `market`, `limit`, `stopMarket`, `stopLimit`, `trailingStop`, `twap`, `ladder`, `scale`, `oco`, `oto`, `takeProfit`, `iceberg`. | | `orderFlags` | array\[string] | no | Execution modifier flags. Any subset of `reduceOnly`, `postOnly`, `ioc`, `fok`. | | `timeInForce` | string | no | Time-in-force policy. `gtc` (good till cancelled), `ioc` (immediate or cancel), `fok` (fill or kill), `gtt` (good till time). | | `expiresAt` | ISO8601 | no | Expiry timestamp. Only set when `timeInForce` is `gtt`. | | `stopPrice` | number | no | Trigger price for stop orders. Set on `stopMarket` and `stopLimit` orders. | | `trailAmount` | number | no | Trail distance. Units depend on `trailType`. | | `trailType` | string | no | Trail amount unit. `percent` or `absolute`. | | `activationPrice` | number | no | Price at which trailing stop begins tracking. | | `triggerPriceType` | string | no | Price feed used to evaluate the trigger. `mark`, `last`, or `index`. | | `twapConfig` | [TwapConfig](/for-partners/schemas/twap-config) | no | TWAP execution parameters. Only present on `twap` orders. | | `linkedOrderId` | string | no | Partner order ID for OCO (one-cancels-other) pairs. | | `isSystemGenerated` | boolean | no | `true` if created automatically by the DEX (e.g. mandatory stop-loss). | | `accountId` | string | no | Subaccount or portfolio ID. | ## Example Response ```json { "success": true, "data": [ { "orderId": "vela:0x1a2b3c4d5e6f7890abcdef1234567890abcdef12:85", "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12", "exchange": "vela", "side": "long", "baseAsset": "BTC", "quoteAsset": "USD", "assetType": "crypto", "limitPrice": 40500.0, "positionSizeUsd": 200.0, "positionSizeToken": 0.00493, "collateralUsd": 20.0, "leverage": 10, "feeFundingUsd": 0.0, "closingFeeUsd": 0.0, "chainId": 42161, "createdAt": "2024-09-05T19:48:05Z", "triggerOrders": [ { "action": "takeProfit", "triggerPrice": 45000.0, "amountPercent": 100.0, "createdAt": "2024-09-05T19:48:05Z" } ] } ] } ``` ## Error Responses | Status | Error | When | | ------ | ------------------------------------ | ------------------------- | | `400` | `"Missing required parameter: addr"` | `addr` absent | | `401` | `"Invalid or missing API key"` | Bad or absent auth header | | `500` | `"Internal server error"` | Unexpected failure | ## Notes * Only return orders with status `pending` (not yet filled, cancelled, or expired). Filled orders appear in [`history`](/for-partners/endpoints/user-history). * If none of the provided addresses have pending orders, return `"data": []`. * `positionSizeToken` should be calculated at the `limitPrice`, not the current market price. * Not all DEXes support trigger orders on limit orders. Return an empty `triggerOrders` array if not applicable. # User History Returns a paginated history of trading events for the provided wallet addresses within a given time range. Each item represents a discrete event (position opened, size increased, position closed, liquidation, etc.). > **Collection endpoint:** Return history for any requested address the DEX can read, even if the wallet has not used DexPal's affiliate code. DexPal enforces any user-facing visibility restrictions after collection. If none of the provided addresses have history, return `200` with `"data": []`. See the [Overview](/for-partners/dex-api-spec). ## Overview | | | | -------------- | -------------- | | **Method** | GET | | **Auth** | Bearer API key | | **Rate limit** | 120 req/min | ## Request ### Query Parameters | Param | Type | Required | Description | | -------- | ------- | -------- | -------------------------------------------------- | | `addr` | string | yes | Comma-separated list of wallet addresses to query. | | `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 ` | ### Example Request ``` GET /dexpal/v1/users/history?addr=0x1a2b...,0x9c3d...&from=2026-01-01T00:00:00Z&to=2026-01-31T23:59:59Z&limit=100&offset=0 ``` ## Response Returns a paginated `data` array of trade event objects, ordered by `createdAt` descending (most recent first). ### Fields — History Event Object | Field | Type | Required | Description | | -------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | `positionId` | string | yes | Links this event back to a position. Same format as [`positions`](/for-partners/endpoints/user-positions): `exchange:wallet:id`. | | `address` | string | yes | The wallet address associated with this event. | | `exchange` | string | yes | DEX slug where the event occurred. | | `category` | enum | yes | Type of event. See values below. | | `side` | enum | yes | Position direction at the time of the event. `long` or `short`. | | `baseAsset` | string | yes | Base currency symbol. | | `quoteAsset` | string | yes | Quote currency symbol. | | `assetType` | string | yes | Asset category. See [AssetObject](/for-partners/schemas/asset-object) for valid values. | | `price` | number | yes | Asset mark price at the time of the event, in quote currency. | | `avgEntryPrice` | number | yes | Average entry price for the position at the time of the event. | | `positionSizeUsd` | number | yes | Position size at the time of the event, in USD. | | `collateralUsd` | number | no | Collateral posted at the time of the event, in USD. | | `leverage` | number | no | Leverage used at the time of the event. | | `realizedPnl` | number | no | Realized profit/loss in USD. Present only on `closePosition`, `liquidation`, `takeProfit`, and `stopLoss` events. | | `feeBorrowingUsd` | number | no | Borrow fees attributed to this event, in USD. | | `feeFundingUsd` | number | no | Funding fees attributed to this event, in USD. | | `feeTradingUsd` | number | no | Trading fees attributed to this event, in USD. | | `feeNetworkUsd` | number | no | Gas/network fees attributed to this event, in USD. | | `role` | enum | no | User's role in the trade. `maker` or `taker`. Present only on `openPosition` events. | | `chainId` | integer | no | Wagmi/viem chain ID of the network where the event occurred. | | `txHash` | string | no | On-chain transaction hash. Allows the user to verify the event on a block explorer. | | `createdAt` | ISO8601 | yes | Timestamp when the event occurred. | | `updatedAt` | ISO8601 | no | Timestamp of the last update to this event record. | | `feeRateBps` | number | no | Effective fee rate for this event in basis points. | | `liquidationType` | string | no | Liquidation scope. `partial`, `full`, or `backstop`. Only set when `category` is `liquidation`. | | `remainingSize` | number | no | Remaining position size in USD after a partial liquidation. | | `realizedPnlGross` | number | no | Realized PnL before fees. `realizedPnl` is always net of fees. | | `collateralDeltaUsd` | number | no | Collateral change in USD. Positive = added, negative = removed. Only set on `collateralAdd` / `collateralRemove` events. | | `accountId` | string | no | Subaccount or portfolio ID. | ### `category` Values | Value | Description | | ------------------ | ----------------------------------------------------- | | `openPosition` | A new position was opened. | | `increaseSize` | An existing position's size was increased. | | `decreaseSize` | An existing position's size was partially reduced. | | `closePosition` | A position was fully closed by the user. | | `liquidation` | A position was liquidated by the protocol. | | `takeProfit` | A take profit trigger order was executed. | | `stopLoss` | A stop loss trigger order was executed. | | `adl` | Position was auto-deleveraged against a counterparty. | | `fundingPayment` | A periodic funding payment was applied. | | `collateralAdd` | Collateral was added to the position. | | `collateralRemove` | Collateral was withdrawn from the position. | ## Example Response ```json { "success": true, "data": [ { "positionId": "vela:0x1a2b3c4d5e6f7890abcdef1234567890abcdef12:85", "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12", "exchange": "vela", "category": "openPosition", "side": "long", "baseAsset": "WIF", "quoteAsset": "USD", "assetType": "crypto", "price": 1.506775, "avgEntryPrice": 1.506775, "positionSizeUsd": 90.0, "collateralUsd": 20.0, "leverage": 4.5, "realizedPnl": null, "feeBorrowingUsd": 0.0, "feeFundingUsd": 0.0, "feeTradingUsd": 0.04, "feeNetworkUsd": 0.01, "role": "taker", "chainId": 42161, "txHash": "0x9a9305605ee27d2cff45122479306271459b06b88d6bbed244d0a6cdf00eb390", "createdAt": "2024-09-06T22:52:39Z", "updatedAt": "2024-09-06T22:52:39Z" }, { "positionId": "vela:0x1a2b3c4d5e6f7890abcdef1234567890abcdef12:85", "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12", "exchange": "vela", "category": "closePosition", "side": "long", "baseAsset": "WIF", "quoteAsset": "USD", "assetType": "crypto", "price": 1.92, "avgEntryPrice": 1.506775, "positionSizeUsd": 90.0, "collateralUsd": 20.0, "leverage": 4.5, "realizedPnl": 24.86, "feeBorrowingUsd": 0.03, "feeFundingUsd": 0.01, "feeTradingUsd": 0.04, "feeNetworkUsd": 0.01, "chainId": 42161, "txHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890", "createdAt": "2024-09-09T17:43:57Z" } ], "pagination": { "limit": 100, "offset": 0, "total": 432, "hasMore": true } } ``` ## Error Responses | Status | Error | When | | ------ | ------------------------------------------- | ------------------------- | | `400` | `"Missing required parameter: addr"` | `addr` absent | | `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 * Results are ordered by `createdAt` descending (most recent first). * `realizedPnl` should only be present on closing events (`closePosition`, `liquidation`, `takeProfit`, `stopLoss`). Omit or return `null` for all other categories. * `role` should only be present on `openPosition` events. * All fee fields on a given event represent fees attributed to that event only, not cumulative position totals. * If a position was partially closed via `decreaseSize` and then fully closed, each action is a separate event with the same `positionId`. # User Holdings Returns wallet and DEX account balances for the provided addresses. Covers both on-chain token balances and funds deposited into a DEX account (for DEXes that require account deposits). > **Collection endpoint:** Return holdings for any requested address the DEX can read, even if the wallet has not used DexPal's affiliate code. If none of the provided addresses have holdings, return `200` with `"data": []`. See the [Overview](/for-partners/dex-api-spec). ## Overview | | | | -------------- | -------------- | | **Method** | GET | | **Auth** | Bearer API key | | **Rate limit** | 120 req/min | ## Request ### Query Parameters | Param | Type | Required | Description | | ------ | ------ | -------- | -------------------------------------------------- | | `addr` | string | yes | Comma-separated list of wallet addresses to query. | ### Headers | Header | Required | Description | | --------------- | -------- | ------------------ | | `Authorization` | yes | `Bearer ` | ### Example Request ``` GET /dexpal/v1/users/holdings?addr=0x1a2b...,0x9c3d... ``` ## Response Returns a `data` array where each item represents one asset holding for one address. A single address may appear multiple times for different assets or networks. ### Fields — Holding Object | Field | Type | Required | Description | | ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- | | `address` | string | yes | The wallet address that holds this balance. | | `asset` | string | yes | Token symbol e.g. `"BTC"`, `"USDC"`, `"ETH"`. | | `assetType` | string | yes | Asset category e.g. `"crypto"`. See [AssetObject](/for-partners/schemas/asset-object) for valid values. | | `network` | string | yes | Chain slug where this balance is held e.g. `"arbitrum"`, `"base"`. | | `exchange` | string | no | `null` for on-chain wallet balances. DEX slug (e.g. `"gmx"`) for funds deposited into a DEX account. | | `amount` | number | yes | Raw token amount held. | | `amountUsd` | number | yes | USD value of the holding at current price (`amount × priceUsd`). | | `priceUsd` | number | yes | Current price of the asset in USD at the time of the response. | ## Example Response ```json { "success": true, "data": [ { "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12", "asset": "BTC", "assetType": "crypto", "network": "arbitrum", "exchange": null, "amount": 0.0056, "amountUsd": 378.24, "priceUsd": 67543.21 }, { "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12", "asset": "ETH", "assetType": "crypto", "network": "arbitrum", "exchange": null, "amount": 1.25, "amountUsd": 4320.98, "priceUsd": 3456.78 }, { "address": "0x9c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d", "asset": "USDC", "assetType": "crypto", "network": "arbitrum", "exchange": "gmx", "amount": 349.27, "amountUsd": 349.27, "priceUsd": 1.0 } ] } ``` ## Error Responses | Status | Error | When | | ------ | ------------------------------------ | ------------------------- | | `400` | `"Missing required parameter: addr"` | `addr` absent | | `401` | `"Invalid or missing API key"` | Bad or absent auth header | | `500` | `"Internal server error"` | Unexpected failure | ## Notes * Return one item per asset per network per address. If an address holds ETH on both Arbitrum and Base, return two separate items. * Zero balances may be omitted. * `exchange: null` indicates a standard on-chain wallet balance. `exchange: "gmx"` (or similar) indicates funds deposited into a DEX's internal account system, separate from the wallet. * `amountUsd` must equal `amount × priceUsd` at the time of the response. Do not use stale prices. * Only return holdings relevant to this DEX's supported networks and assets. Do not return balances from unrelated chains. # User LP Holdings Returns the LP, vault, and staking positions held by the provided addresses, along with any accrued pending rewards. > **Collection endpoint:** Return LP, vault, and staking positions for any requested address the DEX can read, even if the wallet has not used DexPal's affiliate code. If none of the provided addresses have LP/vault/staking positions, return `200` with `"data": []`. See the [Overview](/for-partners/dex-api-spec). ## Overview | | | | -------------- | -------------- | | **Method** | GET | | **Auth** | Bearer API key | | **Rate limit** | 120 req/min | ## Request ### Query Parameters | Param | Type | Required | Description | | ------ | ------ | -------- | -------------------------------------------------- | | `addr` | string | yes | Comma-separated list of wallet addresses to query. | ### Headers | Header | Required | Description | | --------------- | -------- | ------------------ | | `Authorization` | yes | `Bearer ` | ### Example Request ``` GET /dexpal/v1/users/lp-holdings?addr=0x1a2b...,0x9c3d... ``` ## Response Returns a `data` array where each item represents one earn position for one address. A single address may appear multiple times across different mechanisms or networks. ### Fields — LP Holding Object | Field | Type | Required | Description | | ------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | string | yes | The wallet address holding this position. | | `mechanismName` | string | yes | Human-readable name of the earn mechanism e.g. `"wBTC/USDC Liquidity Pool"`, `"GNS Staking"`. Matches `name` from the [`earn`](/for-partners/endpoints/dex-earn) endpoint. | | `type` | enum | yes | Mechanism category. `staking`, `vault`, `lp`, or `lending`. | | `network` | string | yes | Chain slug where this position is held e.g. `"arbitrum"`. | | `exchange` | string | yes | DEX slug e.g. `"gmx"`, `"gains"`. | | `amount` | number | yes | Deposited or staked amount in token units. | | `amountUsd` | number | yes | USD value of the position at current price. | | `autoCompounding` | boolean | yes | Whether rewards are automatically reinvested into the position. | | `pendingRewardsUsd` | number | no | Accrued but unclaimed rewards in USD. `0` if no pending rewards. | | `dexLink` | string | no | Deep link to this earn position on the DEX. | ## Example Response ```json { "success": true, "data": [ { "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12", "mechanismName": "GNS Staking", "type": "staking", "network": "arbitrum", "exchange": "gains", "amount": 1250.0, "amountUsd": 2412.50, "autoCompounding": false, "pendingRewardsUsd": 12.50, "dexLink": "https://gains.trade/staking" }, { "address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12", "mechanismName": "DAI Vault", "type": "vault", "network": "arbitrum", "exchange": "gains", "amount": 500.0, "amountUsd": 500.0, "autoCompounding": true, "pendingRewardsUsd": 0, "dexLink": "https://gains.trade/vaults" }, { "address": "0x9c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d", "mechanismName": "wBTC/USDC Liquidity Pool", "type": "lp", "network": "arbitrum", "exchange": "gmx", "amount": 0.0056, "amountUsd": 378.24, "autoCompounding": false, "pendingRewardsUsd": 4.20, "dexLink": "https://app.gmx.io/#/earn" } ] } ``` ## Error Responses | Status | Error | When | | ------ | ------------------------------------ | ------------------------- | | `400` | `"Missing required parameter: addr"` | `addr` absent | | `401` | `"Invalid or missing API key"` | Bad or absent auth header | | `500` | `"Internal server error"` | Unexpected failure | ## Notes * Return one item per earn mechanism per address per network. If a user has staked in the same pool on two networks, return two separate items. * Zero-balance positions may be omitted. * `pendingRewardsUsd` represents rewards that have accrued but not yet been claimed or compounded. For `autoCompounding: true` mechanisms, this is typically `0`. * `amount` is in the deposit token units — for LP positions this is LP token units, for staking this is the staked token units. * `mechanismName` should match the `name` field returned by the [`earn`](/for-partners/endpoints/dex-earn) endpoint so DexPal can correlate user holdings with mechanism metadata. # Schemas # Asset Object A reusable object representing a single asset in a market pair. Used in the [`markets`](/for-partners/endpoints/dex-markets) endpoint for `baseAssets` and `quoteAssets` arrays. ## Schema | Field | Type | Required | Description | | ----------- | ------ | ---------------------------------- | -------------------------------------------------- | | `symbol` | string | yes | Asset ticker symbol e.g. `"BTC"`, `"ETH"`, `"USD"` | | `assetType` | string | yes (baseAssets), no (quoteAssets) | Asset category. See values below. | ## `assetType` Values | Value | Description | | ------------ | ------------------------------------- | | `crypto` | Cryptocurrency | | `forex` | Foreign exchange currency | | `commodity` | Physical commodity e.g. gold, oil | | `equity` | Stock or equity | | `index` | Market index | | `premarket` | Pre-market or prediction market asset | | `dominance` | Crypto dominance market e.g. BTC.D | | `volatility` | Volatility index | ## Example ```json { "symbol": "BTC", "assetType": "crypto" } ``` ```json { "symbol": "USD", "assetType": "forex" } ``` ## Notes * `baseAssets` and `quoteAssets` are arrays to support multi-asset or basket markets. For standard pairs, each array contains a single object. * `assetType` is required on `baseAssets` and optional on `quoteAssets` (quote is almost always a USD stablecoin). # Collateral Breakdown Per-asset collateral entry for multi-asset margin accounts. Used in [`positions`](/for-partners/endpoints/user-positions) as a nested array in `collateralBreakdown`. ## Schema | Field | Type | Required | Description | | ----------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `asset` | string | yes | Asset symbol e.g. `"BTC"`, `"ETH"`, `"USDC"`. | | `amount` | number | yes | Raw token amount of this asset posted as collateral. | | `amountUsd` | number | yes | USD value of `amount` at the time of the response. | | `haircut` | number | yes | Collateral factor (0–1). Fraction of USD value credited toward margin. e.g. `0.85` = 85 cents of margin credit per dollar of this asset. | ## Example ```json [ { "asset": "BTC", "amount": 0.01, "amountUsd": 670.0, "haircut": 0.95 }, { "asset": "ETH", "amount": 0.5, "amountUsd": 1750.0, "haircut": 0.90 } ] ``` ## Notes * `amountUsd` should be calculated at the current mark price of each asset at response time. * The sum of `amount * haircut` across all entries determines the effective margin the position can use. * Only present when the DEX supports multi-asset collateral (`collateralBreakdown` in `RawPosition`). # Leverage Tier One tier in a market's leverage schedule, where maximum allowed leverage decreases as position size increases. Used in [`markets`](/for-partners/endpoints/dex-markets) as a nested array in `leverageTiers`. ## Schema | Field | Type | Required | Description | | ----------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------- | | `notionalFloor` | number | yes | Minimum notional position size in USD for this tier (inclusive). | | `notionalCeil` | number | yes | Maximum notional position size in USD for this tier (inclusive). Use a large number (e.g. `1e15`) for the top tier. | | `maxLeverage` | number | yes | Maximum leverage allowed within this notional range. | | `maintenanceMarginRate` | number | yes | Maintenance margin rate as a decimal. e.g. `0.005` = 0.5%. | ## Example ```json [ { "notionalFloor": 0, "notionalCeil": 50000, "maxLeverage": 100, "maintenanceMarginRate": 0.005 }, { "notionalFloor": 50000, "notionalCeil": 250000, "maxLeverage": 50, "maintenanceMarginRate": 0.01 }, { "notionalFloor": 250000, "notionalCeil": 1000000000000000, "maxLeverage": 20, "maintenanceMarginRate": 0.025 } ] ``` ## Notes * Tiers should be contiguous — the `notionalCeil` of one tier equals the `notionalFloor` of the next. * Return tiers sorted ascending by `notionalFloor`. * `maintenanceMarginRate` is used to determine the liquidation price: position is liquidated when remaining collateral / notional ≤ `maintenanceMarginRate`. # Trigger Order A reusable object representing a stop loss or take profit order attached to a position or limit order. Used in [`positions`](/for-partners/endpoints/user-positions) and [`orders`](/for-partners/endpoints/user-orders) as a nested array. ## Schema | Field | Type | Required | Description | | --------------- | ------- | -------- | ---------------------------------------------------------------------------------- | | `action` | enum | yes | Type of trigger. `takeProfit` or `stopLoss`. | | `triggerPrice` | number | yes | Price at which the order fires, in quote currency. | | `amountPercent` | number | yes | Percentage of the position to close when triggered. `100` = close entire position. | | `createdAt` | ISO8601 | yes | Timestamp when the trigger order was created. | ## Example ```json { "action": "takeProfit", "triggerPrice": 70000.0, "amountPercent": 100.0, "createdAt": "2024-09-06T23:00:00Z" } ``` ```json { "action": "stopLoss", "triggerPrice": 58000.0, "amountPercent": 100.0, "createdAt": "2024-09-06T23:00:00Z" } ``` ## Notes * A single position or order may have multiple trigger orders at different price points (e.g. partial take profits). * `amountPercent` values across multiple triggers do not need to sum to 100 — DEX behaviour varies. * Not all DEXes support trigger orders on limit orders. Return an empty array if not applicable. # Trading Hours Trading hours schedule for markets that are not open 24/7 (e.g. traditional asset markets). Present in [`markets`](/for-partners/endpoints/dex-markets) as `tradingHours`. Omit entirely (or return `null`) for perpetual crypto markets that trade continuously. ## Schema | Field | Type | Required | Description | | ----------------- | ------- | -------- | --------------------------------------------------------------------- | | `timezone` | string | yes | IANA timezone name e.g. `"America/New_York"`, `"Europe/London"`. | | `schedule` | string | yes | Human-readable schedule string e.g. `"Mon–Fri 09:30–16:00"`. | | `isCurrentlyOpen` | boolean | yes | Whether the market is open at the time of the response. | | `nextOpenAt` | ISO8601 | no | Timestamp of the next market open. Omit if currently open or unknown. | ## Example ```json { "timezone": "America/New_York", "schedule": "Mon–Fri 09:30–16:00", "isCurrentlyOpen": true, "nextOpenAt": null } ``` ```json { "timezone": "America/New_York", "schedule": "Mon–Fri 09:30–16:00", "isCurrentlyOpen": false, "nextOpenAt": "2026-04-21T13:30:00Z" } ``` ## Notes * `isCurrentlyOpen` must be evaluated at response time in the market's local timezone. * `nextOpenAt` should account for holidays and closures where known. * Crypto perpetual markets should omit `tradingHours` entirely — they are always open. # TWAP Config Execution parameters for a TWAP (time-weighted average price) order. Present in [`orders`](/for-partners/endpoints/user-orders) when `orderType` is `twap`. ## Schema | Field | Type | Required | Description | | ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | `intervals` | integer | yes | Number of sub-orders the TWAP splits into. | | `intervalSecs` | integer | yes | Seconds between each sub-order execution. | | `maxSlippagePct` | number | yes | Maximum allowed slippage per interval as a percentage. `0.5` = 0.5%. If slippage exceeds this, the sub-order is skipped. | ## Example ```json { "intervals": 10, "intervalSecs": 60, "maxSlippagePct": 0.5 } ``` ## Notes * Total execution duration = `intervals × intervalSecs`. The example above executes over 10 minutes. * Each sub-order is approximately `totalSize / intervals` in size. * Not all DEXes expose TWAP config via API — omit if unavailable. # Pagination All paginated endpoints return a `pagination` object at the top level of the response alongside `data`. ## Schema | Field | Type | Description | | --------- | ------- | --------------------------------------------------- | | `limit` | integer | Number of items requested per page. | | `offset` | integer | Number of items skipped from the start. | | `total` | integer | Total number of items available. | | `hasMore` | boolean | `true` if more items exist beyond the current page. | ## Example ```json { "pagination": { "limit": 100, "offset": 0, "total": 432, "hasMore": true } } ``` ## Query Parameters Paginated endpoints accept the following query parameters: | Param | Type | Default | Description | | -------- | ------- | ------- | ----------------------------------- | | `limit` | integer | 100 | Max items to return. Capped at 500. | | `offset` | integer | 0 | Number of items to skip. | ## Example Request ``` GET /dexpal/v1/rewards?from=2026-02-01T00:00:00Z&to=2026-02-01T23:59:59Z&limit=500&offset=0 ``` # Error All errors return a consistent envelope with `success: false`. ## Schema ```json { "success": false, "error": "Human-readable description of the error" } ``` ## HTTP Status Codes | Status | When | | --------------------------- | ---------------------------------------------- | | `400 Bad Request` | Missing or invalid query parameters | | `401 Unauthorized` | Missing or invalid API key | | `404 Not Found` | Resource does not exist (e.g. unknown address) | | `429 Too Many Requests` | Rate limit exceeded | | `500 Internal Server Error` | Unexpected server-side error | ## Examples ```json // 400 { "success": false, "error": "Missing required parameter: addr" } ``` ```json // 401 { "success": false, "error": "Invalid or missing API key" } ``` ```json // 429 { "success": false, "error": "Rate limit exceeded. Try again in 30 seconds." } ``` ## Notes * Never return a `200` status with `success: false`. Use the appropriate HTTP status code. * Do not expose internal stack traces or implementation details in the `error` field.