Order & Position Types

OrderMeta

Metadata attached to orders for tracking and analysis. All fields are optional.

interface OrderMeta {
  signal?: string;    // Signal name shown in results (e.g., 'buy', 'sell')
  reason?: string;    // Human-readable reason
  type?: 'full_entry' | 'full_exit' | 'partial_entry' | 'partial_exit';
  [key: string]: unknown;  // Custom fields
}

ctx.order.market('ASSET', 1, {
  signal: 'buy',
  reason: 'ema_crossover',
  type: 'full_entry',
  confidence: 0.85,  // custom field
});

Allocation and Partial Orders

Order quantities are fractions of the strategy allocation. Use ctx.order.market() to enter or add to a position, and ctx.order.reduce() to realize part of an open position.

Set the metadata type to describe the order lifecycle. This allows backtests, live validation, and Adaptive Flow to preserve the remaining position after a partial exit and record its realized profit separately from the final close.

// Build a position, take partial profit, then close the remainder.
ctx.order.market('ASSET', 0.2, {
  signal: 'scout',
  type: 'partial_entry',
});

ctx.order.market('ASSET', 1, {
  signal: 'confirmed_entry',
  type: 'full_entry',
});

ctx.order.reduce('ASSET', 0.25, {
  signal: 'first_target',
  type: 'partial_exit',
});

ctx.order.close('ASSET', {
  signal: 'final_exit',
  type: 'full_exit',
});

Position

Returned by ctx.position(symbol). Reflects the current state of your position.

interface Position {
  qty: number;           // Quantity held (positive = long, negative = short, 0 = flat)
  avgPrice: number;      // Average entry price
  unrealizedPnL: number; // Unrealized profit/loss at current bar
  realizedPnL: number;   // Realized profit/loss from closed trades
}

Common Patterns

const pos = ctx.position('ASSET');

// Check if flat
if (pos.qty === 0) { /* no position */ }

// Check if long
if (pos.qty > 0) { /* holding long */ }

// Check if short
if (pos.qty < 0) { /* holding short */ }

// Check profit
if (pos.unrealizedPnL > 0) { /* in profit */ }

OrderAPI

The full order interface available via ctx.order:

interface OrderAPI {
  market(symbol: string, qty: number, meta?: OrderMeta): void;
  close(symbol: string, meta?: OrderMeta): void;
  reduce(symbol: string, pct: number, meta?: OrderMeta): void;
  limit(symbol: string, qty: number, price: number, meta?: OrderMeta): void;
  stop(symbol: string, qty: number, stopPrice: number, meta?: OrderMeta): void;
}

See the Strategy API for detailed usage of each method.