### Spot Deploy Auction Response Example Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot.md Example JSON response structure for the spotDeployState request. ```json { "states": [ { "token": 150, "spec" : { "name": "HYPE", "szDecimals": 2, "weiDecimals": 8, }, "fullName": "Hyperliquid", "spots": [107], "maxSupply": 1000000000, "hyperliquidityGenesisBalance": "120000", "totalGenesisBalanceWei": "100000000000000000", "userGenesisBalances": [ ("0xdddddddddddddddddddddddddddddddddddddddd", "428,062,211")... ], "existingTokenGenesisBalances": [ (1, "0")... ] } ], "gasAuction": { "startTimeSeconds": 1733929200, "durationSeconds": 111600, "startGas": "181305.90046", "currentGas": null, "endGas": "181291.247358" } } ``` -------------------------------- ### L2Book Info Request Example Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/post-requests.md An example of sending an L2Book info request and the corresponding successful response. ```json { "method": "post", "id": 123, "request": { "type": "info", "payload": { "type": "l2Book", "coin": "ETH", "nSigFigs": 5, "mantissa": null } } } ``` ```json { "channel": "post", "data": { "id": , "response": { "type": "info", "payload": { "type": "l2Book", "data": { "coin": "ETH", "time": , "levels": [ [{"px":"3007.1","sz":"2.7954","n":1}], [{"px":"3040.1","sz":"3.9499","n":1}] ] } } } } } ``` -------------------------------- ### Order Signed Action Request Example Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/post-requests.md An example of sending a signed order action request and the corresponding successful response. ```json { "method": "post", "id": 256, "request": { "type": "action", "payload": { "action": { "type": "order", "orders": [{"a": 4, "b": true, "p": "1100", "s": "0.2", "r": false, "t": {"limit": {"tif": "Gtc"}}}], "grouping": "na" }, "nonce": 1713825891591, "signature": { "r": "...", "s": "...", "v": "..." }, "vaultAddress": "0x12...3" } } } ``` ```json { "channel": "post", "data": { "id": 256, "response": { "type":"action", "payload": { "status": "ok", "response": { "type": "order", "data": { "statuses": [ { "resting": { "oid": 88383, } } ] } } } } } } ``` -------------------------------- ### Retrieve subaccounts response example Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example JSON response returned when successfully querying subaccounts for a user. ```json [ { "name": "Test", "subAccountUser": "0x035605fc2f24d65300227189025e90a0d947f16c", "master": "0x8c967e73e6b15087c42a10d344cff4c96d877f1d", "clearinghouseState": { "marginSummary": { "accountValue": "29.78001", "totalNtlPos": "0.0", "totalRawUsd": "29.78001", "totalMarginUsed": "0.0" }, "crossMarginSummary": { "accountValue": "29.78001", "totalNtlPos": "0.0", "totalRawUsd": "29.78001", "totalMarginUsed": "0.0" }, "crossMaintenanceMarginUsed": "0.0", "withdrawable": "29.78001", "assetPositions": [], "time": 1733968369395 }, "spotState": { "balances": [ { "coin": "USDC", "token": 0, "total": "0.22", "hold": "0.0", "entryNtl": "0.0" } ] } } ] ``` -------------------------------- ### Order Status Response Example Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint.md Example JSON response structure for an order status query. ```json { "status":"ok", "response":{ "type":"order", "data":{ "statuses":[ { "filled":{ "totalSz":"0.02", "avgPx":"1891.4", "oid":77747314 } } ] } } } ``` -------------------------------- ### Historical funding rate response examples Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals.md Examples of successful JSON responses for different perpetual dex configurations. ```json [ { "coin":"ETH", "fundingRate": "-0.00022196", "premium": "-0.00052196", "time":1683849600076 } ] ``` ```json [ { "coin": "xyz:XYZ100", "fundingRate": "-0.00022196", "premium": "-0.00052196", "time": 1683849600076 } ] ``` -------------------------------- ### Successful Response Example Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint.md The response returned upon a successful leverage update request. ```json {'status': 'ok', 'response': {'type': 'default'}} ``` -------------------------------- ### FastAssetCtxs Payload Example Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions.md Example payload and decoded JSON structure for the fastAssetCtxs subscription. ```json payload: "q1ZyCnFWsqpWyk0syg6oULJSsjQ3NTDQM1Wq1VFyDfFAkTI2MzXQMwJLVVRWWfmFuTiiyBuamOoZKdXWAgA=" ``` ```json decoded: { "BTC": { "markPx": "97500.5" }, "ETH": { "markPx": "3650.25" }, "xyz:NVDA": { markPx": "145.2" }} ``` -------------------------------- ### API Response Examples for Order Info Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Examples of JSON responses for successful order retrieval and cases where the order ID is not found. ```json { "status": "order", "order": { "order": { "coin": "ETH", "side": "A", "limitPx": "2412.7", "sz": "0.0", "oid": 1, "timestamp": 1724361546645, "triggerCondition": "N/A", "isTrigger": false, "triggerPx": "0.0", "children": [], "isPositionTpsl": false, "reduceOnly": true, "orderType": "Market", "origSz": "0.0076", "tif": "FrontendMarket", "cloid": null }, "status": , "statusTimestamp": 1724361546645 } } ``` ```json { "status": "unknownOid" } ``` -------------------------------- ### Exchange Endpoint Response Examples Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint.md Examples of JSON response structures for successful resting orders, error messages, and filled orders. ```json { "status":"ok", "response":{ "type":"order", "data":{ "statuses":[ { "resting":{ "oid":77738308 } } ] } } } ``` ```json { "status":"ok", "response":{ "type":"order", "data":{ "statuses":[ { "error":"Order must have minimum value of $10." } ] } } } ``` -------------------------------- ### Query Staking Summary Response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example JSON response for a successful delegator summary query. ```json { "delegated": "12060.16529862", "undelegated": "0.0", "totalPendingWithdrawal": "0.0", "nPendingWithdrawals": 0 } ``` -------------------------------- ### Successful Funding History Response Examples Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals.md Examples of successful JSON responses for funding history queries, showing variations in data structure between different dex versions. ```json [ { "delta": { "coin": "ETH", "fundingRate": "0.0000417", "szi": "49.1477", "type": "funding", "usdc":" -3.625312", "nSamples": null }, "hash": "0xa166e3fa63c25663024b03f2e0da011a00307e4017465df020210d3d432e7cb8", "time": 1681222254710 }, ... ] ``` ```json [ { "delta":{ "type": "funding", "coin": "xyz:XYZ100", "usdc": "2.378343", "szi": "-15.0", "fundingRate": "0.00000625", "nSamples": null }, "time": 1767654000068, "hash": "0xa166e3fa63c25663024b03f2e0da011a00307e4017465df020210d3d432e7cb9" }, ... ] ``` -------------------------------- ### Query Staking Delegations Response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example JSON response for a successful delegations query. ```json [ { "validator":"0x5ac99df645f3414876c816caa18b2d234024b487", "amount":"12060.16529862", "lockedUntilTimestamp":1735466781353 }, ... ] ``` -------------------------------- ### Frontend Open Orders Response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example of a successful 200 OK response containing an array of open order objects. ```json [ { "coin": "BTC", "isPositionTpsl": false, "isTrigger": false, "limitPx": "29792.0", "oid": 91490942, "orderType": "Limit", "origSz": "5.0", "reduceOnly": false, "side": "A", "sz": "5.0", "timestamp": 1681247412573, "triggerCondition": "N/A", "triggerPx": "0.0", } ] ``` -------------------------------- ### Query user role responses Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example JSON responses for different user roles returned by the userRole query. ```json {"role":"user"} # "missing", "user", "agent", "vault", or "subAccount" ``` ```json {"role":"agent", "data": {"user": "0x..."}} ``` ```json {"role":"vault"} ``` ```json {"role":"subAccount", "data":{"master":"0x..."}} ``` ```json {"role":"missing"} ``` -------------------------------- ### Borrow/Lend User State Response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example JSON response structure for a successful borrowLendUserState query. ```json { "tokenToState":[ [ 0, { "borrow":{ "basis": "0.0", "value": "0.0" }, "supply":{ "basis": "44.69295862", "value": "44.69692314" } } ], [ 1105, { "borrow":{ "basis": "0.0", "value": "0.0" }, "supply":{ "basis": "0.0", "value": "0.0" } } ], ], "health":"healthy", "healthFactor":null } ``` -------------------------------- ### Successful Response for First Perp Dex Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals.md Example response structure when querying the default perpetual dex. ```json [ { "universe": [ { "name": "BTC", "szDecimals": 5, "maxLeverage": 50 }, { "name": "ETH", "szDecimals": 4, "maxLeverage": 50 }, { "name": "HPOS", "szDecimals": 0, "maxLeverage": 3, "onlyIsolated": true } ], "marginTables":[ [ 50, { "description":"", "marginTiers":[ { "lowerBound":"0.0", "maxLeverage":50 } ] } ] ], "collateralToken":0 }, [ { "dayNtlVlm":"1169046.29406", "funding":"0.0000125", "impactPxs":[ "14.3047", "14.3444" ], "markPx":"14.3161", "midPx":"14.314", "openInterest":"688.11", "oraclePx":"14.32", "premium":"0.00031774", "prevDayPx":"15.322" }, { "dayNtlVlm":"1426126.295175", "funding":"0.0000125", "impactPxs":[ "6.0386", "6.0562" ], "markPx":"6.0436", "midPx":"6.0431", "openInterest":"1882.55", "oraclePx":"6.0457", "premium":"0.00028119", "prevDayPx":"6.3611" }, { "dayNtlVlm":"809774.565507", "funding":"0.0000125", "impactPxs":[ "8.4505", "8.4722" ], "markPx":"8.4542", "midPx":"8.4557", "openInterest":"2912.05", "oraclePx":"8.4585", "premium":"0.00033694", "prevDayPx":"8.8097" } ] ] ``` -------------------------------- ### Retrieve Spot Metadata Response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot.md Example of a successful 200 OK response containing token and universe metadata. ```json { "tokens": [ { "name": "USDC", "szDecimals": 8, "weiDecimals" 8, "index": 0, "tokenId": "0x6d1e7cde53ba9467b783cb7c530ce054", "isCanonical": true, "evmContract":null, "fullName":null }, { "name": "PURR", "szDecimals": 0, "weiDecimals": 5, "index": 1, "tokenId": "0xc1fb593aeffbeb02f85e0308e9956a90", "isCanonical": true, "evmContract":null, "fullName":null }, { "name": "HFUN", "szDecimals": 2, "weiDecimals": 8, "index": 2, "tokenId": "0xbaf265ef389da684513d98d68edf4eae", "isCanonical": false, "evmContract":null, "fullName":null }, ], "universe": [ { "name": "PURR/USDC", "tokens": [1, 0], "index": 0, "isCanonical": true }, { "tokens": [2, 0], "name": "@1", "index": 1, "isCanonical": false }, ] } ``` -------------------------------- ### Retrieve Builder-Deployed Perp Market Limits Response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals.md Example JSON response for a successful perpDexLimits request. ```json { "totalOiCap": "10000000.0", "oiSzCapPerPerp": "10000000000.0", "maxTransferNtl": "100000000.0", "coinToOiCap": [["COIN1", "100000.0"], ["COIN2", "200000.0"]], } ``` -------------------------------- ### User Rate Limit Response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example JSON response for a successful user rate limit query. ```json { "cumVlm": "2854574.593578", "nRequestsUsed": 2890, // max(0, cumulative_used minus reserved) "nRequestsCap": 2864574, "nRequestsSurplus": 0, // max(0, reserved minus cumulative_used) } ``` -------------------------------- ### Perpetuals account summary response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals.md Example of a successful 200 OK response containing asset positions and margin summaries. ```json { "assetPositions": [ { "position": { "coin": "ETH", "cumFunding": { "allTime": "514.085417", "sinceChange": "0.0", "sinceOpen": "0.0" }, "entryPx": "2986.3", "leverage": { "rawUsd": "-95.059824", "type": "isolated", "value": 20 }, "liquidationPx": "2866.26936529", "marginUsed": "4.967826", "maxLeverage": 50, "positionValue": "100.02765", "returnOnEquity": "-0.0026789", "szi": "0.0335", "unrealizedPnl": "-0.0134" }, "type": "oneWay" } ], "crossMaintenanceMarginUsed": "0.0", "crossMarginSummary": { "accountValue": "13104.514502", "totalMarginUsed": "0.0", "totalNtlPos": "0.0", "totalRawUsd": "13104.514502" }, "marginSummary": { "accountValue": "13109.482328", "totalMarginUsed": "4.967826", "totalNtlPos": "100.02765", "totalRawUsd": "13009.454678" }, "time": 1708622398623, "withdrawable": "13104.514502" } ``` -------------------------------- ### All Borrow/Lend Reserve States Response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example JSON response for a successful query of all available borrow/lend reserve states. ```json [ [ 0, { "borrowYearlyRate": "0.05", "supplyYearlyRate": "0.0008244951", "balance": "3245960.0596176102", "utilization": "0.0183221137", "oraclePx": "1.0", "ltv": "0.0", "totalSupplied": "3306530.3251102199", "totalBorrowed": "60582.62446067" } ], [ 150, { "borrowYearlyRate": "0.05", "supplyYearlyRate": "0.0", "balance": "11318.09684696", "utilization": "0.0", "oraclePx": "23.99", "ltv": "0.5", "totalSupplied": "11318.09684696", "totalBorrowed": "0.0" } ] ] ``` -------------------------------- ### Get Perp Market Status Response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals.md Example JSON response for a successful perpDexStatus request. ```json { "totalNetDeposit": "4103492112.4478230476" } ``` -------------------------------- ### Connect to WebSocket via CLI Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket.md Use wscat to establish a connection and send a subscription message for trade data. ```bash $ wscat -c wss://api.hyperliquid.xyz/ws Connected (press CTRL+C to quit) > { "method": "subscribe", "subscription": { "type": "trades", "coin": "SOL" } } < {"channel":"subscriptionResponse","data":{"method":"subscribe","subscription":{"type":"trades","coin":"SOL"}}} ``` -------------------------------- ### Query Documentation Index Source: https://hyperliquid.gitbook.io/hyperliquid-docs/builder-tools Perform an HTTP GET request to the documentation index with 'ask' and optional 'goal' parameters to query specific information. The 'ask' parameter should contain the immediate question, and 'goal' can describe the broader end goal. ```http GET https://hyperliquid.gitbook.io/hyperliquid-docs/trading/builder-codes.md?ask=&goal= ``` -------------------------------- ### Constructing and sending a raw action in Solidity Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/hyperevm/interacting-with-hypercore.md Demonstrates how to encode an action and send it to the CoreWriter contract address on HyperCore. ```solidity contract CoreWriterCaller { function sendUsdClassTransfer(uint64 ntl, bool toPerp) external { bytes memory encodedAction = abi.encode(ntl, toPerp); bytes memory data = new bytes(4 + encodedAction.length); data[0] = 0x01; data[1] = 0x00; data[2] = 0x00; data[3] = 0x07; for (uint256 i = 0; i < encodedAction.length; i++) { data[4 + i] = encodedAction[i]; } CoreWriter(0x3333333333333333333333333333333333333333).sendRawAction(data); } } ``` -------------------------------- ### Ask a Question via Documentation API Source: https://hyperliquid.gitbook.io/hyperliquid-docs/support Use this GET request to ask a specific question about the documentation. The 'ask' parameter is required for your question, and the 'goal' parameter is optional to tailor the response. ```http GET https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore.md?ask=&goal= ``` -------------------------------- ### User Fills Response Format Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example response showing various fill types including perpetuals, HIP-3 assets, and spot trades. ```json [ // Perp fill (first perp dex) { "closedPnl": "0.0", "coin": "AVAX", "crossed": false, "dir": "Open Long", "hash": "0xa166e3fa63c25663024b03f2e0da011a00307e4017465df020210d3d432e7cb8", "oid": 90542681, "px": "18.435", "side": "B", "startPosition": "26.86", "sz": "93.53", "time": 1681222254710, "fee": "0.01", // the total fee, inclusive of builderFee below "feeToken": "USDC", "builderFee": "0.01", // this is optional and will not be present if 0 "tid": 118906512037719 }, // Perp Fill (HIP-3) { "coin": "xyz:XYZ100", // For HIP-3, the asset has the dex name as a prefix "px": "25372.0", "sz": "0.0353", "side": "B", "time": 1767651180109, "startPosition": "0.7045", "dir": "Open Long", "closedPnl": "0.0", "hash": "0xa166e3fa63c25663024b03f2e0da011a00307e4017465df020210d3d432e7cb9", "oid": 287286372177, "crossed": false, "fee": "0.026868", "tid": 164087028129848, "feeToken":" USDC" }, // Spot fill - note the difference in the "coin" format. Refer to // https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/asset-ids // for more information on how spot asset IDs work { "coin": "@107", "px": "18.62041381", "sz": "43.84", "side": "A", "time": 1735969713869, "startPosition": "10659.65434798", "dir": "Sell", "closedPnl": "8722.988077", "hash": "0x2222138cc516e3fe746c0411dd733f02e60086f43205af2ae37c93f6a792430b", "oid": 59071663721, "crossed": true, "fee": "0.304521", "tid": 907359904431134, "feeToken": "USDC" } ] ``` -------------------------------- ### Deploying the PURR ERC20 Token Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/hyperevm/hypercore-less-than-greater-than-hyperevm-transfers.md Example implementation of an ERC20 token contract using OpenZeppelin's ERC20Permit, designed for linking to HyperCore. ```solidity // SPDX-License-Identifier: MIT pragma solidity 0.8.28; import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol"; contract Purr is ERC20Permit { constructor() ERC20("Purr", "PURR") ERC20Permit("Purr") { address initialHolder = 0x2000000000000000000000000000000000000001; uint256 initialBalance = 600000000; _mint(initialHolder, initialBalance * 10 ** decimals()); } } ``` -------------------------------- ### Retrieve Perpetual Categories Response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals.md Example JSON response for the perpCategories request type. ```json [["birb:PENGU","test_cat"],["nq:TEST","preipo"],["nq:TEST1","all"],["nq:TEST2","ai"]] ``` -------------------------------- ### Retrieve Perpetual Annotation Response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals.md Example JSON response for a successful perpAnnotation request. ```json { "category": "other", "description": "other perps" } ``` -------------------------------- ### Calculate AQAv2 Revenue Intervals Source: https://hyperliquid.gitbook.io/hyperliquid-docs/hypercore/aligned-quote-assets.md Example illustrating the calculation of system interest payments based on daily balances and AQA-publisher effective rates over 30-day intervals. ```text Jan 1: X1 = balance at 0 UTC, RATE1 = AQA-publisher effective rate, published onchain by validators Jan 2: X2, RATE2 (analogously defined) ... Jan 31: X31, RATE31 Feb 1: X32, RATE32 Feb 7: X38, RATE38 Feb 28: X59, RATE59 Mar 1: X60, RATE60 System interest address pays X1 * RATE1 + X2 * RATE2 + ... X30 * RATE30 on Feb 7 at 0 UTC System interest address pays X31 * RATE31 + ... + X60 * RATE60 on Mar 9 at 0 UTC ``` -------------------------------- ### Retrieve outcome metadata response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot.md Example JSON response for the outcomeMeta request type. ```json { "outcomes": [ { "outcome": 123, "name": "Recurring", "description": "class:priceBinary|underlying:HYPE|expiry:20260310-1100|targetPrice:34.5|period:3m", "sideSpecs": [ { "name": "Yes" }, { "name": "No" } ] } ] } ``` -------------------------------- ### Typed Data Signature Example Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint.md The structure required for generating the signature for a spot send transaction. ```json Example sign typed data for generating the signature: { "types": { "HyperliquidTransaction:SpotSend": [ { "name": "hyperliquidChain", "type": "string" }, { "name": "destination", "type": "string" }, { "name": "token", "type": "string" }, { "name": "amount", "type": "string" }, { "name": "time", "type": "uint64" } ] }, "primaryType": "HyperliquidTransaction:SpotSend", "domain": { "name": "HyperliquidSignTransaction", "version": "1", "chainId": 42161, "verifyingContract": "0x0000000000000000000000000000000000000000" }, "message": { "destination": "0x0000000000000000000000000000000000000000", "token": "PURR:0xc1fb593aeffbeb02f85e0308e9956a90", "amount": "0.1", "time": 1716531066415, "hyperliquidChain": "Mainnet" } } ``` -------------------------------- ### Cancel Order Response Examples Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint.md JSON responses for successful and failed order cancellation attempts. ```json { "status":"ok", "response":{ "type":"cancel", "data":{ "statuses":[ "success" ] } } } ``` ```json { "status":"ok", "response":{ "type":"cancel", "data":{ "statuses":[ { "error":"Order was never placed, already canceled, or filled." } ] } } } ``` -------------------------------- ### Spot Deployment Data Structures Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/deploying-hip-1-and-hip-2-assets.md Defines the TypeScript types for spot deployment actions, including token registration, genesis, and hyperliquidity configuration. ```typescript type SpotDeployAction = | { type: "spotDeploy"; registerToken2: RegisterToken2; } | { type: "spotDeploy"; userGenesis: UserGenesis; } | { type: "spotDeploy"; genesis: Genesis; } | { type: "spotDeploy"; registerSpot: RegisterSpot; } | { type: "spotDeploy"; registerHyperliquidity: RegisterHyperliquidity; } | { type: "spotDeploy"; setDeployerTradingFeeShare: SetDeployerTradingFeeShare; } | { type: "spotDeploy"; enableQuoteToken: { token: number }; } | { type: "spotDeploy"; enableAlignedQuoteToken: { token: number }; } | { type: "spotDeploy"; disableQuoteToken: { token: number }; } | { /* note: must be sent after disableQuoteToken */ type: "spotDeploy"; disableAlignedQuoteToken: { token: number }; }; type RegisterToken2 = { spec: TokenSpec; maxGas: number; fullName?: string; } type TokenSpec = { name: string, szDecimals: number, weiDecimals: number, } /** * UserGenesis can be called multiple times * @param token - The token involved in the genesis. * @param userAndWei - A list of tuples of user address and genesis amount (wei). * @param existingTokenAndWei - A list of tuples of existing token and total genesis amount for holders of that token (wei). * @param blacklistUsers - A list of tuples of users and blacklist status (True if blacklist, False to remove existing blacklisted user). */ type UserGenesis = { token: number; userAndWei: Array<[string, string]>; existingTokenAndWei: Array<[number, string]>; blacklistUsers?: Array<[string, boolean]>; } /** * Genesis denotes the initial creation of a token with a maximum supply. * @param maxSupply - Checksum ensureing all calls to UserGenesis succeeded * @param noHyperliquidity - Set hyperliquidity balance to 0. */ type Genesis = { token: number; maxSupply: string; noHyperliquidity?: boolean; } /** * @param tokens - [base index, quote index] * This is also the action used to deploy pairs between an existing base and existing quote asset. * Deployments between pairs of existing assets follow an independent Dutch auction. * This auction's status is available from the `spotPairDeployAuctionStatus` info request. */ type RegisterSpot = { tokens: [number, number]; } /** * @param spot - The spot index (different from base token index) * @param startPx - The starting price. * @param orderSz - The size of each order (float, not wei) * @param nOrders - The number of orders. If "noHyperliquidity" was set to True, then this must be 0. * @param nSeededLevels - The number of levels the deployer wishes to seed with usdc instead of tokens. */ type RegisterHyperliquidity = { spot: number; startPx: string; orderSz: string; nOrders: number; nSeededLevels?: number; } /** * This is an optional action that can be performed at any time after * RegisterToken2. While the fee share defaults to 100%, this action * can be resent multiple times as long as the fee share is not increasing. * @param token - The token * @param share - The deployer trading fee share. Range: ["0%", "100%"]. Examples: "0.012%", "99.4%" */ type SetDeployerTradingFeeShare { token: number; share: string; } ``` -------------------------------- ### RegisterAsset2 Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/hip-3-deployer-actions.md Initializes a new DEX and registers an asset simultaneously. ```APIDOC ## RegisterAsset2 ### Description Initializes a new DEX and registers an asset. If the schema is omitted, RegisterAsset can be called subsequently to add more assets to the existing DEX. ### Parameters - **maxGas** (number) - Optional - Max gas in native token wei. If 0, a reserve deployment is used. - **assetRequest** (RegisterAssetRequest2) - Required - Parameters for the new asset listing. - **dex** (string) - Required - Name of the perp dex (2-4 characters). - **schema** (PerpDexSchemaInput) - Optional - Parameters for the new perp dex. ### RegisterAssetRequest2 Fields - **coin** (string) - Asset ticker. - **szDecimals** (number) - Size decimals. - **oraclePx** (string) - Oracle price. - **marginTableId** (number) - Margin table ID. - **marginMode** ("strictIsolated" | "noCross" | "normal") - Margin mode configuration. ``` -------------------------------- ### Query delegator rewards response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example JSON response for a successful delegator rewards query. ```json [ { "time": 1736726400073, "source": "delegation", "totalAmount": "0.73117184" }, { "time": 1736726400073, "source": "commission", "totalAmount": "130.76445876" }, ... ] ``` -------------------------------- ### Query delegator history response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example JSON response for a successful delegator history query. ```json [ { "time": 1735380381353, "hash": "0x55492465cb523f90815a041a226ba90147008d4b221a24ae8dc35a0dbede4ea4", "delta": { "delegate": { "validator": "0x5ac99df645f3414876c816caa18b2d234024b487", "amount": "10000.0", "isUndelegate": false } } }, ... ] ``` -------------------------------- ### User Fees Response Structure Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example JSON response for a successful userFees query, containing fee rates, schedules, and active discounts. ```json { "dailyUserVlm": [ { "date": "2025-05-23", "userCross": "0.0", "userAdd": "0.0", "exchange": "2852367.0770729999" }, ... ], "feeSchedule": { "cross": "0.00045", "add": "0.00015", "spotCross": "0.0007", "spotAdd": "0.0004", "tiers": { "vip": [ { "ntlCutoff": "5000000.0", "cross": "0.0004", "add": "0.00012", "spotCross": "0.0006", "spotAdd": "0.0003" }, ... ], "mm": [ { "makerFractionCutoff": "0.005", "add": "-0.00001" }, ... ] }, "referralDiscount": "0.04", "stakingDiscountTiers": [ { "bpsOfMaxSupply": "0.0", "discount": "0.0" }, { "bpsOfMaxSupply": "0.0001", "discount": "0.05" }, ... ] }, "userCrossRate": "0.000315", "userAddRate": "0.000105", "userSpotCrossRate": "0.00049", "userSpotAddRate": "0.00028", "activeReferralDiscount": "0.0", "trial": null, "feeTrialReward": "0.0", "nextTrialAvailableTimestamp": null, "stakingLink": { "type": "tradingUser", "stakingUser": "0x54c049d9c7d3c92c2462bf3d28e083f3d6805061" }, "activeStakingDiscount": { "bpsOfMaxSupply": "4.7577998927", "discount": "0.3" } } ``` -------------------------------- ### Retrieve user vault deposits response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint.md Example JSON response for a successful userVaultEquities query. ```json [ { "vaultAddress": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303", "equity": "742500.082809", } ] ``` -------------------------------- ### Retrieve Concise Perpetual Annotations Response Source: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals.md Example JSON response for the perpConciseAnnotations request type. ```json [ [ "dex:CATS", { "category": "indices", "keywords": ["meow"] } ], [ "dex:DOGS", { "category": "indices" } ] ] ``` -------------------------------- ### Calculate Fee Rates in TypeScript Source: https://hyperliquid.gitbook.io/hyperliquid-docs/trading/fees.md Calculates maker and taker fee percentages using user fee data, referral discounts, and market-specific arguments like spot or perp configurations. ```typescript type Args = | { type: "spot"; isStablePair: boolean; } | { type: "perp"; deployerFeeScale: number; growthMode: boolean; }; function feeRates( fees: { makerRate: number; takerRate: number }, // fees from userFees info endpoint activeReferralDiscount: number, // number from userFees info endpoint isAlignedQuoteToken: boolean, args: Args, ) { const scaleIfStablePair = args.type === "spot" && args.isStablePair ? 0.2 : 1; let scaleIfHip3 = 1; let growthModeScale = 1; let deployerShare = 0; if (args.type === "perp") { scaleIfHip3 = args.deployerFeeScale < 1 ? args.deployerFeeScale + 1 : args.deployerFeeScale * 2; deployerShare = args.deployerFeeScale < 1 ? args.deployerFeeScale / (1 + args.deployerFeeScale) : 0.5; growthModeScale = args.growthMode ? 0.1 : 1; } let makerPercentage = fees.makerRate * 100 * scaleIfStablePair * growthModeScale; if (makerPercentage > 0) { makerPercentage *= scaleIfHip3 * (1 - activeReferralDiscount); } else { const makerRebateScaleIfAlignedQuoteToken = isAlignedQuoteToken ? (1 - deployerShare) * 1.5 + deployerShare : 1; makerPercentage *= makerRebateScaleIfAlignedQuoteToken; } let takerPercentage = fees.takerRate * 100 * scaleIfStablePair * scaleIfHip3 * growthModeScale * (1 - activeReferralDiscount); if (isAlignedQuoteToken) { const takerScaleIfAlignedQuoteToken = isAlignedQuoteToken ? (1 - deployerShare) * 0.8 + deployerShare : 1; takerPercentage *= takerScaleIfAlignedQuoteToken; } return { makerPercentage, takerPercentage }; } ```