Metadata-Version: 2.4
Name: perp-md
Version: 0.2.0
Summary: Typed asynchronous perpetual-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,funding-rate,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: crypto-derivative-markets==0.1.0
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: jsonschema<5,>=4.23; 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 and funding. Separate clients present stable
contracts while keeping provider protocols, pagination, validation,
normalization evidence, and optional CCXT integration behind adapter
boundaries.

Provider-independent economics and native-identity envelopes use the public `cdm` namespace from
`crypto-derivative-markets`. `perp-md` owns acquisition protocols, provider
identity requirements, source evidence, retrieval limits, and declared adapter coverage; it
does not define a parallel instrument or datapoint vocabulary.

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 and follows Semantic Versioning.

## Behavior

- `fetch_reference(provider_id, reference, ...)` accepts a CDM
  `InstrumentReferenceV1` unchanged; the legacy `Instrument` API remains a
  compatibility path.
- Provider-native identities are selected by exact CDM role and namespace.
  Missing and ambiguous selections are structured gaps; values are never
  guessed, rewritten, or selected by input order.
- 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.
- Proven canonical base OI quantity and reporting notional are exposed through
  CDM `OpenInterestValueV1` values while the legacy scalar fields remain
  available.
- Funding observations distinguish indicative and settled rates, timestamp
  meaning, calculation lineage, and interval evidence.
- The versioned funding observation wire codec preserves the exact CDM sample
  and acquisition evidence for storage or distribution without adding identity.
- 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.
- Runtime assessment accepts an incomplete CDM reference and reports
  structured field-path and identity-selector issues without embedding
  consumer or catalog concepts.
- Optional adapter support is probed from exact installed provider methods;
  consumers do not copy runtime feature identifiers or infer support from
  package presence.
- Runtime operation plans expose only generic scheduler constraints, including
  proven fixed cadence, bounded lookback, and explicit-start requirements.
- Versioned adapter manifests drive machine-readable coverage JSON and human
  documentation inputs from one source.
- Static native product families use exact catalog evidence names and contexts;
  open-ended runtime-scoped templates are declared but never treated as exact
  catalog matches.
- 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.

`perp-md-coverage` writes the deterministic declared adapter coverage manifest
as JSON. The bundled producer schema has the stable identifier
`urn:perp-md:schema:declared-coverage:1`.

## License

Apache-2.0.
