aster-agent-gateway 0.1.0__tar.gz

aster_agent_gateway-0.1.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

aster_agent_gateway-0.1.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=aster_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}

aster_agent_gateway-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+*.log
+.coverage
+.pytest_cache/
+uv.lock

aster_agent_gateway-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.1.0 (2026-09-06)
+
+Initial release.
+
+- Read-only, keyless MCP gateway to Aster DEX public data.
+- REST client (`aster_mcp/rest.py`): weight-aware (reads
+  `X-MBX-USED-WEIGHT-1M`, self-throttles at 80% of 2400/min fapi and
+  6000/min sapi, 429 backoff honoring Retry-After, 418 IP-ban cooldown),
+  per-endpoint TTL caches, weight-aware depth/kline limit snapping.
+- On-chain client (`aster_mcp/chain.py`): tapi Aster Chain JSON-RPC
+  (privacy-aware account views), Solana vault signatures, EVM vault
+  Transfer logs gated on `ASTER_EVM_RPC_URL*` env (honest
+  "no RPC configured" when unset).
+- 13 MCP tools (`aster_mcp/server.py`): market_overview,
+  exchange_symbols, order_book, klines, trades, spot_overview,
+  funding_overview, tradfi_markets (with tradfi_crypto_corr),
+  funding_screener (with funding_regime headroom), oi_snapshot,
+  deposit_flows (with deposit_stats), account_view,
+  mark_index_divergence - all annotated read-only with honest
+  degradation (error dicts, never tracebacks) and freshness fields.
+- Offline test suite on schema-realistic fixtures (fixtures refreshed
+  from live captures by `scripts/smoke_live.py`, budget 10 calls).
+- `scripts/recorder.py` live-fixture recorder + systemd deploy units
+  (6h schedule, disabled by default).

aster_agent_gateway-0.1.0/LICENSE

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

aster_agent_gateway-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: aster-agent-gateway
+Version: 0.1.0
+Summary: MCP gateway for AI agents to Aster DEX public data: futures and spot market overviews, order books, klines, funding and TradFi-perp screeners, vault deposit flows, public account views. Read-only, keyless.
+Project-URL: Homepage, https://github.com/alekskram/aster-agent-gateway
+Project-URL: Repository, https://github.com/alekskram/aster-agent-gateway
+Project-URL: Issues, https://github.com/alekskram/aster-agent-gateway/issues
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,aster,asterdex,defi,funding,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
+
+# aster-agent-gateway
+
+[![CI](https://github.com/alekskram/aster-agent-gateway/actions/workflows/tests.yml/badge.svg)](https://github.com/alekskram/aster-agent-gateway/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/aster-agent-gateway.svg)](https://pypi.org/project/aster-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 **Aster DEX** public data - ~580 futures symbols
+(including 24/7 TradFi perps: metals, equity indices, energy,
+treasuries), ~68 spot pairs, funding, order books, klines, vault
+deposit flows and tapi account views. No API keys, no auth, no
+signing, no writes: every tool reads public endpoints only
+(`fapi.asterdex.com/fapi/v3`, `sapi.asterdex.com/api/v3`,
+`tapi.asterdex.com/info`, `api.mainnet-beta.solana.com`, plus optional
+EVM RPCs), cached and rate-limited so an enthusiastic agent cannot
+hammer the upstream.
+
+## Use cases
+
+- **Screen 731 funding rates in one call** — ranked by annualized rate with funding regime and mark/index spread; the 793% outliers are visible instantly
+- **Trade TradFi 24/7** — metals, equity indices, energy, treasuries perps next to crypto, one consistent API
+- **Follow the vault money** — deposit flows per vault: who is parking capital where
+- **Spot index dislocations** — mark vs index divergence ranking across the whole board
+- **Morning scan** — market overview + funding overview + OI snapshot, three cheap calls
+
+Full walkthroughs: [examples/use-cases.md](examples/use-cases.md).
+
+## Quickstart
+
+stdio (default, for local agents):
+
+```bash
+uvx aster-agent-gateway
+```
+
+or from a checkout:
+
+```bash
+git clone https://github.com/alekskram/aster-agent-gateway
+cd aster-agent-gateway
+uv sync
+uv run aster-agent-gateway
+```
+
+Claude Desktop / Cursor config:
+
+```json
+{
+  "mcpServers": {
+    "aster": {
+      "command": "uvx",
+      "args": ["--from",
+               "git+https://github.com/alekskram/aster-agent-gateway",
+               "aster-agent-gateway"]
+    }
+  }
+}
+```
+
+Hosted form - streamable HTTP on port **8904**:
+
+```bash
+uv run aster-agent-gateway --http            # 127.0.0.1:8904
+curl http://127.0.0.1:8904/health   # -> {"ok": true, "service": "aster-agent-gateway", ...}
+```
+
+<details>
+<summary><b>Codex</b> (~/.codex/config.toml)</summary>
+
+```toml
+[mcp_servers.aster]
+command = "uvx"
+args = ["aster-agent-gateway"]
+```
+</details>
+
+<details>
+<summary><b>ZCode</b> — register the server (copy-paste)</summary>
+
+```bash
+# 1) start the gateway (keep it running)
+uvx aster-agent-gateway --http --port 8904 &
+
+# 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", {})["aster"] = {
+    "type": "http", "url": "http://127.0.0.1:8904/mcp"}
+json.dump(cfg, open(p, "w"), indent=2)
+print("aster-agent-gateway registered:", p)
+PY
+```
+</details>
+
+Hosted form — streamable HTTP on port **8904**:
+
+```bash
+uvx aster-agent-gateway --http
+```
+
+## Tools
+
+All 13 tools are read-only (annotated `readOnlyHint: true,
+destructiveHint: false`).
+
+| # | Tool | Signature | What it does |
+|---|------|-----------|--------------|
+| 1 | `market_overview` | `market_overview(limit=20, sort="volume")` | Futures panel from ONE ticker/24hr ALL call joined with exchangeInfo: TRADING markets, top volumes, status counts, fresh listings (onboardDate). |
+| 2 | `exchange_symbols` | `exchange_symbols(venue="futures", symbol=None, include_junk=False)` | Symbol universe with filters/precisions incl. MIN_NOTIONAL, stepSize, leverageFilter; TEST*/SETTLING junk filtered by default. |
+| 3 | `order_book` | `order_book(symbol, venue="futures", depth=10)` | fapi depth / sapi api/v3 depth; limit snapped to a priced tier (weight-aware). |
+| 4 | `klines` | `klines(symbol, interval="1h", limit=100, market="futures", price_type="last")` | last/mark/index klines on fapi; spot via sapi. |
+| 5 | `trades` | `trades(symbol, limit=20, venue="futures")` | Fresh keyless trades; spot path probed live (honest error dict if dead). |
+| 6 | `spot_overview` | `spot_overview(limit=20)` | Spot pairs from sapi ticker/24hr + exchangeInfo; TEST* junk filtered. |
+| 7 | `funding_overview` | `funding_overview(limit=20, sort="rate")` | All ~730 rates from premiumIndex + fundingInfo: mixed 1/2/4/8h intervals (flagged), cap/floor, interestRate, nextFundingTime. |
+| 8 | `tradfi_markets` | `tradfi_markets(limit=20, window=None)` | TradFi-perp screener by asset class (metals/equity/energy/treasuries/forex) + `tradfi_crypto_corr` sub-block: local TradFi-vs-BTC correlation from klines. |
+| 9 | `funding_screener` | `funding_screener(top=10, direction="both")` | One-call ranking by annualized funding, premium, mark-index spread + `funding_regime` headroom to cap/floor. |
+| 10 | `oi_snapshot` | `oi_snapshot(symbols=None, top=10)` | Per-symbol openInterest (max 10 symbols/call). No keyless OI history (404) - stated honestly. |
+| 11 | `deposit_flows` | `deposit_flows(chain="all", limit=20)` | Solana vault signatures (keyless) + EVM vault Transfers when `ASTER_EVM_RPC_URL*` set + `deposit_stats` hourly/chain buckets. |
+| 12 | `account_view` | `account_view(address, data="balance")` | tapi `aster_getBalance`/`openOrders`/`userFills` keyless for any address; privacy-empty returns an honest error dict explaining why. |
+| 13 | `mark_index_divergence` | `mark_index_divergence(limit=20)` | mark vs index spread screener from ONE premiumIndex call + markPriceKlines-vs-klines crosscheck on the top 3. |
+
+## Rate limits
+
+Two REST buckets, locally enforced and weight-aware:
+
+- **fapi 2400 weight/min**, **sapi 6000/min** (header
+  `X-MBX-USED-WEIGHT-1M` read after every call). Above 80% of a
+  bucket the client self-throttles; 429 backs off honoring
+  `Retry-After`; a 418 (repeated 429 = IP ban) triggers a 60s refusal
+  cooldown. Depth/kline limits snap to priced tiers so callers cannot
+  accidentally burn weight.
+- **Solana 10 req/min, tapi 30/min, EVM 20/min** local budgets
+  (separate ledgers, fail-fast honest errors).
+
+TTL caches: exchangeInfo 3600s, fundingInfo 600s, premiumIndex and
+tickers 15s, depth 5s, klines 60s, trades 10s, openInterest 30s.
+
+## Data notes
+
+- Every numeric from the API is a STRING upstream; parsed 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.
+- **No OI history exists keyless** (`/futures/data/openInterestHist`
+  404s) - the gateway says so instead of inventing data.
+- **EVM vault logs** need `ASTER_EVM_RPC_URL` (or per-chain
+  `ASTER_EVM_RPC_URL_{BSC,ETH,ARB}`); free public RPCs reject vault
+  queries with -32005. Unset -> honest "no RPC configured".
+- **tapi account privacy**: most accounts are private; empty results
+  are reported as privacy, not as data.
+- Cached responses carry `age_seconds` / `fetched_at` freshness
+  fields.
+
+
+## License
+
+MIT.

aster_agent_gateway-0.1.0/README.md

@@ -0,0 +1,162 @@
+# aster-agent-gateway
+
+[![CI](https://github.com/alekskram/aster-agent-gateway/actions/workflows/tests.yml/badge.svg)](https://github.com/alekskram/aster-agent-gateway/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/aster-agent-gateway.svg)](https://pypi.org/project/aster-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 **Aster DEX** public data - ~580 futures symbols
+(including 24/7 TradFi perps: metals, equity indices, energy,
+treasuries), ~68 spot pairs, funding, order books, klines, vault
+deposit flows and tapi account views. No API keys, no auth, no
+signing, no writes: every tool reads public endpoints only
+(`fapi.asterdex.com/fapi/v3`, `sapi.asterdex.com/api/v3`,
+`tapi.asterdex.com/info`, `api.mainnet-beta.solana.com`, plus optional
+EVM RPCs), cached and rate-limited so an enthusiastic agent cannot
+hammer the upstream.
+
+## Use cases
+
+- **Screen 731 funding rates in one call** — ranked by annualized rate with funding regime and mark/index spread; the 793% outliers are visible instantly
+- **Trade TradFi 24/7** — metals, equity indices, energy, treasuries perps next to crypto, one consistent API
+- **Follow the vault money** — deposit flows per vault: who is parking capital where
+- **Spot index dislocations** — mark vs index divergence ranking across the whole board
+- **Morning scan** — market overview + funding overview + OI snapshot, three cheap calls
+
+Full walkthroughs: [examples/use-cases.md](examples/use-cases.md).
+
+## Quickstart
+
+stdio (default, for local agents):
+
+```bash
+uvx aster-agent-gateway
+```
+
+or from a checkout:
+
+```bash
+git clone https://github.com/alekskram/aster-agent-gateway
+cd aster-agent-gateway
+uv sync
+uv run aster-agent-gateway
+```
+
+Claude Desktop / Cursor config:
+
+```json
+{
+  "mcpServers": {
+    "aster": {
+      "command": "uvx",
+      "args": ["--from",
+               "git+https://github.com/alekskram/aster-agent-gateway",
+               "aster-agent-gateway"]
+    }
+  }
+}
+```
+
+Hosted form - streamable HTTP on port **8904**:
+
+```bash
+uv run aster-agent-gateway --http            # 127.0.0.1:8904
+curl http://127.0.0.1:8904/health   # -> {"ok": true, "service": "aster-agent-gateway", ...}
+```
+
+<details>
+<summary><b>Codex</b> (~/.codex/config.toml)</summary>
+
+```toml
+[mcp_servers.aster]
+command = "uvx"
+args = ["aster-agent-gateway"]
+```
+</details>
+
+<details>
+<summary><b>ZCode</b> — register the server (copy-paste)</summary>
+
+```bash
+# 1) start the gateway (keep it running)
+uvx aster-agent-gateway --http --port 8904 &
+
+# 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", {})["aster"] = {
+    "type": "http", "url": "http://127.0.0.1:8904/mcp"}
+json.dump(cfg, open(p, "w"), indent=2)
+print("aster-agent-gateway registered:", p)
+PY
+```
+</details>
+
+Hosted form — streamable HTTP on port **8904**:
+
+```bash
+uvx aster-agent-gateway --http
+```
+
+## Tools
+
+All 13 tools are read-only (annotated `readOnlyHint: true,
+destructiveHint: false`).
+
+| # | Tool | Signature | What it does |
+|---|------|-----------|--------------|
+| 1 | `market_overview` | `market_overview(limit=20, sort="volume")` | Futures panel from ONE ticker/24hr ALL call joined with exchangeInfo: TRADING markets, top volumes, status counts, fresh listings (onboardDate). |
+| 2 | `exchange_symbols` | `exchange_symbols(venue="futures", symbol=None, include_junk=False)` | Symbol universe with filters/precisions incl. MIN_NOTIONAL, stepSize, leverageFilter; TEST*/SETTLING junk filtered by default. |
+| 3 | `order_book` | `order_book(symbol, venue="futures", depth=10)` | fapi depth / sapi api/v3 depth; limit snapped to a priced tier (weight-aware). |
+| 4 | `klines` | `klines(symbol, interval="1h", limit=100, market="futures", price_type="last")` | last/mark/index klines on fapi; spot via sapi. |
+| 5 | `trades` | `trades(symbol, limit=20, venue="futures")` | Fresh keyless trades; spot path probed live (honest error dict if dead). |
+| 6 | `spot_overview` | `spot_overview(limit=20)` | Spot pairs from sapi ticker/24hr + exchangeInfo; TEST* junk filtered. |
+| 7 | `funding_overview` | `funding_overview(limit=20, sort="rate")` | All ~730 rates from premiumIndex + fundingInfo: mixed 1/2/4/8h intervals (flagged), cap/floor, interestRate, nextFundingTime. |
+| 8 | `tradfi_markets` | `tradfi_markets(limit=20, window=None)` | TradFi-perp screener by asset class (metals/equity/energy/treasuries/forex) + `tradfi_crypto_corr` sub-block: local TradFi-vs-BTC correlation from klines. |
+| 9 | `funding_screener` | `funding_screener(top=10, direction="both")` | One-call ranking by annualized funding, premium, mark-index spread + `funding_regime` headroom to cap/floor. |
+| 10 | `oi_snapshot` | `oi_snapshot(symbols=None, top=10)` | Per-symbol openInterest (max 10 symbols/call). No keyless OI history (404) - stated honestly. |
+| 11 | `deposit_flows` | `deposit_flows(chain="all", limit=20)` | Solana vault signatures (keyless) + EVM vault Transfers when `ASTER_EVM_RPC_URL*` set + `deposit_stats` hourly/chain buckets. |
+| 12 | `account_view` | `account_view(address, data="balance")` | tapi `aster_getBalance`/`openOrders`/`userFills` keyless for any address; privacy-empty returns an honest error dict explaining why. |
+| 13 | `mark_index_divergence` | `mark_index_divergence(limit=20)` | mark vs index spread screener from ONE premiumIndex call + markPriceKlines-vs-klines crosscheck on the top 3. |
+
+## Rate limits
+
+Two REST buckets, locally enforced and weight-aware:
+
+- **fapi 2400 weight/min**, **sapi 6000/min** (header
+  `X-MBX-USED-WEIGHT-1M` read after every call). Above 80% of a
+  bucket the client self-throttles; 429 backs off honoring
+  `Retry-After`; a 418 (repeated 429 = IP ban) triggers a 60s refusal
+  cooldown. Depth/kline limits snap to priced tiers so callers cannot
+  accidentally burn weight.
+- **Solana 10 req/min, tapi 30/min, EVM 20/min** local budgets
+  (separate ledgers, fail-fast honest errors).
+
+TTL caches: exchangeInfo 3600s, fundingInfo 600s, premiumIndex and
+tickers 15s, depth 5s, klines 60s, trades 10s, openInterest 30s.
+
+## Data notes
+
+- Every numeric from the API is a STRING upstream; parsed 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.
+- **No OI history exists keyless** (`/futures/data/openInterestHist`
+  404s) - the gateway says so instead of inventing data.
+- **EVM vault logs** need `ASTER_EVM_RPC_URL` (or per-chain
+  `ASTER_EVM_RPC_URL_{BSC,ETH,ARB}`); free public RPCs reject vault
+  queries with -32005. Unset -> honest "no RPC configured".
+- **tapi account privacy**: most accounts are private; empty results
+  are reported as privacy, not as data.
+- Cached responses carry `age_seconds` / `fetched_at` freshness
+  fields.
+
+
+## License
+
+MIT.

aster_agent_gateway-0.1.0/aster_mcp/API_NOTES.md

@@ -0,0 +1,99 @@
+# API notes - Aster 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.
+
+## fapi - futures (https://fapi.asterdex.com/fapi/v3/*)
+
+- Binance-compatible v3 REST, keyless for market data. ALL numerics
+  arrive as STRINGS ("0.0001"); parse with a never-raising `_f()`.
+- **Rate limits: weight-based per IP, 2400 weight/min** on fapi
+  (header `X-MBX-USED-WEIGHT-1M` on every response). 429 -> backoff
+  honoring `Retry-After`; repeated 429 -> **418 IP ban** (the client
+  cools down 60s and refuses calls).
+- `exchangeInfo` (weight 1): ~580 symbols; statuses ~559 TRADING /
+  15 SETTLING / 6 PENDING; quotes USDT 568 / USD1 10; symbol rows
+  carry `onboardDate`, `contractType`, `status`, `filters`
+  (PRICE_FILTER tickSize, LOT_SIZE stepSize, MIN_NOTIONAL,
+  LEVERAGE_FILTER).
+- `ticker/24hr` with NO symbol param (weight ~40): ALL ~574 rows in
+  ONE call - symbol, lastPrice, priceChangePercent, quoteVolume,
+  volume, highPrice, lowPrice, weightedAvgPrice, count.
+- `premiumIndex` no param (weight ~10): ALL ~730 rows - symbol,
+  markPrice, indexPrice, lastFundingRate, nextFundingTime,
+  interestRate.
+- `fundingInfo` (weight 1): ~730 rows - fundingIntervalHours MIXED
+  (1/2/4/8h histogram ~351/3/103/273), cap 0.003-0.03, floor -0.03,
+  interestRate.
+- `depth?symbol=&limit=` - weight by limit: 5/10/20/50 = 2, 100 = 5,
+  500 = 10, 1000 = 20 (client snaps requests down to a priced tier).
+- `klines` / `markPriceKlines` / `indexPriceKlines` -
+  `?symbol=&interval=&limit=`; weight 1 (limit<=100) .. 5.
+- `/trades?symbol=` - fresh keyless trades.
+- `openInterest?symbol=` - per-symbol snapshot ONLY (weight 1).
+  **`/futures/data/openInterestHist` returns 404** - no keyless OI
+  history exists; the gateway says so instead of inventing data.
+
+## sapi - spot (https://sapi.asterdex.com/api/v3/*)
+
+- MIGRATION note: the old `/sapi/v1/*` paths **404**; live base is
+  `/api/v3/*`.
+- Rate limit 6000 weight/min (separate bucket; same header).
+- `exchangeInfo`: 68 TRADING pairs plus TEST*-named junk symbols -
+  filtered by name in this gateway (flag to include).
+- `klines`, `depth`: live 200, keyless.
+- Spot `/trades`: path was uncertain at recon; probed in the smoke
+  script - if it 404s the tool degrades to an honest error dict.
+
+## tapi - Aster Chain JSON-RPC (https://tapi.asterdex.com/info)
+
+- Body `{"jsonrpc":"2.0","id":1,"method":"aster_getBalance","params":
+  ["0x...", "latest"]}` (PARAMS IS AN ARRAY: address + blockTag; the
+  object form `{"userAddress": ...}` returns HTTP 400 - live-verified)
+  - answers KEYLESS, but **account privacy hides most accounts**:
+  private accounts return a result with only {address,
+  accountPrivacy: "enabled"} and no balances (observed on the BSC vault
+  address and a burn address). Empty = privacy, not an API failure -
+  the gateway returns an honest error-dict explaining why.
+- `aster_openOrders` on a privacy-hidden account returns JSON-RPC
+  -32603 (internal error) - also mapped to the privacy degradation
+  path.
+- Methods used (read-only): `aster_getBalance`, `aster_openOrders`,
+  `aster_userFills` (+ `aster_spotGetBalance` /
+  `aster_spotOpenOrders` / `aster_spotUserFills` variants).
+- `eth_*` NOT supported (eth_chainId -> -32601 method not found): the
+  Aster Chain EVM-RPC is closed.
+
+## Solana vault (https://api.mainnet-beta.solana.com)
+
+- `getSignaturesForAddress` for the Aster vault program
+  `EhUtRgu9iEbZXXRpEvDj6n1wnQRjMi2SERDo3c6bmN2c` - live 200 keyless,
+  fresh signatures (signature / slot / blockTime / err). Treated
+  politely (10 req/min local cap) - it is a free public node.
+
+## EVM vaults (BSC / ETH / ARB)
+
+- Vaults: BSC `0x128463A60784c4D3f46c23Af3f65Ed859Ba87974`, ETH
+  `0x604DD02d620633Ae427888d41bfd15e38483736E`, ARB
+  `0x9E36CB86a159d479cEd94Fa05036f235Ac40E1d5`.
+- Deposit flow = ERC-20 `Transfer` (topic0 `0xddf252ad...523b3ef`)
+  with `to` = vault, via `eth_getLogs`.
+- Free public RPCs reject even 300-block windows with **-32005
+  (limit exceeded)**, so the RPC URL comes from env:
+  `ASTER_EVM_RPC_URL` (generic) or `ASTER_EVM_RPC_URL_{BSC,ETH,ARB}`
+  (per-chain). Unset -> honest `"no RPC configured"` error dict -
+  never a traceback, never invented logs.
+
+## Endpoints NOT used, and why
+
+- **`/futures/data/*` history endpoints** - 404 on Aster (only
+  openInterestHist was probed; the futures/data tree is absent).
+- **WebSocket streams** (`fstream`/`sstream`) - deferred; the MCP
+  request/response model gains little from push feeds and the TTL
+  caches already cover freshness.
+- **Signed/trading endpoints** - out of scope by design: this gateway
+  is strictly read-only and keyless; no API keys ever enter the
+  process.
+- **aster-scan.com / asterscan.io explorers** - dead/unreachable at
+  recon time; not a dependency.

aster_agent_gateway-0.1.0/aster_mcp/__init__.py

@@ -0,0 +1,14 @@
+"""aster_mcp - read-only, keyless MCP gateway to Aster DEX public data.
+
+Package layout:
+    rest.py    stdlib-only REST client for fapi.asterdex.com/fapi/v3
+               and sapi.asterdex.com/api/v3 (weight-aware, TTL caches)
+    chain.py   stdlib-only clients for tapi (Aster Chain JSON-RPC),
+               Solana vault signatures and EVM vault Transfer logs
+    server.py  FastMCP server wiring the 13 read-only tools
+
+No API keys, no auth headers, no signing, no order placement - public
+data only.
+"""
+
+__version__ = "0.1.0"