honornet-sdk 0.2.0

Merchant SDK for the HonorNet agent-transaction acceptance network

honornet-sdk

The Python merchant SDK for the HonorNet acceptance network — authorize AI-agent-initiated transactions in real time.

Async-first, with a synchronous wrapper. Pure Python, no native dependencies.

Install

pip install honornet-sdk

Authorize a transaction

from honornet import Client, Money, Transaction

client = Client("https://api.honornet.ai", api_key="sk_live_...")

result = client.authorize(
    credential=agent_credential,            # presented by the agent
    transaction=Transaction(
        merchant_id="merchant_123",
        amount=Money("USD", 4999),          # integer minor units
        merchant_category_code="5732",
        country="US",
    ),
)

if result.approved:
    fulfil_order(result.authorization_code)
else:
    handle_decline(result.decline_reason)

authorize returns an AuthorizeResult for every outcome — approve, decline, or review. Call result.raise_for_decision() to turn a non-approval into a typed exception (ScopeDeclinedError, CredentialDeclinedError, …) instead.

Async

from honornet import AsyncClient

async with AsyncClient("https://api.honornet.ai") as client:
    result = await client.authorize(credential=cred, transaction=txn)

Verify a decision

Every decision is recorded in HonorNet's append-only, cryptographically verifiable log. Confirm one independently — record signature, Merkle inclusion proof, signed log root, and that the signing key is a genuine published HonorNet ledger key — with the public honornet-verify library:

from honornet import verify_decision

# Trust-anchored to the published HonorNet key-set by default.
verified = verify_decision(client, result.decision_id)
assert verified.verification.ok and verified.trust_anchored

Pass trusted_keys= to pin to a different key-set (e.g. a sandbox ledger), or trusted_keys=None for structural-only verification. Verification adds a round trip, so latency-sensitive paths skip it and verify out of band.

Built in

• Idempotency — every call carries an auto-generated idempotency key, so a retried request never creates a second decision. Override it with idempotency_key=....
• Retries — connection errors, timeouts, HTTP 429 and 5xx are retried up to three times with exponential backoff.
• Typed errors — transport failures raise HonorNet*Error; declines map to DeclinedError subclasses; DeclineReason enumerates the full taxonomy.

Framework middleware

Drop-in middleware for FastAPI lives at honornet.middleware.fastapi — see examples/fastapi-middleware.

Licence

Apache-2.0.