hyperliquid-agent-gateway 0.1.1__tar.gz

hyperliquid_agent_gateway-0.1.1/.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

hyperliquid_agent_gateway-0.1.1/.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=hyperliquid_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}

hyperliquid_agent_gateway-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+*.log
+.coverage
+.pytest_cache/
+tests/fixtures/live_*

hyperliquid_agent_gateway-0.1.1/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## 0.1.1 (2026-09-06)
+
+Fix release from the independent v0.1.0 review.
+
+- `liquidation_risk` (blocker): the LIVE `clearinghouseState` response
+  carries no `markPx` in positions, so `mark_px` and
+  `liq_distance_pct` were null in every branch live. Mark is now
+  resolved per coin from `metaAndAssetCtxs` (60s cache) with an
+  `allMids` fallback; each row reports `mark_px_source`
+  ('position' | 'metaAndAssetCtxs' | 'allMids' | null) and distances
+  stay null (honest) when no source knows the coin. `trader_activity`
+  open-position rows get the same resolver. Note documents that
+  `withdrawable` may be omitted by the venue while positions are open.
+- `tests/fixtures/clearinghouseState.json` re-recorded from the live
+  API (no `markPx` in positions, no `withdrawable` in marginSummary)
+  so the offline suite exercises the live shape; regression tests
+  cover mark from cache / allMids fallback / neither, liqPx present
+  and null, cross and isolated.
+- `wallet_balance` / `token_transfers`: per-token decimals via a
+  static map of canonical HyperEVM tokens (6 for USDC/USDT-style,
+  18 for PURR/HYPE) with honest `decimals_source`
+  ('static_map' | 'assumed_18') on every row; unknown tokens assume
+  18 and say so.
+- `funding_history` / `userFunding` README note: the venue returns
+  only non-zero funding events, so a live `funding_drag` of null for a
+  fresh address is expected, not a bug.
+- Version bumped to 0.1.1 (pyproject == package == server).
+
+## 0.1.0 (2026-09-06)
+
+Initial release.
+
+- Read-only, keyless MCP gateway to Hyperliquid public data.
+- `/info` client (`hyperliquid_mcp/info.py`): weight-based rate bucket
+  (1200 weight/min), per-type TTL caches, retries with backoff on
+  429/5xx, `User-Agent: hyperliquid-agent-gateway/0.1`.
+- HyperEVM JSON-RPC client (`hyperliquid_mcp/evm.py`): separate 100
+  req/min budget, `RpcError` taxonomy, adaptive `eth_getLogs` window
+  (30-block start, halve on too-big, double on quiet, cap 60).
+- 12 MCP tools (`hyperliquid_mcp/server.py`): market_overview,
+  spot_overview, quote, order_book, candles, trades, funding_history,
+  liquidation_risk, trader_activity, funding_carry_screener,
+  token_transfers, wallet_balance - all annotated read-only with honest
+  degradation (error dicts, never tracebacks) and freshness fields.
+- Offline test suite on schema-realistic fixtures (well over a hundred
+  checks; run `pytest -q` for the exact count); live online checks are
+  opt-in via `-m online`.
+- `scripts/recorder.py` live-fixture recorder + systemd units
+  (6h schedule, disabled by default).

hyperliquid_agent_gateway-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hyperliquid-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.

hyperliquid_agent_gateway-0.1.1/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.5
+Name: hyperliquid-agent-gateway
+Version: 0.1.1
+Summary: MCP gateway for AI agents to Hyperliquid public data: perp/spot market overviews, quotes, order books, candles, trades, funding, account risk and HyperEVM transfers. Read-only, keyless.
+Project-URL: Homepage, https://github.com/alekskram/hyperliquid-agent-gateway
+Project-URL: Repository, https://github.com/alekskram/hyperliquid-agent-gateway
+Project-URL: Issues, https://github.com/alekskram/hyperliquid-agent-gateway/issues
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,defi,funding,hyper evm,hyperliquid,mcp,perps
+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: fastmcp>=3.0
+Provides-Extra: dev
+Requires-Dist: hatchling; 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
+
+# hyperliquid-agent-gateway
+
+[![CI](https://github.com/alekskram/hyperliquid-agent-gateway/actions/workflows/tests.yml/badge.svg)](https://github.com/alekskram/hyperliquid-agent-gateway/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/hyperliquid-agent-gateway.svg)](https://pypi.org/project/hyperliquid-agent-gateway/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](pyproject.toml)
+
+An MCP (Model Context Protocol) server that gives AI agents read-only,
+keyless access to **Hyperliquid** public data - the ~233-perp DEX
+market, ~326 spot pairs, funding, per-account risk and HyperEVM (chain
+999) token transfers. No API keys, no auth, no signing, no writes:
+every tool reads public endpoints only (`api.hyperliquid.xyz/info` and
+`rpc.hyperliquid.xyz/evm`), cached and rate-limited so an enthusiastic
+agent cannot hammer the upstream.
+
+## Use cases
+
+- **Watch a wallet's risk** — per-account margin summary, leverage, liquidation distance on any address (`account risk` view)
+- **Fund the carry, not the noise** — funding history + carry screener across 233 perps to find stable paid positions
+- **Trace HyperEVM flows** — token transfers on chain 999 tied back to the perp markets (`token_transfers`)
+- **Read the book before you enter** — order book + recent trades + all-mids in one pass
+- **Trader scouting** — activity of any address: positions, volume, what they actually trade
+
+Full walkthroughs: [examples/use-cases.md](examples/use-cases.md).
+
+## Quickstart
+
+stdio (default, for local agents):
+
+```bash
+uvx hyperliquid-agent-gateway
+```
+
+or from a checkout:
+
+```bash
+git clone https://github.com/alekskram/hyperliquid-agent-gateway
+cd hyperliquid-agent-gateway
+uv sync
+uv run hyperliquid-agent-gateway
+```
+
+Claude Desktop / Cursor config:
+
+```json
+{
+  "mcpServers": {
+    "hyperliquid": {
+      "command": "uvx",
+      "args": ["--from",
+               "git+https://github.com/alekskram/hyperliquid-agent-gateway",
+               "hyperliquid-agent-gateway"]
+    }
+  }
+}
+```
+
+Hosted form - streamable HTTP on port **8903**:
+
+```bash
+uv run hyperliquid-agent-gateway --http            # 127.0.0.1:8903
+curl http://127.0.0.1:8903/health   # -> {"ok": true, "service": "hyperliquid-agent-gateway", ...}
+```
+
+<details>
+<summary><b>Codex</b> (~/.codex/config.toml)</summary>
+
+```toml
+[mcp_servers.hyperliquid]
+command = "uvx"
+args = ["hyperliquid-agent-gateway"]
+```
+</details>
+
+<details>
+<summary><b>ZCode</b> — register the server (copy-paste)</summary>
+
+```bash
+# 1) start the gateway (keep it running)
+uvx hyperliquid-agent-gateway --http --port 8903 &
+
+# 2) register it (merges into ~/.zcode/cli/config.json)
+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", {})["hyperliquid"] = {
+    "type": "http", "url": "http://127.0.0.1:8903/mcp"}
+json.dump(cfg, open(p, "w"), indent=2)
+print("hyperliquid-agent-gateway registered:", p)
+PY
+```
+</details>
+
+Hosted form — streamable HTTP on port **8903**:
+
+```bash
+uvx hyperliquid-agent-gateway --http
+```
+
+## Tools
+
+All 12 tools are read-only (annotated `readOnlyHint: true,
+destructiveHint: false, openWorldHint: true`).
+
+| # | Tool | Signature | What it does |
+|---|------|-----------|--------------|
+| 1 | `market_overview` | `market_overview(limit=20, sort="open_interest")` | Perp market snapshot from ONE `metaAndAssetCtxs` call: per-coin mark, open interest, day volume, premium, max leverage + totals. `sort` in {open_interest, volume, premium}. |
+| 2 | `spot_overview` | `spot_overview(limit=20)` | Spot pairs from `spotMeta` + ctxs with HIP-1 to ERC-20 links; `@{index}` names resolved to readable token names. |
+| 3 | `quote` | `quote(coin)` | Bid/ask/mid/spread + top-of-book sizes from `allMids` + `l2Book`. Unknown coin raises with 5 examples. |
+| 4 | `order_book` | `order_book(coin, depth=10)` | Book levels per side with nSigFigs aggregation and per-side total liquidity. |
+| 5 | `candles` | `candles(coin, interval="1h", limit=100)` | OHLCV rows newest-first; intervals 1m/15m/1h/4h/1d/1w/1M; `startTime` computed from `limit`. |
+| 6 | `trades` | `trades(coin, limit=20)` | Recent public fills WITH both sides' addresses (`users: [maker, taker]`). |
+| 7 | `funding_history` | `funding_history(coin, limit=100)` | Hourly funding rows + `premium_now` from the live asset ctx. |
+| 8 | `liquidation_risk` | `liquidation_risk(address)` | Per-account risk: margin summary, cross maintenance margin, per-position leverage + `liquidationPx` when published; when null, an explicitly flagged ESTIMATED distance from the maintenance-margin ratio. Mark px is resolved per coin from `metaAndAssetCtxs` (fallback `allMids`) because live positions carry no `markPx` - see `mark_px_source` on each row. Includes funding drag. |
+| 9 | `trader_activity` | `trader_activity(address, limit=50)` | Fills PnL/fees/volume/win-rate, funding net, open positions, per-coin breakdown. |
+| 10 | `funding_carry_screener` | `funding_carry_screener(topN=10, metric="premium")` | Ranks ALL perps from ONE call; `fundingHistory` fetched only for the topN (weight economy). |
+| 11 | `token_transfers` | `token_transfers(contract, limit=100, from_block=None)` | HyperEVM ERC-20 Transfer logs via adaptive-window `eth_getLogs`; rows carry from/to/value/txHash/blockNumber/ts with per-token `decimals` + `decimals_source` (static map or `assumed_18`). |
+| 12 | `wallet_balance` | `wallet_balance(address)` | Native (eth_getBalance) + up to 20 ERC-20s (eth_call balanceOf, resolved from spotMeta) + Hyperliquid spot balances; every row carries `decimals`/`decimals_source`. |
+
+## Rate limits
+
+Two independent, locally enforced budgets protect the upstream:
+
+**`/info` - 1200 weight per rolling 60s** (Hyperliquid's documented
+weight pricing), tracked per request type:
+
+| type | weight |
+|------|--------|
+| `allMids` | 2 |
+| `l2Book` | 2 |
+| `meta`, `metaAndAssetCtxs`, `spotMeta`, `spotMetaAndAssetCtxs` | 20 |
+| `recentTrades`, `clearinghouseState`, `userFills`, `userFunding`, `spotClearinghouseState` | 20 |
+| `fundingHistory` | 20 base + extra per 20 items beyond the first |
+| `candleSnapshot` | 60 |
+
+When the next request would exceed the budget the client waits once
+(<=5s) for the window to roll, then raises a clear error naming the
+limit - it never sleep-blocks forever.
+
+**HyperEVM RPC - 100 requests per rolling 60s** (flat 1 per request),
+enforced separately from /info. Over-budget calls raise immediately
+(`rpc-limit`) - tools surface an honest error dict, and
+`wallet_balance` stops its ERC-20 scan at the cap.
+
+TTL caches additionally dedupe repeated calls per data type: allMids
+15s, recentTrades 15s, l2Book 5s, metaAndAssetCtxs 60s, spotMeta 3600s,
+spotMetaAndAssetCtxs 60s, candleSnapshot 300s, fundingHistory 300s,
+per-address account types 60s.
+
+## Data notes
+
+- Every numeric from the API is a STRING upstream; the gateway parses
+  them with a never-raising helper - `null` always means "not
+  available", never zero.
+- Every upstream failure returns an error dict
+  `{"error": ..., "source": ..., "reason": ...}`, never a traceback;
+  partial data degrades field-by-field with `warnings[]`.
+- `liquidation_risk` never invents a liquidation price: when the venue
+  publishes none, `liq_px` stays `null` and the distance is an
+  explicitly flagged estimate (formula in the tool's note). Mark px is
+  likewise never invented: live positions carry no `markPx`, so it is
+  resolved from `metaAndAssetCtxs` (fallback `allMids`) and the row's
+  `mark_px_source` says which; no source -> `null`.
+- `funding_drag` / `funding_net`: the venue's `userFunding` returns
+  only NON-ZERO funding events, so a live `null`/empty for a fresh or
+  quiet address is expected behaviour, not a bug.
+- ERC-20 amounts use a static decimals map for canonical HyperEVM
+  tokens (6 for USDC/USDT-style, 18 for PURR/HYPE); unknown tokens
+  assume 18 and every row says `decimals_source: "assumed_18"` - do
+  not trust 6dp precision for unmapped tokens.
+- Cached responses carry `age_seconds` / `fetched_at` freshness fields.
+
+
+## License
+
+MIT.

hyperliquid_agent_gateway-0.1.1/README.md

@@ -0,0 +1,178 @@
+# hyperliquid-agent-gateway
+
+[![CI](https://github.com/alekskram/hyperliquid-agent-gateway/actions/workflows/tests.yml/badge.svg)](https://github.com/alekskram/hyperliquid-agent-gateway/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/hyperliquid-agent-gateway.svg)](https://pypi.org/project/hyperliquid-agent-gateway/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](pyproject.toml)
+
+An MCP (Model Context Protocol) server that gives AI agents read-only,
+keyless access to **Hyperliquid** public data - the ~233-perp DEX
+market, ~326 spot pairs, funding, per-account risk and HyperEVM (chain
+999) token transfers. No API keys, no auth, no signing, no writes:
+every tool reads public endpoints only (`api.hyperliquid.xyz/info` and
+`rpc.hyperliquid.xyz/evm`), cached and rate-limited so an enthusiastic
+agent cannot hammer the upstream.
+
+## Use cases
+
+- **Watch a wallet's risk** — per-account margin summary, leverage, liquidation distance on any address (`account risk` view)
+- **Fund the carry, not the noise** — funding history + carry screener across 233 perps to find stable paid positions
+- **Trace HyperEVM flows** — token transfers on chain 999 tied back to the perp markets (`token_transfers`)
+- **Read the book before you enter** — order book + recent trades + all-mids in one pass
+- **Trader scouting** — activity of any address: positions, volume, what they actually trade
+
+Full walkthroughs: [examples/use-cases.md](examples/use-cases.md).
+
+## Quickstart
+
+stdio (default, for local agents):
+
+```bash
+uvx hyperliquid-agent-gateway
+```
+
+or from a checkout:
+
+```bash
+git clone https://github.com/alekskram/hyperliquid-agent-gateway
+cd hyperliquid-agent-gateway
+uv sync
+uv run hyperliquid-agent-gateway
+```
+
+Claude Desktop / Cursor config:
+
+```json
+{
+  "mcpServers": {
+    "hyperliquid": {
+      "command": "uvx",
+      "args": ["--from",
+               "git+https://github.com/alekskram/hyperliquid-agent-gateway",
+               "hyperliquid-agent-gateway"]
+    }
+  }
+}
+```
+
+Hosted form - streamable HTTP on port **8903**:
+
+```bash
+uv run hyperliquid-agent-gateway --http            # 127.0.0.1:8903
+curl http://127.0.0.1:8903/health   # -> {"ok": true, "service": "hyperliquid-agent-gateway", ...}
+```
+
+<details>
+<summary><b>Codex</b> (~/.codex/config.toml)</summary>
+
+```toml
+[mcp_servers.hyperliquid]
+command = "uvx"
+args = ["hyperliquid-agent-gateway"]
+```
+</details>
+
+<details>
+<summary><b>ZCode</b> — register the server (copy-paste)</summary>
+
+```bash
+# 1) start the gateway (keep it running)
+uvx hyperliquid-agent-gateway --http --port 8903 &
+
+# 2) register it (merges into ~/.zcode/cli/config.json)
+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", {})["hyperliquid"] = {
+    "type": "http", "url": "http://127.0.0.1:8903/mcp"}
+json.dump(cfg, open(p, "w"), indent=2)
+print("hyperliquid-agent-gateway registered:", p)
+PY
+```
+</details>
+
+Hosted form — streamable HTTP on port **8903**:
+
+```bash
+uvx hyperliquid-agent-gateway --http
+```
+
+## Tools
+
+All 12 tools are read-only (annotated `readOnlyHint: true,
+destructiveHint: false, openWorldHint: true`).
+
+| # | Tool | Signature | What it does |
+|---|------|-----------|--------------|
+| 1 | `market_overview` | `market_overview(limit=20, sort="open_interest")` | Perp market snapshot from ONE `metaAndAssetCtxs` call: per-coin mark, open interest, day volume, premium, max leverage + totals. `sort` in {open_interest, volume, premium}. |
+| 2 | `spot_overview` | `spot_overview(limit=20)` | Spot pairs from `spotMeta` + ctxs with HIP-1 to ERC-20 links; `@{index}` names resolved to readable token names. |
+| 3 | `quote` | `quote(coin)` | Bid/ask/mid/spread + top-of-book sizes from `allMids` + `l2Book`. Unknown coin raises with 5 examples. |
+| 4 | `order_book` | `order_book(coin, depth=10)` | Book levels per side with nSigFigs aggregation and per-side total liquidity. |
+| 5 | `candles` | `candles(coin, interval="1h", limit=100)` | OHLCV rows newest-first; intervals 1m/15m/1h/4h/1d/1w/1M; `startTime` computed from `limit`. |
+| 6 | `trades` | `trades(coin, limit=20)` | Recent public fills WITH both sides' addresses (`users: [maker, taker]`). |
+| 7 | `funding_history` | `funding_history(coin, limit=100)` | Hourly funding rows + `premium_now` from the live asset ctx. |
+| 8 | `liquidation_risk` | `liquidation_risk(address)` | Per-account risk: margin summary, cross maintenance margin, per-position leverage + `liquidationPx` when published; when null, an explicitly flagged ESTIMATED distance from the maintenance-margin ratio. Mark px is resolved per coin from `metaAndAssetCtxs` (fallback `allMids`) because live positions carry no `markPx` - see `mark_px_source` on each row. Includes funding drag. |
+| 9 | `trader_activity` | `trader_activity(address, limit=50)` | Fills PnL/fees/volume/win-rate, funding net, open positions, per-coin breakdown. |
+| 10 | `funding_carry_screener` | `funding_carry_screener(topN=10, metric="premium")` | Ranks ALL perps from ONE call; `fundingHistory` fetched only for the topN (weight economy). |
+| 11 | `token_transfers` | `token_transfers(contract, limit=100, from_block=None)` | HyperEVM ERC-20 Transfer logs via adaptive-window `eth_getLogs`; rows carry from/to/value/txHash/blockNumber/ts with per-token `decimals` + `decimals_source` (static map or `assumed_18`). |
+| 12 | `wallet_balance` | `wallet_balance(address)` | Native (eth_getBalance) + up to 20 ERC-20s (eth_call balanceOf, resolved from spotMeta) + Hyperliquid spot balances; every row carries `decimals`/`decimals_source`. |
+
+## Rate limits
+
+Two independent, locally enforced budgets protect the upstream:
+
+**`/info` - 1200 weight per rolling 60s** (Hyperliquid's documented
+weight pricing), tracked per request type:
+
+| type | weight |
+|------|--------|
+| `allMids` | 2 |
+| `l2Book` | 2 |
+| `meta`, `metaAndAssetCtxs`, `spotMeta`, `spotMetaAndAssetCtxs` | 20 |
+| `recentTrades`, `clearinghouseState`, `userFills`, `userFunding`, `spotClearinghouseState` | 20 |
+| `fundingHistory` | 20 base + extra per 20 items beyond the first |
+| `candleSnapshot` | 60 |
+
+When the next request would exceed the budget the client waits once
+(<=5s) for the window to roll, then raises a clear error naming the
+limit - it never sleep-blocks forever.
+
+**HyperEVM RPC - 100 requests per rolling 60s** (flat 1 per request),
+enforced separately from /info. Over-budget calls raise immediately
+(`rpc-limit`) - tools surface an honest error dict, and
+`wallet_balance` stops its ERC-20 scan at the cap.
+
+TTL caches additionally dedupe repeated calls per data type: allMids
+15s, recentTrades 15s, l2Book 5s, metaAndAssetCtxs 60s, spotMeta 3600s,
+spotMetaAndAssetCtxs 60s, candleSnapshot 300s, fundingHistory 300s,
+per-address account types 60s.
+
+## Data notes
+
+- Every numeric from the API is a STRING upstream; the gateway parses
+  them with a never-raising helper - `null` always means "not
+  available", never zero.
+- Every upstream failure returns an error dict
+  `{"error": ..., "source": ..., "reason": ...}`, never a traceback;
+  partial data degrades field-by-field with `warnings[]`.
+- `liquidation_risk` never invents a liquidation price: when the venue
+  publishes none, `liq_px` stays `null` and the distance is an
+  explicitly flagged estimate (formula in the tool's note). Mark px is
+  likewise never invented: live positions carry no `markPx`, so it is
+  resolved from `metaAndAssetCtxs` (fallback `allMids`) and the row's
+  `mark_px_source` says which; no source -> `null`.
+- `funding_drag` / `funding_net`: the venue's `userFunding` returns
+  only NON-ZERO funding events, so a live `null`/empty for a fresh or
+  quiet address is expected behaviour, not a bug.
+- ERC-20 amounts use a static decimals map for canonical HyperEVM
+  tokens (6 for USDC/USDT-style, 18 for PURR/HYPE); unknown tokens
+  assume 18 and every row says `decimals_source: "assumed_18"` - do
+  not trust 6dp precision for unmapped tokens.
+- Cached responses carry `age_seconds` / `fetched_at` freshness fields.
+
+
+## License
+
+MIT.

hyperliquid_agent_gateway-0.1.1/deploy/hyperliquid-recorder.service

@@ -0,0 +1,16 @@
+[Unit]
+Description=Hyperliquid Agent Gateway - fixture recorder (one pass)
+Documentation=https://github.com/hyperliquid-agent-gateway/hyperliquid-agent-gateway
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+# One pass = 13 /info requests (~264 weight, well inside 1200/min) plus
+# 1-2 HyperEVM eth_getLogs calls (inside 100/min). Fixtures land in
+# tests/fixtures/ of the checkout below.
+WorkingDirectory=/opt/hyperliquid-agent-gateway
+ExecStart=/usr/bin/env python scripts/recorder.py --out tests/fixtures
+Environment=PYTHONUNBUFFERED=1
+# A full pass is ~15 requests: 1-3 minutes worst case with retries
+TimeoutStartSec=300

hyperliquid_agent_gateway-0.1.1/deploy/hyperliquid-recorder.timer

@@ -0,0 +1,15 @@
+[Unit]
+Description=Hyperliquid Agent Gateway - fixture recorder schedule (6h)
+Documentation=https://github.com/hyperliquid-agent-gateway/hyperliquid-agent-gateway
+
+[Timer]
+# Every 6 hours; keeps tests/fixtures/ schema-realistic without
+# approaching either rate budget (a pass costs ~264 /info weight and
+# 1-2 rpc requests).
+# OPT-IN ONLY: this unit ships DISABLED. Enable explicitly with
+#   systemctl enable --now hyperliquid-recorder.timer
+OnCalendar=*-*-* 00/6:00:00
+Persistent=true
+
+[Install]
+WantedBy=timers.target

hyperliquid_agent_gateway-0.1.1/hyperliquid_mcp/API_NOTES.md

@@ -0,0 +1,92 @@
+# API notes - Hyperliquid public surfaces (as verified 2026-09-05/06)
+
+Facts the gateway depends on. Every claim below was checked against the
+live endpoints before v0.1.0 was coded; fixtures in `tests/fixtures/`
+mirror these shapes.
+
+## /info (POST https://api.hyperliquid.xyz/info)
+
+- Single POST endpoint; body is `{"type": "<Type>", ...}`. Keyless,
+  read-only. Action types (signing) are NOT used by this gateway.
+- **ALL numerics are STRINGS** (`"42350.1"`, `"-0.00012"`). Parse with
+  a never-raising `_f()`; empty/absent optionals become `None`.
+- Weight-based rate limit: **1200 weight / 60s**. Per-request weights
+  implemented in `hyperliquid_mcp/info.py`:
+
+  | type | weight |
+  |------|--------|
+  | allMids | 2 |
+  | l2Book | 2 |
+  | meta, metaAndAssetCtxs, spotMeta, spotMetaAndAssetCtxs | 20 |
+  | recentTrades, clearinghouseState, userFills, userFunding, spotClearinghouseState | 20 |
+  | fundingHistory | 20 base + extra per 20 items beyond the first |
+  | candleSnapshot | 60 |
+
+- `metaAndAssetCtxs` returns a **pair** `[meta, assetCtxs]`: meta =
+  `{"universe": [{"name", "szDecimals", "maxLeverage",
+  "onlyIsolated"}]}`; assetCtxs rows align by index with universe and
+  carry `dayNtlVlm`, `openInterest` (coin units), `premium`, `markPx`,
+  `midPx`, `oraclePx`, `impactPxs {bidPx, askPx}`, `funding`
+  (hourly). ~233 perps at capture time.
+- `spotMeta` = `{"universe": [{"name": "@1/PURR", "tokens": [int
+  indices], "isCanonical", "index"}], "tokens": [{"name", "index",
+  "token"}], "deployAuctionStatus", "registeredContracts": [{"name",
+  "builder"}]}`. `token` is the ERC-20 contract (0x...) for HIP-1
+  deployed coins, otherwise the coin name. ~326 pairs.
+- `spotMetaAndAssetCtxs` likewise returns `[spotMeta, spotCtxs]`;
+  spotCtxs rows carry `coin`, `markPx`, `midPx`, `dayNtlVlm`,
+  `prevDayPx`, `circulating`, `funding`.
+- `l2Book` body `{"coin"}` -> `{"coin", "time", "levels": {"bids":
+  [{"px","sz","nSigFigs"}], "asks": [...]}}` - already aggregated to
+  significant figures by the venue.
+- `candleSnapshot` body `{"coin", "interval", "startTime"}`; intervals
+  `1m,15m,1h,4h,1d,1w,1M`; rows oldest-first with `t/T` (ms), `o/c/h/l/v`
+  (STRINGS), `n` (int trade count).
+- `recentTrades` body `{"coin"}` -> rows with `side` ('B'/'A'), `px`,
+  `sz`, `time` (ms), `hash`, **`users: [maker, taker]`** (both sides).
+- `fundingHistory` body `{"coin", "startTime?", "endTime?"}` -> flat
+  `[{coin, fundingRate, premium, time}]`, hourly, newest-last.
+- `clearinghouseState` body `{"user": address}` ->
+  `marginSummary {accountValue, totalNtlPos, totalRawUsd,
+  totalMarginUsed, withdrawable}`, `crossMaintenanceMarginUsed`,
+  `assetPositions [{type, position {coin, szi, leverage {type, value},
+  entryPx, positionValue, unrealizedPnl, returnOnEquity,
+  liquidationPx | null, marginUsed, maintMarginUsed, isolatedMargin}}]`.
+  **`liquidationPx` can be null** - the estimate path in
+  `liquidation_risk` exists for exactly that case.
+- `userFills` -> `[{coin, dir, px, sz, time, closedPnl, fee, feeToken,
+  builderFee, hash, oid}]`.
+- `userFunding` -> non-zero funding payments `[{coin, fundingRate,
+  premium, time, delta}]`; `delta` is the USD payment, negative when
+  the trader pays.
+- `spotClearinghouseState` -> `{"balances": [{"coin": "@/PURR",
+  "hold", "total"}]}`.
+
+## HyperEVM RPC (POST https://rpc.hyperliquid.xyz/evm)
+
+- Chain id **999** (0x3e7). Keyless public node, separate from /info
+  budgets: this gateway enforces its own **100 requests/min** cap
+  locally.
+- `eth_getLogs` responses are capped (~1MB); active tokens need
+  roughly **30-60 block windows**. `evm.get_logs` adapts: start 30
+  blocks, halve on failure/too-big (floor 2), double on quiet success
+  (cap 60), max 14 slices.
+- Transfer topic
+  `0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef`;
+  `balanceOf(address)` selector `0x70a08231`; native balance via
+  `eth_getBalance`.
+- Env override: `HL_EVM_RPC_URL`.
+
+## Endpoints NOT used, and why
+
+- **info type `leaderboard`** - returns 403 behind Cloudflare bot
+  protection for non-browser clients; unreliable for a gateway.
+- **Blockscout-style explorers** (`explorer.hyperliquid.xyz` API) - the
+  free tier was dead/unstable at verification time; all on-chain reads
+  go through the raw RPC instead.
+- **WebSocket subscriptions** (`wss://api.hyperliquid.xyz/ws`) -
+  deferred to v0.2; the MCP request/response model gains little from
+  push feeds and the TTL caches already cover freshness.
+- **Exchange/exchangeAction (signing) endpoints** - out of scope by
+  design: this gateway is strictly read-only and keyless; no private
+  keys ever enter the process.

hyperliquid_agent_gateway-0.1.1/hyperliquid_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""hyperliquid_mcp - read-only, keyless MCP gateway to Hyperliquid public data.
+
+Package layout:
+    info.py    stdlib-only POST client for https://api.hyperliquid.xyz/info
+    evm.py     stdlib-only JSON-RPC client for https://rpc.hyperliquid.xyz/evm
+    server.py  FastMCP server wiring the 12 read-only tools
+
+No private keys, no signing, no order placement - public data only.
+"""
+
+__version__ = "0.1.1"