Skip to content
First Access Exchange

Indexer API

The indexer is dYdX's own indexer (ender, comlink, socks, vulcan, roundtable), forked at the chain's upstream commit and extended for chain markets. It reads a full node's stream of on-chain and off-chain events (every fill, every order, short-term orders included) into Postgres and Redis and serves them:

APIBasePages
HTTP (comlink)https://indexer.testnet.firstaccess.exchange/v4HTTP API
WebSocket (socks)wss://indexer.testnet.firstaccess.exchange/v4/wsWebSocket API

Paths, parameters and responses are dYdX's, so dYdX's indexer clients (IndexerClient and SocketClient in @dydxprotocol/v4-client-js, IndexerClient and IndexerSocket in dydx-v4-client) work against it with the base URL changed (endpoints).

Use the indexer for what the node doesn't keep or show: the full order book (short-term orders are only in validators' memory), trades, candles, fills, orders with their statuses, entry prices and PnL, transfers, funding payments, and live updates. Use the node for anything a transaction depends on (balances and sequences before signing, the index, S, chain-market parameters).

Any origin may call the HTTP API from a browser (CORS *); only GET, HEAD and OPTIONS reach it. Some of dYdX's routes are present but empty or meaningless on this chain: affiliates, trading rewards, leaderboards, social trading. There is no address screening and no geoblocking: no address is ever blocked, and dYdX's screening routes (/compliance/..., /screen) answer 404, as do its Turnkey and Skip bridge routes (/bridging/...; use the bridge instead), its Turnkey sign-in (/turnkey/...), trader search (/trader/...) and vaults and MegaVault (/vault/...; there are no vaults). A path must be sent plain: one with %-escapes, . or .. segments or // answers 404.

Chain markets in the indexer

Every chain market is listed in GET /v4/perpetualMarkets, and in the v4_markets channel, like an isolated perpetual, with one more field, chainMarket. It is absent for an ordinary perpetual.

chainMarket?: {
  kind: 'BINARY' | 'CALL' | 'PUT' | 'PERP';
  eventId: number | null;    // binaries and options: the IPO event
  companyId: number | null;  // company perpetuals and company expiries
  strike: string | null;     // CALL and PUT: K in $B
  deadline: string | null;   // event markets: RFC 3339
  status: string;            // the x/binary market's, or for a PERP the company's, status
  settlementPrice: string | null; // what one contract settled at, in dollars, once known
}
Field
kindPERP (a private company's perpetual), BINARY (a Yes share paying $1 or $0), CALL, PUT (on the IPO-day closing market cap)
eventIdThe IPO event a binary, call or put belongs to (/dydxprotocol/binary/event/{id} on the node); null for a company perpetual and a standalone binary
companyIdThe company of a perpetual, or of the expiry a binary, call or put belongs to (/dydxprotocol/binary/company/{id}); null otherwise
strikeA call's or put's strike in $B, which is also dollars a contract, as a decimal string ("50", "37.5"); null for the others
deadlineA binary's, call's or put's resolution time (RFC 3339, UTC); null for a company perpetual
statusA binary, call or put: the x/binary market's TRADING, HALTED, RESOLVING, RESOLVED_YES or RESOLVED_NO. A company perpetual: its company's ACTIVE, HALTED_IPO, SETTLING, SETTLED or PENDING_GOVERNANCE
settlementPriceWhat one contract settles at, in dollars, from RESOLVING on: a binary "1" or "0", a call or put its payout, a company perpetual its settlement value u; null before

chainMarket changes in the block the market's status changes: the chain sends the indexer an event when a market is listed and whenever its status changes. In v4_markets the change arrives as an update of that market carrying only chainMarket: {"trading": {"TESTCOPERP-USD": {"chainMarket": {...}}}}.

Every other field keeps dYdX's meaning:

FieldOn a chain market
tickerTESTCOPERP-USD, TESTCOY2711C50-USD, ...
oraclePriceThe chain's oracle price, in dollars a contract: I for a PERP, the mark for a call, the last trade for a binary or put (from its listing, its starting price). A binary's and a put's stops trigger on another price (stop orders)
marketTypeISOLATED
atomicResolution, quantumConversionExponent0 and 0
stepBaseQuantums, stepSize1, "1": whole contracts
subticksPerTick, tickSize10,000 and "0.01"; on a binary 1,000 and "0.001"
initialMarginFraction, maintenanceMarginFractionFrom the reserved tier: "0.5" and "0.3" for a PERP; "1" and "1" for binaries and puts (fully backed); "0.2" and "0.16" for calls, which a call doesn't use: a short call's requirement is its own rule (margin)
nextFundingRateThe company perpetual's next rate; 0 for binaries and options
statusdYdX's book status (ACTIVE, FINAL_SETTLEMENT once halted); the chain market's own status is chainMarket.status

Example

const INDEXER = 'https://indexer.testnet.firstaccess.exchange';
const { markets } = await (await fetch(`${INDEXER}/v4/perpetualMarkets`)).json();
for (const m of Object.values<any>(markets)) {
  if (m.chainMarket?.kind === 'PERP') console.log(m.ticker, m.oraclePrice, m.nextFundingRate, m.chainMarket.status);
}

What the chain sends the indexer

Every change the chain makes to USDC or positions reaches the indexer through dYdX's own indexer events (subaccount updates, market price updates, funding updates, transfers, and fills where they are fills), so the indexer's balances and positions equal the chain's: settlement payouts, insurance seeding, the index and S as oracle prices, and the chain's funding.

How the changes that aren't trades appear:

  • Settlement. When a market resolves, the chain closes its positions, not by trades: there is no fill and no transfer. In /v4/perpetualPositions the position becomes CLOSED; the contracts it held close at what the chain actually paid for them, so exitPrice, sumClose and realizedPnl include the payout. That is the market's settlementPrice unless the payout was cut: a call whose writers couldn't pay what it owed pays less (a haircut), a company perpetual's payout can be withheld in part when its insurance funds fall short, and a short pays what it had if that is less than it owed. exitPrice is never below 0 (a long the withholding took more from than it was worth shows 0; realizedPnl has the loss). The USDC moves into the subaccount's assetPositions, and equity and /v4/historical-pnl follow. On v4_subaccounts it arrives as a perpetualPositions and assetPositions update; a position paid out in the block its market starts resolving arrives twice in that block, first CLOSED without the settlement, then with it: keep the last.
  • Funding on a company perpetual: /v4/historicalFunding has the rates the chain applied (within the company's bound); /v4/fundingPayments and the subaccount's USDC carry the payments. nextFundingRate is dYdX's estimate from this hour's samples, not yet clamped to the company's bound. Binaries, calls and puts pay no funding.
  • Chain prices (I, the marks, the binaries' and puts' last trades) arrive as oracle price updates, at most one per market a block, in v4_markets' oraclePrices.
  • Deposits, withdrawals and transfers between wallets and subaccounts (x/sending) are in /v4/transfers as dYdX's are. IBC transfers of the bridge move wallet balances only, which the indexer doesn't track: read them from the node.

Rate limits

dYdX's defaults, per client IP, over 10-second windows: 100 requests for most routes (orders, fills, positions, PnL, funding payments, sparklines each have their own budget of 100), 1,000 for candles. Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (epoch milliseconds); a 429 carries Retry-After in milliseconds. A page beyond the first costs more: 1 + ⌊(page − 1) × limit / 1,000⌋ points.

The WebSocket allows 2 subscribe messages a second per channel and id, 2 invalid messages a second, and per connection 256 subaccount subscriptions and 32 each of markets, order books, trades and candles. A connection over its limit is closed with code 1008.

The testnet keeps dYdX's limits, and its edge adds two per client address: 20 HTTP requests a second (bursts of 40, then 429) and at most 20 open WebSockets.

Known gaps

These are dYdX's indexer's own behaviour, unchanged here; read around them.

  • Realized PnL on a flip. A fill that turns a position to the other side (long 5, sell 8) closes the old position without realizing its closing part: the old position's realizedPnl misses (fill price − entry) × its size (the opposite for a short), and its sumClose and exitPrice cover its earlier closes only. The new position's realizedPnl starts at the old one's (summing realizedPnl over positions counts it twice), and its sumOpen and entryPrice count the whole fill as an opening (8 for a size of 3), so if it adds at other prices its entry price and PnL are off by (closing part) × (entryPrice − fill price). /v4/tradeHistory gets flips right.
  • Settlements aren't trades. A position the chain closes by settlement has no fill, so it is in neither /v4/fills nor /v4/tradeHistory; /v4/perpetualPositions, assetPositions, equity and /v4/historical-pnl have it.
  • Subscriptions and the HTTP limit. The WebSocket fetches each subscription's first message from the HTTP API itself, so the HTTP API's per-address limit doesn't count subscriptions; the WebSocket's own limits do.
  • Shared addresses. Every limit is per client IP address, so users behind one carrier address (most phones) share them.
  • Generated names. /v4/affiliates/metadata gives every address dYdX's generated referral code, publicly.
  • Node 16. The indexer's services run on Node 16, dYdX's version, past its end of life.