NautilusTrader PAPI

nautilus-trader-papi is an unofficial, full NautilusTrader distribution maintained in the imbingox/nautilus_trader fork. It adds guarded Binance Portfolio Margin (PAPI) account, reconciliation, and execution support while retaining the standard nautilus_trader import path and a single Rust extension.

This package is not published or supported by Nautech Systems. Nautech Systems remains the author and copyright holder of the upstream project. Report fork-specific issues to the fork issue tracker.

Supported wheel

The 2.0.0rc14 release supports only:

• CPython 3.14 with the GIL enabled
• Linux x86_64 with a manylinux_2_34 baseline

No source distribution is published. Installations on other Python versions, operating systems, architectures, or free-threaded Python builds are unsupported and must not fall back to a local Rust build.

Install the exact binary release in a new virtual environment:

python3.14 -m venv .venv
.venv/bin/python -m pip install --only-binary=:all: nautilus-trader-papi==2.0.0rc14

Do not install nautilus-trader and nautilus-trader-papi together. Both distributions provide the same nautilus_trader package and _libnautilus extension. Remove the official distribution, or preferably create a fresh environment, before installing this fork.

The fork uses its own PEP 440 version sequence. 2.0.0rc7 is the first published PAPI candidate; future PAPI changes receive a new public version even when the tracked upstream version is unchanged. A matching number does not imply that the two distributions are interchangeable.

Standard account queries in 2.0.0rc14

Running strategies can call self.query_account(account_id, client_id=BINANCE_PAPI_CLIENT_ID). Successful current-round collection publishes a standard AccountState with exact PM equity and margin ratio under info["papi"]["portfolio_margin"]. Each client admits one query task, coalescing concurrent requests. Failure or a pending recovery/risk application checkpoint publishes no query event; applications own refresh scheduling, timeouts and per-source last-good values.

The existing explicit execution instrument scope and wallet restrictions still apply. This does not enable strategy startup when node recovery is blocked or change trading authorization. See the field and availability contract.

Account-wide current reports

Version 2.0.0rc8 supports current UM positions and ordinary/algo open orders without a manually supplied instrument list:

client = BinancePapiReadOnlyClient(config)
positions = await client.generate_position_status_reports()
orders = await client.generate_order_status_reports(open_only=True)

These methods return native Nautilus reports and discover required USD-M instrument metadata. Historical reports and trading recovery still require an explicit instrument scope.

Recovery fixes in 2.0.0rc9

Risk-increasing orders remain blocked during private-stream recovery until the execution engine has applied the current baseline and fresh risk evidence is acknowledged. Restart reconciliation restores the original strategy owner from matching durable submission records even with an empty Cache, without replaying unresolved orders. The command journal format is unchanged.

Risk refresh recovery in 2.0.0rc13

Account events can trigger a new risk collection without first waiting for those same account facts to be applied. Previously delivered execution reports must still be applied, and new risk evidence is installed only after the engine applies its matching report. Superseded snapshots cannot restore authorization, and freshness limits are unchanged.

Recovery diagnostics include the latest received fact version and session issues. Application checkpoint and risk-report acknowledgement timeouts restrict the session and stop the refresh worker. The host must handle the failure and recreate the execution client. This change has offline regression coverage; it does not add a live strategy acceptance claim.

Cancellation of claimed orders in 2.0.0rc12

A strategy can cancel its recovered ordinary UM orders through the standard single, batch, and cancel-all APIs without the original Submit journal entry. Cancellation uses the engine's current order ownership and venue identity. The journal records the new cancellation and its recovery; no position handoff or fabricated submission history is required.

Recovery evidence and position handoff in 2.0.0rc11

The production BinancePapiExecutionClientFactory exposes recovery_state_json(client_id) for the same execution client used by the Node. Evidence includes scope, generation, freshness, report application progress, and operation permissions. Readers do not retain journal ownership.

Explicit position handoff verifies the account, instruments, quantities, and stable strategy ownership before persisting a receipt after Cache application. Historical external orders remain EXTERNAL, and legacy fills already covered by the position snapshot are not counted twice. Failed handoff, foreign open orders, or lost receipts block new risk-increasing orders. Startup reconciliation also notifies the source execution client after applying recovered positions.

Safety boundary

Importing PAPI support does not authorize trading. BinancePapiExecutionClientConfig defaults to trading=None. Trading requires explicit credentials, a durable absolute command-journal path, finite per-instrument and account limits, an explicit report scope, and current authenticated risk evidence.

The first release is deliberately limited to one-way USD-M perpetual execution for explicitly configured instruments. Unsupported products, hedge mode, ambiguous account state, stale risk evidence, unknown command outcomes, and unsupported borrowing or interest state fail closed.

Live trading can lose real capital. Review the adapter documentation and the account verification record before configuring a live process. The verification record distinguishes offline coverage, limited live evidence, known gaps, and unsupported behavior.

Upgrades and rollback

Stop the existing process before changing the installed extension. Record the installed package version, reconcile the account, and back up the command journal and related persistent state. Install the new version into a fresh environment, then start through the normal recovery and reconciliation path.

Never delete a command journal or replay an unresolved POST to force recovery. Before rolling back, confirm that the older version can read the persisted format and reconcile against current venue state. Published files are immutable; a corrected build is released under a new version.

Source, build constraints, release manifests, and the operator procedure are maintained in the fork repository.