dydx-agent-gateway

dYdX Agent Gateway

One MCP server that gives any AI agent analytics access to dYdX v4: market data, funding analytics, verified trader PnL, leaderboards, anomaly detection. Read-only and keyless — the gateway holds no keys and cannot move funds.

Use cases

• Verify a trader before you copy them — deposit-adjusted PnL, day winrate, drawdown in USD, and phantom-PnL detection that flags unreliable equity curves
• Hunt funding and OI anomalies — funding heatmap ranked by |rate| with OI context, OI-spike-without-price detectors, liquidation-cascade alerts
• Find real smart money — verified leaderboard from on-chain trader discovery, farmer-bot flags so you don't copy a rewards farmer
• Check the book before entering — one-call market digest: latest anomaly events + funding extremes + leaderboard top
• Plan the exit while you plan the entry — ATR-based stop/take-profit/ breakeven/trailing plan per side

Full walkthroughs with real outputs: examples/use-cases.md.

Install

Claude Code:

claude mcp add dydx -- uvx dydx-agent-gateway

Claude Desktop / Cursor / any mcp.json:

{"mcpServers": {"dydx": {
  "command": "uvx",
  "args": ["dydx-agent-gateway"]}}}

Codex (~/.codex/config.toml)

[mcp_servers.dydx]
command = "uvx"
args = ["dydx-agent-gateway"]

ZCode — register the server and copy the agent skill (copy-paste)

# 1) start the gateway (keep it running)
uvx dydx-agent-gateway --http --port 8901 &

# 2) register it (merges into ~/.zcode/cli/config.json; workspace .zcode/config.json works too)
python3 - <<'PY'
import json, os
p = os.path.expanduser("~/.zcode/cli/config.json")
os.makedirs(os.path.dirname(p), exist_ok=True)
cfg = json.load(open(p)) if os.path.exists(p) else {}
cfg.setdefault("mcp", {}).setdefault("servers", {})["dydx"] = {
    "type": "http", "url": "http://127.0.0.1:8901/mcp"}
json.dump(cfg, open(p, "w"), indent=2)
print("dydx MCP server registered:", p)
PY

# 3) copy the agent skill (tool guide + data gotchas)
git clone -q --depth 1 https://github.com/alekskram/dydx-agent-gateway /tmp/dag
cp -r /tmp/dag/.agents/skills/dydx-gateway ~/.zcode/skills/ && rm -rf /tmp/dag
echo "ZCode setup done — restart your session and call any dydx tool"

Plain Python:

pip install dydx-agent-gateway
python -c "from dydx_mcp import server; import json; print(json.dumps(server.market_digest(), default=str)[:400])"

Hosted (streamable HTTP): dydx-agent-gateway --http --port 8901, then any client:

{"mcpServers": {"dydx": {"type": "http", "url": "http://host:8901/mcp"}}}

Requires Python ≥ 3.11. Deps (fastmcp, pycryptodome, ecdsa) install automatically. See examples/ for ready-made configs and a working autonomous agent script.

Tools (22 — read-only, keyless)

Group	Tools
Market data	list_markets, market_detail, candles, recent_trades, height, historical_funding
Analytics	funding_heatmap, market_ta, suggest_stops, cvd, correlation
Traders	trader_profile, trader_pnl_stats, fills_review, raw_fills
Discovery	discover_traders, leaderboard, list_traders, registry_stats
Signals	latest_events (funding extremes, OI spikes, liquidation cascades, equity jumps)
Briefing	market_digest — one call: events + funding + leaderboard top. Start here.
Meta	usage_stats — tool-call counters (traction/uptime of your instance)

Real outputs of every tool: examples/tool-output.md.

Solving real trader problems — 5 scenarios with live data: examples/use-cases.md.

What makes it different

• Verified trader PnL. trader_pnl_stats reconciles the identity equity-Δ = Δpnl + ΣnetTransfers on every account — residual ≠ 0 means the numbers lie. Live-checked on real accounts to $0.0000 (see reports/qa-logic.md). Deposit-adjusted maxDD, day-winrate, sharpe-like.
• Anomaly detectors, not dashboards. Funding extremes, OI spikes without price, equity jumps, and a liquidation-cascade signature (|Δprice|↑ + OI↓) — the patterns that matter before they're charts. Live catches in reports/.
• Analyst pack. Funding-rate history, CVD, cross-market correlation, raw fills for execution analysis; TA enrichments MACD/VWAP/realized vol; sortino-like downside risk.
• Data-quality discipline. Five documented indexer API gotchas (.agents/skills/dydx-gateway/references/data-gotchas.md) that silently corrupt naive analytics. 129 tests, CI on 3.11/3.13.

Why a gateway and not the raw indexer API?

You can point an agent at indexer.dydx.trade directly — and then rebuild, one by one, what this gateway already handles:

Raw indexer gives you	You would have to build
paginated endpoints (≤1000/req)	per-endpoint pagination logic
a funding endpoint that intermittently returns EMPTY or rpc-times out	retry + cached-series fallback
per-bucket (non-cumulative) netTransfers, newest-first PnL, an unreliable priceChange24H field	reconciliation math — this gateway verifies the identity equity-Δ = Δpnl + ΣnetTransfers per account (phantom-PnL detection)
raw candles and trades	anomaly detectors (funding extremes, OI spikes without price, liquidation-cascade signature), a TA pack (RSI/MACD/ATR/Bollinger/VWAP), CVD, cross-market correlation, ATR-based stop plans
address strings in blocks	a validated bech32 trader registry with farmer-bot flags and verified leaderboard

The five documented indexer gotchas: .agents/skills/dydx-gateway/references/data-gotchas.md.

Data notes

Indicators are computed over the current candle window and change with every new bar. nextFundingRate is the exchange's live preview and is recomputed continuously; volume24H is a rolling window. Two calls moments apart legitimately differ.

Safety model

All tools are read-only and keyless. The gateway signs nothing and holds no credentials. An offline-tested EIP-712 signer remains in dydx_mcp/signer.py as a library for anyone building their own execution layer — it is wired to no MCP tool.

FAQ

• Does it trade? No. Analytics only, by design.
• API keys? None. Everything runs on public indexer endpoints.
• Rate limits? Public endpoints, no auth; a 60s markets cache keeps you polite.
• How do I verify a trader before copying them? trader_profile → trader_pnl_stats → fills_review — check the identity residual and maker/taker mix first.

Part of the suite

Four sibling read-only MCP gateways, one style — keyless, cached, honest degradation:

Gateway	Focus
dydx-agent-gateway (you are here)	dYdX v4: verified trader PnL, funding/OI anomaly detectors, leaderboard
arcus-agent-gateway	194 tokenized US equities on Robinhood Chain: quotes, holders, whale transfers
hyperliquid-agent-gateway	Hyperliquid: 233 perps + spot, funding carry, account risk, HyperEVM
aster-agent-gateway	Aster DEX: ~580 futures incl. 24/7 TradFi perps, funding caps/floors

All four are on glama.ai and PyPI — install any of them with uvx <name>.

License

MIT. Not affiliated with dYdX Trading Inc.