| name | hypaper-api |
| description | HyPaper paper trading API reference. Use when working with HyPaper endpoints, placing paper trades, querying positions, or integrating with the HyperLiquid-compatible paper trading backend. |
HyPaper — Agent Paper Trading Guide
Paper trading backend for HyperLiquid. Fake money, real prices, same wire format.
Quick Start
- Discover assets:
POST /info {"type": "meta"} — response universe[] maps coin names to asset indices (a)
- Check balance:
POST /hypaper {"type": "getAccountInfo", "user": "0xagent"} — auto-created with $100k USDC
- Get prices:
POST /info {"type": "allMids"}
- Place order:
POST /exchange {"wallet": "0xagent", "action": {"type": "order", "grouping": "na", "orders": [{"a": 0, "b": true, "p": "90000", "s": "0.01", "r": false, "t": {"limit": {"tif": "Gtc"}}}]}}
- Monitor:
POST /info {"type": "clearinghouseState", "user": "0xagent"}
- Close: Same as place order but
"b": false, "r": true
Base URL & Auth
- Base URL:
http://localhost:3000 (configurable via PORT env var)
- Auth: None. Wallet address passed in request body. Any string works.
- Content-Type:
application/json for all endpoints.
- Health check:
GET /health
Endpoints Overview
| Endpoint | Purpose |
|---|
POST /exchange | Place orders, cancel orders, update leverage |
POST /info | Query prices, positions, orders, fills, market data |
POST /hypaper | Reset account, set balance, get account info |
WS /ws | Real-time allMids, l2Book, orderUpdates, userFills |
Key Mechanics
- Order matching runs on every price tick from HyperLiquid
- Fill price is VWAP from real L2 order book, clamped to limit price
- Fees: Taker 3.5 bps, Maker 1 bp (enabled by default, matches HL).
crossed: true = taker
- Funding: Applied every 8h from live HL rates. Longs pay positive rates, shorts receive
- Margin:
marginNeeded = (size * price) / leverage, default 20x cross
- TIF:
Gtc (rests on book), Ioc (fill or reject), Alo (post-only)
- Position flipping: excess size becomes opposite direction at fill price
- reduceOnly orders skip margin checks
Wire Field Reference
| Wire | Meaning | Type |
|---|
a | asset index | number |
b | isBuy | boolean |
p | limit price | string |
s | size | string |
r | reduceOnly | boolean |
t | order type (tif + trigger) | object |
c | client order ID | string (optional) |
o | order ID (for cancels) | number |
Additional Resources
- For complete API reference with all request/response shapes, error codes, and examples, see api-reference.md
