aster-agent-gateway 0.1.0__py3-none-any.whl

aster_agent_gateway-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+aster_mcp/API_NOTES.md,sha256=LDIPy0Tdoktsb8y6jGML_5apzvK-yWKoPXBRRNU2fTE,4885
+aster_mcp/__init__.py,sha256=l12zxeqIENwd4xbClVO1kfAuZ-wmfJIqFZCetiDAfoE,533
+aster_mcp/chain.py,sha256=GMDMow4P1IGTuqdrIx-Ord82ZBWfY8GmKEl54x6fkfM,11256
+aster_mcp/rest.py,sha256=ZrApV4gzKraqsaOYoWYsCrQab3HN_WdImmcQ6S_VHig,16251
+aster_mcp/server.py,sha256=OD3_LxH9Y4ABVwTvb_cNhWwzyelIvT1p-dN18XtZjDo,48059
+aster_agent_gateway-0.1.0.dist-info/METADATA,sha256=aFo1iJ_35Y7PkebdCchPkx8kzwuzzctEWmihmcs2pfA,8558
+aster_agent_gateway-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+aster_agent_gateway-0.1.0.dist-info/entry_points.txt,sha256=VxYNjpiJndfRIL2_0ocomSfJiVVWd_2zw0q65BvrNYM,62
+aster_agent_gateway-0.1.0.dist-info/licenses/LICENSE,sha256=ViMP6VKf71rJhWk_KyCZFUL_8oOL-_Dpq3SRfpO4vJU,1089
+aster_agent_gateway-0.1.0.dist-info/RECORD,,

aster_agent_gateway-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

aster_agent_gateway-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aster-agent-gateway = aster_mcp.server:main

aster_agent_gateway-0.1.0.dist-info/licenses/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_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_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"

aster_mcp/chain.py

@@ -0,0 +1,287 @@
+"""Stdlib-only clients for Aster on-chain surfaces: tapi (Aster Chain
+JSON-RPC), Solana vault signatures, and EVM vault Transfer logs.
+
+tapi  POST https://tapi.asterdex.com/info  {"jsonrpc":"2.0","id":1,
+      "method":"aster_getBalance","params":{...}} - answers keyless,
+      but account privacy hides most accounts: private accounts return
+      an EMPTY result (or accountPrivacy:"enabled") - that is an honest
+      degradation, never an error-dict pretending data exists. Methods
+      used (read-only): aster_getBalance / aster_openOrders /
+      aster_userFills (+ spot variants when they exist).
+
+solana RPC https://api.mainnet-beta.solana.com getSignaturesForAddress
+      for the Aster vault program
+      EhUtRgu9iEbZXXRpEvDj6n1wnQRjMi2SERDo3c6bmN2c (keyless, fresh
+      signatures: signature/slot/blockTime/err).
+
+evm   eth_getLogs Transfer(topic0=0xddf252ad...) to the Aster vault
+      contracts on BSC/ETH/ARB. Free public RPCs reject even 300-block
+      windows with -32005 (limit exceeded), so the RPC URL comes from
+      env ASTER_EVM_RPC_URL / ASTER_EVM_RPC_URL_{BSC,ETH,ARB}; when
+      unset the tools return an honest "no RPC configured" error dict -
+      NEVER an invented log, NEVER a traceback.
+
+Each surface keeps its own small rate ledger (solana 10 req/min is
+polite for a free public node; tapi 30/min) and raises RpcError with a
+taxonomy kind so tools can degrade honestly.
+"""
+from __future__ import annotations
+
+import itertools
+import json
+import os
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+TAPI_URL = "https://tapi.asterdex.com/info"
+SOLANA_RPC = "https://api.mainnet-beta.solana.com"
+ASTER_SOLANA_VAULT = "EhUtRgu9iEbZXXRpEvDj6n1wnQRjMi2SERDo3c6bmN2c"
+
+# EVM vaults (official Aster docs; chain -> vault address)
+EVM_VAULTS = {
+    "bsc": "0x128463a60784c4d3f46c23af3f65ed859ba87974",
+    "eth": "0x604dd02d620633ae427888d41bfd15e38483736e",
+    "arb": "0x9e36cb86a159d479ced94fa05036f235ac40e1d5",
+}
+TRANSFER_TOPIC = ("0xddf252ad1be2c89b69c2b068fc378daa952ba7f1"
+                  "63c4a11628f55a4df523b3ef")
+
+UA = {"User-Agent": "aster-agent-gateway/0.1",
+      "Content-Type": "application/json"}
+
+_TIMEOUT = 15.0
+_RETRIES = 2  # these are secondary surfaces: fail fast, degrade honestly
+
+_IDS = itertools.count(1)
+
+
+class RpcError(Exception):
+    """On-chain RPC failure with a taxonomy kind.
+
+    kind: "rpc-limit" (local request budget / server 429), "rpc-http"
+    (JSON-RPC error payload, e.g. -32005 range limit), "rpc-timeout",
+    "rpc-network", "no-rpc" (env not configured - EVM only).
+    """
+
+    def __init__(self, message: str, *, kind: str,
+                 status: int | None = None, code: int | None = None):
+        super().__init__(message)
+        self.kind = kind
+        self.status = status
+        self.code = code
+
+
+# ---------------------------------------------------------------------------
+# Shared rolling-window request budgets (one per surface)
+
+_BUDGETS: dict[str, dict] = {
+    "tapi": {"limit": 30, "ts": []},
+    "solana": {"limit": 10, "ts": []},
+    "evm": {"limit": 20, "ts": []},
+}
+_BUDGET_LOCK = threading.Lock()
+
+
+def requests_last_minute(surface: str) -> int:
+    """Requests admitted on a surface in the rolling 60s (test hook)."""
+    with _BUDGET_LOCK:
+        _prune(surface, time.monotonic())
+        return len(_BUDGETS[surface]["ts"])
+
+
+def _prune(surface: str, now: float) -> None:
+    cutoff = now - 60.0
+    lst = _BUDGETS[surface]["ts"]
+    while lst and lst[0] <= cutoff:
+        lst.pop(0)
+
+
+def _admit(surface: str) -> None:
+    with _BUDGET_LOCK:
+        now = time.monotonic()
+        _prune(surface, now)
+        b = _BUDGETS[surface]
+        if len(b["ts"]) >= b["limit"]:
+            raise RpcError(
+                f"{surface} local request budget exhausted "
+                f"({b['limit']}/min); wait for the window to roll",
+                kind="rpc-limit")
+        b["ts"].append(now)
+
+
+# ---------------------------------------------------------------------------
+# Generic JSON-RPC POST (tapi / solana / evm share the shape)
+
+def rpc_post(url: str, method: str, params: list | dict | None = None,
+             surface: str = "tapi", retries: int = _RETRIES) -> Any:
+    """POST one JSON-RPC request; returns the `result` field.
+
+    Honors JSON-RPC error payloads (code/message) and retries 429/5xx
+    twice. Raises RpcError on final failure."""
+    body = json.dumps({"jsonrpc": "2.0", "id": next(_IDS),
+                       "method": method, "params": params or {}}).encode()
+    for attempt in range(retries):
+        _admit(surface)
+        req = urllib.request.Request(url, data=body, headers=UA)
+        try:
+            with urllib.request.urlopen(req, timeout=_TIMEOUT) as r:
+                payload = json.loads(r.read())
+        except urllib.error.HTTPError as e:
+            if (e.code in (429, 418) or 500 <= e.code <= 599) \
+                    and attempt < retries - 1:
+                ra = e.headers.get("Retry-After")
+                try:
+                    delay = min(30.0, float(ra)) if ra else 2.0 * (attempt + 1)
+                except ValueError:
+                    delay = 2.0 * (attempt + 1)
+                time.sleep(delay)
+                continue
+            try:
+                detail = e.read(300).decode("utf-8", "replace")
+            except Exception:
+                detail = ""
+            raise RpcError(
+                f"{surface} rpc {e.code} on {method}: "
+                f"{detail or e.reason}",
+                kind="rpc-limit" if e.code in (429, 418) else "rpc-http",
+                status=e.code) from e
+        except TimeoutError as e:
+            raise RpcError(f"{surface} rpc timeout on {method} after "
+                           f"{_TIMEOUT}s", kind="rpc-timeout") from e
+        except (urllib.error.URLError, ConnectionError, OSError) as e:
+            if isinstance(e, urllib.error.URLError) and isinstance(
+                    getattr(e, "reason", None), TimeoutError):
+                raise RpcError(f"{surface} rpc timeout on {method} after "
+                               f"{_TIMEOUT}s", kind="rpc-timeout") from e
+            if attempt < retries - 1:
+                time.sleep(2.0 * (attempt + 1))
+                continue
+            raise RpcError(f"{surface} rpc unreachable on {method}: {e}",
+                           kind="rpc-network") from e
+        except ValueError as e:
+            raise RpcError(f"{surface} rpc invalid JSON on {method}: {e}",
+                           kind="rpc-http") from e
+        if "error" in payload:
+            err = payload.get("error") or {}
+            raise RpcError(
+                f"{surface} rpc error on {method}: "
+                f"{err.get('code')} {err.get('message')}",
+                kind="rpc-http", code=err.get("code")) from None
+        if "result" not in payload:
+            raise RpcError(f"{surface} rpc malformed response on "
+                           f"{method}: no result", kind="rpc-http")
+        return payload["result"]
+    raise RpcError(f"{surface} rpc failed on {method}", kind="rpc-network")
+
+
+# ---------------------------------------------------------------------------
+# tapi: Aster Chain account views (read-only, keyless, privacy-aware)
+
+TAPI_METHODS = {
+    "balance": "aster_getBalance",
+    "openOrders": "aster_openOrders",
+    "userFills": "aster_userFills",
+    "spotBalance": "aster_spotGetBalance",
+    "spotOpenOrders": "aster_spotOpenOrders",
+    "spotUserFills": "aster_spotUserFills",
+}
+
+
+def tapi_call(method: str, address: str, extra: dict | None = None) -> Any:
+    """One tapi read for `address`. Params use the DOCUMENTED array form
+    [address, blockTag] (live-verified: the object {"userAddress": ...}
+    form returns HTTP 400). extra params are ignored for now - tapi
+    methods take only the two positional params. Returns the raw
+    result; the SERVER layer decides privacy-empty vs data (see
+    server.account_view)."""
+    params: list = [(address or "").strip(), "latest"]
+    return rpc_post(TAPI_URL, method, params, surface="tapi")
+
+
+def tapi_balance(address: str) -> Any:
+    return tapi_call("aster_getBalance", address)
+
+
+def tapi_open_orders(address: str) -> Any:
+    return tapi_call("aster_openOrders", address)
+
+
+def tapi_user_fills(address: str) -> Any:
+    return tapi_call("aster_userFills", address)
+
+
+# ---------------------------------------------------------------------------
+# Solana vault signatures
+
+def solana_vault_signatures(limit: int = 20,
+                            vault: str = ASTER_SOLANA_VAULT) -> list:
+    """getSignaturesForAddress on the Aster Solana vault program.
+    Rows: signature/slot/blockTime/err (newest first)."""
+    n = max(1, min(100, int(limit)))
+    return rpc_post(SOLANA_RPC, "getSignaturesForAddress",
+                    [vault, {"limit": n}], surface="solana") or []
+
+
+# ---------------------------------------------------------------------------
+# EVM vault Transfer logs (env-gated, honest when unconfigured)
+
+def evm_rpc_url(chain: str) -> str | None:
+    """ASTER_EVM_RPC_URL_{CHAIN} wins over the generic
+    ASTER_EVM_RPC_URL; None when nothing is configured."""
+    chain = (chain or "").lower()
+    specific = os.environ.get(f"ASTER_EVM_RPC_URL_{chain.upper()}")
+    if specific:
+        return specific
+    return os.environ.get("ASTER_EVM_RPC_URL")
+
+
+def evm_vault_transfers(chain: str, from_block: int, to_block: int,
+                        limit_blocks: int = 300) -> list:
+    """eth_getLogs Transfer->vault on `chain`. The window is clamped to
+    `limit_blocks` (free RPCs reject wide ranges with -32005). Raises
+    RpcError(kind="no-rpc") when no RPC is configured."""
+    chain = (chain or "").lower()
+    if chain not in EVM_VAULTS:
+        raise ValueError(f"unknown chain {chain!r}: use one of "
+                         f"{', '.join(sorted(EVM_VAULTS))}")
+    url = evm_rpc_url(chain)
+    if not url:
+        raise RpcError(
+            f"no RPC configured for {chain}: set ASTER_EVM_RPC_URL or "
+            f"ASTER_EVM_RPC_URL_{chain.upper()} (free public RPCs reject "
+            f"vault log queries with -32005, so a real endpoint is "
+            f"required)", kind="no-rpc")
+    vault = EVM_VAULTS[chain]
+    lo = max(0, min(from_block, to_block - limit_blocks))
+    hi = to_block
+    logs = rpc_post(url, "eth_getLogs", [{
+        "fromBlock": hex(lo), "toBlock": hex(hi),
+        "address": vault,
+        "topics": [TRANSFER_TOPIC, None,
+                   "0x" + "0" * 24 + vault[2:]],  # Transfer(_, vault)
+    }], surface="evm")
+    return logs or []
+
+
+def evm_latest_block(chain: str) -> int:
+    """eth_blockNumber on the configured RPC (int)."""
+    url = evm_rpc_url(chain)
+    if not url:
+        raise RpcError(f"no RPC configured for {chain}",
+                       kind="no-rpc")
+    res = rpc_post(url, "eth_blockNumber", [], surface="evm")
+    try:
+        return int(res, 16)
+    except (TypeError, ValueError):
+        raise RpcError(f"eth_blockNumber returned non-hex: {res!r}",
+                       kind="rpc-http")
+
+
+def reset_budgets() -> None:
+    """Clear the per-surface request ledgers (test hook)."""
+    with _BUDGET_LOCK:
+        for b in _BUDGETS.values():
+            b["ts"].clear()