# Pa1m Hyperliquid — Full Agent Reference

Pa1m Hyperliquid is a pay-per-call API exposing real-time Hyperliquid perpetuals data.
Protocol: x402 (HTTP 402 Payment Required). Payment: USDC on Base (eip155:8453).
No API key, no account, no subscription. Pay only for what you use.

ERC-8004 agentId: 59960
MCP endpoint: https://hyperliquid.hypa1m.xyz/mcp
OpenAPI: https://hyperliquid.hypa1m.xyz/openapi.json

## How payment works
1. Make a request to any paid endpoint
2. Receive HTTP 402 with payment requirements (amount, wallet address, chain)
3. Sign USDC transferWithAuthorization on Base
4. Retry the same request with X-PAYMENT header
5. Receive data in the same lifecycle

## Pricing tiers
- Market data: $0.001/call (prices, meta, orderbook, candles)
- Strategic data: $0.003/call (funding, predicted-funding, portfolio, history)

## Endpoints

### GET /top — FREE
Returns live mid prices for BTC, ETH, SOL, BNB, XRP.
No payment needed. Cached 5 seconds server-side. Rate limit: 20 req/min per IP.
Response: {"BTC": "67234.5", "ETH": "3456.7", "SOL": "187.2", "BNB": "612.1", "XRP": "0.621"}

### GET /prices — $0.001
Returns mid prices for all ~170 Hyperliquid perpetual assets.
Response: {"BTC": "67234.5", "ETH": "3456.7", ...170 assets}

### GET /meta — $0.001
Returns asset universe with symbols, max leverage tiers, and margin table IDs.
Use when: you need to know available assets or leverage limits before trading.

### GET /orderbook/{coin} — $0.001
Returns L2 order book snapshot (up to 20 levels per side) for a specific coin.
Params: coin (e.g. BTC, ETH, SOL)
Response: {"coin":"BTC","levels":[[["67100.0","0.5"],["67050.0","1.2"]],[["67200.0","0.8"]]]}

### GET /candles/{coin}?interval=1h&lookback=100 — $0.001
Returns OHLCV candle data.
Params: coin, interval (1m,5m,15m,1h,4h,1d), lookback (number of candles, max 5000)
Response: [{"t":1784900000000,"o":"67000","h":"67500","l":"66800","c":"67234","v":"123.4"}, ...]

### GET /funding — $0.003
Returns current funding rates + open interest for all perps.
Use when: evaluating carry cost before opening a position.
Response: [{"coin":"BTC","funding":"0.0001","openInterest":"12345.6"}, ...]

### GET /predicted-funding — $0.003
Returns predicted funding rates for the next period.
UNIQUE: not available elsewhere in the x402 ecosystem.
Use when: finding funding arbitrage opportunities across venues.

### GET /portfolio/{address} — $0.003
Returns open perpetual positions and margin summary for a wallet address.
Params: address (0x... format)
Response: clearinghouse state with positions, margin, and unrealized PnL.

### GET /history/{address} — $0.003
Returns up to 2000 most recent trade fills for a wallet address.
Params: address (0x... format)
Response: array of fill objects with coin, price, size, side, time.

## Discovery surfaces
- llms.txt: https://hyperliquid.hypa1m.xyz/llms.txt
- llms-full.txt: https://hyperliquid.hypa1m.xyz/llms-full.txt
- catalog.txt: https://hyperliquid.hypa1m.xyz/catalog.txt
- endpoints.txt: https://hyperliquid.hypa1m.xyz/endpoints.txt
- prompt.txt: https://hyperliquid.hypa1m.xyz/prompt.txt
- openapi.json: https://hyperliquid.hypa1m.xyz/openapi.json
- agent.json: https://hyperliquid.hypa1m.xyz/.well-known/agent.json
- ERC-8004: https://8004scan.io/agents/base/59960

## Related Pa1m agents
- Pa1m SEO (website audit): https://seo.hypa1m.xyz/llms-full.txt
- Pa1m Reddit (Reddit data): https://reddit.hypa1m.xyz/llms-full.txt