Metadata-Version: 2.4
Name: perp-md
Version: 0.5.4
Summary: Typed asynchronous perpetual-market open-interest and funding acquisition
Author: perp-md contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/latheiere/perp-md
Project-URL: Documentation, https://github.com/latheiere/perp-md/tree/main/docs
Project-URL: Repository, https://github.com/latheiere/perp-md
Project-URL: Changelog, https://github.com/latheiere/perp-md/blob/main/CHANGELOG.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

[![PyPI](https://img.shields.io/pypi/v/perp-md)](https://pypi.org/project/perp-md/)
[![Python](https://img.shields.io/pypi/pyversions/perp-md)](https://pypi.org/project/perp-md/)
[![CI](https://github.com/latheiere/perp-md/actions/workflows/ci.yml/badge.svg)](https://github.com/latheiere/perp-md/actions/workflows/ci.yml)

Typed, asynchronous acquisition of perpetual-market open interest and funding
for Python applications.

Release `0.5.4` refreshes optional-provider market catalogs after fifteen
minutes and refreshes unresolved native identities at most once per venue
per minute. Catalog retention is bounded by bytes and venue count. Expiry
releases idle clients without another request; in-flight acquisition finishes
before its retired client closes. Completed HTTP responses retain their
three-second expiry and identical pending requests remain shared.

`perp-md` turns provider-independent
[CDM instrument references](https://github.com/latheiere/crypto-derivative-markets)
into source-faithful observations. It keeps provider protocols, identity
requirements, pagination, and acquisition evidence behind a small public API.

## Install

```sh
pip install perp-md
```

Optional CCXT fallback adapters are available through the `ccxt` extra:

```sh
pip install "perp-md[ccxt]"
```

## Quick start

Pass the CDM reference supplied by your instrument catalog directly to a
client:

```python
from cdm import InstrumentReferenceV1
from perp_md import OpenInterestClient


async def current_open_interest(
    provider_id: str,
    reference: InstrumentReferenceV1,
):
    async with OpenInterestClient() as client:
        result = await client.fetch_reference(
            provider_id,
            reference,
            include_history=False,
        )
        return result.current
```

`FundingClient` provides the corresponding funding workflow. Both clients can
assess runtime support and return structured metadata or identity gaps before
acquisition. Observations retain native values, timestamps, calculation
lineage, and normalization evidence; missing data is never represented as
zero.

## Scope

The library owns market-data acquisition: provider protocols, operation-level
identity requirements, source validation, bounded history retrieval, and
declared adapter coverage. It does not discover instruments, persist data,
schedule jobs, calculate application metrics, or expose a service API.

See the [public contract](https://github.com/latheiere/perp-md/blob/main/docs/CONTRACT.md)
for data and error semantics, the
[architecture guide](https://github.com/latheiere/perp-md/blob/main/docs/ARCHITECTURE.md)
for module boundaries, and the
[changelog](https://github.com/latheiere/perp-md/blob/main/CHANGELOG.md) for
release notes. `perp-md-coverage` emits the deterministic declared-coverage
manifest for documentation and capability tooling.

## Status and support

The API is alpha, follows Semantic Versioning, and supports Python 3.11–3.13.
Use [GitHub Issues](https://github.com/latheiere/perp-md/issues) for defects and
feature requests, and [private security advisories](https://github.com/latheiere/perp-md/security/advisories/new)
for vulnerabilities. Licensed under Apache-2.0.
