# Hfun Labs Docs ## Hfun Sentry Gated access to the Alphaticks validator sentry via [aHYPESeat](/hfun-ahype/ahypeseat/introduction). ### Overview Hfun Sentry provides direct connection to the Alphaticks validator sentry node running in `ap-northeast-1` (Tokyo). This enables low-latency access to Hyperliquid L1 data for node operators. Access is managed through the aHYPESeat contract - users purchase a seat and whitelist their node's IP address. ### Benefits * **Low latency**: Direct connection to validator sentry in AWS Tokyo * **Reliable**: Enterprise-grade infrastructure * **Permissionless**: Purchase access via aHYPESeat contract ### Requirements * aHYPE collateral for seat purchase * A running [Hyperliquid node](https://github.com/hyperliquid-dex/node) * Static IP address for your node ## Setup ### 1. Purchase a Seat 1. Go to [alphaticks.io/alpha-hype-sentry](https://alphaticks.io/alpha-hype-sentry) 2. Connect your wallet 3. Purchase a seat by locking aHYPE collateral ### 2. Whitelist Your IP After purchasing a seat, configure your node's IP address: 1. Enter the static IP of your Hyperliquid node 2. Submit the whitelist transaction 3. Wait for confirmation ### 3. Configure Your Node Update your Hyperliquid node `gossip_config.json` to connect to the Alphaticks sentry: ```json { "root_node_ips": [ { "Ip": "3.114.22.239" } ], "try_new_peers": false, "chain": "Mainnet" } ``` See the [Hyperliquid node documentation](https://github.com/hyperliquid-dex/node) for full setup instructions. ### 4. Verify Connection Once configured, your node should sync from the Alphaticks sentry. Check your node logs to confirm the connection is established. ### Managing Your Seat * **Add collateral**: Top up aHYPE to maintain healthy collateral ratio * **Update IP**: Change your whitelisted IP if your node moves * **Monitor health**: Ensure your seat doesn't become liquidatable See [aHYPESeat documentation](/hfun-ahype/ahypeseat/introduction) for contract details and automation. ## Client Messages All messages sent from the client to the server. ### Subscribe ```json {"method": "subscribe", "subscription": {...}} ``` See [Subscriptions](./subscriptions) for available subscription types. ### Unsubscribe ```json {"method": "unsubscribe", "subscription": {...}} ``` ### Ping ```json {"method": "ping"} ``` The server responds with `{"channel": "pong"}`. ### Post (Query) ```json {"method": "post", "id": 123, "request": {...}} ``` See [Post Requests](./post-requests) for available query types. ### Example: wscat ```bash wscat -c "wss://api.example.com/ws?jwt=" ``` Once connected: ``` > {"method": "subscribe", "subscription": {"type": "l2Book", "coin": "BTC"}} > {"method": "ping"} > {"method": "unsubscribe", "subscription": {"type": "l2Book", "coin": "BTC"}} ``` ## HTTP Endpoints ### POST /info HTTP endpoint for querying order book data. Your IP address must be whitelisted - authentication is automatic. *** ### All Mids Request mid prices for all trading pairs. **Request:** ```json { "type": "allMids" } ``` **Response:** ```json { "BTC": "97000.5", "ETH": "3500.25", ... } ``` Returns a map of coin symbols to their mid prices as strings. *** ### Impact Price Calculate impact prices for a given coin and notional size. **Request:** ```json { "type": "impactPrice", "coin": "BTC", "notional": "10000" } ``` | Field | Type | Required | Description | | ---------- | ------ | -------- | ------------------------------------- | | `type` | string | yes | Must be `"impactPrice"` | | `coin` | string | yes | Trading pair (e.g., `"BTC"`, `"ETH"`) | | `notional` | string | yes | Notional size in USD | **Response:** ```json { "buyImpactPx": "97100.5", "sellImpactPx": "96900.3", "time": 1703271234000 } ``` | Field | Type | Description | | -------------- | -------------- | --------------------------------------------- | | `buyImpactPx` | string \| null | Price to buy the notional amount (walk asks) | | `sellImpactPx` | string \| null | Price to sell the notional amount (walk bids) | | `time` | number | Timestamp in milliseconds | **Error Responses:** * `400 Bad Request` - Invalid notional value * `500 Internal Server Error` - Failed to process request *** ### Example: cURL #### All Mids ```bash curl -X POST https://api.example.com/info \ -H "Content-Type: application/json" \ -d '{"type": "allMids"}' ``` #### Impact Price ```bash curl -X POST https://api.example.com/info \ -H "Content-Type: application/json" \ -d '{"type": "impactPrice", "coin": "BTC", "notional": "100000"}' ``` *** ### IP Whitelist Management Endpoints for managing IP whitelists. Requires signature authentication. **Authentication Header:** ``` Authorization: Signature ts=,sig= ``` | Parameter | Type | Description | | --------- | ------ | ------------------------------------------------------------- | | `ts` | number | Unix timestamp in seconds (must be within 60s of server time) | | `sig` | string | Ethereum signature (hex with 0x prefix) | Sign the message `hfun-feed:` with your Ethereum wallet. The signature must be from an address with an active AlphaHype seat. **Example (JavaScript/ethers.js):** ```javascript const timestamp = Math.floor(Date.now() / 1000); const message = `hfun-feed:${timestamp}`; const signature = await wallet.signMessage(message); const headers = { 'Authorization': `Signature ts=${timestamp},sig=${signature}`, 'Content-Type': 'application/json' }; ``` *** #### POST /ip/add Add an IP address to the whitelist for the authenticated address. **Request:** ```json { "ip": "203.0.113.42" } ``` | Field | Type | Required | Description | | ----- | ------ | -------- | --------------------------- | | `ip` | string | yes | IPv4 or IPv6 address to add | **Response (200 OK):** ```json { "status": "ok", "ip": "203.0.113.42" } ``` **Errors:** * `400 Bad Request` - Invalid IP address format or IP already whitelisted * `401 Unauthorized` - Invalid or missing signature * `403 Forbidden` - Signer does not have an active seat, or max IPs per seat exceeded * `503 Service Unavailable` - IP whitelist feature not enabled *** #### POST /ip/remove Remove an IP address from the whitelist for the authenticated address. **Request:** ```json { "ip": "203.0.113.42" } ``` | Field | Type | Required | Description | | ----- | ------ | -------- | ------------------------------ | | `ip` | string | yes | IPv4 or IPv6 address to remove | **Response (200 OK):** ```json { "status": "ok", "ip": "203.0.113.42" } ``` **Errors:** * `400 Bad Request` - Invalid IP address format * `401 Unauthorized` - Invalid or missing signature * `403 Forbidden` - Signer does not have an active seat * `503 Service Unavailable` - IP whitelist feature not enabled *** #### POST /ip/list List all whitelisted IP addresses for the authenticated address. **Request:** Empty body or `{}`. **Response (200 OK):** ```json { "ips": [ "203.0.113.42", "198.51.100.10" ] } ``` **Errors:** * `401 Unauthorized` - Invalid or missing signature * `403 Forbidden` - Signer does not have an active seat * `503 Service Unavailable` - IP whitelist feature not enabled *** ### Example: IP Management with cURL #### Add IP ```bash curl -X POST https://api.example.com/ip/add \ -H "Content-Type: application/json" \ -H "Authorization: Signature ts=1234567890,sig=0x..." \ -d '{"ip": "203.0.113.42"}' ``` #### Remove IP ```bash curl -X POST https://api.example.com/ip/remove \ -H "Content-Type: application/json" \ -H "Authorization: Signature ts=1234567890,sig=0x..." \ -d '{"ip": "203.0.113.42"}' ``` #### List IPs ```bash curl -X POST https://api.example.com/ip/list \ -H "Content-Type: application/json" \ -H "Authorization: Signature ts=1234567890,sig=0x..." \ -d '{}' ``` ## HFun Feed WebSocket API Real-time order book data from Hyperliquid node infrastructure. ### Overview This server provides real-time order book data from Hyperliquid node infrastructure. It implements endpoints compatible with [Hyperliquid's official API](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions), with extensions. ### AlphaHype Seats Access to the API requires an AlphaHype seat. The seat system is an on-chain smart contract on the Hyper EVM with a limited number of seats available (currently 10). #### How It Works 1. **Purchase a seat** by depositing aHYPE tokens as collateral 2. **Whitelist your IP** via the [`/ip/add`](./http-endpoints)#post-ipadd) endpoint 3. **Connect** - authentication is automatic once your IP is whitelisted #### Pricing Model Seat fees are based on utilization - the more seats occupied, the higher the fee rate: * Fee rate scales linearly from a minimum to maximum rate * Fees accrue per second while you hold a seat * Higher utilization = higher fees for all seat holders #### Collateral & Health * Your collateral must always cover your accrued fees (debt) * If your debt exceeds your collateral, your position becomes unhealthy * Unhealthy seats are automatically disconnected from the API * Unhealthy positions can be liquidated ("kicked"), forfeiting the collateral * Add collateral or repay fees to maintain a healthy position #### Management Seats can be purchased and managed on [alphaticks](https://alphaticks.io/alpha-hype-api). ### Available Subscriptions | Type | Description | | ----------------------------------------------- | ---------------------------------------------------- | | [`l1Book`](./subscriptions/l1-book) | Top of book (best bid/ask) | | [`l2Book`](./subscriptions/l2-book) | Aggregated price levels (periodic snapshots) | | [`l3Book`](./subscriptions/l3-book) | Order-level data, lightweight fields | | [`l4Book`](./subscriptions/l4-book) | Order-level data, full details (triggers, TIF, etc.) | | [`trades`](./subscriptions/trades) | Real-time trade stream | | [`candle`](./subscriptions/candles) | Real-time candlestick data | | [`allMids`](./subscriptions/all-mids) | Mid prices for all trading pairs | | [`impactPrice`](./subscriptions/impact-price) | Impact price calculations | | [`orderUpdates`](./subscriptions/order-updates) | Real-time order status updates | | [`userFills`](./subscriptions/user-fills) | Real-time fill notifications | ### Available Queries | Type | Description | | ----------------------------- | ------------------------------ | | [`l3Orders`](./post-requests) | Query L3 orders by price range | | [`l4Orders`](./post-requests) | Query L4 orders by price range | ## Post Requests (Queries) Query orders by price range without subscribing to full book. ### Request Format ```json { "method": "post", "id": 123, "request": { "type": "info", "payload": { "type": "l4Orders", "coin": "BTC", "pxMin": "35000", "pxMax": "37000" } } } ``` ### Payload Types | Type | Description | | ---------- | ------------------------------ | | `l4Orders` | Query L4 orders in price range | | `l3Orders` | Query L3 orders in price range | ### Payload Fields | Field | Type | Description | | ------- | ---------------------------- | ------------------------- | | `type` | `"l4Orders"` \| `"l3Orders"` | Query type | | `coin` | string | Trading pair | | `pxMin` | string | Minimum price (inclusive) | | `pxMax` | string | Maximum price (inclusive) | ### Response ```json { "channel": "post", "data": { "id": 123, "response": { "type": "info", "payload": { "type": "l4Orders", "data": { "coin": "BTC", "time": 1699900000000, "orders": [ [/* bids */], [/* asks */] ] } } } } } ``` ### Response Fields | Field | Type | Description | | ------------------------------ | ------ | -------------------------------- | | `id` | number | Request ID (echoed from request) | | `response.type` | string | Response type (`"info"`) | | `response.payload.type` | string | Query type | | `response.payload.data.coin` | string | Trading pair | | `response.payload.data.time` | number | Timestamp | | `response.payload.data.orders` | array | `[bids, asks]` arrays | ### Example: Query L3 Orders **Request:** ```json { "method": "post", "id": 1, "request": { "type": "info", "payload": { "type": "l3Orders", "coin": "ETH", "pxMin": "3400", "pxMax": "3600" } } } ``` **Response:** ```json { "channel": "post", "data": { "id": 1, "response": { "type": "info", "payload": { "type": "l3Orders", "data": { "coin": "ETH", "time": 1699900000000, "orders": [ [ {"user": "0x...", "coin": "ETH", "side": "B", "limitPx": "3500.0", "sz": "1.0", "oid": 123, "timestamp": 1699899000000} ], [ {"user": "0x...", "coin": "ETH", "side": "A", "limitPx": "3550.0", "sz": "2.0", "oid": 456, "timestamp": 1699899500000} ] ] } } } } } ``` ## Rate Limits Rate limits are enforced per authenticated identity (Ethereum address or Telegram user ID). All limits are shared across your WebSocket connections - if you open multiple connections, they draw from the same pool. ### Connections Each identity can maintain a limited number of concurrent WebSocket connections. AlphaHype users can open up to **10 connections**, while Telegram users can open up to **20 connections**. This allows you to run multiple clients or services under the same identity without interference. If you try to open a new connection after reaching the limit, it will be rejected with HTTP 429. ### Subscriptions You can have up to **100 active subscriptions** across all your connections. When you hit the limit, new `subscribe` requests will fail, but your existing subscriptions keep working. Unsubscribe from channels you no longer need to free up slots. ### Unique Users For user-specific subscriptions (`orderUpdates` and `userFills`), there's a limit of **10 unique user addresses** you can track across all connections. This prevents any single client from monitoring too many accounts. Subscribing to both `orderUpdates` and `userFills` for the same address counts as just one unique user. When you close a connection, the user slots it was using become available again. ### Messages Inbound WebSocket messages are limited to **1,000 per minute** with a small burst allowance for temporary spikes. This includes all message types: `subscribe`, `unsubscribe`, `ping`, and `post` requests. Under normal usage you won't hit this limit - it's primarily there to protect against runaway clients or bugs that might flood the server. ### Inflight Posts The `post` method for queries allows up to **100 concurrent requests** awaiting response. This is a high limit that accommodates heavy query workloads while preventing any single client from monopolizing server resources. If you hit this limit, wait for some of your pending requests to complete before sending more. ### HTTP Requests The HTTP `/info` endpoint is limited to **30 requests per minute**. For real-time data, prefer WebSocket subscriptions which don't count against this limit. ### Errors When any rate limit is exceeded, the server responds with: ```json { "channel": "error", "data": { "error": "rate limit exceeded" } } ``` For connection limits, the WebSocket handshake is rejected with HTTP 403. ## Server Messages All server messages have this structure: ```json { "channel": "", "data": { ... } } ``` ### Channels | Channel | Description | | ---------------------- | ------------------------------------ | | `subscriptionResponse` | Confirms subscription/unsubscription | | `l1Book` | Top of book data | | `l2Book` | Aggregated book levels | | `l3Book` | Order-level book (lightweight) | | `l4Book` | Order-level book (full detail) | | `allMids` | All mid prices | | `trades` | Trade stream | | `candle` | Candlestick data | | `impactPrice` | Impact price calculations | | `orderUpdates` | Order status updates | | `userFills` | User fill notifications | | `post` | Query response | | `pong` | Ping response | | `error` | Error message | ### Subscription Response Confirms subscription or unsubscription. ```json { "channel": "subscriptionResponse", "data": { "method": "subscribe", "subscription": { "type": "l2Book", "coin": "BTC", ... } } } ``` ### Pong Response to ping. ```json { "channel": "pong" } ``` ### Error ```json { "channel": "error", "data": { "error": "Invalid subscription based on universe: ..." } } ``` #### Error Types * `Invalid websocket request` * `Invalid spot subscription` * `Invalid subscription based on universe` * `Already subscribed` * `Already unsubscribed` * `Failed to get order book universe` * `Failed to get order book snapshot` ## Subscriptions ### Authentication Your IP address must be whitelisted to connect. Once whitelisted via the [`/ip/add`](./http-endpoints)#post-ipadd) endpoint, authentication is automatic - no headers or query parameters needed. The server checks the client IP against the whitelist. If found, the connection is authenticated under the associated AlphaHype seat holder's address. IP whitelisting can be managed on [alphaticks](https://alphaticks.io/alpha-hype-api). *** ### Subscription Types The `subscription` field in subscribe/unsubscribe messages is a discriminated union based on the `type` property. | Type | Description | Updates | | ----------------------------------------------- | ------------------------ | ---------------------- | | [`l1Book`](./subscriptions/l1-book) | Top of book | Periodic snapshots | | [`l2Book`](./subscriptions/l2-book) | Aggregated price levels | Periodic snapshots | | [`l3Book`](./subscriptions/l3-book) | Order-level, lightweight | Snapshot + incremental | | [`l4Book`](./subscriptions/l4-book) | Order-level, full detail | Snapshot + incremental | | [`trades`](./subscriptions/trades) | Trade stream | Real-time | | [`candle`](./subscriptions/candles) | Candlestick data | Real-time | | [`allMids`](./subscriptions/all-mids) | All mid prices | Periodic (1s) | | [`impactPrice`](./subscriptions/impact-price) | Impact prices | Periodic | | [`orderUpdates`](./subscriptions/order-updates) | Order status | Real-time | | [`userFills`](./subscriptions/user-fills) | User fills | Real-time | ### Coin Parameter Most subscriptions require a `coin` parameter: * Perpetual contracts: `"BTC"`, `"ETH"`, `"SOL"`, etc. * Spot markets: Use the `@` prefix, e.g., `"@1"` for spot asset ID 1 ### Rate Limits See [Rate Limits](./rate-limits) for subscription and message limits. ## TypeScript Types Complete TypeScript type definitions for the WebSocket API. ### Subscription Types ```typescript type Subscription = | { type: 'l2Book'; coin: string; nSigFigs?: number; nLevels?: number; mantissa?: number; interval?: string } | { type: 'l3Book'; coin: string; snapshot?: boolean } | { type: 'l4Book'; coin: string; snapshot?: boolean } | { type: 'trades'; coin: string; withSideInfo?: boolean } | { type: 'candle'; coin: string; interval: string } | { type: 'l1Book'; coin: string; interval?: string } | { type: 'allMids' } | { type: 'impactPrice'; coin: string; notional: string; interval?: string } | { type: 'orderUpdates'; user: string } | { type: 'userFills'; user: string; aggregateByTime?: boolean }; ``` ### Client Messages ```typescript type ClientMessage = | { method: 'subscribe'; subscription: Subscription } | { method: 'unsubscribe'; subscription: Subscription } | { method: 'ping' } | { method: 'post'; id: number; request: PostRequest }; ``` ### Server Messages ```typescript type ServerMessage = | { channel: 'subscriptionResponse'; data: ClientMessage } | { channel: 'l1Book'; data: L1BookData } | { channel: 'l2Book'; data: L2BookData } | { channel: 'l3Book'; data: L3BookSnapshot | L3BookUpdates } | { channel: 'l4Book'; data: L4BookSnapshot | L4BookUpdates } | { channel: 'allMids'; data: AllMidsData } | { channel: 'trades'; data: Trade[] } | { channel: 'candle'; data: Candle } | { channel: 'impactPrice'; data: ImpactPriceData } | { channel: 'orderUpdates'; data: OrderUpdate[] } | { channel: 'userFills'; data: Fill[] } | { channel: 'post'; data: PostResponse } | { channel: 'pong' } | { channel: 'error'; data: { error: string } }; ``` ### HTTP Types ```typescript type InfoRequest = | { type: 'allMids' } | { type: 'impactPrice'; coin: string; notional: string }; interface ImpactPriceHttpResponse { buyImpactPx: string | null; sellImpactPx: string | null; time: number; } ``` ### Common Types ```typescript type Side = 'A' | 'B'; ``` ### L1 Book Data ```typescript interface L1BookData { coin: string; time: number; bid: Level | null; ask: Level | null; } interface Level { px: string; sz: string; n: number; } ``` ### L2 Book Data ```typescript interface L2Level { px: string; sz: string; n: number; } interface L2BookData { coin: string; time: number; levels: [L2Level[], L2Level[]]; // [bids, asks] } ``` ### L3 Book Data ```typescript interface L3Order { user: string; coin: string; side: Side; limitPx: string; sz: string; oid: number; timestamp: number; } interface L3BookSnapshot { coin: string; time: number; height: number; sequence: number; levels: [L3Order[], L3Order[]]; } interface L3BookUpdates { time: number; height: number; diffs: SequencedOrderDiff[]; } ``` ### L4 Book Data ```typescript interface L4Order extends L3Order { triggerCondition: string; isTrigger: boolean; triggerPx: string; isPositionTpsl: boolean; reduceOnly: boolean; orderType: 'Market' | 'Limit' | 'Stop Market' | 'Stop Limit' | 'Take Profit Limit' | 'Take Profit Market' | 'Vault Close'; tif?: string; cloid?: string; } interface L4BookSnapshot { coin: string; time: number; height: number; sequence: number; levels: [L4Order[], L4Order[]]; } interface L4BookUpdates { time: number; height: number; orders: OrderStatus[]; diffs: SequencedOrderDiff[]; } interface OrderStatus { time: string; user: string; status: 'open' | 'filled' | 'canceled' | 'triggered' | 'rejected'; order: L4Order; } ``` ### Order Diffs ```typescript type RawBookDiff = | { New: { sz: string } } | { Update: { origSz: string; newSz: string } } | 'Remove'; interface OrderDiff { user: string; oid: number; px: string; coin: string; side: Side; rawBookDiff: RawBookDiff; } interface SequencedOrderDiff extends OrderDiff { sequence: number; } ``` ### Order Updates ```typescript interface OrderUpdate { order: OrderUpdateInner; status: string; statusTimestamp: number; } interface OrderUpdateInner { coin: string; side: Side; limitPx: string; sz: string; oid: number; timestamp: number; origSz: string; cloid?: string; } ``` ### All Mids Data ```typescript interface AllMidsData { mids: Record; // coin -> mid price } ``` ### Impact Price Data ```typescript interface ImpactPriceData { coin: string; notional: string; buyImpactPx: string | null; sellImpactPx: string | null; time: number; } ``` ### Trades ```typescript interface Trade { coin: string; side: Side; px: string; sz: string; hash: string; time: number; tid: number; users: [string, string]; sideInfo?: SideInfo[]; } interface SideInfo { user: string; startPos: string; oid: number; twapId?: number; cloid?: string; } ``` ### Candles ```typescript interface Candle { t: number; // open time (ms) T: number; // close time (ms) s: string; // symbol/coin i: string; // interval o: string; // open price c: string; // close price h: string; // high price l: string; // low price v: string; // volume n: number; // trade count } ``` ### Fills ```typescript interface Fill { coin: string; px: string; sz: string; side: Side; time: number; startPosition: string; dir: string; closedPnl: string; hash: string; oid: number; crossed: boolean; fee: string; builderFee?: string; tid: number; cloid?: string; feeToken: string; twapId?: number; liquidation?: Liquidation; } interface Liquidation { liquidatedUser: string; markPx: string; method: string; } ``` ## All Mids Mid prices for all trading pairs, updated every second. ```json {"method": "subscribe", "subscription": {"type": "allMids"}} ``` Data format: `AllMidsData` ```json {"channel": "allMids", "data": {"mids": {"BTC": "65000.5", "ETH": "3500.25", "SOL": "125.50"}}} ``` ## Candles Real-time candlestick data. ```json {"method": "subscribe", "subscription": {"type": "candle", "coin": "BTC", "interval": "1m"}} ``` Supported intervals: `"1m"`, `"3m"`, `"5m"`, `"15m"`, `"30m"`, `"1h"` Data format: `Candle` ```json {"channel": "candle", "data": {"t": 1699900000000, "T": 1699900060000, "s": "BTC", "i": "1m", "o": "65000.0", "c": "65100.0", "h": "65150.0", "l": "64950.0", "v": "125.5", "n": 342}} ``` ## Impact Price Impact price calculations for a given notional size, sent as periodic snapshots. ```json {"method": "subscribe", "subscription": {"type": "impactPrice", "coin": "BTC", "notional": "10000"}} ``` The `interval` field is optional (default `"1s"`). Valid values: `"500ms"`, `"1s"`. Maximum notional is $100,000,000. Data format: `ImpactPriceData` ```json {"channel": "impactPrice", "data": {"coin": "BTC", "notional": "10000", "buyImpactPx": "65100.5", "sellImpactPx": "64900.3", "time": 1699900000000}} ``` Impact prices are calculated by simulating a market order of the specified notional size. If the book doesn't have enough liquidity, the corresponding price will be `null`. ## L1 Book Best bid and ask (top of book), sent as periodic snapshots. ```json {"method": "subscribe", "subscription": {"type": "l1Book", "coin": "BTC"}} ``` The `interval` field is optional (default `"500ms"`). Valid values: `"200ms"`, `"500ms"`, `"1s"`. Data format: `L1BookData` ```json {"channel": "l1Book", "data": {"coin": "BTC", "time": 1699900000000, "bid": {"px": "65000.0", "sz": "1.5", "n": 3}, "ask": {"px": "65001.0", "sz": "1.0", "n": 2}}} ``` ## L2 Book Aggregated price levels, sent as periodic snapshots. ```json {"method": "subscribe", "subscription": {"type": "l2Book", "coin": "BTC"}} ``` Optional fields: * `nSigFigs`: Significant figures for price aggregation (2-5) * `nLevels`: Number of price levels per side (default 20, max 100) * `mantissa`: Price rounding mantissa (2 or 5, only when nSigFigs=5) * `interval`: Update interval (default `"500ms"`). Valid values: `"100ms"`, `"200ms"`, `"500ms"` Data format: `L2BookData` ```json {"channel": "l2Book", "data": {"coin": "BTC", "time": 1699900000000, "levels": [[{"px": "65000.0", "sz": "1.5", "n": 3}], [{"px": "65001.0", "sz": "1.0", "n": 2}]]}} ``` The `levels` array contains `[bids, asks]`. ## L3 Book Order-level data with basic fields. Sends an initial snapshot followed by incremental diffs. ```json {"method": "subscribe", "subscription": {"type": "l3Book", "coin": "BTC"}} ``` Set `"snapshot": false` to skip the initial snapshot. Data format: `L3BookSnapshot | L3BookUpdates` ### Applying Diffs Diffs may arrive before the snapshot. Use `sequence` and `height` to apply them correctly: 1. Cache incoming diffs while waiting for the snapshot 2. When the snapshot arrives, note its `height` and `sequence` 3. Apply a diff only if: `diff.height >= snapshot.height && diff.sequence > snapshot.sequence` 4. Discard diffs that don't meet this condition ### Diff Types ```typescript type RawBookDiff = | { New: { sz: string } } | { Update: { origSz: string; newSz: string } } | 'Remove'; ``` ## L4 Book Order-level data with full details (triggers, TIF, order type, etc.). Sends an initial snapshot followed by incremental diffs and order status updates. ```json {"method": "subscribe", "subscription": {"type": "l4Book", "coin": "BTC"}} ``` Set `"snapshot": false` to skip the initial snapshot. Data format: `L4BookSnapshot | L4BookUpdates` ### Applying Diffs Same as L3 Book - use `sequence` and `height` to apply diffs correctly: ``` diff.height >= snapshot.height && diff.sequence > snapshot.sequence ``` ### Order Status Values * `open` - Order is active on the book * `filled` - Order completely filled * `canceled` - Order was canceled * `triggered` - Trigger order activated * `rejected` - Order was rejected ### Limitations L4 subscriptions do not support spot order books. ## Order Updates Real-time order status updates for a user address. ```json {"method": "subscribe", "subscription": {"type": "orderUpdates", "user": "0x1234567890abcdef1234567890abcdef12345678"}} ``` Data format: `OrderUpdate[]` ```json {"channel": "orderUpdates", "data": [{"order": {"coin": "BTC", "side": "B", "limitPx": "65000.0", "sz": "1.0", "oid": 12345, "timestamp": 1699900000000, "origSz": "1.0"}, "status": "open", "statusTimestamp": 1699900000000}]} ``` ### Status Values * `open` - Order is active * `filled` - Order completely filled * `canceled` - Order canceled * `triggered` - Trigger activated * `rejected` - Order rejected ## Trades Real-time trade stream. ```json {"method": "subscribe", "subscription": {"type": "trades", "coin": "BTC"}} ``` Set `"withSideInfo": true` to include detailed side info (user addresses, positions, order IDs). Data format: `Trade[]` ```json {"channel": "trades", "data": [{"coin": "BTC", "side": "B", "px": "65000.5", "sz": "0.1", "hash": "0x...", "time": 1699900000000, "tid": 12345, "users": ["0x...", "0x..."]}]} ``` The `users` array contains `[maker, taker]` addresses. ## User Fills Real-time fill notifications for a user address. ```json {"method": "subscribe", "subscription": {"type": "userFills", "user": "0x1234567890abcdef1234567890abcdef12345678"}} ``` Set `"aggregateByTime": true` to combine fills for the same order at the same timestamp (sizes summed, prices weighted-averaged, fees summed). Data format: `Fill[]` ```json {"channel": "userFills", "data": [{"coin": "BTC", "px": "65000.5", "sz": "0.1", "side": "B", "time": 1699900000000, "startPosition": "0.5", "dir": "Open Long", "closedPnl": "0", "hash": "0x...", "oid": 12345, "crossed": false, "fee": "6.50", "tid": 111, "feeToken": "USDC"}]} ``` ### Direction Values * `Open Long` / `Close Long` * `Open Short` / `Close Short` ## HpumpCore The **Hpump Market** operates on a **bonding curve model**, allowing tokens to build liquidity and establish a fair price before being launched on HyperCore or HyperEVM. *** ### Bonding Curve Overview The bonding curve model is inspired by **Uniswap V2’s Constant Product Market Maker (CPMM)** and uses the formula: **X ⋅ Y = K** ##### Key Components: * **X (USDC)**: Represents the amount of USDC inflow during token purchases. * **Y (Tokens)**: The number of tokens available for sale. * **K**: A constant value ensuring the bonding curve remains balanced. ##### **Threshold Formula for Bonding** For a launch token to bond and be listed on HyperCore, the following condition must be met: **X⋅0.65 ≥ Auction Price** This ensures that sufficient USDC has been accumulated in the bonding curve to pay for the gas cost and seed initial liquidity in the buy-side order book. *** #### **How It Works** 1. **Market Dynamics:** * As buyers purchase tokens, **X (USDC)** increases while **Y (tokens)** decreases. * **For example:** * Initial Parameters: X0=500; Y0=1,000,000; starting price = $0.0005. * After $99,500 net inflow: X=100,000, price = $0.10. 2. **Bonding Trigger:** * Once X⋅0.65 reaches the auction threshold (e.g., $65,000), the token is **automatically created**. * However, the **token creator** **must** **manually deploy the trading pair**, giving them the flexibility to launch their token on Hyperliquid at their preferred timing. 3. **USDC Allocation:** * **65% (Auction Price):** Pays the gas cost for deploying the token. * **35% (Remaining USDC):** Automatically added to the HIP-2 liquidity pool, creating a reliable buy-side market. 4. **Airdrop to Buyers:** * Once bonded, early buyers receive a **proportional airdrop** of the actual token. * This is sent directly to their **Hypurr Fun bot wallet**. ## HpumpEVM **The HpumpEVM Market** operates on a **bonding curve model**, allowing tokens to build liquidity before transitioning to **HyperSwap** through liquidity pool creation. **Bonding Curve Overview** The bonding curve model uses a mathematical formula to determine token pricing as trading volume increases. **Key Components:** * **Trading Phase**: Users can buy and sell tokens immediately after creation * **Bonding Curve**: Price increases as more tokens are purchased from the curve * **Liquidity Pool Creation**: When bonding requirements are met, tokens transition to HyperSwap **How It Works** 1. **Token Creation:** • Tokens are created and immediately available for trading • Trading occurs on the bonding curve with dynamic pricing 2. **Trading Phase:** • Users trade tokens while they remain on the bonding curve • Price increases as supply decreases through purchases 3. **Transition to HyperSwap:** • When bonding requirements are met, tokens migrate to **HyperSwap** • Liquidity pools are created for continued trading • Seamless transition from bonding curve to AMM trading **Detailed Mechanics** *Coming soon - full documentation on bonding thresholds, liquidity allocation, and migration process.* ## Account #### Creating an Account 1. **Get Started with Telegram**\ Hypurr Fun is a Telegram bot, so you’ll need a [Telegram](https://telegram.org/) account to use it. If you don’t already have one, create an account on Telegram first. 2. **Access the Bot**\ Search for **@HypurrFunBot** on Telegram or use this [direct link](https://t.me/HypurrFunBot). Press **“Start”** or type **/start** to begin. 3. **Set Up Your Wallet**\ After starting the bot, you’ll receive a welcome message along with your personal wallet address.

4. **Secure Your Wallet** It is strongly recommended to **export your private key** to avoid losing access to your wallet. * Go to **Settings** and select **Export private key**. * Save the key in a secure location and **NEVER** share it with anyone (including Hypurr Fun team members).

5. **Deposit USDC**\ To use **Hypurr Fun**, you’ll need to send **at least 10 USDC** from either the **Arbitrum chain** or **Hyperliquid**. For full details, we highly recommend reading the [Deposit](account/wallet-actions/deposit) section of this documentation. 6. **Transfer USDC to Spot Wallet** After depositing funds, ensure you transfer your USDC to the **Spot Wallet** using the **Perp to Spot** option in the **/spotwallet** command. All operations in the Hypurr Fun bot, including trading and plugins, require assets to be in the Spot Wallet. You’re now ready to start trading with Hypurr Fun! *** #### **View and Manage Your Wallets** Hypurr Fun provides several commands to view and manage different parts of your wallet and access essential features: * **Spot Wallet Operations**: * Use the **`/spotwallet`** command to view your **Spot Wallet** on Hyperliquid and perform operations such as **withdrawals** or other fund management tasks. * For a detailed **PnL report** of your spot trading activity, use the **`/spotpnl`** command. * **Perp Wallet Operations**: * Use the `/perpwallet` command to view your **Perp Wallet** on Hyperliquid and see your positions. * **Hpump Wallet**: * Use the **`/launchwallet`** command to view your HpumpCore and HpumpEVM assets. * For a detailed **PnL report** of your Hpump trading activity, use the **`/launchpnl`** command. * **Wallet Configuration**: * Use `/wallets` to manage and select your default wallet. * Use `/settings` to configure and manage your wallet preferences, set up the trade widget, and extract information. *** #### Advanced Wallet Management While a default wallet is created for you, Hypurr Fun offers advanced options to customize and expand your wallet setup: * [Multi Wallets](account/multi-wallets) * **Link** or **import** multiple wallets into the bot. * Your number of available wallet slots depends on your **HFUN balance** (3 by default, with one extra slot per HFUN held, up to 10 slots). * [Wallet Actions](account/wallet-actions) * Set a **Default Wallet** for trading, deposits, and plugins like the Sniper or Dumper. * **Learn how to deposit and withdraw funds** from Hypurr. * [Wallet Settings](account/wallet-settings) * Manage your wallet preferences, enhance security with **2FA**, configure trade options, adjust display settings, and export data via the **/settings** widget. ## Getting Started You can trade on Hypurr Fun through two platforms: * **Telegram**: Start by [creating your account](account) - Full trading experience with advanced features * **Website**: Use your own EOA wallet (MetaMask, Rabby) at [hpump.trade](https://hpump.trade/) **Next Steps**: Check out our guides for[ Hpump (trade & launch tokens)](hpump), [HyperCore spot & perp trading](hypercore), and [HyperEVM trading](hyperevm)