2.1 Account — Account information

2.2 Balance — Balance information

2.3 Position — Position information

2.4 Order — Order information

2.5 Kline — Candlestick data

2.6 Ticker — Market ticker

Backtests do not simulate an order book: last_price is the only meaningful price; bid_price and ask_price equal the latest price; and bid_qty and ask_qty are 0.0.

2.7 SymbolInfo — Symbol information

3.1 UserContext — Runtime context

The main entry point for strategy code. It provides unified access to trading, logging, signals, and file storage, and supports dynamic attributes for retaining user-defined state across bars.

def init(ctx: UserContext):
    ctx.max_position = 0.1  # Dynamic attribute retained across bars
    ctx.entry_price = {}


def handle_data(ctx: UserContext, datas):
    client = ctx.exchange[0]
    ctx.log.info("Processing bar")

3.2 Client — Trading client

Provides a consistent interface for queries, market data, positions, and order placement across backtesting, paper trading, and live trading. Access it through ctx.exchange[0].

Metadata and utility methods

Account queries

Order queries

Market data

Funding rates and fees

Real data is available only for UM/CM futures clients. Spot markets and unsupported environments return None or [].

get_funding_rate returns a dict containing symbol, fundingRate, nextFundingRate, nextFundingTimeMs, markPrice, indexPrice, and intervalHours.

client = ctx.exchange[0]  # Must be a UM/CM futures account

info = client.get_funding_rate("BTC_USDT")
if info is not None:
    rate = info.get("fundingRate", 0.0)        # Current rate; 0.0001 = 0.01%
    next_ms = info.get("nextFundingTimeMs", 0) # Next settlement time in milliseconds
    hours = info.get("intervalHours", 8)       # Settlement interval in hours

High-level trading methods ⭐

target_percent() explained

Automatically calculates the target position quantity from total account equity and the current price. This is the recommended way to manage position size.

client.target_percent(
    symbol="BTC_USDT",
    target_percent=0.1,  # Target position value as a share of total equity
    limit_price=None,    # None places a market order
    threshold=0.05,      # Skip rebalancing when the deviation is below 5%
    auto_partial=True,   # Reduce the order automatically if funds are insufficient
)

# Assume total equity is 10,000 USDT and BTC is priced at 50,000 USDT.
# target_percent = 0.8 -> target quantity = 10,000 * 0.8 / 50,000 = 0.16 BTC

client.target_percent("BTC_USDT", 0.8)   # No position -> open a 0.16 BTC long
client.target_percent("BTC_USDT", 0.8)   # 0.1 BTC long -> add 0.06 BTC
client.target_percent("BTC_USDT", 0.8)   # 0.2 BTC long -> reduce by 0.04 BTC
client.target_percent("BTC_USDT", -0.8)  # 0.1 BTC long -> close the long, then open a short
client.target_percent("BTC_USDT", 0)     # Close the position

Basic trading methods

# Spot
client.buy(symbol, qty=None, price=None, cost=None)
client.sell(symbol, qty=None, price=None, cost=None)

# One-way futures positions
client.open_long(symbol, qty=None, price=None, cost=None)
client.close_long(symbol, qty=None, price=None, cost=None)
client.open_short(symbol, qty=None, price=None, cost=None)
client.close_short(symbol, qty=None, price=None, cost=None)

# Other methods
client.set_leverage(symbol, leverage=None)
client.cancel_order(symbol, order_id)

3.3 Exchange — Client manager

Manages multiple client instances and supports lookup by name or index.

3.4 Signal — Signal access

Provides access to trading signals generated by the strategy. The system retrieves data from ctx.signal.get() in advance and passes it to the datas parameter of handle_data.

# datas is supplied automatically, so you normally do not call ctx.signal.get() yourself.
def handle_data(ctx: UserContext, datas):
    signal_df = datas  # DataFrame for one time step, including symbol/timestamp/prediction

# Historical features are calculated by upstream processing nodes.
# historyPeriods must cover the required lookback window.

3.5 Log — Logging service

3.6 File — File persistence

Persists model files (machine learning) and parameter files (strategy state recovery) across runs. Every method is addressed by file name; saving under an existing name overwrites it (and does not consume an extra file slot). Internal file IDs are never exposed.

Local paths: the strategy process can only read and write the task work directory. /tmp, the home directory and arbitrary absolute paths are rejected. Always use ctx.file.work_path(name) when you need a path on disk.

The work directory is ephemeral: work_path(name) points at the task container's local disk, which is destroyed when the task ends.torch.save() and booster.save_model() only cover the "write locally" step —you must then call ctx.file.save_model(name) to upload before the file is actually persisted. Loading works the same way: call ctx.file.load_model(name) to fetch the remote file locally, then hand the path to the library.

FileInfo: .name / .kind ("model" | "params") / .size / .size_str / .hash / .created_at / .updated_at; FileQuota: .file_count / .max_files / .used_bytes / .max_total_bytes / .max_model_bytes / .max_params_bytes

Allowed extensions (the test is whether strategy code can legally read the file back): models .lightgbm (lgb.Booster(model_file=...)), .pt / .pth (torch.load(..., weights_only=True)), .lstm / .transformer (platform AiModel loader); parameters .json.

⚠ .pkl / .pickle / .joblib cannot be saved (existing files stay readable and deletable): the static security rules permanently block import pickle, pickle.load and joblib.load, so such a file could never be deserialized. Export scikit-learn parameter arrays to .json, or switch to lightgbm / torch. tensorflow, onnxruntime and safetensors are not preinstalled either, so .h5 / .keras / .onnx / .safetensors are unsupported. Note that open(), pathlib, os and tempfile are blocked as well: writing to local disk must be done by the library itself (torch.save / booster.save_model). That step only fills the ephemeral work directory — you still need ctx.file.save_model(name) to persist it. For parameter files ctx.file.save_params() does both in one call.

# Model: persist after training, reuse on the next run
path = ctx.file.load_model("alpha.pt")
if path:
    model.load_state_dict(torch.load(path, weights_only=True))
else:
    train(model)
    torch.save(model.state_dict(), ctx.file.work_path("alpha.pt"))
    ctx.file.save_model("alpha.pt")

# LightGBM
booster.save_model(ctx.file.work_path("alpha.lightgbm"))
ctx.file.save_model("alpha.lightgbm")

# Parameters: strategy state recovery
state = ctx.file.load_params("state.json", default={"grid_level": 0})
state["grid_level"] += 1
ctx.file.save_params("state.json", state)

# Quota: clean up before hitting the file-count limit
q = ctx.file.quota()
if q.file_count >= q.max_files:
    oldest = sorted(ctx.file.list_files(), key=lambda f: f.updated_at)[0]
    ctx.file.delete(oldest.name)