Hyperliquid Connection¶

Paros trades your Hyperliquid account through an agent key that you approve. This page covers which key signs what, how to bind the account, and the operations that drive the trading loop.

Agent and master signing¶

Every action on Hyperliquid is signed by one of two keys.

The agent is the automated trading key Paros holds. It signs immediately: no approval step, no round trip to custody.

The master wallet is your custody account's wallet, and it signs through threshold signing. Anything that moves money out of the Hyperliquid account is master-signed, and the request waits while that signature is produced.

The rule that follows from this: the agent can do anything that keeps money inside the account. Anything that moves money out needs the master.

Signed by the agent, instant	Signed by the master, waits
Place an order	Move funds between spot and futures
Add margin to a position	Move funds between the exchange and the chain
Reduce or close a position	Withdraw off Hyperliquid
Set or change a stop or target	Approve the builder fee
Cancel orders
Change leverage or margin mode
Run a staged order (TWAP)

A rebalance that mixes both kinds of step runs instantly except for the step that moves money, which waits on the master.

Open the diagram full screen ↗

What this means for liquidation defence¶

The margin top-up is an agent action, so it lands with no signature in the loop. A position drifting toward liquidation can be defended immediately.

One condition: the top-up has to use margin already sitting in the futures balance. If the money first has to move from the spot side, that transfer is a master action and waits.

Keep a margin buffer on the futures side

A top-up that draws on futures margin is instant. A top-up that first pulls money from spot inherits the custody wait, which is the wrong thing to discover while a position is under pressure.

Binding an account¶

Hyperliquid runs against one custody account, and that account's wallet address becomes your Hyperliquid identity. Hyperliquid requires a funded account before anything else.

Fund the account before you approve

Hyperliquid rejects agent approval from an unfunded account. Get equity above zero on the venue first, then approve. A deposit playlist financed with the hyperliquid_deposit strategy template is the usual way to do it, and the positions feed is how you confirm the money landed.

Open the diagram full screen ↗

Check for an existing binding¶

Hyperliquid ↗ · Managed Accounts ↗

GET /api/managed-accounts/hyperliquid-binding/accounts?customerId={customerId}

data: null means a new user. If an account comes back, a binding already exists and may still be pending. Reuse that account in the steps below rather than starting a second binding.

Approve the agent¶

Hyperliquid ↗ · Managed Accounts ↗

POST /api/managed-accounts/{id}/hyperliquid-binding/approve

{
  "venueAccountAddress": "0x...",
  "agentName": "paros-agent",
  "expiryDays": 30,
  "isRevoke": false
}

agentName is at most 16 characters, using letters, digits, spaces, - and _.
expiryDays runs from 1 to 180. Send either expiryDays or expiresAt as an ISO datetime, never both.
expiresAt is optional. The agent's validUntil comes back from the venue, and a null validUntil means the agent does not expire. Around 90 days is typical.

The call creates the Hyperliquid agent and asks your custody signers to authorise it against the master account. Because the agent's authority is gated by that master account, the agent cannot remove funds from Hyperliquid.

Give the call at least 180 seconds

Approve waits synchronously for the signing ceremony, and the ceremony can exceed 60 seconds. A client timeout of 30 or 60 seconds will cut off a request that is still succeeding on the venue. Set at least 180 seconds.

A 409 means do not retry

409 with "already in progress" means the first approve call is still running. Firing a second approve starts a second ceremony and lengthens the wait. Poll approval status instead.

Confirm the approval¶

Hyperliquid ↗ · Managed Accounts ↗

GET /api/managed-accounts/{id}/hyperliquid-binding/approval-status

Setup is complete when the response has approved: true and agents[] contains the agent's agentAddress. If approved is false and agents is empty, the binding is still pending: check the equity on the positions feed, then call approve again.

Read this from the venue rather than from a stored copy. Agent approval status is the source of truth.

Setup is complete when the account is bound and the agent is approved

The builder fee is only part of setup when the fee feature is enabled for your account.

Builder fee¶

Hyperliquid ↗

The builder fee is an optional per-trade fee on Hyperliquid, capped at a configurable maximum rate, for example 0.1% on perps. Approve it only if the fee feature is enabled for your account.

POST /api/managed-accounts/{id}/hyperliquid-binding/builder-fee
{ "isRevoke": false }

GET  /api/managed-accounts/{id}/hyperliquid-binding/builder-fee

The read returns approved and maxFeeRate. maxFeeRate is in tenths of a basis point, so a 0.1% fee reads as 100.

To revoke, approve again with isRevoke: true. That clears the fee and updates the same builder in place, so it does not consume a slot against the builder cap. A builder has to hold a balance before it can be approved.

Reading account state¶

Hyperliquid ↗

Method	Endpoint	Returns
`GET`	`/api/managed-accounts/{id}/hyperliquid/positions`	Open positions and equity
`GET`	`/api/managed-accounts/{id}/hyperliquid/markets`	Market list
`GET`	`/api/managed-accounts/{id}/hyperliquid/markets/{symbol}/state`	Mark price, funding and the values you use for rule thresholds
`GET`	`/api/managed-accounts/{id}/hyperliquid/open-orders`	Working orders
`GET`	`/api/managed-accounts/{id}/hyperliquid/orders`	Resting orders plus running TWAPs
`GET`	`/api/managed-accounts/{id}/hyperliquid/twaps`	TWAP runs
`GET`	`/api/managed-accounts/{id}/hyperliquid/activity`	Fills and account activity
`GET`	`/api/managed-accounts/{id}/hyperliquid/spot-balances`	Spot balances
`GET`	`/api/managed-accounts/{id}/hyperliquid/settings`	Trading settings

Portfolio and summary are scoped by query parameter rather than by path:

Managed Accounts ↗

GET /api/managed-accounts/hyperliquid/portfolio?customerId={customerId}&accountId={id}
GET /api/managed-accounts/hyperliquid/summary?customerId={customerId}&accountId={id}

portfolio also accepts include to select the sections you want back.

Read against the master address

Hyperliquid state reads must query the master account address. Read against the agent address and every feed comes back empty, even with the agent live and approved. An empty positions response from a funded account is usually this mistake, not a broken binding.

Managing positions¶

Hyperliquid ↗

POST /api/managed-accounts/{id}/hyperliquid/positions/add-margin
{ "productId": "ETH", "amountUsd": "50" }

POST /api/managed-accounts/{id}/hyperliquid/positions/close
{ "productId": "ETH" }

add-margin takes productId and amountUsd and works only on isolated-margin positions. Leverage and position limits are enforced on the venue, so an over-cap leverage value comes back rejected rather than silently clamped.

close takes productId alone and sends a reduce-only market order.

Both operations invalidate the account's portfolio cache, so a read straight afterwards returns fresh values.

Cancelling:

POST /api/managed-accounts/{id}/hyperliquid/orders/cancel
{ "orderId": "...", "productId": "ETH" }

POST /api/managed-accounts/{id}/hyperliquid/twaps/cancel

orders/cancel needs orderId together with productId. twaps/cancel stops a running TWAP. Both are agent-signed and instant.

Settings are writable through PUT /api/managed-accounts/{id}/hyperliquid/settings. The writable field is the spot reserve floor, for example { "spotReserveFloorUsd": "10" }. Leverage is not set here.

Placing orders¶

There is no standalone order-placement endpoint in the public API. Orders come from an armed advanced strategy or from a playlist action, and both manage the order lifecycle, ownership and cancel path.

Advanced Strategies ↗

For a one-off order, express it as a playlist step or as an advanced strategy with a single rule. Decide which surface your integration targets before you build the order flow, because neither one is a thin wrapper over a place-order call.

Practical notes¶

Resolve asset indices from the market universe instead of hardcoding them. The BTC asset index differs between mainnet and testnet, so a constant that works in one place is wrong in the other.
Order prices take five significant figures, then no more than 6 − szDecimals decimals. BTC ends up with integer prices.
updateIsolatedMargin takes ntli as dollars × 1e6.
Fund the account on the venue before approving the agent or trading.