67 lines
4.0 KiB
Markdown
67 lines
4.0 KiB
Markdown
|
# 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.
|