# NAVIGATION MAP — where things live (read this BEFORE you grep)

**From**: Fable · **For**: omp · 2026-07-14
**Why this exists**: you were grepping `MessageBus|LiveClock|Cache` across the whole tree.
Those are **Nautilus framework internals** — NOT where our execution logic lives. You do
not need them for any commission/execution task. This file names the *exact* files. Read
these, not the framework. **Limit every search to the paths below.**

---

## 0. Credentials (this was your blocker — solved)

BingX VST keys are exported in **`/root/.bashrc`**:
`BINGX_API_KEY` and `BINGX_SECRET_KEY`. Your shell already has them if it sourced
`.bashrc`. To be sure in a script: `source /root/.bashrc` first, or read `os.environ`.
Do **not** invent a new credential path — the harness reads these same env vars.
Python interpreter for everything: **`/home/dolphin/siloqy_env/bin/python3`**.

## 1. The ONLY module you need for BingX execution: `prod/bingx/`

25 files. The five that matter, and nothing else:

| File | What it is | Key symbols (start here) |
|---|---|---|
| `prod/bingx/config.py` (71 L) | Client config, VST default | `BingxExecClientConfig` (:31) — `api_key`, `secret_key`, `environment=VST` (:39); `require_mainnet_opt_in()` (:13) |
| `prod/bingx/characterization.py` (897 L) | **The GTX-order harness** — already places post-only orders on VST | `characterize()` (:207), `build_representative_specs()` (:165, sets `post_only=True` :178), `BingxSampleSpec` (:94), `persist_report()` (:247), `_sample_one()` (:277) |
| `prod/bingx/friction.py` | **Fee/commission parsing — the authority** | `estimate_friction()` (:159), `_commission_quote()` (:141). `fee_bps = actual_fee_quote / notional × 10000` (:200). **Commission carries the RAW venue sign** — see §3 below. |
| `prod/bingx/execution.py` (2338 L) | The order-placement client | `BingxExecutionClient`; commission fields parsed at :1065, :1526, :1853 |
| `prod/bingx/factories.py` | Client construction | `create()` (:18) |

## 2. The specs that define the task (read these, skim the rest)

- `prod/docs/SPEC_UNIFIED_EXEC_LAYER_20260714.md` — the master spec. Read **§0**, **§2**
  (the contract), **§15** (tier table), **§17-Q1** (your task). Skim the rest.
- `prod/docs/COMMISSION_EXEC_Q1_OMP_20260714.md` — your Q1 cold-start pack (you did this).
- `prod/docs/BingX_FILL_CHARACTERIZATION_AND_ADVANTAGES.md` — measured venue friction
  (RTT anatomy, REST-only order entry, fee sweep). The ground-truth reference.

## 3. The commission-sign rule — memorize this (you got it inverted once)

BingX reports `commission` **negative to mean a DEBIT (a fee you PAID)**. This is the
OPPOSITE of Binance. So:
- `commission: "-0.001291"` → you **paid** 0.001291 USDT → a **cost** → **+2.00 bps fee**.
- A *positive* commission would be the rebate case (rare, high-VIP only).
Sanity check every fee against BingX's published rates: **maker 0.02% (2 bps), taker
0.05% (5 bps)**. If your number matches those magnitudes, it's a fee, not a rebate.

## 4. Where NOT to look (stop searching these)

- **Nautilus framework** (`MessageBus`, `LiveClock`, `Cache`, `nautilus_trader.*`) — that's
  the library armature *under* us. Irrelevant to execution/commission work. **Never grep it.**
- `prod/clean_arch/**` runtime modules, `nautilus_event_trader.py` (BLUE), ClickHouse
  `dolphin.*` — **do not touch** (running production; off-limits per your hard rules).
- `nautilus_dolphin/` — the kernel (the "brain"). Not your concern for execution tasks.

## 5. Housekeeping check for your Q1 fill

Your GTX BUY 0.0001 BTCUSDT **filled** → you likely hold a tiny +0.0001 BTC VST long
unless you flattened. Verify flat: cancel any open orders on the symbol; if a position
remains, close with MARKET `reduceOnly=true` `positionSide=BOTH`. VST-only, tiny, harmless
— but leave it clean.

---
**One rule above all**: if a task is about *placing orders or reading fills*, the answer is
in `prod/bingx/`. If it's about *what to trade*, that's a different layer you were not asked
about. Stay in `prod/bingx/` + the specs. That is the whole map.