Perps
Let a strategy open long and short positions with leverage on Hyperliquid's perps markets, run by rules and AI steps on your own key.
A strategy can open a perps position instead of buying a token. The position is the strategy's outcome, like a buy: when the trigger fires and the rules hold, the bot opens a long or a short on a Hyperliquid market, with the margin and the leverage you set. Its exit rules, its stop loss and its take profit close it.
The markets are every perps market Hyperliquid lists that is margined in USDC: Hyperliquid's own (BTC, ETH, SOL, HYPE and more) and those of other dexes on Hyperliquid, such as stocks and indices (xyz:TSLA, xyz:NVDA).
Paper only for now
Perps strategies run on paper: the bot trades at Hyperliquid's live prices, but no money moves. Live perps come once each Spinner has its own Hyperliquid account. Until then, a perps strategy cannot be put live.
Tiers
| Tier | What it allows |
|---|---|
| Rare | Perps at 1x (no leverage), with rules and AI steps on your own key. |
| Epic | Up to 10x leverage, and AI steps that read MCP servers. |
| Legendary | Up to each market's own maximum leverage (40x on BTC), and the webhook trigger. |
A strategy can set a lower maximum for itself with Leverage at most in its limits.
Set up a perps strategy
Start a perps strategy
On the Strategies tab, select New strategy, then Perps. Choose a starting point, or Start blank: a candle trigger on BTC, a long of $50 at 1x, a 5% stop loss and a 10% take profit.
Choose the trigger and the markets
In the When block, choose A candle closes, the candle size and up to 20 markets. Or choose On a timer and one market. See the candle trigger.
Add the rules or an AI step
Add the conditions that must hold, for example RSI (14 candles of 1 hour) at most 30, or choose a signal in the When block. Or add an AI step with AI: long, short or none: it reads the market and chooses the side. See AI steps.
Set the position
In the Open block, set the side, the amount and the leverage under The position, and the stop loss and the take profit under Protection. The margin as a share, the margin type and the slippage are in More options. See the position.
Set the exits and the limits
Add close rules if you want more than the stop loss and the take profit, for example after a time, or when the AI says so. Then set the limits. See exits and limits.
The candle trigger
A candle closes checks each of its markets once a candle of that size closes. The rules and the AI steps then read that market.
| Field | JSON | Values |
|---|---|---|
| Candle | interval | 1m, 5m, 15m, 1h, 4h, 1d |
| Markets | markets | 1 to 20 Hyperliquid markets, for example "BTC" or "xyz:TSLA" |
{ "on": "candle", "markets": ["BTC", "ETH", "SOL"], "interval": "1h" }The bot checks a market within about a second of its candle's close. The first candle that the bot sees only starts the count: the first check is at the next close.
A timer works too: it checks the one market that the position names. Launches and trades on Robinhood Chain are not perps triggers.
The position
| Field | JSON | What it does |
|---|---|---|
| Market | market | The market to trade, or an AI step's answer ("{{pick.market}}"). Left out with a candle trigger: it is the market whose candle closed. |
| Side | side | "long" gains when the price rises, "short" when it falls. Or an AI step's answer ("{{idea.side}}"): an answer of "none" opens nothing. |
| Margin: a dollar amount | margin_usd | The margin, in USD. |
| Margin: a share of the perps balance | margin_pct | A percent of the free USDC in the Spinner's perps account. Live only: on paper there is no balance. |
| Leverage | leverage | 1 to 50. The position is the margin times the leverage. The entry, the strategy's Leverage at most and the market's own maximum cap it. |
| Margin type | margin_mode | "isolated" (the default): only this position's margin can be lost. "cross": the account's margin backs it. |
| Stop loss | stop_loss_pct | Closes it when the price moves this far against it, in percent of the entry price. |
| Take profit | take_profit_pct | Closes it when the price moves this far in its favour. |
| Slippage | max_slippage_pct | The order fills at most this far from the mark price, or not at all. 1% by default. |
The stop loss and the take profit are Hyperliquid's own orders, sent with the position. They work even if the bot is down. Price moves are of the entry price: at 5x, a 2% move against the position is 10% of its margin.
"perp": {
"side": "short",
"margin_usd": 100,
"leverage": 3,
"margin_mode": "isolated",
"stop_loss_pct": 4,
"take_profit_pct": 8
}The bot holds one position per market. A new signal on a market with an open position is skipped, or, with Add to an open position, adds to it when the side is the same.
The values
A perps strategy reads its market with perp.* values, in rules and in AI prompts. It has no token.* or event.* values. The prices are in USD.
| The perps market (Hyperliquid) | In the editor | Meaning |
|---|---|---|
perp.market | Market name The market | The perps market's name on Hyperliquid: "BTC", "xyz:TSLA". |
perp.price | Price Price | The market's mark price, USD. |
perp.price_change(window_s) | Price change Price | Price now divided by the price window_s seconds ago (1 = flat; up to 7 days). Null until the history reaches back that far. |
perp.high(window_s) | Highest price Price | Highest price in the last window_s seconds (up to 7 days). |
perp.low(window_s) | Lowest price Price | Lowest price in the last window_s seconds (up to 7 days). |
perp.rsi(period, interval_s) | RSI Indicators | RSI (Wilder's, 0 to 100) of the last period closed candles of interval_s seconds (60, 300, 900, 3600, 14400, 86400...). |
perp.sma(period, interval_s) | Simple moving average Indicators | Simple moving average of the closes of the last period closed candles of interval_s seconds, USD. |
perp.ema(period, interval_s) | Exponential moving average Indicators | Exponential moving average over period closed candles of interval_s seconds, USD. |
perp.atr_pct(period, interval_s) | Average true range Indicators | Average true range (Wilder's) of period closed candles of interval_s seconds, in percent of the price. |
perp.volatility_pct(window_s) | Volatility Indicators | Standard deviation of one-minute returns over the last window_s seconds, in percent. |
perp.funding_pct | Funding rate The market | Funding now, in percent per hour (positive: longs pay shorts; Hyperliquid pays it every hour). |
perp.open_interest_usd | Open interest The market | Open interest, USD (coins open at the mark price). |
perp.open_interest_change(window_s) | Change in open interest The market | Open interest now divided by open interest window_s seconds ago (in coins; 1 = flat; up to 7 days). |
perp.volume_usd | Volume in 24 hours The market | Traded in the last 24 hours, USD. |
perp.premium_pct | Premium over the oracle price The market | How far the mark price is above the oracle price, in percent (negative: below). |
perp.max_leverage | Maximum leverage The market | The market's maximum leverage on Hyperliquid. |
perp.candles(interval_s, count) | Recent candles The market | The last count closed candles of interval_s seconds as text, one a line: start (UTC), open, high, low, close. For AI prompts; at most 200. |
The candle values (perp.rsi, perp.sma, perp.ema, perp.atr_pct, perp.candles) take an interval in seconds: 60, 300, 900, 3600, 14400 or 86400. They use closed candles only. The bot keeps one-minute candles for 7 days and hourly candles for 90 days, and loads them from Hyperliquid when a strategy starts to use a market.
The position values work for both sides. position.multiple is the price move in the position's favour: for a short, the entry price divided by the price now. So position.multiple >= 1.5 means 50% in the position's favour on either side, and a trailing stop on position.drawdown_pct follows the best price either way.
| The position (exits only) | In the editor | Meaning |
|---|---|---|
position.multiple | Price against the entry price The position | Price now divided by the price at entry (before costs). For a perps short: the entry price divided by the price now, so it is the price move in the position's favour either way (1.5 = 50% in its favour). |
position.peak_multiple | Best price against the entry price The position | The best position.multiple since entry (the highest price since entry over the entry price; for a perps short, the lowest). |
position.drawdown_pct | Fall from its best price The position | Percent the price has moved against the position from its best since entry: below the highest price (for a perps short, above the lowest). For trailing stops. |
position.pnl_pct | Return if closed now The position | Estimated return if sold now, after the venue fee and tax, ignoring price impact. For perps: the return on the margin put up, with leverage, every fee (ours too, on the way home) and funding. |
position.side | Side The position | A perps position's side: "long" or "short". Every other position is "long". |
position.leverage | Leverage The position | A perps position's leverage (1 for any other position). |
position.liq_distance_pct | Distance to liquidation The position | How far the price is from a perps position's liquidation price, in percent of the price (null when it cannot be liquidated, and for other positions). |
position.funding_usd | Funding paid The position | Funding a perps position has paid since it opened, in USD (negative: received). |
position.copied_sold_pct | Share the copied wallet has sold The position | For a position that copied a wallet's buy: the percent of what that wallet bought that it has sold since (0 to 100; e.g. > 0 sells when it starts selling). Null for any other position. |
position.age_s | Age of the position The position | Seconds since the position opened. |
bot.perps_balance_usd is the free USDC in the Spinner's perps account (live only).
AI steps
A perps strategy at Rare can use AI steps, for its entries and for its exits. With MCP servers, it needs Epic.
A prompt can name any perp.* value. The bot fills it in when the step runs, for the market whose candle closed:
{{perp.market}} is at {{perp.price}}, funding {{perp.funding_pct}}% an hour,
RSI {{perp.rsi(14, 3600)}}. The last 2 days of hourly candles (start, open,
high, low, close):
{{perp.candles(3600, 48)}}
Answer long, short or none.To let the AI choose the side, give the step an answer that is a list of words with long and short (and none to pass), and set Side to that answer. To let it choose the market, give it a list of the markets it may pick from, and set Market to that answer: the bot follows only those markets.
Exits
Exits work as for tokens: each close rule closes its share of the position once, when its condition holds, or when the AI says so. The editor calls them Close rules. A position with no close rules closes by its stop loss and its take profit.
Limits
| Limit | JSON | What it does |
|---|---|---|
| Open positions at most | max_open | Positions open at the same time, one per market. |
| Opens an hour at most | max_entries_per_hour | Positions opened in the last hour. |
| Leverage at most | max_leverage | No entry uses more. |
| Daily loss at most | max_daily_loss_usd | No new positions for the rest of the day (UTC) once the positions closed that day lost this much. |
| AI runs an hour at most | max_ai_runs_per_hour | As for every strategy. |
Fees
| Fee | Amount |
|---|---|
| The protocol's fee on the margin | 0.5% when it goes to Hyperliquid, and 0.5% when it comes home |
| The protocol's fee on each order | 0.1% of the position's value (a Hyperliquid builder fee) |
| Hyperliquid's fee on each order | 0.045% of the position's value on its own markets; some other dexes charge more |
| Funding | Paid or received every hour, at the market's rate |
For example, $100 of margin at 3x is a $300 position. One round trip costs about $1.00 of the 0.5% fees, $0.60 of builder fees and $0.27 of Hyperliquid fees.
Paper trading
On paper, the bot trades at Hyperliquid's live prices:
- An order fills at the mark price, 0.05% against the order.
- Every fee above is taken, the protocol's 0.5% on the margin included.
- Funding is paid or received every hour, at the market's rate.
- A position whose price reaches its liquidation price is liquidated, and its margin is lost.
- An order must be at least $10 of position value, as on Hyperliquid.
Results and activity
Perps positions show in the Performance tab's positions tables, with the token positions. Each row shows the market, long or short, the leverage, the size and its dollar value, the entry and exit prices, and the result in dollars and in percent of the margin. The ETH totals at the top of the tab do not count perps positions, whose money is in USD.
The Activity tab shows each position's opening, with its side and leverage, and its close, with its prices, its result after every fee and funding, and how long it was open. A liquidation shows as liquidated.
Leverage can lose all of the margin
A leveraged position can lose its whole margin in a small price move: at 10x, a move of about 9% against it. Funding is a cost while the market pays the other side. See risks.