Reconify Python SDK

Typed synchronous and asynchronous clients for the Reconify Public API.

Installation

pip install reconify-python

Quickstart

from reconify import Reconify

with Reconify(api_key="rk_...") as client:
    sources = client.ledger.list_ledger_sources(limit=25)
    for source in sources.sources or []:
        print(source.id, source.name)

The key may also be supplied through RECONIFY_API_KEY. The default endpoint is https://api.reconifyhq.com/v1; pass base_url="https://staging.example/v1" for staging or self-hosted deployments. /v1 is added when it is absent.

Async usage and pagination

from reconify import AsyncReconify

async with AsyncReconify() as client:
    async for event in client.iter_events(limit=100):
        print(event.id)

Cursor and offset iterators preserve opaque cursors and the server's page size. When an endpoint accepts both cursor and offset pagination, after takes precedence.

Every list operation also has a natural iterator on the client, for example client.iter_reconciliations(limit=100) or client.iter_wallet_transactions(after="cursor"). The async equivalent is an async iterator. Iterators forward query parameters using keyword arguments, so they never expose transport details.

Errors and retries

HTTP failures raise typed ReconifyError subclasses. Every HTTP error exposes status_code, detail, code, validation details, response headers, and the response request_id without including credentials or request bodies.

429, 503, and transient HTTP transport failures such as timeouts are retried for safe methods with bounded exponential backoff and jitter. Mutating methods are not retried unless RetryConfig(retry_unsafe_methods=True) is supplied. Transaction ingestion retries must reuse each row's idempotencyKey.

The client default timeout is 30 seconds. Individual operations can override it with timeout=..., including an httpx.Timeout object. Async operations also support normal asyncio cancellation, which is the Python equivalent of context cancellation in other SDKs.

Use raw=True on any operation to receive status, headers, request ID, and raw body through RawResponse.

Test-session and ingestion headers

Integrity ingestion and test-session submission accept integrity_test_session=..., which is sent as X-Integrity-Test-Session. Integrity batches support 1–500 events and ledger transaction batches support 1–5000 transactions; the SDK does not truncate caller input.

The SDK intentionally excludes reconciliation adjustment, evidence, lifecycle, report-item, and signoff operations. The retained reconciliation surface is integrity sources, reconciliation list/create/get, and all schedule operations.

API reference

The public operation methods are grouped by API module. Request bodies use the typed Pydantic models exported from reconify.models; list query parameters use the OpenAPI names in snake_case. Every operation accepts raw=True and a per-request timeout override.

Build and deploy

Build the distributable artifacts locally or in CI:

python -m pip install build
python -m build

The resulting wheel and source archive in dist/ are ready for publication to an internal or public Python package registry. CI builds both artifacts after running lint, type checking, and tests.