QuantScript version: 2.0 applies to strategies created after QuantScript v2 became the default. If your strategy was written with Market.Ticker, Orders.Buy or TA.RSI, it is a v1 strategy. See Moving from QuantScript v1 to v2.

QuantScript is the language QuantPilot strategies are written in. It is a dialect of Starlark (a small, safe subset of Python) with a trading API built in: market data, orders, balances, positions, technical indicators and persistent storage. The same script is used for backtests, paper trading and live trading.

This article is the reference. It covers the complete API surface as it exists today, one entry per type, method, attribute and limit. Every code sample in it has been checked against the QuantScript v2 validator.

Sample code assumes conn, spot and perp were opened at the top level of the script:

A strategy has two phases.

Set-up (runs once). When the strategy starts, the engine executes the top level of the script from top to bottom. Use it to declare your parameters, open your connection and markets, and define helper functions.

Tick (runs many times). The engine then calls your Run() function once per tick. Live, a tick is roughly once per second. In a backtest, simulated time advances one minute at a time and Run() is called at every boundary of the smallest timeframe your strategy reads: get_candles(..., timeframe="1h", limit=200) counts as one hour, and get_ticker counts as one minute. So a strategy that only reads 1-hour candles runs once per simulated hour, while one that also reads a ticker runs every simulated minute. Orders are matched against every 1-minute bar either way.

Everything that needs to happen repeatedly (reading prices, computing indicators, placing orders) goes inside Run() or a function it calls.

Run() must exist and must take no parameters. A script without it, or with def Run(x):, is rejected before it starts.

If your logic should fire once per closed candle (a crossover check, for example), remember the timestamp of the newest candle and return early while it has not changed:

Only two kinds of statements may appear at the top level of the script: assignments and function definitions. Control flow (if, for) and bare function calls are rejected by the validator.

Anything that involves logic or a side effect belongs inside a function.

Variables assigned at the top level keep their value from one tick to the next, until the strategy restarts. Variables created inside Run() are gone when the tick ends. For values that must survive a restart, use state (below).

Put every tunable value (symbol, timeframe, thresholds, sizing, lookbacks) in a single top-level dictionary named StrategyParams. QuantPilot reads this dictionary and shows one form field per key, so a strategy can be tuned in the app without editing code.

Rules:

state is a dictionary-like global that persists between ticks and across restarts. Use it for runtime bookkeeping: whether you are in a trade, the entry price, an order id to check next tick, a cooldown timestamp.

There is no del state["k"]. Starlark has no del. Use state.pop.

Only scalar values can be stored: None, bool, int, float, str, Decimal, datetime and timedelta. Lists, dicts, sets and tuples are rejected on assignment. To keep several ids, join them into one string and split it on read, or re-derive them from market.get_open_orders(...).

Limits: 1,000 keys and 256,000 bytes in total; exceeding either raises when you assign. State is saved after every tick that changes it and kept for 7 days after the strategy stops. Re-enabling within that window restores it.

Do not seed state at the top level. The top level runs again on every restart and would overwrite the values you wanted to keep. Read with state.get(key, default) inside Run() instead.

The API has two levels. A connection is one exchange account (or one exchange without an account). A market is one instrument on that connection: spot, or a linear perpetual. Prices, candles, orders, balances and positions all hang off the market.

Open the connection and the markets you need once at the top level, then reuse them every tick.

Opens an exchange, with or without an account on it.

Returns: Connection

Whether you pass an id decides what the connection can do:

No id means no account. get_ticker, get_candles and get_symbol_spec work; balances, positions, leverage and every order call raise. Use an id-less connection to read one exchange while trading on another:

One id belongs to one exchange for the whole script. Opening the same id on a second exchange is an error.

Which id to write in QuantPilot. Strategies in QuantPilot use id="mock_hyperliquid". In backtests and paper trading this connection is funded with a simulated USDC wallet. When you start the strategy live, QuantPilot binds it to the exchange connection you choose at start-up; you do not edit the id yourself.

A Connection has three read-only attributes: id, name (human-readable) and exchange (for example "hyperliquid").

Returns the Market for one instrument on the connection. Raises if the exchange does not offer that instrument.

Hyperliquid offers Market.SPOT and Market.LINEAR_PERPETUAL. Asking a Hyperliquid connection for any other instrument raises.

A Market has one attribute, instrument (for example "spot").

Symbols follow the unified BASE/QUOTE format; a perpetual adds the settlement currency after a colon.

The validator checks every symbol literal against the catalogue of supported symbols and rejects one it does not know before the strategy runs, so a typo is caught early. Note that the check is against the supported catalogue as a whole, not against the exchange you named: a symbol can pass validation and still not exist on that exchange. On Hyperliquid, everything is quoted in USDC; there are no USDT pairs.

The current price snapshot for one symbol. Raises if no data has arrived yet for this symbol.

Returns: Ticker

Historical candles for one symbol.

Returns: CandleSeries

Every series in QuantScript (candle columns and indicator outputs) uses reverse indexing: index 0 is the most recent value, 1 the one before it, and -1 the oldest. This matches PineScript and most trading tools. It does not match Python lists, so be deliberate when you loop.

A series is a sequence, not a value. Comparing or doing arithmetic on it directly is a validation error. Index it first.

Indicators that return several series come back as a tuple. Unpack first, then index.

Returned by get_candles. Supports indexing (candles[0] is the latest Candle), slicing (candles[0:5], candles[-5:]), iteration and len().

One candlestick, usually reached by indexing a CandleSeries.

The contract specification for a symbol: the metadata you need for order sizing and leverage checks. Raises if the market has no specification for the symbol.

Returns: SymbolSpec

These calls read the money state of the account behind a market. They need an account-backed connection (one opened with an id). Three facts apply to all of them:

The real exchange balance of one currency, from the wallet behind this market: the spot wallet for spot, the derivatives wallet for perpetuals, or the unified wallet on exchanges that have one. A currency you do not hold returns a zero balance, not an error. Live, the call raises until the first balance snapshot has arrived.

Returns: Balance

free and total are not interchangeable. free excludes quote currency reserved by your own resting limit orders, so size new entries from free, and compute fractions of the portfolio from total.

Portfolio value on spot. A spot wallet has no single equity number: after a buy, value has moved from the quote currency into the base asset. Mark the holdings to market when you need it:

You often need neither. A strategy that trades a fixed quantity or a fixed notional already knows its size; reach for balances only when the sizing rule is a fraction of the portfolio.

The exchange's own summary of the account that funds this market: equity, withdrawable collateral, margin in use and floating PnL, in the account's reference currency. On unified-account exchanges every market of a connection returns the same account.

Raises on spot markets: a spot wallet carries no margin, so the exchange has no equity figure to report. Use get_balance there. Also raises when the simulated wallet is funded in more than one currency, because there is then no single currency to express equity in.

Returns: Account

Per-position numbers (liquidation price, margin of one position) are on Position, not here.

The open position for a symbol. Flat is a zero position, not an error: is_open is False, size is 0 and side is "", and the object still carries stale, so you can tell "flat and the data is fresh" from "flat because the stream is down" before re-entering. Live, the call raises until the first position snapshot has arrived. Spot symbols never have a position, so spot reads are always flat.

Returns: Position

Position frames are whole-set snapshots: a symbol missing from the exchange's next frame is closed and is served as a zero position from then on.

Sets the leverage for a symbol on this market. It applies to the next position opened on that symbol, in backtests and live alike. Only isolated margin is supported.

Returns: None

The engine does not check the request against the exchange's ceiling. Compare with get_symbol_spec(symbol).max_leverage first (see the example under get_symbol_spec).

All order methods live on the market. Constants for side and type live on Order.

Places an order and returns it.

Returns: Order

Stop and stop-limit order types are not available yet.

Only these attributes exist. Fill price, executed amount, fees and timestamps are not on the order.

The runtime fills in error_code and error_message, but the validator does not yet accept a script that reads them, so a strategy cannot use them today. Until that changes, branch on status alone; the reason appears in the backtest's order log.

The constants are lowercase; the returned strings are uppercase. Order.BUY is "buy", but a returned order's side is "BUY". So order.side == Order.BUY is always False. When you inspect an order you got back, compare against the uppercase strings: order.side == "BUY", order.status == "FILLED".

Rejections differ between backtest and live. In a backtest, an order the wallet cannot back comes back with status == "REJECTED" and an error_code, so the strategy can decide what to do. Live, place_order raises instead and the tick ends. A check like if order.status == "REJECTED" therefore works in a backtest and never fires live.

Cancels one order and returns the updated Order.

Cancels every open order on this market, or only those for one symbol. Returns the cancelled orders as a list.

Returns one order by id. Raises if it is not found.

Returns the working orders on this market, all symbols or one. Returns a list of Order.

Returns finished orders (filled, cancelled, rejected, expired) on this market, all symbols or one. Returns a list of Order.

ta holds the built-in indicators. Each takes a CandleSeries as its first argument (named candles) and returns a DecimalSeries, or a tuple of them for multi-line indicators. Indicators run natively in the engine, so always prefer a ta function over a hand-written loop.

Five indicators (sma, ema, wma, smma and std_dev) also accept a DecimalSeries as input, which lets you chain them: ta.sma(ta.rsi(candles, length=14), length=5) is a smoothed RSI.

Every series is indexed newest-first, and a series must be indexed before it is compared (rsi[0] > Decimal("50")).

target can be another DecimalSeries, a Decimal, an int or a float.

Use the aggregation methods on a DecimalSeries for rolling highs, lows, sums and averages instead of writing loops.

Use Decimal for everything that is money, price or quantity. Never use float for these: floats cannot represent values like 0.1 exactly and the error compounds. Every price and quantity the API returns is already a Decimal.

Construct from a string whenever you can. Decimal(0.1) first builds a binary float and then converts it, carrying the float's error along; Decimal("0.1") is exact.

Decimal supports + - * / // %, unary minus, all comparisons, and mixing with int. A zero Decimal is falsy. Passing an unparseable value (Decimal("abc")) raises and ends the tick.

The type returned by every indicator and by the candle columns (closes, highs, and so on). Indexed newest-first. Supports indexing, slicing (series[0:5], series[1:21]), iteration, len() and membership tests (value in series).

It cannot be compared or used in arithmetic directly. Index it first.

If length is larger than the series, the whole series is used.

Spelled lowercase, like Python's. All times are UTC. Immutable.

datetime.now() returns the current time. In a backtest this is the simulated time of the bar being processed, not the wall clock.

datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0) builds a specific moment.

Arithmetic: datetime + timedelta, datetime - timedelta, and datetime - datetime (which gives a timedelta). All comparisons work.

timedelta(days=0, hours=0, minutes=0, seconds=0, microseconds=0). Attributes days and seconds (the remainder after whole days); method total_seconds(). Supports +, -, unary minus and comparisons. Can be stored in state.

math mirrors Python's math module for a subset of functions. Every function takes and returns float (or int where natural). Use it for non-monetary calculations only; keep money in Decimal.

log.info(message), log.warning(message) and log.error(message) write to the strategy's log, which you can read in QuantPilot. Logs are diagnostics: they are never sent to you. A message longer than 1,000 characters is trimmed in the stored log.

There are no f-strings in Starlark. Build messages with + or the % operator.

notification.send(...) is how a strategy tells you something worth your attention. In a live strategy it is delivered as a Telegram message. In a backtest nothing is sent; every notification is recorded so you can read back what the strategy would have told you.

notification.send(message, channel=notification.TELEGRAM, data={...})

Returns: None

Values in data become strings: int, bool, Decimal (same text as .string()), datetime (RFC 3339) and float are accepted. Nested dictionaries, lists, None and API objects are rejected. Prefer Decimal over float for numbers a reader will look at. A float carries its noise into the text (0.30000000000000004).

Delivery is best effort. A notification never blocks or stops your strategy. Three things drop one:

A dropped notification is not retried: a message that says "position closed" twenty minutes late is a wrong message, not a late one. Size violations, by contrast, are errors and end the tick, so they surface in the backtest long before going live.

QuantScript is Starlark, so most everyday Python works: if/elif/else, for loops with break and continue, functions, lists, dictionaries, tuples, comprehensions, lambdas, string methods (split, upper, startswith, replace, join), % formatting and the ternary a if cond else b.

What differs from Python:

Predeclared names. These exist in every script and must not be redefined: Connection, Market, Order, Decimal, datetime, timedelta, ta, state, log, notification, math.

Validation before the first tick. Every script is checked before it runs. Besides syntax, the validator rejects: a missing Run() or a Run() with parameters; control flow or bare calls at the top level; a series used in a comparison or arithmetic without indexing; unknown attributes and methods; an unsupported timeframe, instrument or exchange constant; a symbol outside the supported catalogue; and any v1 API name. It also reports warnings (an unused variable, unreachable code, a name that shadows a built-in) which do not stop the script but are worth reading.

Limits.

Performance. Indicators run natively; a hand-written RSI in Starlark is slower and usually wrong. Compute each series once per tick and keep it in a variable. For rolling windows use sum, avg, max and min on a series rather than a loop.