senpi-trading-runtime

Senpi Trading Runtime — the runtime contract

This skill is infrastructure: the canonical knowledge of how the Senpi runtime (@senpi-ai/runtime) behaves and how a strategy interacts with it. The lifecycle skills — author (build), ops (install/monitor), discover (recommend) — reference this one for the contract.

The runtime model

A strategy runs from a runtime.yaml that points at an in-repo Python module. The runtime spawns and supervises that module and calls a frozen scan(inputs, ctx) every interval_seconds. The division of labor is fixed:

• Your code produces signals — nothing else. scan(inputs, ctx) reads market and account data and returns a list[dict] of candidate signals. It does not open, close, size, schedule, or execute anything.
• The runtime owns everything downstream: scheduling (interval_seconds), spawning + supervising + restarting the scanner, validating (signal_data_schema) + de-duplicating the signals you return, sizing & order execution (FEE_OPTIMIZED_LIMIT), slot accounting, risk.guard_rails, the two-phase DSL trailing-stop exits, and crash-safe position reconcile on restart.

How your code talks to the runtime

The interaction surface is small and one-directional — you read, you return signals, the runtime acts.

• runtime.yaml declares the scanner(s), the action gate, the exit engine, and the risk guard-rails, and passes author tunables down via inputs:. → references/runtime-yaml.md
• scan(inputs, ctx) is the single entry point. inputs is the runtime's inputs: map; ctx gives you:
  • ctx.senpi_mcp.call_tool(name, args) — the Senpi MCP client, read-only (market, account, leaderboard, discovery, strategy_get*, …). It is the only way to fetch data.
  • ctx.state — transactional, runtime-persisted history (last() / append() / len) for dedup, rotation, and first-seen ledgers; advances only on a clean tick.
  • ctx.wallet — the strategy's wallet address.
  • → references/scan-contract.md
• The return value is a list[dict], one per candidate signal (asset, direction, marginPct, leverage, data{}). The runtime validates each data{} against the runtime.yaml's signal_data_schema, then sizes, executes, and manages exits.