================================================================
 RITHMIC NEXUS BRIDGE V6.1  -  README
 Data bridge for 3D NEXUS META  (ws://localhost:5556)
================================================================

------------------------------------------------------------
 WHAT YOUR LAST RUN PROVED
------------------------------------------------------------
You ran V6 and got this (it is the important result, not a bug):

  system 'Rithmic Paper Trading' -> server says only 'Rithmic Test' is valid
  system 'Rithmic Test'          -> rpCode 13, permission denied (ticker plant)

That means:
  * You are on rituz00100.rithmic.com = Rithmic's TEST / CONFORMANCE gateway.
  * On that login the ONLY valid system name is "Rithmic Test" (a fully
    provisioned account would also expose "Rithmic Paper Trading" / a prod name).
  * Even on the test tier, the TICKER plant (= market data) returns
    "permission denied". So the data feed is not switched on for this account.

This is a Rithmic-side ENTITLEMENT, not a code bug. No bridge can stream data
the account is not allowed to receive. So V6.1's job is to (1) tell you exactly
what is missing, (2) help you switch it on, and (3) stream the moment it is on.

------------------------------------------------------------
 WHAT IS NEW IN V6.1
------------------------------------------------------------
Two new one-click tools that pinpoint and unblock the problem:

  --probe       Logs in to the ORDER / TICKER / PNL plants SEPARATELY.
                This separates the two very different cases:
                  (a) credentials VALID, only market DATA missing
                      (order plant logs in, ticker plant denied), or
                  (b) account not provisioned at all
                      (even the order plant is denied).
                You need to know which one you are in - the fix differs.

  --conformance Logs in to the ORDER plant and HOLDS IT OPEN. This is the
                exact Rithmic conformance step (it matches async_rithmic's own
                conformance script): leave it running so Rithmic can approve
                the app, after which they can enable your data entitlement.

The bridge itself is unchanged and correct: it connects only the ticker plant,
auto-detects the system name, resolves YM -> the real front-month, keeps a full
L2 book and feeds NEXUS the exact {type:'book'} / {type:'trade'} messages it
expects. Your password is masked in every log line AND in the support report.

------------------------------------------------------------
 FILES IN THIS PACK
------------------------------------------------------------
  rithmic_nexus_bridge_v6.py          The bridge (single file, V6.1).
  RUN_RITHMIC_V6_PROBE.bat            STEP 1 - per-plant probe (do this first).
  RUN_RITHMIC_V6_CONFORMANCE.bat      STEP 2a - hold order plant open (if needed).
  RUN_RITHMIC_V6_DIAGNOSE.bat         Full report: probe + exchanges + stream test.
  START_RITHMIC_V6_BRIDGE.bat         STEP 3 - run the live bridge for NEXUS.
  rithmic_credentials\
      RITHMIC_PAPER_TRADING.ini.example   Copy -> .ini and fill in.

The .bat files build an ISOLATED env (.venv_rithmic_v6) with async_rithmic 1.6.1
+ websockets 14.2 + protobuf 4.x, so they never touch your global Python. If you
prefer, you can also just run it directly in your own Python (it already worked
for you), e.g.:  python rithmic_nexus_bridge_v6.py --probe

------------------------------------------------------------
 SETUP (once)
------------------------------------------------------------
1. Put this folder somewhere simple, e.g. C:\nexus\rithmic_v6
2. In rithmic_credentials\, copy
       RITHMIC_PAPER_TRADING.ini.example  ->  RITHMIC_PAPER_TRADING.ini
   and fill in your real user + password. Leave system_name as is - the bridge
   auto-detects the correct one. (Tip: your old INI had
   app_version = 4.1.0-data-hotfix; you can set it to 6.1, it does not affect
   the result.)

------------------------------------------------------------
 STEP 1 - PROBE  (do this first)
------------------------------------------------------------
Double-click  RUN_RITHMIC_V6_PROBE.bat   (or: python rithmic_nexus_bridge_v6.py --probe)

Read the VERDICT:

  CASE A - "CREDENTIALS ARE VALID / MARKET DATA IS NOT ENABLED"
     (order plant OK, ticker plant denied)
     -> Your login works; only the data feed is missing. Go to STEP 2a AND 2b.

  CASE B - "Even the ORDER plant login was refused"
     (everything denied)
     -> The account/app is not provisioned for the API at all. Skip conformance;
        go straight to STEP 2b (your broker must enable API access first).

Either way the probe writes rithmic_support_report.txt.

------------------------------------------------------------
 STEP 2a - CONFORMANCE  (only for CASE A)
------------------------------------------------------------
Double-click  RUN_RITHMIC_V6_CONFORMANCE.bat  and LEAVE THE WINDOW OPEN.
It connects the order plant and holds it. Tell Rithmic / your broker the app is
now connected for conformance. Press Ctrl+C once they confirm.

------------------------------------------------------------
 STEP 2b - ASK YOUR BROKER / RITHMIC TO ENABLE DATA
------------------------------------------------------------
Send rithmic_support_report.txt (or the text below) to your broker / Rithmic:

  ------------------------------------------------------------
  Hello,
  I can log in to R Trader Pro with this account, but a direct Rithmic
  R|Protocol API login is rejected for market data.
    Endpoint: rituz00100.rithmic.com:443
    Error:    rpCode 13, permission denied (at TICKER plant login)
  Please confirm whether this user is entitled to R|Protocol / R|API
  TICKER_PLANT market data (Level 1 and Level 2, CME/CBOT/COMEX), enable it,
  and run any required API conformance test.
  Thank you.
  ------------------------------------------------------------

------------------------------------------------------------
 STEP 3 - RUN THE BRIDGE  (once data is enabled)
------------------------------------------------------------
Double-click  START_RITHMIC_V6_BRIDGE.bat
Then in 3D NEXUS META: choose Rithmic, subscribe to YM (or ES, NQ, GC...).
The bridge resolves the root to the live front-month and feeds NEXUS the full
book + trades. Nothing in the code needs to change - the same bridge that is
denied today will stream the moment the entitlement is on.

Optional full check first:  RUN_RITHMIC_V6_DIAGNOSE.bat
(this runs the probe, then lists exchange entitlements and does a live stream
test, so you can confirm data is really flowing before opening NEXUS).

------------------------------------------------------------
 IF YOU JUST WANT A LIVE MAP TODAY
------------------------------------------------------------
You already have a working Sierra Chart -> NEXUS path (file-based) on
ws://localhost:5559 with Sierra's own entitled data. That is the fastest way to
a live map right now, while the Rithmic API entitlement is being switched on in
parallel. V6.1 takes over the Rithmic path the moment data is enabled.

------------------------------------------------------------
 COMMAND-LINE OPTIONS
------------------------------------------------------------
  --probe              Per-plant login probe (credentials vs data) and exit.
  --conformance        Hold an order-plant connection open (conformance step).
  --diagnose           Probe + exchange entitlement table + live stream test.
  --env paper|live     Which INI to load (default paper).
  --port 5556          NEXUS websocket port (default 5556).
  --depth 40           L2 levels per side sent to NEXUS.
  --symbols ES,YM,NQ   Symbols used by --diagnose.
  --seconds 15         Seconds per symbol during --diagnose.
  --debug              Verbose logging.
  --host localhost     Bind address.

================================================================
