# Generic Stock Position Query (`stock_t.py`)

Per-symbol ad-hoc query tool for any LongBridge holding — no hardcoded symbol.
Lives at `~/.hermes/scripts/stock_t.py`.

## Why this exists

Earlier `rgti_auto_t.py` was RGTI-specific. When user asked to check UNH, AMD,
or 3416.HK, that script refused. The generic version accepts the symbol as
a CLI arg and supports both invocation orders:

```bash
# Format A: command then symbol
python3 stock_t.py status RGTI.US
python3 stock_t.py plan UNH.US
python3 stock_t.py cancel SOXS.US
python3 stock_t.py list

# Format B: symbol then command (also supported)
python3 stock_t.py RGTI.US status
```

## Usage

Always wrap in proxychains4 (for env + region override) before any call:
```bash
LONGBRIDGE_REGION=ap \
proxychains4 -f ~/.proxychains/proxychains.conf \
  python3 ~/.hermes/scripts/stock_t.py status <SYMBOL>
```

| Command | What it does | Side effects |
|---|---|---|
| `list` | All positions, total value | read-only |
| `status <SYM>` | Quote + position + today's orders for SYM | read-only |
| `plan <SYM>` | T-plan with buy/sell trigger levels | read-only |
| `cancel <SYM>` | Cancel all open orders for SYM | **mutates orders** |
| `execute` / `auto` | Placeholder (TODO) — currently just prints manual command | none |

## Per-symbol config (optional)

`stock_t.py` looks for `~/.hermes/scripts/<symbol>_t_config.json` (e.g.
`rgti_us_t_config.json`). Schema:

```json
{
  "trade_qty": 30,
  "buy_levels":  [18.50, 18.00, 17.50],
  "sell_levels": [20.50, 21.00, 21.50],
  "spread_buffer": 0.10
}
```

Without this file, `plan` shows generic placeholders. State file
`~/.hermes/scripts/<symbol>_t_state.json` is auto-managed by future
`execute`/`auto` implementations.

## Pitfalls

- **Status/plan always read-only.** They never place orders. If a user asks
  "what should I do", answer with a plan output + a proposed longbridge CLI
  command for them to copy-paste, not an auto-execution.
- **Symbol format must be canonical**: `RGTI.US`, `UNH.US`, `3416.HK`,
  `823.HK`. The script uppercases the input but does not auto-suffix `.US`
  or `.HK` — wrong format returns empty position silently.
- **602315 bypass is required**: The script sets `LONGBRIDGE_REGION=ap`
  internally, but it still needs to run under `proxychains4` for the TCP
  routing to actually reach the AWS endpoint. Running it bare will
  hang on `quote()` / `stock_positions()` and eventually fail.

## How to extend `execute` / `auto`

These are TODO. The pattern (when implemented) should be:

1. Load `stock_t.py` config for the symbol.
2. Read current position from `stock_positions()`.
3. Compare current price to buy/sell levels.
4. If a level is hit and we don't already have a working order at that
   level, place a limit order via `submit_order()`.
5. Persist to state file so we don't re-place the same order on next tick.

The 602315 bypass must be in place for the auto-execute path to work.
See `longbridge-602315-bypass.md` for the recipe.