perp-md

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

Release 0.5.3 expires completed HTTP response payloads without requiring the same request key to recur. Timestamped history windows cannot accumulate responses for the lifetime of a client. Identical pending requests remain shared until completion; successful responses retain the three-second TTL.

perp-md turns provider-independent CDM instrument references into source-faithful observations. It keeps provider protocols, identity requirements, pagination, and acquisition evidence behind a small public API.

Install

pip install perp-md

Optional CCXT fallback adapters are available through the ccxt extra:

pip install "perp-md[ccxt]"

Quick start

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

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 for data and error semantics, the architecture guide for module boundaries, and the changelog 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 for defects and feature requests, and private security advisories for vulnerabilities. Licensed under Apache-2.0.