# aere-cloud (Python)

The official Python client for the [Aere Cloud API](https://aere.network/cloud.html) — one keyed
endpoint for RPC, post-quantum signature verification, chain data, notarization, webhooks and
gas sponsorship on Aere Network (chain 2800). Standard library only; Python 3.9+.

Mirror of the JavaScript client `@aere/cloud`: same routes, same semantics, snake_case names.

## Install

```
pip install "git+https://git.aere.network/aere-network/aere-cloud-sdk.git#subdirectory=python"   # not on PyPI yet
```

Get a key: the free trial is self-serve at [aere.network/cloud.html#subscribe](https://aere.network/cloud.html#subscribe).
A key looks like `ak2800.<your-0x-address>.<secret>`.

## Use

```python
import os
from aere_cloud import AereCloud, AereCloudError, verify_webhook

aere = AereCloud(api_key=os.environ["AERE_KEY"])

# chain data
head = aere.data_head()
anchors = aere.anchors(5)          # post-quantum anchor certificates
vals = aere.validators()           # live QBFT validator set

# JSON-RPC
n = aere.block_number()

# post-quantum verification, computed by the chain's own precompiles
out = aere.pq_verify({
    "scheme": "ml-dsa-44", "publicKey": "0x...", "signature": "0x...", "message": "0x...",
})

# notarize a document hash — Aere pays the gas
receipt = aere.notarize("0x" + sha256_hex)

# Trust API (1.6.0): any AERE Proof Protocol (AIP-23) envelope -> VALID / INVALID / PARTIAL, with the levels checked
r = aere.verify(envelope, chain=2800)   # {"verdict", "levels", "verifier", "reproduce"}
# identity and compliance (1.7.0): an AERE Identity presentation judged by the published command line; read "verdict"
idv = aere.identity_verify({"presentation": presentation, "audience": "https://your.app/verifier", "nonce": nonce, "trustedIssuers": [issuer_id]})
# payments (1.8.0): the risk step and the receipt, judged by the published module payments/; USD at the rate you declare; a REFUSE is a verdict
risk = aere.payments_risk({"policy": policy, "inputs": inputs})
receipt = aere.payments_receipt({"policy": policy, "inputs": inputs, "txHash": tx_hash})["receipt"]
check = aere.payments_verify({"receipt": receipt, "policy": policy, "inputs": inputs})
cc = aere.compliance_check({"presentation": presentation, "policy": policy, "audience": "https://your.app/verifier", "nonce": nonce, "record": True})
proof = aere.proof_of("0x" + sha256_hex)

# a smart account with a POST-QUANTUM owner (Falcon-512), gas sponsored:
acct = aere.sponsor_create_pq_account("0x09" + falcon_pk_hex, salt=0)
# -> {"txHash": ..., "account": "0x...", "alreadyDeployed": False}
```

Every method raises `AereCloudError` on a non-2xx response, carrying `.status` and the server's
JSON `.body` so you can act on the exact error.

## Proof under a post-quantum certificate, quantum readiness (1.2.0, 2026-09-17)

```python
full = aere.proof(digest_hex)            # first appearance, covering post-quantum anchor, finality, verification steps
scan = aere.readiness("example.com")     # free, no key: score, verdict, measured TLS facts, findings
attested = aere.readiness("example.com", attest=True)  # + attestation: report digest notarized on chain 2800
perimeter = aere.readiness_perimeter("example.com", hosts=["api", "mail"])  # 1.3.0: every public host of the domain, one report (keyed)
# pq_verify: {"interface": "external"} verifies a standard FIPS 204/205 signature (the precompile implements the
# internal interface; the gateway builds M' = 0x00 || len(ctx) || ctx || message)
```

## Webhooks

Never trust a webhook payload without checking its signature (constant-time, HMAC-SHA256):

```python
from aere_cloud import verify_webhook

# in your handler; raw_body must be the exact request bytes, not re-serialized JSON
if not verify_webhook(raw_body, request.headers["x-aere-signature"], stored_secret):
    return 401
```

## Tests

```
python3 test_aere_cloud.py                    # unit, offline, fake transport
AERE_KEY=ak2800... python3 test_aere_cloud.py --live   # + live probes against production
```