Glossary

Trading vocabulary and project-specific terms used across the codebase and docs. Skim this once before reading the architecture docs.

---

Trading terms

Perp / Perpetual A perpetual futures contract — a derivative that tracks the spot price of an asset with no expiry, settled via periodic funding payments between longs and shorts. Hyperliquid is a perp DEX.

Long / Short A long position profits when price goes up; a short position profits when price goes down. On a perp, shorting is symmetric to longing.

Leverage Multiplier on notional exposure relative to margin posted. 3x leverage means $1,000 of margin controls $3,000 notional. Amplifies both gains and losses. Liquidation distance shrinks as leverage grows.

Notional The total dollar value of a position. notional = price × size. Risk is typically reasoned about in notional, not in coins.

Margin Collateral posted to open and maintain a leveraged position. Initial margin opens the position; maintenance margin is the minimum required to keep it open.

Liquidation Forced closure of a leveraged position when its margin falls below the maintenance threshold. The platform's risk caps target keeping positions far from liquidation distance.

Liquidation price The mark price at which an open position would trigger an account-level liquidation under cross-margin, holding all other positions' marks constant. Hyperliquid's model — the paper broker matches it (see ADR-0014). For accounts with substantial cushion from cash or other positions' PnL, the per-position liquidation price can be unreachable (price would have to go below zero for a long, or to infinity for a short); the agent context renders this case as liq=unreachable. Authoritative source: the paper broker computes it locally; live Hyperliquid adapters MUST source it from the exchange's clearinghouseState.

Maintenance margin rate Fractional buffer that determines the liquidation threshold under cross-margin. The account is liquidated when equity < Σ (position_notional × maintenanceMarginRate). The paper broker uses a single constant (default 50 bps, ≈ Hyperliquid tier-1 majors). Real Hyperliquid uses tiered rates per symbol and surfaces them directly from the exchange.

Cross-margin Margin model in which all collateral in an account backs all positions. A position's losses can be cushioned by cash and by other positions' profits, and liquidation is evaluated account-wide rather than per-position. Hyperliquid's default; the paper broker matches.

Funding rate On a perp, the periodic payment from longs to shorts (or vice versa) that keeps the perp price tethered to spot. Positive funding = longs pay shorts. Funding is per-symbol and changes through the day.

Open Interest (OI) Total notional value of open positions in a market. Useful as a sentiment / flow indicator. The platform tracks OI as a per-symbol time series in open_interest (snapshots via pullOpenInterest since Hyperliquid has no historical-OI endpoint) and exposes the latest snapshot to the agent on demand through the get_open_interest tool (whitelist it in tools.builtIn — OI is not auto-injected into per-tick context). On a perp DEX every long is matched by a short, so notional long OI ≡ short OI ≡ total. The schema has nullable long_oi_usd / short_oi_usd columns reserved for future positioning-aware data sources (e.g., CoinGlass) — Hyperliquid populates oi_usd only.

Slippage Difference between the price you expected and the price you actually got. Larger orders against thinner books slip more.

Maker / Taker A maker adds liquidity to the book (resting limit order); a taker removes liquidity (market order or aggressive limit). Maker fees are usually lower (sometimes negative).

OHLCV bar Open, High, Low, Close, Volume — the standard candle representation of a time window of price action. Bars are the primary input format for technical analysis.

Sharpe ratio Risk-adjusted return: (return - risk_free_rate) / stddev(return). Used for comparing strategies.

Max drawdown Largest peak-to-trough equity decline over the evaluation window. Key risk metric — large drawdowns end careers.

Profit factor sum(winning trades) / abs(sum(losing trades)). Above 1.0 is profitable; above 2.0 is exceptional.

---

Project terms

Skill The atomic unit of a trading agent on this platform. A versioned bundle of:

• strategy (a mode-discriminated brief — thesis / rules / hybrid — wrapped by a platform-owned framework prompt at runtime; see ADR-0012)
• model selection
• whitelisted tools
• risk caps
• schedule
• optional context configuration (including whether to discover symbols at runtime)

Skills are authored via form, stored in Supabase, and consumed identically by the simulator, the live runner, and the chat agent. See data-model.md.

Strategy The trader-authored portion of a Skill. Three authoring modes share one payload (see ADR-0012):

• Thesis (default) — thesis, horizon, style, lookFor, avoid, sizing. The agent gets a high-level edge to express each tick using the full context.
• Rules (legacy from ADR-0009) — entry, exit, riskManagement. The agent follows literal conditions.
• Hybrid — both, with rules pinning specific behaviors inside the thesis.

Surrounded at runtime by a platform-owned framework prompt that handles tool semantics, action protocol, and prompt-injection hygiene.

Leash The flexibility dial on a Strategy (see ADR-0012). Translated into a paragraph the agent reads at the top of its strategy brief:

• strict — follow the strategy literally; do not improvise.
• balanced (default) — follow faithfully; use judgment on edge cases.
• adaptive — use as guidance; find the best expression of the edge each tick.

Hard kill conditions under the strategy's avoid field remain absolute regardless of leash. Risk-tab caps remain authoritative.

Strategy style A soft taxonomy tag on a Skill (momentum, mean_reversion, breakout, news_driven, carry_funding, discretionary, custom). Surfaces in the editor as a chip picker that fills empty thesis fields with a starting template; also passed to the agent as guidance on how to weight technical / news / funding signals. Non-enforced.

Framework prompt The platform-owned header + leash framing + footer that wraps a Skill's strategy fields into the actual model system: message. Lives in packages/agent-runtime/src/system-prompt.ts. A client-safe mirror for the editor's preview pane lives at apps/web/components/skill-editor/preview-compose.ts. Changes here affect every skill on the platform — treat as a runtime behavior change.

Skill Author The user who creates / edits a Skill. Usually a quant or trader.

Deployer The user who deploys a Skill live. Often the same person as the author, but logically separate. The Deployer is who the chat agent talks to.

Deployment A running instance of a Skill. One Fly machine per deployment. Has lifecycle: provisioning → running → paused → stopped.

Tick One iteration of the agent's decision loop. Per Skill schedule (cron or event). Each tick produces a Decision Snapshot.

Decision Snapshot The full record of a single tick: the context that went into the prompt, the model's tool-call sequence, the model's final reasoning text, the proposed action, and what the Execution Engine did with it. The chat agent reads these to explain past decisions.

Proposed Action Structured JSON emitted by the agent representing a desired exchange action — e.g., {action: "open_long", symbol: "BTC", size_usd: 1000, reason: "...", confidence: 0.7}. Never sent to the exchange directly; always routed through the Execution Engine.

Execution Engine The safety boundary. Validates proposed actions against Skill risk caps and global guards before any order leaves the platform. Same code path in sim and live; only the broker adapter differs. See execution-engine.md.

Broker Adapter A pluggable backend for the Execution Engine. MVP adapters: paper (deterministic simulation) and hyperliquid-mainnet. Testnet was removed in ADR-0015.

Risk Caps Per-Skill numeric limits enforced by the Execution Engine independent of the agent. Examples: maxPositionPct and maxTotalExposurePct (both notional % of equity), maxLeverage, dailyLossHaltPct, maxOrdersPerDay. The caps are also surfaced to the agent in the per-tick user message under ## Risk caps (engine-enforced) so it can size proposals — and choose leverage strategically — within the limits the first time, instead of learning them through rejection codes. Per-order size and intra-day trade frequency are deliberately not capped by the engine (the agent sizes and paces by its strategy).

Tool A function the agent can call during a tick. Defined via defineTool in packages/tools. Has a name, description, zod input schema, and execute function. See tools-and-mcp.md.

Built-in Tool A Tool defined in our repo, hand-written.

MCP Tool A Tool exposed by an external MCP server (Model Context Protocol). Connected to at runtime; treated identically to built-in tools by the agent.

Trading Agent The agent instance that runs at each tick, with full tool access including propose_order. Lives in the live runtime (Fly) or simulator.

Chat Agent A separate agent instance that runs per chat message from the Deployer. Same Skill persona, same model, but with read-only tools (no order placement) plus introspection tools for past decisions. Lives in a Vercel Function.

Command A structured imperative sent by the Deployer to a running Deployment. Examples: stop, pause, resume, flatten, kill, snapshot. Delivered via Postgres LISTEN/NOTIFY. Not issuable via chat. See security/trust-boundaries.md.

Context Assembly The step at the start of each tick that gathers recent bars, news, portfolio state, and funding info into the messages that go to the model. Configured per Skill.

Sim Run One execution of the simulator over a date range for a Skill. Produces a report with equity curve, trade log, decision snapshots, and cost.

Paper Broker Deterministic simulated broker. Fills orders at the bar's close (configurable: open, mid, etc.), applies a configured fee + slippage model. Used in all sim runs and as the default for new deployments.

Skill Marketplace (future) The eventual product surface where Skills can be discovered, forked, and subscribed to.