# Hyperliquid (/docs/nodes/defi/hyperliquid)

Trade Hyperliquid perps with USDC from your Solana wallet: fund from Solana, trade with leverage, take profit, and stop loss, and send the USDC back. Plus live markets, funding, and any account's positions and fills.



The Hyperliquid node lets your workflows trade perpetuals on [Hyperliquid](https://hyperliquid.gitbook.io/hyperliquid-docs)'s on-chain exchange (HyperCore) with USDC from your Solana wallet. `depositFromSolana` moves the USDC in, the node trades it from your own Hyperliquid account (market and limit orders sized in dollars or coins, leverage, reduce-only closes, and take-profit and stop-loss triggers), and `withdrawToSolana` sends it back. Your Solaris AI wallet and credits stay on Solana. The node also reads the public market and account data any workflow can use.

No API key is needed. Reads go to Hyperliquid's public info API, and they work for any account: every Hyperliquid account is public, so the node can watch a known trader's positions, fills, and resting orders by their address. Trading signs from **your Hyperliquid account**, created for your Solaris AI login and held by Privy. Its address starts with `0x` because Hyperliquid accounts use Ethereum-style keys. Each order is an EIP-712 signature the exchange verifies; there is no gas and no transaction to broadcast. No private key ever leaves Privy, and every trading operation carries a **Dry run** switch that builds the exact order against the live price without signing it.

Prerequisites [#prerequisites]

* **Market reads and other accounts**: nothing.
* **Your own account and trading**: open the node's settings and click **Enable Hyperliquid** once. It creates your Hyperliquid account under your login and lets your workflows sign orders for it. You stay the owner, and there is no key to back up. The account card then shows the address, account value, withdrawable USDC, and open positions.
* **Collateral**: the account trades with USDC it holds on Hyperliquid. Fund it with `depositFromSolana`, which moves USDC from your Solana wallet (that operation needs server-side signing authorized on your Solana wallet, like a swap), and bring it back with `withdrawToSolana`.
* **Already trade on Hyperliquid?** Copy your Solaris AI account's address from the account card and send USDC to it from your main account in Hyperliquid's app. It arrives instantly, with no bridge. `sendUsdc` sends it back the same way.

What to build with it [#what-to-build-with-it]

* **Solana in, Solana out**: a cron trigger every hour; `getPosition`, `getAccount`, `getOpenOrders`, `getFills`, `getFundingPayments`, `getTransfers`, and `getMarket` for SOL, plus a Storage ledger of its own deposits; a Code node that picks one action; and a Condition that routes it. On a dip it runs `depositFromSolana`, records the credited deposit and its own client order id, then `placeOrder` with a stop and a take profit. If its long has lost its stop, `setTpSl` puts it back. Once the trade is closed, `withdrawToSolana` sends home exactly its own USDC (the stake plus or minus the trade, fees, and funding). It acts only on what its own fills prove is its own: if anything else trades or holds a position on the account (every market shares its margin), or USDC leaves the account some other way (`getTransfers`), it stands down instead of guessing. While it holds a stake, treat the account as the template's.
* **Funding watch**: a cron trigger every hour, `getMarket` for ETH, a Condition on `{hyperliquidResponse.data.fundingAprPct}` above 30, and a Telegram message. Positive funding means longs pay shorts.
* **Whale tracker**: a cron trigger every 5 minutes, `getAccount` with a known trader's address, a Condition on `{hyperliquidResponse.data.positionCount}`, then an AI node that summarizes `{json hyperliquidResponse.data.positions}`.
* **Breakout entry with protection**: `getCandles` for BTC on `1h`, a Code node that checks the last close against the range, then `placeOrder` long $200 at market with 3x isolated leverage and a stop loss below the range. Run it with Dry run on first; the output carries the exact order.
* **One position at a time**: `getPosition` first and a Condition on `{hyperliquidResponse.data.hasPosition}` so the order node only runs when you are flat.
* **Scheduled de-risking**: a Friday cron, `closePosition` with Close % `50` on each market you hold, and a Discord message with `{hyperliquidResponse.data.avgPx}`.
* **Clean slate**: `cancelAllOrders` before a strategy re-quotes its limit orders.
* **Top up before trading**: `getAccount`, a Condition on `{hyperliquidResponse.data.withdrawable}` below 50, then `depositFromSolana` for 100 USDC, then the order.

Operations [#operations]

Markets are perp tickers exactly as Hyperliquid lists them: `BTC`, `ETH`, `SOL`, `HYPE`, `kPEPE`. The node matches the exact ticker first and then a unique case-insensitive match, so `btc` finds BTC. Delisted markets are refused. Builder-deployed (HIP-3) markets are not covered yet.

Markets [#markets]

**`getMarkets`**: every listed perp, sorted by 24 hour volume. Each row has `coin`, `markPx`, `midPx`, `oraclePx`, `change24hPct`, `dayVolumeUsd`, `fundingRate`, `fundingAprPct`, `openInterest` (coins), `openInterestUsd`, `maxLeverage`, and `szDecimals`. Prices and volumes are decimal strings exactly as the exchange reports them. `fundingRate` is the hourly rate as a fraction (Hyperliquid pays funding every hour, so `0.0000125` is 0.00125% per hour), and `fundingAprPct` annualizes it.

**`getMarket`**: the same fields for one market, plus `prevDayPx`, `premium`, and `onlyIsolated`.

**`getOrderbook`**: the live book for one market. `bids` and `asks` are lists of `{ px, sz, orders }`, best price first, up to **Levels per side** (default 10, at most 20). `bestBid`, `bestAsk`, `mid`, `spread`, and `spreadBps` summarize the top of the book.

**`getCandles`**: OHLCV candles for one market at an **Interval** from `1m` to `1M` (default `1h`), oldest first, up to **Candles** bars (default 100, at most 500). Each candle has `time`, `open`, `high`, `low`, `close`, `volume`, and `trades`; `lastClose` is the newest close.

**`getFundingHistory`**: hourly funding for one market over &#x2A;*Lookback (hours)** (default 24, at most 720). `rates` lists `{ time, fundingRate, premium }`; `latestRate`, `averageRate`, and `averageAprPct` summarize them.

Account [#account]

Each account read takes an optional **Account**: any `0x` address. Leave it blank to read your own account.

**`getAccount`**: `accountValue`, `withdrawable`, `marginUsed`, `totalNotional`, `maintenanceMargin`, the summed `unrealizedPnl`, `positionCount`, and every open position with `coin`, `side` (`long` or `short`), `size`, `entryPx`, `positionValue`, `unrealizedPnl`, `returnOnEquityPct`, `leverage`, `marginMode`, `liquidationPx`, and `marginUsed`. `spotBalances` lists non-zero spot holdings.

**`getPosition`**: the position in one market with the same fields, plus `hasPosition`. A flat market returns `hasPosition: false` and `side: "flat"` rather than failing, which makes it a clean Condition input.

**`getOpenOrders`**: resting orders, optionally for one market, including take-profit and stop-loss triggers. Each order has `orderId`, `cloid`, `side` (`buy` or `sell`), `size`, `limitPx`, `orderType`, `triggerPx`, `reduceOnly`, and `isPositionTpsl`.

**`getFills`**: executed trades over &#x2A;*Lookback (hours)** (default 24), newest first, up to **Max fills** listed (default 50, at most 500), optionally for one market. `count`, `realizedPnl`, `fees`, and `volumeUsd` total the whole window, not just the listed fills. Hyperliquid returns an account's 2,000 most recent fills, so on a very busy account a long window can be cut short: `truncated` is then true and `coveredFromTime` says how far back the totals reach. Each fill carries `fee`, `builderFee` (an app's fee, when one was charged), `closedPnl`, `orderId`, and `tradeId`.

**`getFundingPayments`**: the funding your account paid or received over &#x2A;*Lookback (hours)** (default 24, at most 720), optionally for one market. `totalUsdc` is the net amount (negative means you paid), and `payments` lists `{ time, coin, usdc, positionSize, fundingRate }` newest first, up to **Max payments listed**. The node pages through Hyperliquid's 500-entry limit, up to 4,000 payments; past that, `truncated` is true.

**`getTransfers`**: every balance change other than trades and funding over &#x2A;*Lookback (hours)** (default 24, at most 720): deposits, withdrawals, sends to and from other accounts, moves between perps and spot, vault deposits and withdrawals, and liquidations. Each update has `time`, `type`, `direction`, `usdc`, and `counterparty`. `direction` is `in`, `out`, or `other` (a move between the account's own balances, such as perps to spot, or a kind the node does not classify); `inUsdc` and `outUsdc` total the window. It pages like `getFundingPayments`.

**`getOrderStatus`**: where one order stands, by numeric order id or the `0x` client order id this node attaches to every order it places. `status` is the exchange's own word: `open`, `filled`, `canceled`, `triggered`, `rejected`, `marginCanceled`, and so on. An order the exchange does not know returns `found: false`.

Trading [#trading]

Every trading operation signs from your account and stops before signing when **Dry run** is on. A dry run resolves the market, reads the live price, sizes and prices the order with the exchange's tick and lot rules, checks every limit below, and returns the exact action it would send under `data.action`. A freshly placed node starts in Dry run, and the corner badge on the canvas flips it.

**`placeOrder`** opens or adds to a position.

* **Side** is `long` (buy) or `short` (sell). **Size** is in USD by default: `100` buys or sells about $100 of the coin at the live mid price (or at the limit price for a limit order). Switch **Size in** to Coins to give the size in contracts instead. The size is rounded down to the market's lot size, and the exchange rejects orders worth less than $10, so the node refuses them before signing.
* **Order type** `market` sends an immediate-or-cancel order bounded by &#x2A;*Max slippage %** from the mid price (default 1%, at most 10%). Anything that cannot fill inside the bound is cancelled, never filled worse. `limit` rests at **Limit price** with a **Time in force** of good till cancelled, post only, or immediate or cancel.
* **Leverage** is optional. When set, the node sets it (with **Margin**, cross or isolated) for that market before placing the order, up to the market's own maximum. Leave it blank to keep the market's current setting.
* **Reduce only** makes the order shrink an existing position and never open or flip one.
* **Client order id** is optional: your own `0x` id of 32 hex digits, so a later step can find this order's fills (`getFills` reports each fill's `cloid`). Leave it blank and the node attaches a fresh one.
* **Take profit price** and **Stop loss price** are optional. They attach market triggers sized to the order, which the exchange places once the order fills. Hyperliquid cancels attached triggers when an immediate-or-cancel order fills only partly, so the node then places them again itself for the filled size and reports `partialFill: true`; if that fails, the node fails with the fill in the output. Each must sit on the right side of the entry (a long's take profit above it, its stop loss below it), or the node refuses the order. Triggered orders fill with the exchange's fixed 10% tolerance.

The output reports `status` (`filled`, `resting`, `rejected`, or `simulated`), the `size` sent, `limitPx` (the slippage bound for a market order), `midPx`, `notionalUsd`, `filledSize`, `avgPx`, `orderId`, and `cloid`, with `takeProfit` and `stopLoss` legs when requested.

**`closePosition`** closes &#x2A;*Close %** of a position (default 100) with a reduce-only immediate-or-cancel order bounded by &#x2A;*Max slippage %**. It can never flip the position. If the order fills only part of the way inside the bound, the node fails with what filled, `closedAll` stays false, and nothing is resent. A market with no position returns `status: "noPosition"` without signing, so it is safe on a schedule.

**`setTpSl`** attaches a take profit, a stop loss, or both to an open position as position-level triggers, sized to the whole position at the moment they are set. If the position grows later, run it again to cover the new size. Both prices are checked against the mark price before signing.

**`cancelOrder`*&#x2A; cancels one resting order by order id or client order id. &#x2A;*`cancelAllOrders`** cancels every resting order, or every order in one market when a market is set.

**`updateLeverage`** sets **Leverage** (a whole number up to the market's maximum) and **Margin** for one market without placing an order.

Funding [#funding]

**`depositFromSolana`** moves &#x2A;*Amount (USDC)** from your Solana wallet into your Hyperliquid account through [Relay](/docs/nodes/defi/relay). You sign one Solana transaction; Relay credits the account's perps USDC on Hyperliquid, usually within seconds. The minimum is 5 USDC. Relay's fee comes out of the amount (about $0.02 on a $20 deposit in November 2026), and the node refuses a deposit when the quote would credit less than 98% of it. The first deposit to a new account also pays Hyperliquid's one-time charge for creating the account, which Relay quoted at about $1.20 in November 2026 whatever the amount; for an account Hyperliquid has not seen yet, the node allows up to 1.50 USDC of it on top of the 2%, and the output's `newAccount` says when that applied. The quote must spend exactly the amount you set, and the transaction is simulated before it is signed.

The output reports `expectedReceived` and `minimumReceived` from the quote, `relayFeeUsd`, and Relay's `requestId`. A live run adds the Solana `signature` and `txExplorer`, and `status` is `credited` once Relay reports the funds delivered, or `bridging` while Relay is still finishing (the funds are on their way). A deposit that has not confirmed on Solana within a minute fails the node with `status: "pending"`; it is recorded, and the next run checks it on chain before sending anything new. If Relay refunds a deposit, the USDC returns to your Solana wallet and the node fails with the reason.

**`withdrawToSolana`** moves &#x2A;*Amount (USDC)** of your account's withdrawable balance back to your Solana wallet through Relay, at least 5 USDC. Margin held by open positions is not withdrawable, so close or reduce them first; the node checks the balance and refuses before signing anything. Relay needs two signatures from your Hyperliquid account: one that registers the request with Relay, and the transfer itself, which sends the USDC to Relay on Hyperliquid. Relay then pays the USDC out on Solana. The same fee rule applies (refused above 2%), and the quote must withdraw exactly the amount you set. The transfer is submitted once and never resent: if Hyperliquid's reply is lost, the node fails with Relay's `requestId` so you can check before trying again. `status` is `credited` once Relay reports the USDC paid on Solana, or `bridging` while it finishes.

**`sendUsdc`** sends &#x2A;*Amount (USDC)** of your account's withdrawable balance to another Hyperliquid account, **To account** (a `0x` address), for example the main account you trade from. It is a transfer inside Hyperliquid: one signature from your account, no bridge, and the USDC arrives at once. The node checks the withdrawable balance and refuses before signing when it is short, or when the destination is the same account. The transfer is submitted once and never resent; if Hyperliquid's reply is lost, the node fails with `status: "unknown"` so you can check both balances before trying again. The destination is never copied into a template someone clones from you.

Fees [#fees]

Hyperliquid charges its own trading fee on every fill. Solaris AI adds no fee of its own today. If that changes, the account card will show the rate and ask you to accept it before any order carries it, the order preview will show what it comes to, and closing or protecting a position will never be blocked over it. A fill that carries a Solaris AI fee reports it in `builderFeePct`.

How live orders stay safe [#how-live-orders-stay-safe]

* Everything an order depends on is checked before anything is signed: the market, the live price, the size and its $10 minimum, the leverage cap, isolated-only markets, and which side the protective prices sit on.
* Each run submits once. The engine never retries a trading operation, and the node never resends one. Every order carries a fresh client order id; if the exchange's reply is lost, the node looks the order up by that id and reports what happened instead of placing it again.
* A rejection is a failed node with the exchange's reason in the error. An order that went through while a take-profit or stop-loss leg did not is also a failed node, with the fill and every leg's status in the output, so the run stops instead of carrying on unprotected. Set the missing leg with `setTpSl`.

Configuration [#configuration]

| Field                                 | Type            | Operations                                          | Description                                                                                            |
| ------------------------------------- | --------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| coin                                  | string          | most                                                | Perp ticker (`BTC`, `ETH`, `kPEPE`); optional filter on `getOpenOrders`, `getFills`, `cancelAllOrders` |
| address                               | string          | account reads                                       | Any `0x` address; blank reads your own account                                                         |
| side                                  | string          | `placeOrder`                                        | `long` \| `short`                                                                                      |
| amount                                | number          | `placeOrder`                                        | Size, in USD unless `amountUnit` is `coin`                                                             |
| amountUnit                            | string          | `placeOrder`                                        | `usd` (default) \| `coin`                                                                              |
| orderType                             | string          | `placeOrder`                                        | `market` (default) \| `limit`                                                                          |
| limitPrice                            | number          | `placeOrder` limit                                  | Resting price in USD                                                                                   |
| timeInForce                           | string          | `placeOrder` limit                                  | `Gtc` (default) \| `Alo` \| `Ioc`                                                                      |
| slippagePct                           | number          | market orders, `closePosition`                      | Default 1, at most 10                                                                                  |
| leverage                              | number          | `placeOrder` (optional), `updateLeverage`           | Whole number up to the market maximum                                                                  |
| marginMode                            | string          | `placeOrder`, `updateLeverage`                      | `cross` (default) \| `isolated`                                                                        |
| reduceOnly                            | boolean         | `placeOrder`                                        | Only shrink a position                                                                                 |
| takeProfitPrice, stopLossPrice        | number          | `placeOrder`, `setTpSl`                             | Trigger prices in USD                                                                                  |
| percent                               | number          | `closePosition`                                     | Share to close, default 100                                                                            |
| orderId                               | string          | `cancelOrder`, `getOrderStatus`                     | Numeric order id or `0x` client order id                                                               |
| clientOrderId                         | string          | `placeOrder` (optional)                             | Your own `0x` client order id (32 hex digits)                                                          |
| depth, interval, limit, lookbackHours | number / string | market, fill, and funding reads                     | See each operation above                                                                               |
| amount (funding)                      | number          | `depositFromSolana`, `withdrawToSolana`, `sendUsdc` | USDC to move, at least 5 through Relay                                                                 |
| destination                           | string          | `sendUsdc`                                          | The receiving Hyperliquid account (`0x`); not cloned with templates                                    |
| dryRun                                | boolean         | trading, funding                                    | Build the exact order or transfer, never sign                                                          |

Every field accepts templates, which are resolved and then checked exactly like a typed value.

Output [#output]

```json
{
  "success": true,
  "operation": "placeOrder",
  "data": {
    "dryRun": true,
    "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
    "coin": "BTC",
    "orderType": "market",
    "side": "buy",
    "size": "0.00155",
    "limitPx": "65157",
    "midPx": "64512.5",
    "notionalUsd": 99.99,
    "cloid": "0x6f1c2be0d84a4c5e9b7d3a1f0e2c4b68",
    "status": "simulated",
    "action": {
      "type": "order",
      "orders": [{ "a": 0, "b": true, "p": "65157", "s": "0.00155", "r": false, "t": { "limit": { "tif": "Ioc" } }, "c": "0x6f1c2be0d84a4c5e9b7d3a1f0e2c4b68" }],
      "grouping": "na"
    }
  }
}
```

Reference fields downstream with the response name (default `hyperliquidResponse`), for example `{hyperliquidResponse.data.markPx}` after `getMarket`, `{hyperliquidResponse.data.hasPosition}` after `getPosition`, or `{hyperliquidResponse.data.avgPx}` after a live `placeOrder`. When a trading operation fails, `success` is `false` and `error` carries the reason.
