Aster Agent Gateway

aster-agent-gateway

[CI] [PyPI] [PyPI downloads] [MCP Catalog] [License: MIT] [Python 3.11+]

Aster lists roughly 580 futures, and about 32 of them are things you would not expect on a crypto DEX: gold, oil, treasuries, single equities and index perps that trade 24/7 while the underlying market sleeps. This MCP server puts the whole board, plus ~68 spot pairs, funding, order books, klines and vault deposit flows, in front of an AI agent. Read-only and keyless; public endpoints only (fapi.asterdex.com/fapi/v3, sapi.asterdex.com/api/v3, tapi.asterdex.com/info, Solana RPC, optional EVM RPCs), cached and rate-limited.

Use cases

Funding first, because this is where Aster is different. Intervals vary per market, 1h to 8h; annualize naively and an 8h market reads 8x too cold. The screener computes every row from its own interval and shows cap/floor next to it, so a 4,148%/yr print comes with the context that explains it.

Then the TradFi board at 3am: gold at $4,365 with live volume, oil paying longs to hold (negative funding, -0.0001%/1h when we looked), Micron up 4.8% overnight. One API, same conventions as the crypto rows.

mark_index_divergence ranks all ~756 markets by mark-vs-index spread. The morning we captured it, RTXUSDT topped both that board (505 bps rich) and the funding board at once, which is the classic pre-squeeze picture. Vault deposit flows show who parks capital where; OI snapshots are per-symbol and honest about the fact that Aster has no keyless OI history.

Full walkthroughs: examples/use-cases.md.

Quickstart

Claude Code:

claude mcp add aster -- uvx aster-agent-gateway

stdio (default, for local agents):

uvx aster-agent-gateway

or from a checkout:

git clone https://github.com/alekskram/aster-agent-gatewaycd aster-agent-gatewayuv syncuv run aster-agent-gateway

Claude Desktop / Cursor config:

{  "mcpServers": {    "aster": {      "command": "uvx",      "args": ["aster-agent-gateway"]    }  }}

Hosted form, streamable HTTP on port 8904:

uvx aster-agent-gateway --http             # 127.0.0.1:8904curl http://127.0.0.1:8904/health   # -> {"ok": true, "service": "aster-agent-gateway", ...}

[mcp_servers.aster]command = "uvx"args = ["aster-agent-gateway"]

# 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, osp = 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

Tools

All 13 tools are read-only (annotated readOnlyHint: true, destructiveHint: false).

Why a gateway and not the raw API?

Aster's fapi/sapi/tapi endpoints are plain REST. The traps are in the semantics:

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.

Part of the suite

Four sibling read-only MCP gateways, one style: keyless, cached, honest degradation.

All four are on glama.ai and PyPI; any of them installs with uvx <name>.

License

MIT.