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:
| API | Base | Pages |
|---|---|---|
| HTTP (comlink) | https://indexer.testnet.firstaccess.exchange/v4 | HTTP API |
| WebSocket (socks) | wss://indexer.testnet.firstaccess.exchange/v4/ws | WebSocket 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 | |
|---|---|
kind | PERP (a private company's perpetual), BINARY (a Yes share paying $1 or $0), CALL, PUT (on the IPO-day closing market cap) |
eventId | The 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 |
companyId | The company of a perpetual, or of the expiry a binary, call or put belongs to (/dydxprotocol/binary/company/{id}); null otherwise |
strike | A 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 |
deadline | A binary's, call's or put's resolution time (RFC 3339, UTC); null for a company perpetual |
status | A 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 |
settlementPrice | What 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:
| Field | On a chain market |
|---|---|
ticker | TESTCOPERP-USD, TESTCOY2711C50-USD, ... |
oraclePrice | The 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) |
marketType | ISOLATED |
atomicResolution, quantumConversionExponent | 0 and 0 |
stepBaseQuantums, stepSize | 1, "1": whole contracts |
subticksPerTick, tickSize | 10,000 and "0.01"; on a binary 1,000 and "0.001" |
initialMarginFraction, maintenanceMarginFraction | From 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) |
nextFundingRate | The company perpetual's next rate; 0 for binaries and options |
status | dYdX'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);
}import httpx
INDEXER = "https://indexer.testnet.firstaccess.exchange"
markets = httpx.get(f"{INDEXER}/v4/perpetualMarkets").json()["markets"]
for m in markets.values():
cm = m.get("chainMarket")
if cm and cm["kind"] == "PERP":
print(m["ticker"], m["oraclePrice"], m["nextFundingRate"], cm["status"])curl -s https://indexer.testnet.firstaccess.exchange/v4/perpetualMarkets
curl -s 'https://indexer.testnet.firstaccess.exchange/v4/perpetualMarkets?ticker=TESTCOPERP-USD'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/perpetualPositionsthe position becomesCLOSED; the contracts it held close at what the chain actually paid for them, soexitPrice,sumCloseandrealizedPnlinclude the payout. That is the market'ssettlementPriceunless 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.exitPriceis never below 0 (a long the withholding took more from than it was worth shows 0;realizedPnlhas the loss). The USDC moves into the subaccount'sassetPositions, and equity and/v4/historical-pnlfollow. Onv4_subaccountsit arrives as aperpetualPositionsandassetPositionsupdate; a position paid out in the block its market starts resolving arrives twice in that block, firstCLOSEDwithout the settlement, then with it: keep the last. - Funding on a company perpetual:
/v4/historicalFundinghas the rates the chain applied (within the company's bound);/v4/fundingPaymentsand the subaccount's USDC carry the payments.nextFundingRateis 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/transfersas 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
realizedPnlmisses (fill price − entry) × its size (the opposite for a short), and itssumCloseandexitPricecover its earlier closes only. The new position'srealizedPnlstarts at the old one's (summingrealizedPnlover positions counts it twice), and itssumOpenandentryPricecount 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/tradeHistorygets flips right. - Settlements aren't trades. A position the chain closes by settlement has no fill, so it is
in neither
/v4/fillsnor/v4/tradeHistory;/v4/perpetualPositions,assetPositions, equity and/v4/historical-pnlhave 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/metadatagives 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.