canonical: https://jentic.com/apis/dydx.exchange/dydx

# Dydx Exchange dYdX Indexer API

Jentic publishes the only available OpenAPI specification for the dYdX Indexer API, keeping it validated and agent-ready. The dYdX Indexer is the read-only REST surface for the dYdX v4 decentralized perpetual exchange, exposing market data, order books, candles, account positions, fills, funding payments, historical PnL, and trading rewards across subaccounts and parent subaccounts. The API is unauthenticated for read access - it serves indexed chain data so trading bots, dashboards, and agents can query state on the dYdX chain without running a node.

## For AI agents

Query dYdX v4 perpetual market data, account positions, orders, fills, funding payments, and trading rewards over a public REST surface so agents can monitor or analyse on-chain trading without a node.

## Scope

Does not place orders, sign transactions, or hold custody of funds - use for reading dYdX v4 chain-indexed market and account data only.

## Capabilities

- Fetch live order books and candles for any perpetual market by ticker
- List perpetual markets and their current configuration and status
- Retrieve subaccount and parent subaccount balances and asset positions for an address
- List orders and fills filtered by address, subaccount, market, or status
- Query historical PnL, funding payments, and trading reward aggregations for an address
- Look up affiliate metadata, snapshots, and total volume by referral code
- Run a compliance screen against an address to check sanctions or restriction status

## Use cases

### Trading Bot Market Data Feed

An algorithmic trading bot pulls candles and order book snapshots from the Indexer to drive a signal model, then queries its own subaccount fills and positions to reconcile orders placed via the on-chain validator. Because the Indexer aggregates chain state, the bot avoids running a full dYdX node and can scale read traffic independently of execution.

Example prompt: GET `/candles/perpetualMarkets/ETH-USD` with 1HOUR resolution and GET `/orderbooks/perpetualMarket/ETH-USD`, then merge into the bot's local market state

### Portfolio Dashboard for dYdX Traders

A portfolio tool reads positions, asset balances, fills, and historical PnL for a wallet's subaccounts and renders an aggregated view across markets. The `/historical-pnl/parentSubaccountNumber` and `/assetPositions/parentSubaccountNumber` endpoints roll subaccounts up by parent so multi-account traders see one total without per-subaccount stitching.

Example prompt: GET `/addresses/{address}/parentSubaccountNumber/0` followed by `/historical-pnl/parentSubaccountNumber` and `/assetPositions/parentSubaccountNumber` to assemble a parent-level PnL view

### Trading Rewards and Funding Reconciliation

An accounting workflow pulls funding payments and historical block trading reward aggregations for an address to reconcile expected vs received rewards across epochs. The Indexer exposes these as paginated endpoints keyed by address, so a job can backfill all epochs without reading the chain directly.

Example prompt: GET `/historicalBlockTradingRewards/{address}` and /fundingPayments?address={address} for the past 30 days and store both for reconciliation

### Agent-Driven Market Lookups via Jentic

An AI agent answering a user question like 'what's my current PnL on dYdX' calls the Indexer through Jentic. The agent searches Jentic for 'get historical PnL for a dYdX subaccount', loads the input schema, and executes /historical-pnl with the user's address - no wallet keys are involved because the API is read-only.

Example prompt: Use Jentic to search 'get the order book for a dYdX perpetual market', load the operation, and execute it for ticker BTC-USD

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/perpetualMarkets` | List all perpetual markets |
| GET | `/orderbooks/perpetualMarket/{ticker}` | Fetch the order book for a perpetual market |
| GET | `/candles/perpetualMarkets/{ticker}` | Fetch candles for a perpetual market |
| GET | `/addresses/{address}/subaccountNumber/{subaccountNumber}` | Get a subaccount for an address |
| GET | `/fills` | List fills filtered by subaccount and market |
| GET | `/orders` | List orders for a subaccount |
| GET | `/historical-pnl` | Retrieve historical PnL for a subaccount |
| GET | `/compliance/screen/{address}` | Screen an address for compliance |

## Key resources

- **Perpetual Markets** — List markets, fetch candles, and read order books for v4 perpetuals
- **Subaccounts and Addresses** — Look up subaccount, parent subaccount, asset position, and historical PnL data for a wallet address
- **Orders and Fills** — List orders by status and fills by subaccount or parent subaccount, including individual order lookup by ID
- **Funding and Rewards** — Retrieve historical funding rates, funding payments, and block trading reward aggregations
- **Affiliates** — Query affiliate metadata, snapshots, total volume, and update referral codes
- **Compliance** — Screen an address for sanctions or jurisdictional restrictions before allowing trading actions

## Why Jentic

- **Setup:** The dYdX Indexer API needs no auth, but wiring it still means building each market and account query, handling pagination, and centralising rate-limit retries yourself. Through Jentic you install once, import the dYdX Indexer from the API Directory, and your agent calls it.
- **Permission scoping:** The Indexer is read-only and puts the wallet address in the URL path (`/addresses/{address}/...`), so a rule can pin your agent to reading data for one address. You choose the read operations it may call, so account queries are not included unless you add them.
- **Credential handling:** The Indexer requires no credentials, so there is nothing to store. Jentic still mediates the call through your own Jentic One instance, applying usage policy and centralising rate-limit handling.
- **Discovery method:** Agents search Jentic by intent such as 'get historical PnL for a dYdX subaccount' or 'read a perpetual market orderbook', and Jentic returns the matching Indexer operation with its input schema and pagination shape so the agent calls the right endpoint without browsing the docs.

## Related APIs

- **Dux-Soup LinkedIn Activity API** — Unrelated automation surface; included only as cross-domain reference - not a finance alternative
- **Visma e-conomic API** — Pair with dYdX trading data to record realised PnL into accounting ledgers
- **dweet.io** — Lightweight publish/listen layer for streaming derived metrics from dYdX reads to a dashboard

## FAQ

### Why is there no official OpenAPI spec for the dYdX Indexer API?

dYdX does not publish an OpenAPI specification for the v4 Indexer. Jentic generates and maintains this spec so that AI agents and developers can call the dYdX Indexer API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the dYdX Indexer API use?

The Indexer is fully read-only and unauthenticated - no API key or signed request is required for any endpoint, including subaccount and PnL queries. Trading actions on dYdX v4 are submitted to validators with on-chain signatures and are not part of this Indexer API.

### Can I place orders with the dYdX Indexer API?

No. The Indexer only reads chain state - to place or cancel orders you must broadcast signed transactions to the dYdX v4 validator network using the dYdX client libraries. Use endpoints like GET /orders and GET `/orders/{orderId}` on the Indexer to confirm the status of orders submitted that way.

### What are the rate limits for the dYdX Indexer API?

The OpenAPI spec does not declare a numeric rate limit. The public dYdX-hosted Indexer at indexer.dydx.trade applies fair-use throttling per IP - high-volume traders typically run their own Indexer instance to avoid hitting limits.

### How do I fetch dYdX market data through Jentic?

Run pip install jentic, search for 'get the order book for a dYdX perpetual market', load the operation for GET `/orderbooks/perpetualMarket/{ticker}`, then execute it with the ticker (for example ETH-USD) as the path parameter. No credentials are required because the Indexer is open.

### Does the dYdX Indexer return websocket data?

This OpenAPI spec only documents the REST surface (49 endpoints). dYdX also exposes a websocket channel for live order book and trade updates, but it is not part of this REST API - use the REST endpoints listed here for snapshot reads and reconciliation.

### Can I limit what my agent is allowed to do with the dYdX Indexer API?

Yes. Because you run Jentic One yourself, your own rules decide which Indexer operations the agent may call, so you can expose only the reads you want, such as GET `/orderbooks/perpetualMarket/{ticker}` and GET `/candles/perpetualMarkets/{ticker}`, while withholding account calls like GET /historical-pnl or `/addresses/{address}/subaccountNumber/{subaccountNumber}.` Since the Indexer puts the wallet address in the URL path, you can also pin the agent to reading data for a single address. The API is read-only and holds no credentials, so nothing about your rules ever lets the agent place orders or move funds.