spin docs
Perps

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

TierWhat it allows
RarePerps at 1x (no leverage), with rules and AI steps on your own key.
EpicUp to 10x leverage, and AI steps that read MCP servers.
LegendaryUp 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.

FieldJSONValues
Candleinterval1m, 5m, 15m, 1h, 4h, 1d
Marketsmarkets1 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

FieldJSONWhat it does
MarketmarketThe market to trade, or an AI step's answer ("{{pick.market}}"). Left out with a candle trigger: it is the market whose candle closed.
Sideside"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 amountmargin_usdThe margin, in USD.
Margin: a share of the perps balancemargin_pctA percent of the free USDC in the Spinner's perps account. Live only: on paper there is no balance.
Leverageleverage1 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 typemargin_mode"isolated" (the default): only this position's margin can be lost. "cross": the account's margin backs it.
Stop lossstop_loss_pctCloses it when the price moves this far against it, in percent of the entry price.
Take profittake_profit_pctCloses it when the price moves this far in its favour.
Slippagemax_slippage_pctThe 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 editorMeaning
perp.marketMarket name
The market
The perps market's name on Hyperliquid: "BTC", "xyz:TSLA".
perp.pricePrice
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_pctFunding rate
The market
Funding now, in percent per hour (positive: longs pay shorts; Hyperliquid pays it every hour).
perp.open_interest_usdOpen 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_usdVolume in 24 hours
The market
Traded in the last 24 hours, USD.
perp.premium_pctPremium over the oracle price
The market
How far the mark price is above the oracle price, in percent (negative: below).
perp.max_leverageMaximum 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 editorMeaning
position.multiplePrice 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_multipleBest 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_pctFall 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_pctReturn 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.sideSide
The position
A perps position's side: "long" or "short". Every other position is "long".
position.leverageLeverage
The position
A perps position's leverage (1 for any other position).
position.liq_distance_pctDistance 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_usdFunding paid
The position
Funding a perps position has paid since it opened, in USD (negative: received).
position.copied_sold_pctShare 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_sAge 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

LimitJSONWhat it does
Open positions at mostmax_openPositions open at the same time, one per market.
Opens an hour at mostmax_entries_per_hourPositions opened in the last hour.
Leverage at mostmax_leverageNo entry uses more.
Daily loss at mostmax_daily_loss_usdNo new positions for the rest of the day (UTC) once the positions closed that day lost this much.
AI runs an hour at mostmax_ai_runs_per_hourAs for every strategy.

Fees

FeeAmount
The protocol's fee on the margin0.5% when it goes to Hyperliquid, and 0.5% when it comes home
The protocol's fee on each order0.1% of the position's value (a Hyperliquid builder fee)
Hyperliquid's fee on each order0.045% of the position's value on its own markets; some other dexes charge more
FundingPaid 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.

On this page