Update isolated margin | Hyperliquid exchange

Adds or removes margin from an isolated perpetual position on the Hyperliquid exchange. Chainstack Hyperliquid exchange reference.

POST /exchange

Update isolated margin

cURL

curl --request POST \
  --url https://api.hyperliquid.xyz/exchange \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": {
    "type": "updateIsolatedMargin",
    "asset": 0,
    "isBuy": true,
    "ntli": 100000000
  },
  "nonce": 1705234567890,
  "signature": {
    "r": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "s": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "v": 27
  },
  "vaultAddress": null
}
'

import requests

url = "https://api.hyperliquid.xyz/exchange"

payload = {
    "action": {
        "type": "updateIsolatedMargin",
        "asset": 0,
        "isBuy": True,
        "ntli": 100000000
    },
    "nonce": 1705234567890,
    "signature": {
        "r": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "s": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "v": 27
    },
    "vaultAddress": None
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    action: {type: 'updateIsolatedMargin', asset: 0, isBuy: true, ntli: 100000000},
    nonce: 1705234567890,
    signature: {
      r: '0x0000000000000000000000000000000000000000000000000000000000000000',
      s: '0x0000000000000000000000000000000000000000000000000000000000000000',
      v: 27
    },
    vaultAddress: null
  })
};

fetch('https://api.hyperliquid.xyz/exchange', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hyperliquid.xyz/exchange",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'action' => [
        'type' => 'updateIsolatedMargin',
        'asset' => 0,
        'isBuy' => true,
        'ntli' => 100000000
    ],
    'nonce' => 1705234567890,
    'signature' => [
        'r' => '0x0000000000000000000000000000000000000000000000000000000000000000',
        's' => '0x0000000000000000000000000000000000000000000000000000000000000000',
        'v' => 27
    ],
    'vaultAddress' => null
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hyperliquid.xyz/exchange"

	payload := strings.NewReader("{\n  \"action\": {\n    \"type\": \"updateIsolatedMargin\",\n    \"asset\": 0,\n    \"isBuy\": true,\n    \"ntli\": 100000000\n  },\n  \"nonce\": 1705234567890,\n  \"signature\": {\n    \"r\": \"0x0000000000000000000000000000000000000000000000000000000000000000\",\n    \"s\": \"0x0000000000000000000000000000000000000000000000000000000000000000\",\n    \"v\": 27\n  },\n  \"vaultAddress\": null\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.hyperliquid.xyz/exchange")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": {\n    \"type\": \"updateIsolatedMargin\",\n    \"asset\": 0,\n    \"isBuy\": true,\n    \"ntli\": 100000000\n  },\n  \"nonce\": 1705234567890,\n  \"signature\": {\n    \"r\": \"0x0000000000000000000000000000000000000000000000000000000000000000\",\n    \"s\": \"0x0000000000000000000000000000000000000000000000000000000000000000\",\n    \"v\": 27\n  },\n  \"vaultAddress\": null\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.hyperliquid.xyz/exchange")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": {\n    \"type\": \"updateIsolatedMargin\",\n    \"asset\": 0,\n    \"isBuy\": true,\n    \"ntli\": 100000000\n  },\n  \"nonce\": 1705234567890,\n  \"signature\": {\n    \"r\": \"0x0000000000000000000000000000000000000000000000000000000000000000\",\n    \"s\": \"0x0000000000000000000000000000000000000000000000000000000000000000\",\n    \"v\": 27\n  },\n  \"vaultAddress\": null\n}"

response = http.request(request)
puts response.read_body

200

{
  "status": "ok",
  "response": {
    "type": "updateIsolatedMargin",
    "data": {
      "status": "success"
    }
  }
}

You can only use this endpoint on the official Hyperliquid public API. It is not available through Chainstack, as the open-source node implementation does not support it yet. See Hyperliquid methods for the full availability breakdown.

This endpoint requires signature authentication. See our comprehensive Authentication via Signatures guide for implementation details.

Adds or removes margin from an isolated perpetual position on the Hyperliquid exchange. This allows you to adjust the margin allocated to a specific position without closing it.

Get your own node endpoint today

Start for free and get your app to production levels immediately. No credit card required.

You can sign up with your GitHub, X, Google, or Microsoft account.

Parameters

Required parameters

• action (object, required) — The update isolated margin action object containing:

  • type (string) — Must be "updateIsolatedMargin" or "topUpIsolatedOnlyMargin"
  • For "updateIsolatedMargin":
    • asset (number) — Asset index of the coin
    • isBuy (boolean) — true (reserved for future hedge mode support)
    • ntli (number) — Amount to add (positive) or remove (negative) in USDC with 6 decimals (e.g., 1000000 = 1 USDC)
  • For "topUpIsolatedOnlyMargin":
    • asset (number) — Asset index of the coin
    • leverage (string) — Target leverage as a float string (e.g., “5.0”)

• nonce (number, required) — Current timestamp in milliseconds (must be recent)

• signature (object, required) — EIP-712 signature of the action

Optional parameters

• vaultAddress (string, optional) — Address when trading on behalf of a vault or subaccount
• expiresAfter (number, optional) — Timestamp in milliseconds after which the request is rejected

Margin adjustment types

Direct USDC adjustment

Use "updateIsolatedMargin" to add or remove a specific USDC amount:

• Positive ntli — Adds margin to the position
• Negative ntli — Removes margin from the position

Target leverage adjustment

Use "topUpIsolatedOnlyMargin" to set a target leverage:

• Calculates required margin to achieve the specified leverage
• Only allows adding margin (top-up), not removal

Returns

Returns an object with update status:

• status — "ok" if successful
• response — Contains update details:
  • type — "default"

Example request

cURL

# Add 100 USDC to isolated position
curl -X POST https://api.hyperliquid.xyz/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "type": "updateIsolatedMargin",
      "asset": 0,
      "isBuy": true,
      "ntli": 100000000
    },
    "nonce": 1234567890123,
    "signature": {...}
  }'

# Set position to 5x leverage
curl -X POST https://api.hyperliquid.xyz/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "action": {
      "type": "topUpIsolatedOnlyMargin",
      "asset": 0,
      "leverage": "5.0"
    },
    "nonce": 1234567890123,
    "signature": {...}
  }'

from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants
import eth_account

# Initialize with your private key
account = eth_account.Account.from_key("0x...")
exchange = Exchange(account, constants.MAINNET_API_URL)

# Add 100 USDC to the isolated BTC position
add_result = exchange.update_isolated_margin(amount=100.0, name="BTC")

# Remove 50 USDC from the isolated BTC position (negative for removal)
remove_result = exchange.update_isolated_margin(amount=-50.0, name="BTC")

print(add_result)

import { ExchangeClient, HttpTransport } from "@nktkas/hyperliquid";
import { privateKeyToAccount } from "viem/accounts";

const wallet = privateKeyToAccount("0x...");
const transport = new HttpTransport();
const exchange = new ExchangeClient({ transport, wallet });

// Add 100 USDC to the isolated position (ntli is the float amount * 1e6)
const addResult = await exchange.updateIsolatedMargin({
  asset: 0,
  isBuy: true,
  ntli: 100 * 1e6,
});

// Remove 50 USDC from the isolated position (negative for removal)
const removeResult = await exchange.updateIsolatedMargin({
  asset: 0,
  isBuy: true,
  ntli: -50 * 1e6,
});

// Set the position to 5x leverage by topping up isolated margin
const leverageResult = await exchange.topUpIsolatedOnlyMargin({
  asset: 0,
  leverage: "5.0",
});

console.log(addResult);

Response example

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

Important considerations

• Isolated only — This only works for isolated margin positions, not cross margin
• Position required — Must have an existing isolated position
• Removal limits — Cannot remove margin below minimum requirements
• Liquidation risk — Removing margin increases liquidation risk

Use cases

• Risk management — Add margin to reduce liquidation risk during volatility
• Capital optimization — Remove excess margin for use elsewhere
• Dynamic adjustment — Adjust position margin based on market conditions
• Leverage targeting — Set specific leverage levels for risk management

The isBuy parameter is currently always true but is included for future hedge mode support where long and short positions can be held simultaneously.

Removing margin from a position increases its effective leverage and liquidation risk. Always ensure remaining margin meets minimum requirements.

Body

application/json

action · object · required

Show child attributes

nonce · integer · required

Current timestamp in milliseconds

signature · object · required

EIP-712 signature of the action with r, s, v components

Show child attributes

vaultAddress · string | null

Address when trading on behalf of a vault or subaccount (optional)

Response

200 - application/json

Isolated margin update result

status · string

Request status

response · object

Show child attributes