Exchange endpoint

The exchange endpoint is used to interact with and trade on the Hyperliquid chain. See the Python SDK for code to generate signatures for these requests.

Many of the requests take asset as an input. For perpetuals this is the index in the universe field returned by themeta response. For spot assets, use 10000 + index where index is the corresponding index in spotMeta.universe. For example, when submitting an order for PURR/USDC, the asset that should be used is 10000 because its asset index in the spot metadata is 0.

Place an order

POST https://api.hyperliquid.xyz/exchange

See Python SDK for full featured examples on the fields of the order request.

For limit orders, TIF (time-in-force) sets the behavior of the order upon first hitting the book.

ALO (add liquidity only, i.e. "post only") will be canceled instead of immediately matching.

IOC (immediate or cancel) will have the unfilled part canceled instead of resting.

GTC (good til canceled) orders have no special behavior.

Client Order ID (cloid) is an optional 128 bit hex string, e.g. 0x1234567890abcdef1234567890abcdef

Headers

Name	Type	Description
Content-Type*	String	"application/json"

Request Body

Name	Type	Description
action*	Object	{ "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
nonce*	Number	Recommended to use the current timestamp in milliseconds
signature*	Object
vaultAddress	String	If trading on behalf of a vault, its Onchain address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000

200: OK Successful Response (resting)

{
   "status":"ok",
   "response":{
      "type":"order",
      "data":{
         "statuses":[
            {
               "resting":{
                  "oid":77738308
               }
            }
         ]
      }
   }
}

200: OK Error Response

{
   "status":"ok",
   "response":{
      "type":"order",
      "data":{
         "statuses":[
            {
               "error":"Order must have minimum value of $10."
            }
         ]
      }
   }
}

200: OK Successful Response (filled)

{
   "status":"ok",
   "response":{
      "type":"order",
      "data":{
         "statuses":[
            {
               "filled":{
                  "totalSz":"0.02",
                  "avgPx":"1891.4",
                  "oid":77747314
               }
            }
         ]
      }
   }
}

Cancel order(s)

POST https://api.hyperliquid.xyz/exchange

Headers

Name	Type	Description
Content-Type*	String	"application/json"

Request Body

Name	Type	Description
action*	Object	{ "type": "cancel", "cancels": [ { "a": Number, "o": Number } ] } Meaning of keys: a is asset o is oid (order id)
nonce*	Number	Recommended to use the current timestamp in milliseconds
signature*	Object
vaultAddress	String	If trading on behalf of a vault, its address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000

200: OK Successful Response

{
   "status":"ok",
   "response":{
      "type":"cancel",
      "data":{
         "statuses":[
            "success"
         ]
      }
   }
}

200: OK Error Response

{
   "status":"ok",
   "response":{
      "type":"cancel",
      "data":{
         "statuses":[
            {
               "error":"Order was never placed, already canceled, or filled."
            }
         ]
      }
   }
}

Cancel order(s) by cloid

POST https://api.hyperliquid.xyz/exchange

Headers

Name	Type	Description
Content-Type*	String	"application/json"

Request Body

Name	Type	Description
action*	Object	{ "type": "cancelByCloid", "cancels": [ { "asset": Number, "cloid": String } ] }
nonce*	Number	Recommended to use the current timestamp in milliseconds
signature*	Object
vaultAddress	String	If trading on behalf of a vault, its address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000

200: OK Successful Response

200: OK Error Response

Schedule Cancel (dead man's switch)

POST https://api.hyperliquid.xyz/exchange

{"type": "scheduleCancel", "time": <unix milliseconds> | null}

Schedule a cancel-all operation at a future time. Setting time to null will remove any outstanding scheduled cancel operation.

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, "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) } } 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)
nonce*	Number	Recommended to use the current timestamp in milliseconds
signature*	Object
vaultAddress	String	If trading on behalf of a vault, its Onchain address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000

200: OK Successful Response

200: OK Error Response

Modify multiple orders

POST https://api.hyperliquid.xyz/exchange

Headers

Name	Type	Description
Content-Type*	String	"application/json"

Request Body

Name	Type	Description
action*	Object	{ "type": "batchModify", "modifies": [ "oid": Number, "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) }] } 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)
nonce*	Number	Recommended to use the current timestamp in milliseconds
signature*	Object
vaultAddress	String	If trading on behalf of a vault, its Onchain address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000

Update leverage

POST https://api.hyperliquid.xyz/exchange

Update cross or isolated leverage on a coin.

Headers

Name	Type	Description
Content-Type*	String	"application/json"

Request Body

Name	Type	Description
action*	Object	{ "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, its Onchain address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000

200: OK Successful response

{'status': 'ok', 'response': {'type': 'default'}}

Update isolated margin

POST https://api.hyperliquid.xyz/exchange

Add or remove margin from isolated position

Headers

Name	Type	Description
Content-Type*	String	"application/json"

Request Body

Name	Type	Description
action*	Object	{ "type": "updateIsolatedMargin", "asset": index of coin, "isBuy": true, (this parameter won't have any effect until hedge mode is introduced) "ntli": float representing amount to add or remove, }
nonce*	Number	Recommended to use the current timestamp in milliseconds
signature*	Object
vaultAddress	String	If trading on behalf of a vault, its Onchain address in 42-character hexadecimal format; e.g. 0x0000000000000000000000000000000000000000

200: OK Successful response

{'status': 'ok', 'response': {'type': 'default'}}

L1 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 ins 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

200: OK Successful Response

{'status': 'ok', 'response': {'type': 'default'}}

L1 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 ins 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

200: OK Successful Response

{'status': 'ok', 'response': {'type': 'default'}}

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 ins 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

200: OK

{'status': 'ok', 'response': {'type': 'default'}}

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": "spotUser", "classTransfer": { "usdc": amount of raw usdc to send (i.e. float amount times 1e6), "toPerp": True if (spot -> perp) else False } }
nonce*	Number	Recommended to use the current timestamp in milliseconds, must match the nonce in the action Object above
signature*	Object

Response

200: OK

{'status': 'ok', 'response': {'type': 'default'}}

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

Response

200

{'status': 'ok', 'response': {'type': 'default'}}

Approve an API Wallet

POST https://api.hyperliquid.xyz/exchange

Approves an API Wallet (also sometimes referred to as an Agent Wallet). See here 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 ins 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

200

{'status': 'ok', 'response': {'type': 'default'}}

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 ins 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

200

{'status': 'ok', 'response': {'type': 'default'}}