Alphameta Watchlist

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-market-data or alphameta-portfolio

See the [alphameta](../alphameta) skill for server setup and command execution syntax.

Workflow

Reading

1. Call qlist to get all groups.
2. qlist returns {"groups": {"": {"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-market-data:

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

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.

| Action | Command | Notes | |--------|---------|-------| | Create group + add symbols | qsave | If no symbols given, saves currently streaming quotes into the group | | Add symbols to existing group | qadd | Creates group if it doesn't exist | | Remove specific symbols | qremove | Supports glob patterns (qremove mygroup AAPL*) | | Remove all symbols from group | qremove | Clears the group but keeps it | | Delete entire group | qdelete | Can delete multiple at once. Briefly confirm before executing. |

Chained Workflows (common)

| User asks | Flow | |-----------|------| | "My watchlist stocks' gainers today" | qlist → extract symbols → alphameta-market-data (batch quote) | | "Are any of my watchlist options ITM?" | qlist → extract symbols → alphameta-technical (greeks/IV) | | "Check if these positions are in my portfolio" | qlist → extract symbols → alphameta-portfolio (positions filter) | | "Save my current quotes as a watchlist group" | qsave (no symbols → saves live quotes) |

Common Rationalizations

| Rationalization | Reality | |----------------|---------| | "I'll just use the raw JSON output" | The qlist response is already structured. Present it as a readable table — group name as header, symbols as a comma-separated list. | | "I'll rephrase qlist as watchlist since it's what the user understands" | Correct. The backend calls them "quote groups"; the skill layer should call them "watchlist groups". Translate terminology for the user. | | "I need to run two-step confirmation for all mutations" | Wrong. These are local writes — no broker state change. Only qdelete warrants a quick check. | | "I'll hardcode qadd → qsave mapping" | qadd appends to an existing group (or creates if missing). qsave overwrites. Use qadd for "add to", qsave for "create new group". |

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-market-data.
• 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"]}, ...}}

| Group | Symbols | Live | |-------|---------|:----:| | tech | NVDA, AAPL, MSFT | NVDA ✓, AAPL ✓ | | hk-stocks | 0700.HK, 9988.HK | — |

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

Single Group Detail

| Group: tech | Symbols | |-------------|---------| | NVDA | ✓ (live) | | AAPL | ✓ (live) | | MSFT | — |

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-market-data) requires a connected service.

Command Index

| Action | Command | Example | Returns | |--------|---------|---------|---------| | List all groups | qlist | {"cmd": "qlist"} | {"groups": {"name": {"symbols": [...], "live": [...]}}} | | Filter groups | qlist | {"cmd": "qlist tech hk-stocks"} | Same shape, filtered | | Create / replace group | qsave | {"cmd": "qsave tech NVDA AAPL"} | {"added": [...], "failed": [...]} | | Add to group | qadd | {"cmd": "qadd tech GOOGL"} | {"added": [...], "failed": [...]} | | Remove from group | qremove | {"cmd": "qremove tech AAPL"} | null (success) | | Delete group(s) | qdelete | {"cmd": "qdelete old-group"} | null (success) |

The gateway wraps responses as:

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

Key Concepts

Local Storage

Watchlist groups are stored in AlphaMeta's diskcache under keys ("quotes", "") → set(). 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

| Concept | Detail | |---------|--------| | Group names | Free-form strings (avoid special characters) | | Symbols | Any valid IBKR symbol: NVDA, AAPL260515P00200000, /ESM6, I:VIX | | Empty groups | Show as (empty) in listings | | Symbol casing | Case-sensitive. AAPL and aapl are different. | | live field | Subset of symbols that are currently streaming real-time quotes |

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.

| Feature | client-{id} | User groups | |---------|---------------|-------------| | Created by | qsnapshot (auto) | qadd / qsave (manual) | | Data format | {"contracts": [Contract, ...]} | Plain symbol strings | | Updated | Every add/remove (auto overwrite) | Only on manual edit | | Restore priority | 1st (on startup) | N/A (or global as 2nd fallback) |

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

| Situation | Reply | |-----------|-------| | Service not running | alphameta start to start the service | | qlist returns empty groups | "No watchlist groups yet. Create one with qadd ." | | qadd returns failed: [...] | "Could not qualify: AAPL. Check symbol spelling." | | qdelete on non-existent group | "Group not found. Run qlist to see available groups." | | qremove no matching symbols | "No matching symbols found in that group. Use qlist to check contents." | | Permission error (403) | "This command requires a PRO-tier API key. Set ALPHAMETA_API_KEY." | | Other API error | Surface the error message verbatim. |

Related Skills

• "What's the current price of my watchlist?" → alphameta-market-data
• "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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: intelliscale
• Source: intelliscale/alphameta-skills
• License: MIT
• Homepage: https://alphameta.app

Install and usage instructions live in the source repository linked above.