AlphaMeta Watchlist

Persistent named groups of securities, stored locally via AlphaMeta's quote group system. Think of it as bookmarks for symbols — stocks, options, futures, indices. Data lives in local diskcache, not on any broker server. No network required for CRUD; only live quote lookups need a running AlphaMeta service.

When to Use

• "我的自选股有哪些？" / "Show me my watchlist" — list every group and its symbols
• "我的 Tech 分组里有什么？" / "What's in my Tech group?" — filter by group name
• "显示所有有实时报价的分组" / "Show me all groups with live quotes" — list groups, check live field
• "把 NVDA 加入我的自选" / "Add NVDA to my watchlist" — create or append symbols to a group
• "从自选里移除 AAPL" / "Remove AAPL from my watchlist" — delete a symbol from a group
• "删除我的 test 分组" / "Delete my test group" — remove an entire group
• "批量查看自选股行情" / "Watchlist batch check" — get symbols then route to alphameta-quote or alphameta-portfolio

See the alphameta skill for server setup and command execution syntax.

Workflow

Reading

1. Call qlist to get all groups.
2. qlist returns {"groups": {"<name>": {"symbols": [...], "live": [...]}}}.

• symbols: all symbols saved in the group
• live: subset of symbols currently streaming live quotes

1. Filter by group name (LLM-side) if user asks for a specific group.
2. To batch-check prices, pass the symbols to alphameta-quote:

   Extract symbols → curl POST /api/v1/execute {"cmd": "quote <symbols>"}

Writing (one-shot, no two-step protocol)

All mutations are local (diskcache). No remote side effects.

• Describe what you are about to do in the user's language.
• Execute immediately — no explicit confirmation gate needed.
• Exception: for qdelete (irreversible), briefly confirm with the user before executing.

Chained Workflows (common)

Common Rationalizations

Red Flags

• Using qsave when user says "add" — qsave creates/replaces, qadd appends. GET IT RIGHT.
• Calling qdelete without a brief confirmation — the group is gone permanently.
• Forgetting to route symbols to the display skill — listing symbols without prices is only useful for inventory. If user asks "how are they doing", immediately chain to alphameta-quote.
• Group name collisions — if qadd target doesn't exist, it creates it. If user said "add to group X" and X doesn't exist, warn them it'll be created.
• Treating client-{id} groups as user watchlists — these are auto-generated system snapshots. qadd/qremove edits will be overwritten. qdelete breaks startup auto-restore. Do not manage them manually.
• Assuming global is the primary restore source — client-{id} snapshot takes priority on startup. global is only a fallback.

Output

Present watchlist data as markdown tables.

List All Groups

qlist → {"groups": {"tech": {"symbols": ["NVDA","AAPL","MSFT"], "live": ["NVDA","AAPL"]}, ...}}

When live is non-empty, mark symbols that are actively streaming with a checkmark.

Single Group Detail

After Adding Symbols

qadd tech GOOGL → {"added": ["GOOGL"], "failed": []}

Added GOOGL to tech. ✓ Success. (optional chained query) → "Would you like to see the current price of GOOGL?"

After Removing Symbols

qremove tech AAPL → null (success)

Removed AAPL from tech.

No prior service login needed for CRUD. Watchlist data is stored locally in diskcache and is available even when IBKR is disconnected. Only the live quote routing step (alphameta-quote) requires a connected service.

Command Index

The gateway wraps responses as:

{"success": true, "result": <above>, "request_id": "...", "execution_time_ms": N}

Key Concepts

Local Storage

Watchlist groups are stored in AlphaMeta's diskcache under keys ("quotes", "<group_name>") → set(<symbols>). This means:

• Persistence: survives restarts
• Speed: instantaneous mutations (no network round-trip)
• No broker dependency: works even when IBKR is disconnected
• No sharing: groups are local to this machine

Group Semantics

System Groups

Two group types are managed by the system, not created by the user:

`client-{id}` (e.g. `client-0`, `client-2`) — Auto-generated live quote snapshot

• Created automatically by qsnapshot whenever quotes are added/removed (add, remove, oadd, align).
• Stores full IBKR Contract objects (not plain symbols) — {"contracts": [...]}.
• On startup, AlphaMeta restores from this snapshot first. Only if absent does it fall back to global group or built-in defaults (SPY, QQQ, AAPL + futures + indices).
• Not a user watchlist. qadd/qremove edits are overwritten on the next quote change. Do not qdelete unless you intend to reset saved state.
• Stored in diskcache under key ("quotes", f"client-{clientId}").

`global` — Shared default fallback group

• Plain symbol-set group (set("AAPL", "MSFT")) created via qsave/qadd.
• Loaded only when no client-{id} snapshot exists on startup.
• Legacy fallback mechanism — still works but client-{id} takes priority.

Relationship to Other Commands

The q* commands (qlist, qadd, qsave, qremove, qdelete) are the same system used by AlphaMeta's quote stream management. When you qsave or qadd, you're writing into the same quote-group namespace used by the live quote view. This means a watchlist group is also a "quote group" — it can be loaded into the live stream via qrestore.

Error Handling

Related Skills

• "What's the current price of my watchlist?" → alphameta-quote
• "How are my watchlist options performing?" → alphameta-technical
• "Are any watchlist symbols in my portfolio?" → alphameta-portfolio
• "Set an alert if a watchlist symbol drops below X" → alphameta-predicate