Metadata-Version: 2.4
Name: perp-md
Version: 0.1.6
Summary: Typed, asynchronous open-interest market data adapters
Author: perp-md contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/latheiere/perp-md
Project-URL: Repository, https://github.com/latheiere/perp-md
Project-URL: Issues, https://github.com/latheiere/perp-md/issues
Keywords: market-data,open-interest,perpetuals,asyncio
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Provides-Extra: ccxt
Requires-Dist: ccxt<5,>=4.5; extra == "ccxt"
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: ccxt<5,>=4.5; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Dynamic: license-file

# perp-md

`perp-md` is a typed asynchronous Python library for current and historical
perpetual-market open interest. It presents one stable contract while keeping
venue protocols, pagination, validation, and optional CCXT integration behind
adapter boundaries.

The package contains no persistence, scheduling, catalog discovery,
aggregation, chart policy, or application APIs. Market identity, storage, and
observation use remain outside the library.

## Status

The public API is alpha, follows Semantic Versioning, and covers open interest.

## Behavior

- Venue-native symbols are accepted without symbol guessing or rewriting.
- Namespaced perpetual instruments route through their venue-native product
  scope while default-universe instruments retain unscoped requests.
- Missing and unsupported values are never represented as zero.
- Current observations remain usable when optional history fails.
- Native quantities, units, marks, timestamps, and valuation methods are
  preserved alongside normalized USD notional.
- Aggregate derivative protocols use response-level source time when
  individual market timestamps describe unrelated last-trade activity.
- History ranges are bounded, deduplicated, ordered, and protected by finite
  pagination limits.
- Base-unit linear history is normalized only against exact-timestamp mark
  candles; missing joins are reported as structured partial history.
- History capabilities and requests use the cadence actually supported by each
  venue protocol.
- Native adapters are preferred when registered; fallback is explicit.
- External I/O is asynchronous, bounded, injectable, and independently
  testable.
- The package contains no consumer-specific storage or presentation behavior.

The complete contract is in [docs/CONTRACT.md](docs/CONTRACT.md), and package
boundaries are described in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

CCXT support is optional and selected through the `ccxt` extra.

## License

Apache-2.0.
