aere-cloud-sdk/README.md

@aere/cloud

The official client for the Aere Cloud API — one keyed endpoint for RPC, post-quantum signature verification, chain data, notarization, webhooks and gas sponsorship on Aere Network (chain 2800). Zero dependencies; runs in Node 18+ and modern browsers.

Install

The clients are installed from this repository; they are not on the npm or PyPI registries yet, and a name there that looks like ours is not ours.

npm install git+https://git.aere.network/aere-network/aere-cloud-sdk.git                          # JavaScript (@aere/cloud)
pip install "git+https://git.aere.network/aere-network/aere-cloud-sdk.git#subdirectory=python"   # Python (aere-cloud)
go get git.aere.network/aere-network/aere-cloud-sdk/go@main                                        # Go

Java: build java/ from source with the JDK alone (see java/README.md). All four clients have the same routes and semantics, and none of them follows redirects, so your API key is never sent to a host you did not name.

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

Use

import { AereCloud } from '@aere/cloud';

const aere = new AereCloud({ apiKey: process.env.AERE_KEY });

// chain data
const head = await aere.dataHead();
const anchors = await aere.anchors(5);            // post-quantum anchor certificates
const set = await aere.validators();              // live QBFT validator set

// JSON-RPC
const block = await aere.blockNumber();

// post-quantum verification, computed by the chain's own precompiles
const { valid } = await aere.pqVerify({
  scheme: 'ml-dsa-44', publicKey: '0x…', signature: '0x…', message: '0x…',
});

// notarize a document hash — Aere pays the gas
const receipt = await aere.notarize('0x' + sha256Hex);
const proof = await aere.proofOf('0x' + sha256Hex); // { notarized, firstSeenAt, … }

// 1.2.0 (2026-09-17): the proof with its post-quantum finality: first appearance from the contract log,
// the anchor that covers it, a verdict, and how to verify every claim without Aere Cloud
const full = await aere.proof('0x' + sha256Hex);    // { block, txHash, finality: 'post-quantum', pqAnchor: {…}, verify: {…} }

// quantum readiness of a domain's public TLS edge (free, no key); attest:true notarizes the report digest on chain
const scan = await aere.readiness('example.com');                    // { score, verdict, summary, findings, … }
const attested = await aere.readiness('example.com', { attest: true }); // + attestation: { reportHash, txHash, proof, … }
// the whole public perimeter of a domain (1.3.0): named hosts + common prefixes found through DNS, one report; keyed
const perimeter = await aere.readinessPerimeter('example.com', { hosts: ['api', 'mail'] });
// perimeter.summary: { measured, withoutPqKeyExchange: [...], soonestCertificateExpiry, worstScore, verdict, complete }
// while summary.complete is false, call again: finished scans are cached; { attest: true } notarizes a complete report
// the audit log of a day as a FILE (1.4.0): the exact bytes whose sha256 is the digest you notarize; format: 'cef' for a SIEM
const file = await aere.auditExport({ day: '2026-09-17' });            // file.verified === true: sha256(file.bytes) is the stated digest
const fin = await aere.pqFinality('latest', 'testnet', 'both'); // AIP-21: { finality, agreement, postQuantumConfirmedByBoth, besu: {…}, nethermind: {…} }

// pqVerify: pass interface:'external' to verify a standard FIPS 204/205 signature (the precompile implements the
// internal interface; the gateway builds M' = 0x00 || len(ctx) || ctx || message for you)
const v = await aere.pqVerify({ scheme: 'ml-dsa-44', interface: 'external', publicKey, signature, message });

// transfer history for an address (token from genesis, native from launch)
const tx = await aere.transfers('0xYourAddress', 50);

// a smart account with a POST-QUANTUM owner (Falcon-512), gas sponsored:
const acct = await aere.sponsorCreatePqAccount('0x09' + falconPkHex, 0);
// -> { txHash, account: '0x…', alreadyDeployed: false }

A Python mirror of this client lives in python/ (installed from this repository, see Install): same routes, same semantics, snake_case names. go/ and java/ carry the Go and Java clients.

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

Webhooks

Create a webhook and verify every delivery — never trust a webhook payload without checking its signature:

import { AereCloud, verifyWebhook } from '@aere/cloud';

const aere = new AereCloud({ apiKey: process.env.AERE_KEY });
const wh = await aere.createWebhook({ type: 'pq-anchors', url: 'https://you.example/hook' });
// store wh.secret now — it is shown once

// in your webhook handler (raw body, not re-serialized):
app.post('/hook', async (req, res) => {
  const ok = await verifyWebhook(req.rawBody, req.headers['x-aere-signature'], WEBHOOK_SECRET);
  if (!ok) return res.status(401).end();
  handle(JSON.parse(req.rawBody));
  res.status(200).end();
});

Webhook types: pq-anchors (every 32nd-block certificate), address-activity (transactions touching a watched address, pass watch), subscription-events (your billing events).

Reference

Full API reference and OpenAPI spec: aere.network/cloud-docs.html · live status you compute in your own browser: aere.network/cloud-status.html

MIT licensed.