Metadata-Version: 2.4
Name: honornet-sdk
Version: 0.2.0
Summary: Merchant SDK for the HonorNet agent-transaction acceptance network
Project-URL: Homepage, https://honornet.ai/
Project-URL: Repository, https://honornet.ai/
Author-email: HonorNet <opensource@honornet.ai>
License: Apache-2.0
License-File: LICENSE
Keywords: agent,authorization,honornet,merchant,payments,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: honornet-verify>=1.1.0
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: fastapi>=0.110; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.110; extra == 'fastapi'
Description-Content-Type: text/markdown

# honornet-sdk

The Python merchant SDK for the [HonorNet](https://honornet.ai/) 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

```python
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

```python
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:

```python
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](examples/fastapi-middleware/).

## Licence

Apache-2.0.
