> ## Documentation Index
> Fetch the complete documentation index at: https://chainstack-docs-polygon-erigon-trace-deprecation.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Update isolated margin | Hyperliquid exchange
> Adds or removes margin from an isolated perpetual position on the Hyperliquid exchange. Chainstack Hyperliquid exchange reference.
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](/docs/hyperliquid-methods) for the full availability breakdown.
This endpoint requires signature authentication. See our comprehensive [Authentication via Signatures guide](/docs/hyperliquid-authentication-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.
## 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
```shell cURL theme={null}
# 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": {...}
}'
```
```python Python (hyperliquid-python-sdk) theme={null}
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)
```
```typescript TypeScript (@nktkas/hyperliquid) theme={null}
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
```json theme={null}
{
"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.
## OpenAPI
````yaml openapi/hyperliquid_node_api/hypercore_exchange/exchange_update_isolated_margin.json post /exchange
openapi: 3.0.0
info:
title: Hyperliquid Exchange API
version: 1.0.0
description: >-
API for trading operations on Hyperliquid exchange requiring authentication.
⚠️ WARNING: These endpoints require EIP-712 signatures for authentication.
The example values provided will NOT work without proper cryptographic
signing. You must implement EIP-712 signing to use these endpoints
successfully.
servers:
- url: https://api.hyperliquid.xyz
security: []
paths:
/exchange:
post:
tags:
- hyperliquid exchange
summary: Update isolated margin
operationId: updateIsolatedMargin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
action:
type: object
properties:
type:
type: string
default: updateIsolatedMargin
enum:
- updateIsolatedMargin
description: Action type for updating isolated margin
asset:
type: integer
description: Asset index to update isolated margin for
isBuy:
type: boolean
description: >-
true for long position (always true, reserved for future
hedge mode)
ntli:
type: integer
description: >-
Margin amount to add (positive) or remove (negative) in
raw units
required:
- type
- asset
- isBuy
- ntli
nonce:
type: integer
description: Current timestamp in milliseconds
signature:
type: object
description: EIP-712 signature of the action with r, s, v components
properties:
r:
type: string
description: ECDSA signature r component (hex string)
example: >-
0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
s:
type: string
description: ECDSA signature s component (hex string)
example: >-
0xfedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321
v:
type: integer
description: ECDSA recovery id (27 or 28)
example: 27
required:
- r
- s
- v
vaultAddress:
type: string
description: >-
Address when trading on behalf of a vault or subaccount
(optional)
nullable: true
required:
- action
- nonce
- signature
example:
action:
type: updateIsolatedMargin
asset: 0
isBuy: true
ntli: 100000000
nonce: 1705234567890
signature:
r: >-
0x0000000000000000000000000000000000000000000000000000000000000000
s: >-
0x0000000000000000000000000000000000000000000000000000000000000000
v: 27
vaultAddress: null
responses:
'200':
description: Isolated margin update result
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: Request status
response:
type: object
properties:
type:
type: string
data:
type: object
properties:
status:
type: string
description: Result status
example:
status: ok
response:
type: updateIsolatedMargin
data:
status: success
````