dydx-agent-gateway

# dYdX Agent Gateway

<!-- mcp-name: io.github.alekskram/dydx-agent-gateway -->

[![tests](https://github.com/alekskram/dydx-agent-gateway/actions/workflows/tests.yml/badge.svg)](https://github.com/alekskram/dydx-agent-gateway/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/dydx-agent-gateway.svg)](https://pypi.org/project/dydx-agent-gateway/)
[![PyPI downloads](https://img.shields.io/pypi/dm/dydx-agent-gateway?label=downloads)](https://pypi.org/project/dydx-agent-gateway/)
[![MCP Catalog](https://img.shields.io/badge/MCP_Catalog-glama.ai-4f46e5)](https://glama.ai/mcp/servers/alekskram/dydx-agent-gateway)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

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](examples/use-cases.md).

## Install

**Claude Code:**
```bash
claude mcp add dydx -- uvx dydx-agent-gateway
```

**Claude Desktop / Cursor / any mcp.json:**
```json
{"mcpServers": {"dydx": {
  "command": "uvx",
  "args": ["dydx-agent-gateway"]}}}
```

<details>
<summary><b>Codex</b> (~/.codex/config.toml)</summary>

```toml
[mcp_servers.dydx]
command = "uvx"
args = ["dydx-agent-gateway"]
```
</details>

<details>
<summary><b>ZCode</b> — register the server and copy the agent skill (copy-paste)</summary>

```bash
# 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"
```
</details>

**Plain Python:**
```bash
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:
```json
{"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`](examples/tool-output.md).

**Solving real trader problems** — 5 scenarios with live data: [`examples/use-cases.md`](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](https://github.com/alekskram/arcus-agent-gateway) | 194 tokenized US equities on Robinhood Chain: quotes, holders, whale transfers |
| [hyperliquid-agent-gateway](https://github.com/alekskram/hyperliquid-agent-gateway) | Hyperliquid: 233 perps + spot, funding carry, account risk, HyperEVM |
| [aster-agent-gateway](https://github.com/alekskram/aster-agent-gateway) | Aster DEX: ~580 futures incl. 24/7 TradFi perps, funding caps/floors |

All four are on [glama.ai](https://glama.ai/mcp/servers/alekskram/dydx-agent-gateway) and PyPI — install any of them with `uvx <name>`.

## License

MIT. Not affiliated with dYdX Trading Inc.