Metadata-Version: 2.4
Name: khotem
Version: 0.2.0
Summary: Cryptographic witness for AI agents — receipts, halo-compatible witness, daily Bitcoin anchor. Paid per call via x402 (USDC on Base).
Author: KHOTEM
License: Apache-2.0
Project-URL: Homepage, https://khotem.com
Project-URL: Docs, https://khotem.com/docs
Project-URL: MCP, https://khotem.com/mcp
Keywords: x402,ai-agents,receipts,ed25519,opentimestamps,witness,halo-record
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# khotem

Thin zero-dependency client for **KHOTEM** — cryptographic witness for AI agents
(<https://khotem.com>). Paid per call via x402 (USDC on Base). Python ≥ 3.9, stdlib only.

This package **never** asks for seeds or private keys. Paid calls are signed/settled by
*your* wallet through the x402 flow — see <https://khotem.com/docs/pay-x402>.

## Install

```bash
pip install khotem
```

## Free surfaces ($0, no key)

```python
import khotem

khotem.status()          # service pulse: seals, paid_calls, ledger size
khotem.catalog()         # x402 catalog (endpoints + prices)
khotem.receipt_check(ref)  # is this receipt/ref in the KHOTEM ledger? + Base on-chain fallback
khotem.anchor()          # daily Bitcoin anchor (OpenTimestamps) of the ledger chain tip
```

## Neutral witness (halo-record compatible)

Works with the open-source [`halo-record`](https://github.com/bkuan001/halo-record)
client — point it at `https://khotem.com/api/witness` with any bearer key:

```python
import khotem, hashlib

receipt = khotem.witness_anchor(
    key="your-witness-key",          # any string 8..128 chars; first use binds it to your subject+chain_root
    subject="my-agent-run",
    count=1,
    head=hashlib.sha256(b"head").hexdigest(),
    chain_root=hashlib.sha256(b"root").hexdigest(),
)

# offline verification, no network, no deps:
assert khotem.verify_witness_receipt(receipt) is True

# fetch checkpoints back (CORS-open):
cps = khotem.witness_checkpoints(subject="my-agent-run")
```

Every witness receipt is Ed25519-signed (public key: `khotem.witness_pubkey()`) and the
witness log rides the daily Bitcoin anchor — `khotem.anchor()`.

## Paid calls

```python
resp = khotem.call("/api/seal", method="POST", body={"data": "..."})
# HTTP 402 -> x402 payment required; settle with your wallet, retry with X-Payment.
```

## Security

- Never send us your private keys. We never ask.
- Report issues: <https://khotem.com/.well-known/security.txt>
