Hyperliquid Agent Gateway

OHLCV candles from candleSnapshot for `coin`: rows newest-first, capped at `limit` (max 500). startTime is computed so roughly `limit` candles of `interval` are requested. Valid intervals: 1m, 15m, 1h, 4h, 1d, 1w, 1M. Example: candles(coin="BTC", interval="4h", limit=50)

Rank ALL perps from ONE metaAndAssetCtxs call by `metric` (premium default; oi / volume options) and return the topN rows with premium, oi, dayVolume, markPx. fundingHistory rows are fetched ONLY for the topN coins (weight economy) and appear as 'funding_history' on rows where that call succeeded. Example: funding_carry_screener(topN=5, metric="premium")

Hourly funding history for `coin` (fundingHistory) plus the CURRENT premium from metaAndAssetCtxs (premium_now): rows carry fundingRate (hourly), premium, time (ms). Newest-first, capped at `limit` (max 500). Example: funding_history(coin="BTC", limit=48)

KEY TOOL. Liquidation risk for one perp account (clearinghouseState + userFunding): margin summary (accountValue, totalRawUsd, totalMarginUsed, withdrawable), cross maintenance margin, per-position leverage/entry/mark/unrealizedPnl and liquidationPx when the venue provides it. Positions in the LIVE clearinghouseState response carry NO markPx: mark is resolved per coin from metaAndAssetCtxs (fallback allMids) and each row says where it came from in mark_px_source ('position' | 'metaAndAssetCtxs' | 'allMids' | null). When liquidationPx is null, liq_distance_pct is an ESTIMATE from the maintenance-margin ratio (crossMaintenanceMarginUsed / marginSummary.accountValue; isolated positions use marginUsed / positionValue) - flagged 'estimated': true, liqPx stays null (honest). funding_drag totals negative funding payments from userFunding. Address must be 0x + 40 hex. Example: liquidation_risk(address="0x...")

Perp market overview from ONE metaAndAssetCtxs call (~233 perps): per-coin mark, open interest, day volume, premium (funding basis), max leverage, plus totals (sum OI, sum day volume). Rows are sorted by `sort` in {open_interest (default), volume, premium} descending and capped at `limit` (max 100). Example: market_overview(limit=10)

Aggregated order book for one coin from l2Book: `depth` levels per side (default 10, max 100), aggregated by the book's nSigFigs precision (default taken from the response levels), with total liquidity (sum px*sz) per side. Example: order_book(coin="ETH", depth=20)

One coin's live quote from l2Book: bid/ask/mid/spread and top-of-book sizes. mid is the book midpoint ((bid+ask)/2) whenever both sides are present ('book'); allMids is only a labeled fallback when the book lacks a side ('allMids'), so mid never escapes the [bid, ask] range. The coin is validated against the perp universe (spot '@{index}/NAME' pairs pass through to the book). Example: quote(coin="BTC")

Spot market overview (~326 pairs) from spotMeta + spotMetaAndAssetCtxs: pair rows (name, mark, day volume, OI where published) with HIP-1 <-> ERC-20 links resolved - '@{index}' spot coin names are mapped to token names via spotMeta.tokens. Sorted by day volume descending, capped at `limit` (max 100). Example: spot_overview(limit=10)

Recent ERC-20 Transfer events for `contract` on HyperEVM via eth_getLogs with an ADAPTIVE window (starts 30 blocks, halves on too-big/failing responses, doubles on quiet ones up to 60; active tokens need ~30-60 block windows). Rows (newest-first, max 500): from, to, value (raw/1e18, 6dp), txHash, blockNumber, ts when the log carries a timestamp. `from_block` anchors the walk (default: latest - 300). Errors degrade to an honest error dict naming the RpcError kind (rate-limit vs window-too-wide narrative). Example: token_transfers(contract="0x...", limit=50)

Trading profile for one address (userFills + userFunding + clearinghouseState): total closed PnL, fees (fee + builderFee), volume, fill count, win-rate-ish share of fills with closedPnl > 0, per-coin breakdown, net funding and open positions. `limit` caps fills analyzed (max 500, newest-first). Example: trader_activity(address="0x...", limit=100)

Recent public fills from recentTrades(coin) WITH both sides' addresses: rows (newest-first, max 500) carry side, px, sz, time, coin, hash and users [maker, taker]. Example: trades(coin="BTC", limit=10)

Wallet balances on HyperEVM + Hyperliquid spot: native balance (eth_getBalance), ERC-20 balances via eth_call balanceOf for up to 20 tokens resolved from spotMeta tokens with 0x contract addresses (cap respects the 100 req/min rpc budget), and Hyperliquid spot balances via spotClearinghouseState. Per-token rows: token, balance_raw (wei), balance (units, 6dp), source. Example: wallet_balance(address="0x...")