16, Glossary

Glossary

The terms, roles, tools, and risk caps that appear throughout the Sphynx docs, in one place.

A quick reference for the vocabulary used across these docs. Where a term has its own page, the definition links to it.

Roles & architecture

Portfolio Manager (PM): The main Claude Code session you talk to. It orchestrates the sub-agents and is the only role that can place orders, and only after your approval. See The Desk Team.
Sub-agent: A specialist role defined as a Markdown file in .claude/agents/ with its own restricted tools: list and model:. Loaded when Claude Code starts.
Human-in-the-loop (HITL): The structural rule that no order is placed without your explicit in-session approval. See Guardrails.
Least privilege: Each role holds only the tools its job needs. The analysts and Risk Manager have no order tools; only the PM does.
Claude Code: The agent host Sphynx runs inside. There is no separate backend server or Python orchestrator, the PM *is* the session. See Architecture.
MCP (Model Context Protocol): The protocol that connects Claude Code to the broker. Sphynx uses one MCP server, robinhood-trading. See MCP & Tools.
robinhood-trading: The single MCP server (HTTP transport, OAuth) that is the desk's only path to the account. Defined in .mcp.json.
Robinhood Agentic account: The isolated, equities-only account the desk may trade. Every other account is read-only for context.
OAuth: The in-session authentication flow for the MCP server. The agent never sees your password; there is a Robinhood mobile verification step.

The desk run

Preview card: The desk's standard output: a summary of the proposed order (symbol, side, qty, order type, estimated cost, rationale) that the PM presents and waits on. Built by review_equity_order. See The Desk Run.
review_equity_order: A read-only tool that builds an order preview without submitting anything. allow-ed, because it never transacts.
place_equity_order: The tool that actually submits an order. Held only by the PM and gated behind an ask prompt.
Veto: The Risk Manager's power to block a proposed trade outright. A VETO stops the trade; the PM reports back.
APPROVE-WITH-CHANGES: A Risk Manager verdict that clears a trade only after specific changes (e.g. cut size to N, add a stop at $X).
Scan: A saved technical screen the Technical Analyst runs (run_scan / get_scans) to surface candidate tickers.
Watchlist: A list of symbols the desk screens (get_watchlist_items); mutating watchlists is gated behind ask.
INJECTION ATTEMPTS: The line in the Macro/News Analyst's brief where instruction-like text from the web is quoted verbatim and flagged, never obeyed. See Prompt-Injection Defense.
Prompt injection: External content that tries to act like an instruction ("buy X now", "ignore your rules"). Sphynx treats all external content as untrusted data.

Risk & strategy

NAV (total_value): Account value = cash + positions, read from get_portfolio.total_value for the Agentic account. All risk percentages are of NAV, not the broker equity_value field. See Strategies & Risk.
Per-trade cap: 15% of NAV, the hard ceiling on any single place_equity_order.
Concentration cap: 25% of NAV in any one symbol, including all adds.
Max open positions: 6, forces diversification within a small account.
Max daily orders: 4, throttles churn; counts buys + sells per day.
Stop-loss: −8% from average entry, every entry must define this before it is placed.
Daily loss halt: −5% account day P&L, stop trading, report, and ask for the rest of the day.
Cash buffer: ≥10% of NAV kept in cash, never fully deploy.
Mean reversion: A strategy: buy oversold pullbacks inside a confirmed uptrend; long only, swing. One entry per setup, no averaging.
Left-side accumulation: A strategy: planned, risk-budgeted scale-in at support in a quality name's fear-driven selloff. The only defined exception to "no averaging into losers," bounded by a fixed total-risk budget and a whole-position kill-stop.
No averaging into losers: Adding to an underwater position is forbidden unless a strategy file explicitly permits it with limits.

State, tooling & operations

desk-state.json: The snapshot the PM writes after each run; the dashboard mirrors it. Real state is gitignored; only the sanitized example is committed.
injectionAlerts: The array in desk-state.json where flagged injection attempts surface (source, quote, handledBy, action).
decisionLog: A tail of the JSONL audit log flattened for the dashboard timeline as { ts, event, summary, symbol, tone }. See Audit Logging.
JSONL audit log: The append-only logs/*.jsonl trail, one JSON object per line, of every desk decision, written via tools/desk-log.mjs.
Backtester: The offline, dependency-free engine in backtest/ that sanity-checks strategy logic against historical bars, illustrative, not a track record. See Backtester.
/loop: The Claude Code mechanism used to run the read-only desk on a cadence (e.g. behind the dashboard's Run desk button).
Kill switch: Disconnecting the MCP from the Robinhood app or claude mcp remove robinhood-trading, the desk's hard stop.

On-chain

Robinhood Chain: An Arbitrum Orbit rollup, chainId 4663, gas in ETH. Where the SPHYNX contracts and the Stock Token pools live. RPC rpc.mainnet.chain.robinhood.com, explorer robinhoodchain.blockscout.com.
USDG: Global Dollar, the 6-decimal stablecoin the vault is denominated in (0x5fc5…d168). An 18-decimal look-alike exists on the chain; the deploy script pins 6.
Stock Token: A Robinhood-issued ERC-20 that tracks a stock's price (NVDA, AAPL, SPY…). 18 decimals. Not a share, no voting rights, not for US persons. The vault holds these.
RWAVault / vSPHYNX: The ERC-4626 vault over USDG that holds Stock Tokens. vSPHYNX is its share (12 decimals). Reverts any order that breaches the caps. See The Vault.
previewTrade(): The free view call that returns the first rule an order would break, or None. The same check runs inside executeTrade(). The site's Trade terminal calls it as you type.
Violation: The enum previewTrade() returns: None, Unfunded, DailyLossHalt, PerTradeCap, MaxDailyOrders, Concentration, MaxPositions, CashBuffer, NoAveragingIntoLoser, MissingStop, NotAllowed, ZeroAmount, InsufficientPosition, Paused. Table in the Trading Guide.
GuardrailConfig: The caps as chain state, read by the vault on every order. Owner-changeable within hard ceilings nobody can widen (per-trade ≤ 50%, stop ≤ 25%, cash buffer ≥ 5%).
SessionKeyExecutor: The vault's only trader. Holds one session per agent key: expiry, per-trade notional, budget, trade count, sides, ticker allowlist. A refused order reverts and spends none of it. See Session Keys.
Session: The scoped, expiring permission an agent key holds on the executor. isLive() is true while it is active, unexpired, and has count and budget left.
TWAP: Time-weighted average price. The oracle's mark is the 5-minute TWAP from the token's Uniswap V3 pool; it cannot be moved inside one block.
Deviation bound: If spot is more than 3% from the TWAP the oracle reverts, which freezes valuation and orders until the pool settles. redeemInKind is unaffected.
UniswapV3Adapter: The vault's only execution surface: swaps straight against one owner-registered USDG pool per token. No router, no path, no arbitrary call.
minAmountOut: The slippage floor on an order, set by the caller. Checked by the adapter and again by the vault's own balance delta.
redeemInKind(): Burn shares for a pro-rata slice of cash and every token, minus the exit fee. Always works: while paused, with a broken oracle, without the owner.
Exit fee: 0% at launch, hard-capped at 1%. Stays in the vault for remaining holders. The only fee in the contracts; there is no management or performance fee.
DeskRegistry: Append-only attestations (epoch, NAV, PnL, snapshot hash, URI) keyed by a subject the attester owns. Nothing can be edited or removed. Where refusals get published.
Deposit cap: 10,000 USDG at launch. An owner-changeable setting that bounds the blast radius until the audit and the Safe are done.
Ownable2Step: Ownership transfer that the new owner must accept, so a typo cannot hand the contracts to a dead address. Every SPHYNX contract with an owner uses it.
Timelock: A delay between an owner signing a change and it taking effect. Not deployed yet. The first planned upgrade; see Risks.

Missing a term? The FAQ covers scope and safety questions, and each reference page defines its own vocabulary in context.