dydx-agent-gateway 0.3.0__tar.gz

dydx_agent_gateway-0.3.0/.agents/skills/dydx-gateway/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: dydx-gateway
+description: "Use when the user asks about anything dYdX — markets, prices, funding, OI, volumes, perps — or mentions a perp trader address to vet (equity, PnL curve, day-winrate, maxDD, farmer flag), funding/OI anomalies, liquidation cascades, leaderboards, or wants TA and ATR-based stop plans. Provides dYdX v4 perps analytics via a local read-only MCP gateway: market data, funding heatmap, verified trader PnL, leaderboards, OI and liquidation-cascade anomaly detection."
+when_to_use: "Use for any dYdX questions — markets, prices, funding, OI, volumes; anomalies (OI spikes without price movement, liquidation cascades, extreme funding, trader equity jumps); trader analysis by address (equity, PnL curve, day-winrate, maxDD, farmer flag) before copy-trading; leaderboard and onchain trader screening; TA and ATR-based stop plans. Trigger words: dYdX, perps, funding, OI anomaly, trader PnL, vet this trader, liquidation cascade."
+metadata:
+  version: "0.3.0"
+  agent:
+    requires:
+      bins: ["python3"]
+---
+
+# dYdX Agent Gateway (local MCP server)
+
+The gateway is deployed on this host, endpoint **http://127.0.0.1:8901/mcp**
+(streamable HTTP, systemd unit `dydx-mcp.service`; check with
+`systemctl is-active dydx-mcp`). The code lives at the repository root
+of https://github.com/alekskram/dydx-agent-gateway
+(the skill's source is `.agents/skills/dydx-gateway/`; after edits,
+copy it to `~/.zcode/skills/dydx-gateway/`). If the gateway is not
+running, start it per the repo README Install section
+(`uvx --from git+https://github.com/alekskram/dydx-agent-gateway
+dydx-agent-gateway --http --port 8901`).
+
+Background data: the block scanner (`dydx-scanner`, the address registry
+keeps growing), detectors every 5 min (`dydx-detectors.timer`),
+leaderboard every 6 h (`dydx-leaderboard.timer`), watchdog report on the
+1st of each month.
+
+## MCP tools (22)
+
+Data: `list_markets`, `market_detail`, `candles`, `recent_trades`, `height`
+· Analytics: `funding_heatmap(min_oi_usd)`, `historical_funding(limit≤500)`,
+`market_ta`, `suggest_stops`, `trader_profile`,
+`trader_pnl_stats(limit≤5000)`, `fills_review`, `raw_fills(limit≤200)`,
+`cvd(trades_limit)`, `correlation(ticker_a, ticker_b)`
+· Discovery: `market_digest` (one-call briefing — start here),
+`leaderboard`, `discover_traders`, `list_traders`, `registry_stats`,
+`latest_events`, `usage_stats`
+
+## Quick path without an MCP client
+
+```bash
+cd <repo root> && python -c "
+import sys; sys.path.insert(0,'.')
+from dydx_mcp import server as s
+import json; print(json.dumps(s.market_digest(), indent=1, default=str)[:800])"
+```
+
+Full-blown connections (stdio / Claude Desktop, Codex, Cursor configs):
+`examples/` in the repo.
+
+## Important data caveats
+
+Read `references/data-gotchas.md` (5 documented indexer-API gotchas:
+candle ordering, netTransfers, priceChange24H, subticksPerTick, no
+liquidation feed). Rule of thumb: funding without an OI ≥ $100k filter
+is noise.
+
+## Where to look next
+
+- Reports: `reports/` (monthly data-quality watchdog, digests)

dydx_agent_gateway-0.3.0/.agents/skills/dydx-gateway/references/data-gotchas.md

@@ -0,0 +1,33 @@
+# dYdX indexer API — documented gotchas (found by our watchdog)
+
+Five non-obvious behaviors of indexer.dydx.trade that make naive
+clients lie (each caught on live data and covered by gateway tests):
+
+1. **Candles and historical-pnl arrive newest-first** (newest entries
+   first). A consumer expecting chronology inverts the sign of
+   ΔOI/Δprice and the TA trend. Our API layer normalizes this (sorting
+   by startedAt). Example damage: a signal reading "OI shrank −8.9%"
+   was in fact +9.7% growth.
+
+2. **`netTransfers` in historical-pnl is a flow for the period between
+   points, NOT cumulative.** A running sum is required. Without it, the
+   deposit-adjusted drawdown of a reference market maker looks like
+   79.5% instead of the real 11.9% (a 67 pp phantom gap).
+
+3. **`priceChange24H` in perpetualMarkets does not match the actual 24h
+   price change** (verified against ETH/BTC candles). Compute it
+   yourself: close[-1]/close[-25] over 1H candles.
+
+4. **The price subticks field is called `subticksPerTick`** (not
+   subticksPerBase): price_subticks = price / tickSize × subticksPerTick.
+   For ETH (tick 0.1, spt 100000) — price×10^6.
+
+5. **There is no public liquidations feed** (several candidate paths
+   return 404). Cascades are caught by a candle signature: |Δprice|↑
+   together with OI↓ (2 stages: fresh_2h on 5-min candles,
+   confirmed_6h on hourly).
+
+Plus: **extreme funding on markets with OI < $100k is noise**
+(example: CRO "+2967% annualized" at $4.5k OI). Always filter by OI.
+
+Current version: reports/data-quality-2026-08.md in the gateway repo.

dydx_agent_gateway-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - name: GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

dydx_agent_gateway-0.3.0/.github/workflows/tests.yml

@@ -0,0 +1,27 @@
+name: tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  offline:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - name: Run tests
+        run: |
+          pytest tests/ -q --cov=dydx_mcp --tb=short > pytest_output.txt 2>&1 || FAILED=1
+          grep -E "^(FAILED|ERROR)|Error|error" pytest_output.txt | head -25 | while IFS= read -r line; do
+            echo "::error::${line:0:250}"
+          done
+          tail -40 pytest_output.txt
+          exit ${FAILED:-0}

dydx_agent_gateway-0.3.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.pyc
+data/*.sqlite
+data/*.sqlite-wal
+data/*.sqlite-shm
+alerts.env
+*.log
+.coverage
+
+# internal documents (not for publication)
+PLAN.md
+dist/

dydx_agent_gateway-0.3.0/CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog
+
+## v0.3.0 (2026-09-03) — analyst pack
+- 4 new tools: `historical_funding` (raw 1h funding-rate series with
+  annualized rate = rate*24*365, ticker-guard), `cvd` (cumulative volume
+  delta from the trades tape: buy/sell by side, current CVD + series over
+  the window), `correlation` (Pearson r over log-returns of two tickers'
+  candles + beta(a|b)), `raw_fills` (raw fills of a trader for own
+  execution analysis; addresses from discover_traders/leaderboard).
+- Enrichments: `market_ta` + MACD(12,26,9) + VWAP(20, typical price x
+  volume) + realized_vol (annualized at candle resolution); `market_detail`
+  + basis_pct (mark deviation from oracle); `trader_pnl_stats` +
+  sortino_like_daily (downside deviation) next to the sharpe-like metric.
+- Fix: api historical_funding used a non-working query path (404) —
+  switched to the path form /historicalFunding/{ticker}.
+- Fix (live QA): correlation aligned the two candle series by index
+  tail; candle feeds are trade-driven and can differ by a bar, which
+  shifted one series and collapsed r (BTC/ETH 1h: 0.853 -> 0.033).
+  Now joined on startedAt (inner join). raw_fills prints
+  self-consistent price/size/usd_notional (6 significant digits).
+- Tests: +29 invariant (ta_ext) and regression tests per tool (mocked,
+  incl. ticker-guard cases) + shift-bug regression; plus an independent
+  numpy reference cross-check on randomized data
+  (tests/test_ta_ext_reference.py, tol 1e-9; author ≠ ta_ext author —
+  owner requirement).
+- Version bump 0.2.5 -> 0.3.0 (pyproject, FastMCP server, server.json);
+  numpy added to dev extras (reference cross-check; runtime stays stdlib).
+
+## v0.2.5 (2026-09-02) — logical-QA fixes (review/43, findings A1-A4)
+- A2 (bug, Medium): adaptive price precision in `suggest_stops` /
+  `market_ta` via `_fmt_price` — at least 6 significant digits (never fewer
+  decimals than before), so level geometry (SL < entry < TP) and ATR
+  multipliers hold in the printed JSON fields for sub-cent assets
+  (DOGE entry now prints 0.08148 with SL 0.08073, not 0.08 vs 0.0807).
+- A3 (semantics, Medium): `trader_pnl_stats` adds `max_drawdown_usd` (depth
+  of the same worst drawdown in USD) and `dd_pct_unreliable: true` when the
+  deposit-adjusted curve's running peak at the worst drawdown is near zero
+  (< $1 or < 1% of current equity) — the peak-relative
+  `max_drawdown_pct` exceeds 100% there and misleads (t3 case: 2711.54%);
+  thresholds per Researcher (review).
+- A1/A4 (docs): README "Data notes" — indicators recompute per candle
+  window; `nextFundingRate` is an exchange preview, `volume24H` a rolling
+  window.
+- Version bump 0.2.4 -> 0.2.5 (pyproject, FastMCP server, server.json).
+
+## v0.2.4 (2026-09-02) — pre-publication hardening (review)
+- Crash fixes (found in the review internal review, each with a regression test):
+  pnl_engine.compute no longer raises on None equity/totalPnl/netTransfers
+  fields (API nulls) or on a single history point (ZeroDivisionError in the
+  summary line); market_digest/leaderboard summaries no longer raise
+  TypeError on NULL pnl_window (rows from accounts with 'no pnl history').
+- api.markets() now filters FINAL_SETTLEMENT (settled) markets: 197 of 296
+  listings were dead but still leaked zero-volume rows into list_markets and
+  stale nonzero funding rates into funding_heatmap/detectors. Live markets
+  only (status == ACTIVE) by default.
+- server.json rebuilt against the official MCP Registry server schema
+  (2025-12-11): 0 validation errors — description <= 100 chars, name
+  `io.github.ventures/dydx-agent-gateway` placeholder (GitHub org pending),
+  registryType + transport{stdio} in the package, repository block added,
+  $schema URL fixed (old raw.githubusercontent URL was 404).
+- Demo numbers in README dated "as of 2026-08" (kept, not scrubbed,
+  by design decision).
+- Version bump 0.2.3 -> 0.2.4 (pyproject, FastMCP server, SKILL.md).
+
+## v0.2.1 (2026-08-25) — QA pass: full review and testing
+- Tests: pytest structure (49 offline + 5 online, online marker), dydx_mcp
+  coverage 75% (up from ~8% of functions); dev extras [dev]; CI workflow
+  ready.
+- 7 bugs found and fixed with regression tests: short keys in key_from_hex;
+  event dedup never expired (ts format); prune over-deletion; market_ta
+  crash on flat candles; equity_jumps connection leak; BOUNDARY DUPLICATES
+  in PnL pagination (live test); isError semantics for invalid tickers
+  (ValueError).
+- Chaos 4/4: restore drill, scanner SIGKILL idempotency (+23 = +23), load
+  test 20 clients / 0 errors, state survives force-reinstall.
+- QA report: reports/qa-report.md
+
+## v0.1.1 (2026-08-25)
+- `trader_pnl_stats(limit)` — agents get up to 5000 history points
+  (~7 months); default 1000 (~42 days, fast).
+- `market_digest` — one-call briefing: detector events + funding extremes
+  + leaderboard top.
+- `usage_stats` + tool-call accounting (middleware → sqlite) — traction
+  metrics for grant KPIs (calls/24h/7d, top tools).
+- `watchdog.py` + dydx-watchdog timer (1st of the month, 09:00) — the
+  data-quality report is generated automatically.
+- README: dydx-backup unit in the automation table, deploy-public.md link.
+- fastmcp banner disabled (stdio/HTTP).
+
+## v0.1.0 (2026-08-24)
+- 19 MCP tools: market data, analytics, leaderboard, events, screener.
+- PnL engine: deposit-adjusted curve, day-winrate, maxDD, identity check
+  (residual $0.00 on live data), history pagination up to 5000 points.
+- Block scanner → address registry (bech32 BIP-173, idempotent).
+- Detectors: funding_extreme, oi_spike_no_price, liq_cascade_signature
+  (validated on history: 47 signature hours/7d), equity_jump.
+- EIP-712 signer (Order, ApiCredentials; 12/12 selftests).
+- pip package (pyproject, console entry point), examples for Claude
+  Desktop/Codex/Cursor, skill, HTTP+stdio transports.
+- systemd: 5 units + hardening; WAL-safe backup (restore verified).
+- Tests: suite 15/15; 5 indexer API gotchas found and fixed.
+
+## v0.2.0 (2026-08-25) — skill and MCP standards
+- Skill rewritten to skill-creator standards: EN description with triggers
+  in the visible zone (~250 chars), when_to_use (detailed triggers),
+  metadata.agent.requires.bins; source of truth — .agents/skills/ in the
+  repo (discoverable root), self-contained (references/data-gotchas.md),
+  sync with ~/.zcode/skills documented.
+- MCP compliance: tool annotations (readOnlyHint/destructiveHint/
+  idempotentHint — 21 tools), server instructions (strategy for the
+  agent), /health endpoint (custom_route).
+- recent_traders → list_traders (SEP-986 distinctness from recent_trades).
+- server.json for the official MCP registry (reverse-DNS, draft).
+- deploy-public.md: origin/host validation, OAuth 2.1 note.
+
+## v0.2.3 — analytics-only release
+- Trading tools (place_order / cancel_all / my_positions) removed from the
+  MCP server by design decision: the public gateway is read-only analytics,
+  holds no keys, signs nothing. Signer stays as a library module (offline
+  selftest 12/12), unwired to any tool.
+- demo3_order_consent.py removed; docs (EN/RU README, examples, skill)
+  updated; tool count 21 -> 18.

dydx_agent_gateway-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dydx-agent-gateway contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dydx_agent_gateway-0.3.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: dydx-agent-gateway
+Version: 0.3.0
+Summary: MCP gateway for AI agents to dYdX v4: market data, funding heatmap, TA, verified trader analytics (deposit-adjusted PnL), leaderboards, anomaly & liquidation-cascade detectors. Analytics-only: no trading tools, no keys.
+Project-URL: Homepage, https://github.com/alekskram/dydx-agent-gateway
+Project-URL: Repository, https://github.com/alekskram/dydx-agent-gateway
+Project-URL: Issues, https://github.com/alekskram/dydx-agent-gateway/issues
+Project-URL: Changelog, https://github.com/alekskram/dydx-agent-gateway/blob/master/CHANGELOG.md
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,analytics,defi,dydx,mcp,perpetuals,trading
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: ecdsa>=0.18
+Requires-Dist: fastmcp>=3.0
+Requires-Dist: pycryptodome>=3.20
+Provides-Extra: dev
+Requires-Dist: numpy>=1.26; (python_version >= '3.11') and extra == 'dev'
+Requires-Dist: pip-audit; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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)
+[![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.
+
+## Install
+
+**Claude Code:**
+```bash
+claude mcp add dydx -- uvx --from git+https://github.com/alekskram/dydx-agent-gateway dydx-agent-gateway
+```
+
+**Cursor / any mcp.json:**
+```json
+{"mcpServers": {"dydx": {
+  "command": "uvx",
+  "args": ["--from", "git+https://github.com/alekskram/dydx-agent-gateway", "dydx-agent-gateway"]}}}
+```
+
+**Codex** (`~/.codex/config.toml`):
+```toml
+[mcp_servers.dydx]
+command = "uvx"
+args = ["--from", "git+https://github.com/alekskram/dydx-agent-gateway", "dydx-agent-gateway"]
+```
+
+**ZCode** — register the MCP server and copy the agent skill (all copy-paste):
+```bash
+# 1) start the gateway (keep it running)
+uvx --from git+https://github.com/alekskram/dydx-agent-gateway 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:**
+```bash
+pip install git+https://github.com/alekskram/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.** |
+
+Real outputs of every tool: [`examples/tool-output.md`](examples/tool-output.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.
+
+## 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.
+
+
+## License
+
+MIT. Not affiliated with dYdX Trading Inc.

dydx_agent_gateway-0.3.0/README.md

@@ -0,0 +1,104 @@
+# 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)
+[![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.
+
+## Install
+
+**Claude Code:**
+```bash
+claude mcp add dydx -- uvx --from git+https://github.com/alekskram/dydx-agent-gateway dydx-agent-gateway
+```
+
+**Cursor / any mcp.json:**
+```json
+{"mcpServers": {"dydx": {
+  "command": "uvx",
+  "args": ["--from", "git+https://github.com/alekskram/dydx-agent-gateway", "dydx-agent-gateway"]}}}
+```
+
+**Codex** (`~/.codex/config.toml`):
+```toml
+[mcp_servers.dydx]
+command = "uvx"
+args = ["--from", "git+https://github.com/alekskram/dydx-agent-gateway", "dydx-agent-gateway"]
+```
+
+**ZCode** — register the MCP server and copy the agent skill (all copy-paste):
+```bash
+# 1) start the gateway (keep it running)
+uvx --from git+https://github.com/alekskram/dydx-agent-gateway 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:**
+```bash
+pip install git+https://github.com/alekskram/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.** |
+
+Real outputs of every tool: [`examples/tool-output.md`](examples/tool-output.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.
+
+## 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.
+
+
+## License
+
+MIT. Not affiliated with dYdX Trading Inc.

dydx_agent_gateway-0.3.0/alerts.py

@@ -0,0 +1,68 @@
+"""Alerts: publish unpublished events to Telegram + registered webhooks.
+
+Env: DYDX_TG_BOT_TOKEN + DYDX_TG_CHAT_ID (Telegram),
+     DYDX_WEBHOOKS="https://a/hook,https://b/hook" (comma-separated).
+Without env set, events stay queued (published=0) — nothing is lost.
+"""
+import json
+import os
+import sys
+import urllib.request
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+from dydx_mcp import analytics  # noqa: E402
+
+
+def tg_send(text: str) -> bool:
+    tok, chat = os.environ.get("DYDX_TG_BOT_TOKEN"), os.environ.get("DYDX_TG_CHAT_ID")
+    if not (tok and chat):
+        return False
+    req = urllib.request.Request(
+        f"https://api.telegram.org/bot{tok}/sendMessage",
+        data=json.dumps({"chat_id": chat, "text": text[:4000]}).encode(),
+        headers={"Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=10) as r:
+            return r.status == 200
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def webhook_send(url: str, payload: dict) -> bool:
+    req = urllib.request.Request(url, data=json.dumps(payload).encode(),
+                                 headers={"Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req, timeout=10) as r:
+            return 200 <= r.status < 300
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def publish_all() -> int:
+    hooks = [u for u in os.environ.get("DYDX_WEBHOOKS", "").split(",") if u]
+    con = analytics.con()
+    rows = con.execute("SELECT * FROM events WHERE published=0 ORDER BY id").fetchall()
+    n = 0
+    for r in rows:
+        p = json.loads(r["payload"])
+        text = f"⚠️ {r['kind']} {r['subject']}: {json.dumps(p, ensure_ascii=False)[:300]}"
+        tg_configured = bool(os.environ.get("DYDX_TG_BOT_TOKEN")
+                             and os.environ.get("DYDX_TG_CHAT_ID"))
+        tg_ok = tg_send(text) if tg_configured else True
+        hooks_ok = True
+        for u in hooks:
+            if not webhook_send(u, {"kind": r["kind"], "subject": r["subject"],
+                                    "payload": p, "ts": r["ts"]}):
+                hooks_ok = False
+        delivered = (tg_ok and hooks_ok) and (tg_configured or hooks)
+        if delivered:
+            con.execute("UPDATE events SET published=1 WHERE id=?", (r["id"],))
+            n += 1
+    con.commit()
+    con.close()
+    return n
+
+
+if __name__ == "__main__":
+    print("published:", publish_all())

dydx_agent_gateway-0.3.0/backup.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# Consistent daily backup: sqlite .backup snapshots (WAL-safe) + reports.
+set -e
+BASE=/root/ventures/dydx-grant/agent-gateway
+PY="$BASE/.venv/bin/python"
+S="$(mktemp -d)"
+mkdir -p "$S/reports"
+
+"$PY" - "$BASE" "$S" <<'EOF'
+import sqlite3, sys
+from pathlib import Path
+base, stage = Path(sys.argv[1]), Path(sys.argv[2])
+for name in ("registry.sqlite", "analytics.sqlite"):
+    src, dst = base / "data" / name, stage / name
+    s = sqlite3.connect(f"file:{src}?mode=ro", uri=True)
+    d = sqlite3.connect(dst)
+    s.backup(d)
+    d.close(); s.close()
+    print("snapshot:", name)
+EOF
+
+cp -r "$BASE/reports/." "$S/reports/"
+tar czf "/root/backups/dydx-gateway-$(date +%F).tar.gz" -C "$S" .
+rm -rf "$S"
+find /root/backups -name "dydx-gateway-*.tar.gz" -mtime +30 -delete
+echo "backup done"