# AOTrust API (api.aotrust.link)
> REST + MCP API for cryptographic notarization. Issues 239-byte Ed25519-signed
> PDRs (Provenance Data Records) anchored hourly in a cumulative Merkle log on NEAR Mainnet
> (append-only; RFC 9162 inclusion & consistency proofs).
> x402 payment: $0.01 USDC per PDR — Base (EIP-3009) or Solana (USDC-SPL via MCP,
> X402_SOLANA). HTTP /notarize: Base-only. Free tier: 5/24h per IP.
## Endpoints
- [POST /notarize](https://api.aotrust.link/notarize): Issue a PDR. 402 response carries payment terms.
- [GET /openapi.json](https://api.aotrust.link/openapi.json): OpenAPI 3.0.3 spec.
- [POST /v1/attest/time](https://api.aotrust.link/v1/attest/time): Signed time attestation ($0.002, x402). Body: {"payload_hash":"<sha256 hex>"} (+optional nonce) → Ed25519 timestamp (AOT-TS1), leaf in the cumulative anchor log, inclusion proof.
- [POST /v1/attestation/bundle](https://api.aotrust.link/v1/attestation/bundle): Evidence bundle ($0.02, x402). Body: {"work_hash":"<sha256 hex>"} → PDR + anchor status + cumulative inclusion proof + verify recipe. Read-only: no new PDR.
- [POST /mcp](https://api.aotrust.link/mcp): Model Context Protocol (streamable-http).
- [GET /.well-known/x402](https://api.aotrust.link/.well-known/x402): x402 capability manifest (x402 v2, Bazaar extension, per-resource schemas).
- [GET /.well-known/jwks.json](https://api.aotrust.link/.well-known/jwks.json): notary Ed25519 verification key (RFC 7517, kid = RFC 7638 thumbprint).
- [GET /.well-known/did.json](https://api.aotrust.link/.well-known/did.json): did:web document for the same key.
- [POST /v1/verify/hash](https://api.aotrust.link/v1/verify/hash): FREE registry check by SHA-256 — first registration date (ISO), record id, registration count, anchor status. No PII, no keys, 30/h per IP.
- [POST /v1/verify/file](https://api.aotrust.link/v1/verify/file): same check for raw bytes (`application/octet-stream`, <=32 MB), hashed streamed server-side. In the browser the file never leaves the device (verify.aotrust.link hashes locally).
> Canonical semantics: the first registration of a fingerprint is fixed; every later proof of the same file is marked `reaffirmation` (free, quota-free) and never outranks the first.
- [Bilateral PDR spec (v0x04)](https://docs.aotrust.link/bilateral.html): binding hash, 239-byte layout, offline verifier, live test vector.
- [Transparency log](https://docs.aotrust.link/transparency.html): latest cumulative anchor + in-browser RFC 9162 inclusion/consistency verification.
- [Verifiable security receipts](https://docs.aotrust.link/patched.html): "prove you patched it" — patch/rotate/scan evidence for audits, NIS2/DORA context, insurance questionnaires.
- [Anchor API](https://api.aotrust.link/v1/anchor/status): `/v1/anchor/status`, `/v1/anchor/proof/{seq}`, `/v1/anchor/consistency?from=&to=` (public, CORS *).
- [GET /v1/pdr/verify/{pdr_b64}](https://docs.aotrust.link/api): Verify a PDR (public).
- [POST /v1/shield/free](https://api.aotrust.link/v1/shield/free): FREE notarization — no wallet, no API key. Body: {"work_hash":"<sha256 hex>"} → 200 with pdr_b64 + shield_id. Quota: 5 per 24h per IP. When the quota is exhausted (HTTP 429) the response includes an `upgrade` block: paid PDR $0.01 (no quota) via /notarize (x402), evidence bundle $0.02, signed time $0.002. Every notarization — free or paid — gets a leaf in the hourly cumulative Merkle log on NEAR, with an RFC 9162 inclusion proof. Paid adds no extra anchoring; it removes the free-tier quota ($0.01 x402).
- [POST /v1/shield/transfer](https://api.aotrust.link/v1/shield/transfer): Pay-by-transfer claim — $0.10 USDC on Base by a plain transfer (no signature, no wallet warning). Body: {"tx_hash":"0x…64 hex","work_hash":"<sha256 hex>"} → 200 with pdr_b64, shield id, payer and confirmations. Checks on-chain: USDC transfer to the AOTrust address, amount ≥ 0.10, ≥2 confirmations, block younger than 24 h. One payment = one receipt; repeating the same file returns the same receipt (Idempotency-Replayed), another file gets 409 ALREADY_USED. Same handler on the product host: POST https://shield.aotrust.link/api/pay/claim.
- [GET /v1/pdr/by-tx/{tx}](https://api.aotrust.link/v1/pdr/by-tx/{tx}): idempotent lookup of the PDR that a payment transaction issued.
- [GET /v1/pdr/{job_id}](https://api.aotrust.link/v1/pdr/{job_id}): fetch a PDR by the job id returned from /notarize.
- [GET /v1/status/{job_id}](https://api.aotrust.link/v1/status/{job_id}): processing status for a job id.
- [GET /v1/notary/pubkey](https://api.aotrust.link/v1/notary/pubkey): current notary Ed25519 public key (issuer id included).
- [GET /v1/notarize/quote](https://api.aotrust.link/v1/notarize/quote): price quote for the current tariff.
- [POST /v1/notarize](https://api.aotrust.link/v1/notarize): PDR via partner API key (X-Api-Key) + tx_hash. No self-serve keys — prefer /notarize (x402, no key) or /v1/shield/free (free).
## Pricing
> GET /menu — live tool list with prices (one request = the whole price list)
## x402 discovery (agent-native)
> Protocol: x402 v2. The 402 challenge is returned in the `PAYMENT-REQUIRED` header
> (base64 JSON, includes `extensions.bazaar` with input/output schemas) and the v1
> body (for legacy clients). Networks: `eip155:8453` (Base USDC), and
> `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` via MCP.
- Listed in the facilitator Bazaar catalog (payai): https://facilitator.payai.network/discovery/resources
- Standard clients: any x402 SDK 2.x client (e.g. `x402HttpxClient` + `EthAccountSigner`) can pay without an account or API key.
- Flow: POST /notarize → 402 → sign EIP-3009 authorization for the quoted `accepts[0]` → retry with `PAYMENT-SIGNATURE` → 200 with `pdr_b64`.
- Free probe before paying: `GET /v1/pdr/verify/{pdr_b64}` on any PDR you receive verifies offline-style; `/v1/shield/free` gives one free PDR per IP per window.
## Identity
- Publisher: notary-node.near (NEAR Mainnet)
- MCP Registry: link.aotrust/notary (published, active)