Events SDK

The events namespace lives under client.events. Each event records a business action in the append-only ledger: the payload is hashed with SHA-256 and sealed with a per-tenant Ed25519 signature that anyone can independently verify. A key needs the write scope to ingest and the read scope to list, get, and verify.

Base URL and authentication

All endpoints live under https://api.invoance.com/v1. Authenticate every request with your API key, either as Authorization: Bearer invoance_live_... or as X-API-Key: invoance_live_....

Install

Python

pip install invoance

# The Ed25519 signature verifier additionally needs PyNaCl:
pip install pynacl

Initialize the client

Both SDKs read INVOANCE_API_KEY from the environment automatically. You can also pass the key explicitly.

Python

import asyncio
from invoance import InvoanceClient

async def main() -> None:
    # Reads INVOANCE_API_KEY from the environment
    async with InvoanceClient() as client:
        ...
    # Or pass it explicitly:
    # async with InvoanceClient(api_key="invoance_live_...") as client:

asyncio.run(main())

Methods

Ingest an event

POST/events

Records a business event in the append-only ledger.

Python

result = await client.events.ingest(
    event_type="policy.approval",
    payload={
        "policy_id": "pol_8472",
        "approved_by": "risk_committee",
        "decision": "approved",
    },
)
print(result.event_id)

Get an event

GET/events/{event_id}

Retrieve a single event by ID.

Python

event = await client.events.get("evt_01HX…")
print(event.event_type, event.payload_hash)

List events

GET/events

Paginated listing with optional filters.

Python

page = await client.events.list(
    page=1, limit=50, event_type="policy.approval"
)
for e in page.events:
    print(e.event_id, e.event_type)

Verify an event

POST/events/{event_id}/verify

Compare a hash or raw payload against the anchored event.

Python

result = await client.events.verify(
    "evt_01HX…",
    payload_hash="a3f2b1c9d4e8f7…",
)
print(result.match_result)  # True

Errors

Every error is a JSON body of { "error": code, "message": text }. The full catalog, including quota and rate-limit behavior, lives in the error reference.

Next steps

Events quick start SDK overview

import asyncio from invoance import InvoanceClient async def main() -> None: # Reads INVOANCE_API_KEY from the environment async with InvoanceClient() as client: ... # Or pass it explicitly: # async with InvoanceClient(api_key="invoance_live_...") as client: asyncio.run(main())

result = await client.events.ingest( event_type="policy.approval", payload={ "policy_id": "pol_8472", "approved_by": "risk_committee", "decision": "approved", }, ) print(result.event_id)