Metadata-Version: 2.4
Name: nautilus-trader-papi
Version: 2.0.0rc15
Classifier: Operating System :: POSIX :: Linux
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Requires-Dist: pandas>=2.3.3,<4.0.0 ; extra == 'visualization'
Requires-Dist: plotly>=7.0.0,<8.0.0 ; extra == 'visualization'
Requires-Dist: kaleido>=1.4.0,<2.0.0 ; extra == 'visualization'
Requires-Dist: simplejson>=4.1.2,<5.0.0 ; extra == 'visualization'
Provides-Extra: visualization
License-File: LICENSE
Summary: Unofficial NautilusTrader distribution with guarded Binance Portfolio Margin support
Home-Page: https://github.com/imbingox/nautilus_trader
Author-email: Nautech Systems <info@nautechsystems.io>
Maintainer: imbingox
License-Expression: LGPL-3.0-only
Requires-Python: >=3.14, <3.15
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: homepage, https://github.com/imbingox/nautilus_trader
Project-URL: issues, https://github.com/imbingox/nautilus_trader/issues
Project-URL: repository, https://github.com/imbingox/nautilus_trader
Project-URL: upstream, https://github.com/nautechsystems/nautilus_trader

# NautilusTrader PAPI

`nautilus-trader-papi` is an unofficial, full NautilusTrader distribution maintained in the
[`imbingox/nautilus_trader`](https://github.com/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](https://github.com/imbingox/nautilus_trader/issues).

## Supported wheel

The `2.0.0rc15` 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:

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

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.0rc15

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"]`. The summary also includes optional
`account_equity` and `account_maint_margin` as exact USD decimal strings, plus raw `account_status`.
Missing or invalid optional fields are `None`, without reusing prior values. 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](https://github.com/imbingox/nautilus_trader/blob/papi-v2.0.0rc15/crates/adapters/binance-papi/README.md#standard-account-queries).

## Account-wide current reports

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

```python
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](https://github.com/imbingox/nautilus_trader/blob/main/crates/adapters/binance-papi/README.md)
and the
[account verification record](https://github.com/imbingox/nautilus_trader/blob/main/crates/adapters/binance-papi/ACCOUNT_VERIFICATION.md)
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](https://github.com/imbingox/nautilus_trader).

