const PX_GAP = 0.003;
const MAX_N_ORDERS = 4000;
const MAX_MARKET_CAP_BILLIONS_END = 100;
const MIN_MARKET_CAP_BILLIONS_END = 1;
const MAX_MARKET_CAP_MILLIONS_START = 10;
const MAX_UINT_64 = BigInt("18446744073709551615");
if (
startPx === undefined ||
orderSz === undefined ||
orderCount === undefined ||
nSeededLevels === undefined
) {
displayAlert(
"Lowest price, order size, number of orders and number of seeded levels must be specified.",
"error"
);
return;
}
const minStartPx = getMinStartPx(szDecimals);
if (startPx < minStartPx) {
displayAlert(
`First order price must be at least ${roundPx(
minStartPx,
szDecimals,
true
)}`,
"error"
);
return;
}
if (startPx * orderSz < 1) {
displayAlert("First order size must be at least 1 USDC", "error");
return;
}
if (!activeTokenDeployState || activeTokenDeployState.spots.length === 0) {
displayAlert(
"Unexpected error: spot and token should already be registered.",
"error"
);
return;
}
const pxRange = Math.ceil(Math.pow(1 + PX_GAP, orderCount));
const endPx = startPx * pxRange;
// 1e9 instead of 1e8 because backend checks against u64::MAX / 10
if (
pxRange > 1_000_000 ||
hyperliquidityTotalWei > MAX_UINT_64 ||
endPx * orderSz * 1e9 > MAX_UINT_64
) {
displayAlert(
"Total Hyperliquidity token allocation is too large.",
"error"
);
return;
}
const minTotalGenesisBalanceSz = 100_000_000;
if (totalSupply * Math.pow(10, szDecimals) < minTotalGenesisBalanceSz) {
displayAlert(
`Total genesis balance must be at least ${minTotalGenesisBalanceSz} lots (minimal tradeable units, i.e. one lot is 0.01 if szDecimals is 2)`,
"error"
);
return;
}
const endMarketCap = totalSupply * endPx;
if (endMarketCap > MAX_MARKET_CAP_BILLIONS_END * 1e9) {
displayAlert(
`Market cap must be <${MAX_MARKET_CAP_BILLIONS_END}B USDC at Hyperliquidity end price`,
"error"
);
return;
}
if (endMarketCap < MIN_MARKET_CAP_BILLIONS_END * 1e9) {
displayAlert(
`Market cap must be >${MIN_MARKET_CAP_BILLIONS_END}B USDC at Hyperliquidity end price`,
"error"
);
return;
}
if (totalSupply * startPx > MAX_MARKET_CAP_MILLIONS_START * 1e6) {
displayAlert(
`Market cap must be <${MAX_MARKET_CAP_MILLIONS_START}M USDC at Hyperliquidity start price`,
"error"
);
return;
}
if (orderCount < 10) {
displayAlert("Hyperliquidity must have at least 10 orders", "error");
return;
}
if ((orderSz * orderCount) / totalSupply <= 0.01) {
displayAlert("Hyperliquidity must be >1% of total supply", "error");
return;
}
if (usdcNeeded > webData.clearinghouseState.withdrawable) {
displayAlert(
"Insufficient perps USDC to deploy seeded levels",
"error"
);
return;
}
20000 USDC for BTC and ETH
6000 USDC for all other assets
| | Maximum market order value | $30,000,000 for max leverage >= 25, $5,000,000 for max leverage in \[20, 25), $2,000,000 for max leverage in \[10, 20), otherwise $500,000 | | Maximum limit order value | 10 \* maximum market order value | ### Recurring outcomes Recurring outcomes are automatically deployed and settled by the protocol on a fixed cadence. The specification for the current instance of the recurring outcome is found in the `description` field of `outcomeMeta` . #### Binary ``` class:priceBinary|underlying:BTC|expiry:20260503-0600|targetPrice:78213|period:1d" ``` The target price is computed using a linear interpolation between the mark price updates immediately before and immediately after the settlement timestamp. Precisely, the contract settles to YES if and only if `markPrice0 + (settlementTime - t0) / (t1 - t0) * (markPrice1 - markPrice0) ≥ targetPrice` where `t0` and `t1` are the timestamps of mark price updates immediately before and after `settlementTime` #### Multi-price ``` "class:priceBucket|underlying:BTC|expiry:20260507-0745|priceThresholds:81538,81783|period:15m" ``` There are three price buckets depending on the target price at the time of settlement: `< P1`, `[P1, P2)` and `≥ P2.` Exactly one of the 3 outcomes settles to 1, and the others settle to 0. The target price computation uses the same interpolation as binary markets described above. ### Uniqueness There is guaranteed to be at most one recurring series for each `(seriesType, underlying, period)` combination. # Margining Margin computations follow similar formulas to major centralized derivatives exchanges. ### Margin Mode When opening a position, a margin mode is selected. *Cross margin* is the default, which allows for maximal capital efficiency by sharing collateral between all other cross margin positions. *Isolated margin* is also supported, which allows an asset's collateral to be constrained to that asset. Liquidations in that asset do not affect other isolated positions or cross positions. Similarly, cross liquidations or other isolated liquidations do not affect the original isolated position. Some assets are *strict isolated*, which functions the same as isolated margin with the additional constraint that margin cannot be removed. Margin is proportionally removed as the position is closed. ### HIP-3 Margin Modes When users have perp positions across multiple DEXs, cross margin behaves different depending on the user's account abstraction. For unified account and portfolio margin, the user's cross margin positions in DEXs with the same collateral all share margin. For standard abstraction, cross margin only applies to the assets within the same DEX. See [here](/hyperliquid-docs/trading/account-abstraction-modes) for more details. HIP-3 DEXs also support "no cross" margin mode, which allows isolated margin with margin removal enabled, but does not allow cross margin. ### Initial Margin and Leverage Leverage can be set by a user to any integer between 1 and the max leverage. Max leverage depends on the asset. The margin required to open a position is `position_size * mark_price / leverage`. The initial margin is used by the position and cannot be withdrawn for cross margin positions. Isolated positions support adding and removing margin after opening the position. Unrealized pnl for cross margin positions will automatically be available as initial margin for new positions, while isolated positions will apply unrealized pnl as additional margin for the open position.\ \ The leverage of an existing position can be increased without closing the position. Leverage is only checked upon opening a position. Afterwards, the user is responsible for monitoring the leverage usage to avoid liquidation. Possible actions to take on positions with negative unrealized pnl include partially or fully closing the position, adding margin (if isolated), and depositing USDC (if cross). ### Unrealized PNL and transfer margin requirements Unrealized pnl can be withdrawn from isolated positions or cross account, but only if the remaining margin is at least 10% of the total notional position value of all open positions. The margin remaining must also meet the initial margin requirement, i.e. `transfer_margin_required = max(initial_margin_required, 0.1 * total_position_value)` Here, "transferring" includes any action that removes margin from a position, other than trading. Examples include withdrawals, transfer to spot wallet, and isolated margin transfers. ### Maintenance Margin and Liquidations Cross positions are liquidated when the account value (including unrealized pnl) is less than the *maintenance margin* times the total open notional position. The maintenance margin is currently set to half of the initial margin at max leverage. Isolated positions are liquidated by the same maintenance margin logic, but the only inputs to the computation are the isolated margin and the notional value of the isolated position. # Account abstraction modes A user's *account abstraction mode* determines how spot and perps balances interact, and whether various assets are used as collateral for perps trading. The supported modes are: 1. Unified account (recommended for most users): single balance for each asset. This balance collateralizes all cross margin positions in that asset and is unified with spot balance in that asset. For example, USDC balance is the single source for validator-operated perps, XYZ perps, and spot trading against USDC as a quote asset. USDT spot balance is the single source for CASH perps and spot trading against USDT as a quote asset. 2. Portfolio margin (most capital efficient): single portfolio unifying all eligible assets, which are currently HYPE, BTC, USDC, USDT. See [Portfolio margin](/hyperliquid-docs/trading/portfolio-margin) for more details. 3. Manual / Standard (recommended for market makers, high volume automated users, and deployers/builders): separate perp and spot balances, separate DEX balances. Cross margin applies to each DEX separately. There is one more mode that is not relevant to most users, included here for completeness: 4. DEX abstraction (to be discontinued): USDC balances default to perps balance, all other collateral defaults to spot balance. IMPORTANT: Cross margin on HIP-3 DEXs does not behave intuitively for DEX abstraction users. Interfaces should deprecate DEX abstraction support going forward. Important details: 1. Builder code addresses must be in standard mode to accrue builder fees 2. Portfolio margin and unified account are limited to 50k user actions per day. Standard mode has no such restrictions. 3. For API users, unified account and portfolio margin show all balances and holds in the spot clearinghouse state. Individual perp dex user states are not meaningful. See Python SDK and [API docs](/hyperliquid-docs/for-developers/api) for examples on the agent- and user-signed actions for changing account abstraction modes. ### Unified Account Ratio To compute the precise unified account ratio for monitoring liquidation risk: ```typescript function computeUnifiedAccountRatio( multiverse: Record| VIP tier | 14d weighted volume ($) | Amount kept by builder or referrer |
|---|---|---|
| 0 | 100% | |
| 1 | >5M | 90% |
| 2 | >25M | 80% |
| 3 | >100M | 70% |
| 4 | >500M | 60% |
| 5 | >2B | 50% |
| 6 | >7B | 40% |
| Abbreviation | Full name | Explanation |
|---|---|---|
| Px | Price | |
| Sz | Size | In units of coin, i.e. base currency |
| Szi | Signed size | Positive for long, negative for short |
| Ntl | Notional | USD amount, Px * Sz |
| Side | Side of trade or book | B = Bid = Buy, A = Ask = Short. Side is aggressing side for trades. |
| Asset | Asset | An integer representing the asset being traded. See below for explanation |
| Tif | Time in force | GTC = good until canceled, ALO = add liquidity only (post only), IOC = immediate or cancel |
{"coin": \
For HIP-3, you need to prefix with the dex name, e.g. "xyz:XYZ100"
[
{
"coin":"ETH",
"fundingRate": "-0.00022196",
"premium": "-0.00052196",
"time":1683849600076
}
]
{
"type": "order",
"orders": \[{
"a": Number,
"b": Boolean,
"p": String,
"s": String,
"r": Boolean,
"t": {
"limit": {
"tif": "Alo" | "Ioc" | "Gtc"
} or
"trigger": {
"isMarket": Boolean,
"triggerPx": String,
"tpsl": "tp" | "sl"
}
},
"c": Cloid (optional)
}],
"grouping": "na" | "normalTpsl" | "positionTpsl",
"builder": Optional({"b": "address", "f": Number})
}
Meaning of keys:
a is asset
b is isBuy
p is price
s is size
r is reduceOnly
t is type
c is cloid (client order id)
Meaning of keys in optional builder argument:
b is the address the should receive the additional fee
f is the size of the fee in tenths of a basis point e.g. if f is 10, 1bp of the order notional will be charged to the user and sent to the builder
{
"type": "cancel",
"cancels": \[
{
"a": Number,
"o": Number
}
],
"f": Boolean // fast
}
Meaning of keys:
a is asset
o is oid (order id)
{
"type": "cancelByCloid",
"cancels": \[
{
"asset": Number,
"cloid": String
}
],
"f": Boolean // fast
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | | vaultAddress | String | If trading on behalf of a vault or subaccount, its address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000 | | expiresAfter | Number | Timestamp in milliseconds | {% tabs %} {% tab title="200: OK Successful Response" %} {% endtab %} {% tab title="200: OK Error Response" %} {% endtab %} {% endtabs %} ## Schedule cancel (dead man's switch) `POST` `https://api.hyperliquid.xyz/exchange` #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "scheduleCancel",
"time": number (optional)
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | | vaultAddress | String | If trading on behalf of a vault or subaccount, its address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000 | | expiresAfter | Number | Timestamp in milliseconds | Schedule a cancel-all operation at a future time. Not including time will remove the scheduled cancel operation. The time must be at least 5 seconds after the current time. Once the time comes, all open orders will be canceled and a trigger count will be incremented. The max number of triggers per day is 10. This trigger count is reset at 00:00 UTC. ## Modify an order `POST` `https://api.hyperliquid.xyz/exchange` #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | | | | | ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "modify",
"oid": Number | Cloid,
"order": {
"a": Number,
"b": Boolean,
"p": String,
"s": String,
"r": Boolean,
"t": {
"limit": {
"tif": "Alo" | "Ioc" | "Gtc"
} or
"trigger": {
"isMarket": Boolean,
"triggerPx": String,
"tpsl": "tp" | "sl"
}
},
"c": Cloid (optional)
},
"a": Boolean // always\_place
}
Meaning of keys:
a is asset
b is isBuy
p is price
s is size
r is reduceOnly
t is type
c is cloid (client order id)
{
"type": "batchModify",
"modifies": \[{
"oid": Number | Cloid,
"order": {
"a": Number,
"b": Boolean,
"p": String,
"s": String,
"r": Boolean,
"t": {
"limit": {
"tif": "Alo" | "Ioc" | "Gtc"
} or
"trigger": {
"isMarket": Boolean,
"triggerPx": String,
"tpsl": "tp" | "sl"
}
},
"c": Cloid (optional)
}
}],
"a": Boolean // always\_place
}
Meaning of keys:
a is asset
b is isBuy
p is price
s is size
r is reduceOnly
t is type
c is cloid (client order id)
{
"type": "updateLeverage",
"asset": index of coin,
"isCross": true or false if updating cross-leverage,
"leverage": integer representing new leverage, subject to leverage constraints on that coin
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | | vaultAddress | String | If trading on behalf of a vault or subaccount, its Onchain address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000 | | expiresAfter | Number | Timestamp in milliseconds | {% tabs %} {% tab title="200: OK Successful response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Update isolated margin `POST` `https://api.hyperliquid.xyz/exchange` Add or remove margin from isolated position Note that to target a specific leverage instead of a USDC value of margin change, there is an alternate action `{"type": "topUpIsolatedOnlyMargin", "asset":{
"type": "updateIsolatedMargin",
"asset": index of coin,
"isBuy": true, (this parameter won't have any effect until hedge mode is introduced)
"ntli": int representing amount to add or remove with 6 decimals, e.g. 1000000 for 1 usd,
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | | vaultAddress | String | If trading on behalf of a vault or subaccount, its Onchain address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000 | | expiresAfter | Number | Timestamp in milliseconds | {% tabs %} {% tab title="200: OK Successful response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Send Asset `POST` `https://api.hyperliquid.xyz/exchange` This generalized method is used to transfer tokens between different perp DEXs, spot balance, users, and/or sub-accounts. Use "" to specify the default USDC perp DEX and "spot" to specify spot. Only the collateral token can be transferred to or from a perp DEX. #### Headers | Name | Value | | ---------------------------------------------- | ------------------ | | Content-Type\* | `application/json` | #### Body | Name | Type | Description | | ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "sendAsset",
"hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead),
"signatureChainId": the id of the chain used when signing in hexadecimal format; e.g. "0xa4b1" for Arbitrum,
"destination": address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000,
"sourceDex": name of perp dex to transfer from,
"destinationDex": name of the perp dex to transfer to,
"token": tokenName:tokenId; e.g. "PURR:0xc4bf3f870c0e9465323c0b6ed28096c2",
"amount": amount of token to send as a string; e.g. "0.01",
"fromSubAccount": address in 42-character hexadecimal format or empty string if not from a subaccount,
"nonce": current timestamp in milliseconds as a Number, should match nonce
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds, must match the nonce in the action Object above | | signature\* | Object | | #### Response {% tabs %} {% tab title="200: OK" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Agent Send Asset `POST` `https://api.hyperliquid.xyz/exchange` Similar to send asset, but can be signed by an agent. Destination must match the source address. Use "" to specify the default USDC perp DEX and "spot" to specify spot. Only the collateral token can be transferred to or from a perp DEX. #### Headers | Name | Value | | ---------------------------------------------- | ------------------ | | Content-Type\* | `application/json` | #### Body | Name | Type | Description | | ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "agentSendAsset",
"destination": address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000,
"sourceDex": name of perp dex to transfer from,
"destinationDex": name of the perp dex to transfer to,
"token": tokenName:tokenId; e.g. "PURR:0xc4bf3f870c0e9465323c0b6ed28096c2",
"amount": amount of token to send as a string; e.g. "0.01",
"fromSubAccount": address in 42-character hexadecimal format or empty string if not from a subaccount,
"nonce": current timestamp in milliseconds as a Number, should match nonce
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds, must match the nonce in the action Object above | | signature\* | Object | | #### Response {% tabs %} {% tab title="200: OK" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Send to EVM with data `POST` `https://api.hyperliquid.xyz/exchange` Specialized action for Core to EVM transfer that includes an additional data payload. See [HyperCore <> HyperEVM transfers](/hyperliquid-docs/for-developers/hyperevm/hypercore-less-than-greater-than-hyperevm-transfers) for more details. When used coreReceiveWithData will be called on the linked contract instead of transfer. IMPORTANT: it is the caller's responsibility to ensure that the token is properly linked and the linked contract supports the following interface:{
"type": "sendToEvmWithData",
"hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead),
"signatureChainId": the id of the chain used when signing in hexadecimal format; e.g. "0xa4b1" for Arbitrum,
"token": tokenName:tokenId; e.g. "PURR:0xc4bf3f870c0e9465323c0b6ed28096c2",
"amount": amount of token to send as a string; e.g. "0.01",
"sourceDex": name of perp dex to transfer from,
"destinationRecipient": address in addressEncoding format,
"addressEncoding": "hex" | "base58",
"destinationChainId": number,
"gasLimit": number,
"data": bytes,
"nonce": current timestamp in milliseconds as a Number, should match nonce
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds, must match the nonce in the action Object above | | | signature\* | Object | | | #### Response {% tabs %} {% tab title="200: OK" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Core USDC transfer `POST` `https://api.hyperliquid.xyz/exchange` Send usd to another address. This transfer does not touch the EVM bridge. The signature format is human readable for wallet interfaces. #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "usdSend",
"hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead),
"signatureChainId": the id of the chain used when signing in hexadecimal format; e.g. "0xa4b1" for Arbitrum,
"destination": address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000,
"amount": amount of usd to send as a string, e.g. "1" for 1 usd,
"time": current timestamp in milliseconds as a Number, should match nonce
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | {% tabs %} {% tab title="200: OK Successful Response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Core spot transfer `POST` `https://api.hyperliquid.xyz/exchange` Send spot assets to another address. This transfer does not touch the EVM bridge. The signature format is human readable for wallet interfaces. #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "spotSend",
"hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead),
"signatureChainId": the id of the chain used when signing in hexadecimal format; e.g. "0xa4b1" for Arbitrum,
"destination": address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000,
"token": tokenName:tokenId; e.g. "PURR:0xc4bf3f870c0e9465323c0b6ed28096c2",
"amount": amount of token to send as a string, e.g. "0.01",
"time": current timestamp in milliseconds as a Number, should match nonce
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | {% tabs %} {% tab title="200: OK Successful Response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ``` 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" } } ``` ## Initiate a withdrawal request `POST` `https://api.hyperliquid.xyz/exchange` This method is used to initiate the withdrawal flow. After making this request, the L1 validators will sign and send the withdrawal request to the bridge contract. There is a $1 fee for withdrawing at the time of this writing and withdrawals take approximately 5 minutes to finalize. #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "withdraw3",
"hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead),
"signatureChainId": the id of the chain used when signing in hexadecimal format; e.g. "0xa4b1" for Arbitrum,
"amount": amount of usd to send as a string, e.g. "1" for 1 usd,
"time": current timestamp in milliseconds as a Number, should match nonce,
"destination": address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds, must match the nonce in the action Object above | | signature\* | Object | | {% tabs %} {% tab title="200: OK " %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Transfer from Spot account to Perp account (and vice versa) `POST` `https://api.hyperliquid.xyz/exchange` This method is used to transfer USDC from the user's spot wallet to perp wallet and vice versa. **Headers** | Name | Value | | ---------------------------------------------- | ------------------ | | Content-Type\* | "application/json" | **Body**| Name | Type | Description |
|---|---|---|
| action* | Object | { "type": "usdClassTransfer", "hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead), "amount": amount of usd to transfer as a string, e.g. "1" for 1 usd. If you want to use this action for a subaccount, you can include subaccount: address after the amount, e.g. "1" subaccount:0x0000000000000000000000000000000000000000, "toPerp": true if (spot -> perp) else false, "nonce": current timestamp in milliseconds as a Number, must match nonce in outer request body } |
| nonce* | Number | Recommended to use the current timestamp in milliseconds, must match the nonce in the action Object above |
| signature* | Object |
{
"type": "cDeposit",
"hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead),
"signatureChainId": the id of the chain used when signing in hexadecimal format; e.g. "0xa4b1" for Arbitrum,
"wei": amount of wei to transfer as a number,
"nonce": current timestamp in milliseconds as a Number, must match nonce in outer request body
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds, must match the nonce in the action Object above | | signature\* | Object | | #### Response {% tabs %} {% tab title="200: OK" %} ```json {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Withdraw from staking `POST` `https://api.hyperliquid.xyz/exchange` This method is used to transfer native token from staking into the user's spot account. Note that transfers from staking to spot account go through a 7 day unstaking queue. #### Headers | Name | Value | | ---------------------------------------------- | ------------------ | | Content-Type\* | `application/json` | #### Body | Name | Type | Description | | ------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "cWithdraw",
"hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead),
"signatureChainId": the id of the chain used when signing in hexadecimal format; e.g. "0xa4b1" for Arbitrum,
"wei": amount of wei to transfer as a number,
"nonce": current timestamp in milliseconds as a Number, must match nonce in outer request body
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds, must match the nonce in the action Object above | | signature\* | Object | | #### Response {% tabs %} {% tab title="200: OK" %} ```json {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Delegate or undelegate stake from validator `POST` `https://api.hyperliquid.xyz/exchange` Delegate or undelegate native tokens to or from a validator. Note that delegations to a particular validator have a lockup duration of 1 day. #### Headers | Name | Value | | ---------------------------------------------- | ------------------ | | Content-Type\* | `application/json` | #### Body | Name | Type | Description | | ------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "tokenDelegate",
"hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead),
"signatureChainId": the id of the chain used when signing in hexadecimal format; e.g. "0xa4b1" for Arbitrum,
"validator": address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000,
"isUndelegate": boolean,
"wei": number,
"nonce": current timestamp in milliseconds as a Number, must match nonce in outer request body
}
| | nonce\* | number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | #### Response {% tabs %} {% tab title="200: OK" %} ```json {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Deposit or withdraw from a vault `POST` `https://api.hyperliquid.xyz/exchange` Add or remove funds from a vault. **Headers** | Name | Value | | ---------------------------------------------- | ------------------ | | Content-Type\* | `application/json` | **Body** | Name | Type | Description | | ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "vaultTransfer",
"vaultAddress": address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000,
"isDeposit": boolean,
"usd": number
}
| | nonce\* | number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | | expiresAfter | Number | Timestamp in milliseconds | **Response** {% tabs %} {% tab title="200" %} ```json {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Deposit or withdraw from an HIP-3 DEX's backstop liquidator `POST` `https://api.hyperliquid.xyz/exchange` Add or remove funds from HIP-3 backstop liquidator address. `ntl` is an integer in units of 1e-6 quote tokens. Amount must be a multiple of 1000 quote tokens (i.e. `ntl % 1000000000 == 0`). Only principal amount is withdrawable, not pnl. **Headers** | Name | Value | | ---------------------------------------------- | ------------------ | | Content-Type\* | `application/json` | **Body** | Name | Type | Description | | ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "hip3LiquidatorTransfer",
"dex": string (e.g. "xyz"),
"ntl": number,
"isDeposit": boolean
}
| | nonce\* | number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | | expiresAfter | Number | Timestamp in milliseconds | **Response** {% tabs %} {% tab title="200" %} ```json {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Approve an API wallet `POST` `https://api.hyperliquid.xyz/exchange` Approves an API Wallet (also sometimes referred to as an Agent Wallet). See [here](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/nonces-and-api-wallets#api-wallets) for more details. **Headers** | Name | Value | | ---------------------------------------------- | ------------------ | | Content-Type\* | `application/json` | **Body** | Name | Type | Description | | ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "approveAgent",
"hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead),
"signatureChainId": the id of the chain used when signing in hexadecimal format; e.g. "0xa4b1" for Arbitrum,
"agentAddress": address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000,
"agentName": Optional name for the API wallet. An account can have 1 unnamed approved wallet and up to 3 named ones. And additional 2 named agents are allowed per subaccount,
"nonce": current timestamp in milliseconds as a Number, must match nonce in outer request body
}
| | nonce\* | number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | **Response** {% tabs %} {% tab title="200" %} ```json {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Approve a builder fee `POST` `https://api.hyperliquid.xyz/exchange` Approve a maximum fee rate for a builder. **Headers** | Name | Value | | ---------------------------------------------- | ------------------ | | Content-Type\* | `application/json` | **Body** | Name | Type | Description | | ------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "approveBuilderFee",
"hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead),
"signatureChainId": the id of the chain used when signing in hexadecimal format; e.g. "0xa4b1" for Arbitrum,
"maxFeeRate": the maximum allowed builder fee rate as a percent string; e.g. "0.001%",
"builder": address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000,
"nonce": current timestamp in milliseconds as a Number, must match nonce in outer request body
}
| | nonce\* | number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | **Response** {% tabs %} {% tab title="200" %} ```json {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Place a TWAP order `POST` `https://api.hyperliquid.xyz/exchange` #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "twapOrder",
"twap": {
"a": Number,
"b": Boolean,
"s": String,
"r": Boolean,
"m": Number,
"t": Boolean
}
}
Meaning of keys:
a is asset
b is isBuy
s is size
r is reduceOnly
m is minutes
t is randomize
{
"type": "twapCancel",
"a": Number,
"t": Number
}
Meaning of keys:
a is asset
t is twap\_id
{
"type": "reserveRequestWeight",
"weight": Number
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | | expiresAfter | Number | Timestamp in milliseconds | {% tabs %} {% tab title="200: OK Successful Response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Invalidate Pending Nonce (noop) `POST` `https://api.hyperliquid.xyz/exchange` This action does not do anything (no operation), but causes the nonce to be marked as used. This can be a more effective way to cancel in-flight orders than the cancel action. #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | -------------------------------------------------------- | | action\* | Object |{
"type": "noop"
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | | expiresAfter | Number | Timestamp in milliseconds | {% tabs %} {% tab title="200: OK Successful Response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Enable HIP-3 DEX abstraction `POST` `https://api.hyperliquid.xyz/exchange` NOTE: deprecrated. Prefer `userSetAbstraction`. If set, actions on HIP-3 perps will automatically transfer collateral from validator-operated USDC perps balance for HIP-3 DEXs where USDC is the collateral token, and spot otherwise. When HIP-3 DEX abstraction is active, collateral is returned to the same source (validator-operated USDC perps or spot balance) when released from positions or open orders. #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body| Name | Type | Description |
|---|---|---|
| action* | Object | { "type": "userDexAbstraction", "hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead), "signatureChainId": the id of the chain used when signing in hexadecimal format; e.g. "0xa4b1" for Arbitrum, "user": address in 42-character hexadecimal format. Can be a sub-account of the user, "enabled": boolean, "nonce": current timestamp in milliseconds as a Number, should match nonce } |
| nonce* | Number | Recommended to use the current timestamp in milliseconds |
| signature* | Object |
{
"type": "agentEnableDexAbstraction"
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | {% tabs %} {% tab title="200: OK Successful Response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Set User Abstraction `POST` `https://api.hyperliquid.xyz/exchange` #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | action\* | Object |{
"type": "userSetAbstraction",
"hyperliquidChain": "Mainnet" (on testnet use "Testnet" instead),
"signatureChainId": the id of the chain used when signing in hexadecimal format; e.g. "0xa4b1" for Arbitrum,
"user": address in 42-character hexadecimal format. Can be a sub-account of the user,
"abstraction": one of the strings \["disabled", "unifiedAccount", "portfolioMargin"],
"nonce": current timestamp in milliseconds as a Number, should match nonce
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | {% tabs %} {% tab title="200: OK Successful Response" %} ```json {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Set User Abstraction (agent) `POST` `https://api.hyperliquid.xyz/exchange` #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "agentSetAbstraction",
"abstraction": one of the strings \["i", "u", "p"] where "i" is "disabled", "u" is "unifiedAccount", and "p" is "portfolioMargin"
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | {% tabs %} {% tab title="200: OK Successful Response" %} ```json {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Split outcome Split `X` quote tokens into `X` Yes and `X` No shares. `POST` `https://api.hyperliquid.xyz/exchange` #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | | action\* | Object |{
"type": "userOutcome",
"splitOutcome": { "outcome": Number, amount: String (e.g., "123.0") }
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | {% tabs %} {% tab title="200: OK Successful Response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Merge outcome Merge `X` Yes and `X` No shares into `X` quote tokens. `POST` `https://api.hyperliquid.xyz/exchange` #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | | ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | ----------------------------------- | | action\* | Object |{
"type": "userOutcome",
"mergeOutcome": { "outcome": Number, amount: String | null (null means max) }
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | | signature\* | Object | | | {% tabs %} {% tab title="200: OK Successful Response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Merge question Merge `X` Yes shares from each outcome associated to the same question into `X` quote tokens. `POST` `https://api.hyperliquid.xyz/exchange` #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | | ------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------- | ----------------------------------- | | action\* | Object |{
"type": "userOutcome",
"mergeQuestion": { "question": Number, amount: String | null (null means max) }
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | | signature\* | Object | | | {% tabs %} {% tab title="200: OK Successful Response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Negate outcome Convert `X` No shares from an outcome associated with a question into `X` Yes shares of every other outcome associated with the question. `POST` `https://api.hyperliquid.xyz/exchange` #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "userOutcome",
"negateOutcome": { "question": Number, "outcome": Number, amount: String }
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | {% tabs %} {% tab title="200: OK Successful Response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Validator vote on risk-free rate for aligned quote asset `POST` `https://api.hyperliquid.xyz/exchange` #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------- | | action\* | Object |{
"type": "validatorL1Stream",
"riskFreeRate": String // e.g. "0.04" for 4%
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | {% tabs %} {% tab title="200: OK Successful Response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Authorize AQAv2 role `POST` `https://api.hyperliquid.xyz/exchange` #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | | ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ | ---------------------- | | action\* | Object |{
"type": "authorizeAqav2Role",
"token": number // e.g. 0 for USDC,
"role": "technical" | "treasury"
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | | signature\* | Object | | | {% tabs %} {% tab title="200: OK Successful Response" %} ``` {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} ## Claim rewards `POST` `https://api.hyperliquid.xyz/exchange` #### Headers | Name | Type | Description | | ---------------------------------------------- | ------ | ------------------ | | Content-Type\* | String | "application/json" | #### Request Body | Name | Type | Description | | ------------------------------------------- | ------ | -------------------------------------------------------- | | action\* | Object |{
"type": "claimRewards"
}
| | nonce\* | Number | Recommended to use the current timestamp in milliseconds | | signature\* | Object | | {% tabs %} {% tab title="200: OK Successful Response" %} ```json {'status': 'ok', 'response': {'type': 'default'}} ``` {% endtab %} {% endtabs %} # Websocket WebSocket endpoints are available for real-time data streaming and as an alternative to HTTP request sending on the Hyperliquid exchange. The WebSocket URLs by network are: * Mainnet: `wss://api.hyperliquid.xyz/ws` * Testnet: `wss://api.hyperliquid-testnet.xyz/ws`. ### Connecting To connect to the WebSocket API, establish a WebSocket connection to the respective URL based on the desired network. Once connected, you can start sending subscription messages to receive real-time data updates. Example from command line: ``` $ 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"}}} ``` Important: all automated users should handle disconnects from the server side and gracefully reconnect. Disconnection from API servers may happen periodically and without announcement. Missed data during the reconnect will be present in the snapshot ack on reconnect. Users can also manually query any missed data using the corresponding info request. Note: this doc uses Typescript for defining many of the message types. The python SDK also has examples [here](https://github.com/hyperliquid-dex/hyperliquid-python-sdk/blob/master/hyperliquid/utils/types.py) and example connection code [here](https://github.com/hyperliquid-dex/hyperliquid-python-sdk/blob/master/hyperliquid/websocket_manager.py). # Subscriptions This page describes subscribing to data streams using the WebSocket API. ### Subscription messages To subscribe to specific data feeds, you need to send a subscription message. The subscription message format is as follows: ```json { "method": "subscribe", "subscription": { ... } } ``` The subscription ack provides a snapshot of previous data for time series data (e.g. user fills). These snapshot messages are tagged with `isSnapshot: true` and can be ignored if the previous messages were already processed. The subscription object contains the details of the specific feed you want to subscribe to. Choose from the following subscription types and provide the corresponding properties: 1. `allMids`: * Subscription message: `{ "type": "allMids", "dex": "