{"openapi":"3.0.3","info":{"title":"AOTrust \u2014 Agent Notary Service","description":"Machine contract for AOTrust notarization (2026.10.24).\n\nPaid paths use x402: an unauthenticated request gets HTTP 402 with the\n`PAYMENT-REQUIRED` header (v2, base64 JSON) and a v1 body\n`{x402Version, accepts[], error}`; the client retries with `X-PAYMENT`\n(base64 JSON PaymentPayload v1 or v2). A settlement that the facilitator\nreports successful is checked against the Base receipt before a PDR is\nissued (502 PAYMENT_UNCONFIRMED if the chain disagrees).\n\n`\/shield` (FreelanceShield, $0.10) lives on the shield host, not on the\napi host. `\/menu` and the MCP transport live on the api host (MCP server).\n","version":"2026.11.10","contact":{"name":"A&O Trust Layer","url":"https:\/\/docs.aotrust.link"}},"servers":[{"url":"https:\/\/api.aotrust.link","description":"Production API + MCP (mainnet)"},{"url":"https:\/\/shield.aotrust.link","description":"FreelanceShield host (\/shield only)"}],"security":[],"tags":[{"name":"Notarization"},{"name":"TimeAttestation"},{"name":"Evidence"},{"name":"Shield"},{"name":"Verification"},{"name":"Anchor"},{"name":"Discovery"},{"name":"Partner"}],"paths":{"\/notarize":{"post":{"summary":"x402 paid notarization ($0.01 \/ 10000 micro-USDC, Base)","description":"Discovery-first: no `X-PAYMENT` \u2192 402 challenge (header + v1 body).\nWith payment: verify \u2192 settle \u2192 on-chain receipt check \u2192 PDR.\n","operationId":"notarizePaid","tags":["Notarization"],"security":[],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/NotarizeRequest"}}}},"responses":{"200":{"description":"Signed PDR","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/NotarizeResponse"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"402":{"$ref":"#\/components\/responses\/PaymentRequired"},"422":{"description":"INVALID_AGENT_SIGNATURE \u2014 bilateral sig_A does not match agent_pubkey","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"METHOD_NOT_ALLOWED \u2014 POST only (Allow: POST, OPTIONS)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"502":{"description":"PAYMENT_UNCONFIRMED \u2014 facilitator said success but Base receipt disagrees","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/v1\/shield\/transfer":{"post":{"summary":"Pay by transfer \u2014 claim a plain Base USDC transfer ($0.10)","description":"Read-only chain check, then an atomic claim and the same PDR mint as\n`\/shield` (payment_anchor_type 0x05). Minimum 2 confirmations; the\ntransfer must be to payTo, in USDC, at least 100000 micro-USDC, and not\nolder than 24h. Every error has `reason` and `next_step`.\n","tags":["Shield"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TransferClaimRequest"}}}},"responses":{"200":{"description":"Shielded PDR (replays carry Idempotency-Replayed true)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TransferClaimResponse"}}}},"400":{"description":"BAD_RAIL \/ INVALID_TX_HASH \/ INVALID_WORK_HASH \/ BAD_REQUEST"},"409":{"description":"ALREADY_USED \/ IN_PROGRESS"},"413":{"description":"PAYLOAD_TOO_LARGE (body > 4 KB)"},"422":{"description":"TOO_OLD \/ WRONG_ASSET \/ WRONG_RECIPIENT \/ WRONG_AMOUNT \/ INVALID_AGENT_SIGNATURE"},"425":{"description":"PENDING (retry_after 5)"},"429":{"description":"RATE_LIMITED (10\/hour per IP)"},"503":{"description":"RPC_UNAVAILABLE (retry_after 10; no DB row written)"}}}},"\/v1\/attestation\/bundle":{"post":{"summary":"Evidence bundle ($0.02 \/ 20000 micro-USDC, Base)","description":"Read-only evidence pack for one work_hash: PDR + anchor status +\ninclusion proof + verify recipe. Never creates a PDR. Lookup happens\nbefore payment (404 NOT_FOUND is not charged). By default the EARLIEST\nissuance is returned; `seq` selects a concrete issuance.\n","operationId":"attestationBundle","tags":["Evidence"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/BundleRequest"}}}},"responses":{"200":{"description":"Evidence pack","headers":{"X-PAYMENT-RESPONSE":{"$ref":"#\/components\/headers\/PaymentResponseHeader"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/BundleResponse"}}}},"400":{"description":"INVALID_SEQ \/ SEQ_HASH_MISMATCH \/ BAD_REQUEST","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"402":{"$ref":"#\/components\/responses\/PaymentRequired"},"404":{"description":"NOT_FOUND \u2014 no PDR for this work_hash (not charged)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"405":{"description":"Method not allowed (POST only)"}}}},"\/v1\/attest\/time":{"post":{"summary":"Signed time attestation ($0.002 \/ 2000 micro-USDC, Base)","description":"Signs AOT-TS1 || u64be(ts) || payload_hash || nonce with the notary key\nand appends a kind=1 leaf to the cumulative anchor log. Phase B only\n(ANCHOR_LOG_READS=1); otherwise 404.\n","operationId":"attestTime","tags":["TimeAttestation"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TimeRequest"}}}},"responses":{"200":{"description":"Time attestation","headers":{"X-PAYMENT-RESPONSE":{"$ref":"#\/components\/headers\/PaymentResponseHeader"}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TimeAttestation"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"402":{"$ref":"#\/components\/responses\/PaymentRequired"},"404":{"description":"NOT_FOUND \u2014 time attestation is disabled (Phase A)"},"405":{"description":"METHOD_NOT_ALLOWED \u2014 POST only (Allow: POST, OPTIONS)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"502":{"description":"PAYMENT_UNCONFIRMED"}}}},"\/shield":{"post":{"summary":"FreelanceShield paid pack ($0.10 \/ 100000 micro-USDC, Base)","description":"PDF-pack shield for humans. Available ONLY on shield.aotrust.link.","operationId":"shieldPaid","tags":["Shield"],"servers":[{"url":"https:\/\/shield.aotrust.link","description":"Shield host"}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ShieldPaidRequest"}}}},"responses":{"200":{"description":"Shielded PDR","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ShieldPaidResponse"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"402":{"$ref":"#\/components\/responses\/PaymentRequired"},"405":{"description":"METHOD_NOT_ALLOWED \u2014 POST only (Allow: POST, OPTIONS)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"308":{"description":"Redirect to the shield host (method and body preserved)","headers":{"Location":{"description":"https:\/\/shield.aotrust.link\/shield","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string","example":"public, max-age=3600"}}}},"502":{"description":"PAYMENT_UNCONFIRMED"}}}},"\/v1\/shield\/free":{"post":{"summary":"Free UNPAID PDR (dual-mode work_hash or content)","description":"Free tier: 5\/24h per IP (IPv6 by \/64), CI 50\/24h with X-Api-Key,\nmarket 100\/24h, global 1000\/day. Replay within 24h (same work_hash +\nIP) returns the original PDR with already_exists=true.\n","operationId":"shieldFree","tags":["Shield"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ShieldFreeRequest"}}}},"responses":{"200":{"description":"Free PDR","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ShieldFreeResult"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"413":{"description":"PAYLOAD_TOO_LARGE \u2014 content > 60KB"},"422":{"description":"INVALID_AGENT_SIGNATURE"},"429":{"description":"FREE_TIER_LIMIT_REACHED \/ MARKET_TIER_LIMIT_REACHED \/ CI_TIER_LIMIT_REACHED \/ global pool exhausted","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/v1\/shield\/lookup\/{shield_id}":{"get":{"summary":"Find a PDR by 8-hex Shield ID","operationId":"shieldLookup","tags":["Shield"],"parameters":[{"name":"shield_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-fA-F]{8}$"}}],"responses":{"200":{"description":"Found","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ShieldLookupResult"}}}},"400":{"description":"INVALID_SHIELD_ID \u2014 or PLACEHOLDER_IN_PATH when the URL still contains {shield_id}"},"404":{"description":"Shield ID not found"},"409":{"description":"SHIELD_ID_AMBIGUOUS \u2014 legacy rows share this 8-hex id; use the full tx hash","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/v1\/pdr\/verify\/{pdr_b64}":{"get":{"summary":"Verify a PDR (free, 30\/min per IP)","description":"Verifies the notary signature and, where applicable, the on-chain\npayment. `tx_verified_on_chain` is true\/false\/null; `tx_verification_note`\nexplains null\/failure reasons. Base legacy rows resolve the full tx from\nthe ledger; an invalid signature skips all RPC.\n","operationId":"verifyPdr","tags":["Verification"],"parameters":[{"name":"pdr_b64","in":"path","required":true,"description":"External PDR base64 (URL-safe or standard, padding optional)","schema":{"type":"string"}}],"responses":{"200":{"description":"Verification result","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/VerifyResult"}}}},"400":{"description":"VERIFY_FAILED \u2014 or PLACEHOLDER_IN_PATH when the URL still contains {pdr_b64}","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"TOO_MANY_REQUESTS (30\/min per IP)"},"500":{"description":"CONFIG_ERROR \u2014 notary key unavailable"}}}},"\/v1\/pdr\/by-tx\/{tx}":{"get":{"summary":"PDR lookup by payment transaction (free, 30\/min per IP)","operationId":"pdrByTx","tags":["Verification"],"parameters":[{"name":"tx","in":"path","required":true,"description":"Base tx (`0x` + 64 hex) or Solana base58 signature","schema":{"type":"string"}}],"responses":{"200":{"description":"Found","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ByTxResult"}}}},"400":{"description":"INVALID_TX","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Not found","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/NotFound"}}}},"429":{"description":"TOO_MANY_REQUESTS"}}}},"\/v1\/receipts\/by-payer\/{address}":{"get":{"summary":"Receipts paid by a wallet (free, 30\/min per IP)","description":"Public receipts whose stored payer is this address on the selected rail.\nAmounts, transaction hashes and client details are not disclosed.\n","operationId":"receiptsByPayer","tags":["Verification"],"parameters":[{"name":"address","in":"path","required":true,"description":"Base 0x address or Solana base58 address","schema":{"type":"string"}},{"name":"network","in":"query","required":false,"schema":{"type":"string","enum":["base","solana"],"default":"base"}}],"responses":{"200":{"description":"Receipt list (empty list is 200, never 404)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ByPayerResult"}}}},"400":{"description":"INVALID_ADDRESS or INVALID_NETWORK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"TOO_MANY_REQUESTS (30\/min per IP)"}}}},"\/v1\/pdr\/{job_id}":{"get":{"summary":"Get a PDR by job_id","operationId":"pdrByJob","tags":["Verification"],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PDR","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PdrByJobResult"}}}},"404":{"description":"PDR not found"}}}},"\/v1\/status\/{job_id}":{"get":{"summary":"Job status plus PDR","description":"Alias of the legacy `\/v1\/notarize\/{job_id}\/status`.","operationId":"jobStatus","tags":["Verification"],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Status","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/JobStatus"}}}},"400":{"description":"PLACEHOLDER_IN_PATH \u2014 documentation template used verbatim","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"404":{"description":"Job not found","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/v1\/pdr\/settled":{"get":{"summary":"Find a SETTLED PDR by the provisional hash it supersedes","operationId":"pdrSettled","tags":["Verification"],"parameters":[{"name":"superseded_by_hash","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Found or not found"},"400":{"description":"Missing query parameter"}}}},"\/v1\/anchor\/status":{"get":{"summary":"Cumulative anchor status","operationId":"anchorStatus","tags":["Anchor"],"responses":{"200":{"description":"Status","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AnchorStatus"}}}},"429":{"description":"TOO_MANY_REQUESTS (120\/min per IP)"}}}},"\/v1\/anchor\/proof\/{seq}":{"get":{"summary":"RFC 9162 inclusion proof for a ledger seq in the cumulative tree","operationId":"anchorProof","tags":["Anchor"],"parameters":[{"name":"seq","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Inclusion proof (server self-checked against the committed root)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AnchorProof"}}}},"400":{"description":"INVALID_SEQ"},"404":{"description":"NOT_FOUND \/ NOT_A_LEAF"},"409":{"description":"NO_CUMULATIVE_ANCHOR \/ NOT_YET_ANCHORED (eta_seconds, recheck_url)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AnchorPending"}}}},"429":{"description":"TOO_MANY_REQUESTS"},"500":{"description":"ANCHOR_DATA_INCONSISTENT"}}}},"\/v1\/anchor\/logproof\/{log_index}":{"get":{"summary":"Inclusion proof by opaque cumulative log_index (Phase B)","description":"Phase B only (ANCHOR_LOG_READS=1); 404 when disabled.","operationId":"anchorLogProof","tags":["Anchor"],"parameters":[{"name":"log_index","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Inclusion proof (kind 0 = PDR leaf, kind 1 = time leaf)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AnchorLogProof"}}}},"400":{"description":"INVALID_INDEX"},"404":{"description":"NOT_FOUND (or Phase B disabled)"},"409":{"description":"NO_CUMULATIVE_ANCHOR \/ NOT_YET_ANCHORED"},"500":{"description":"ANCHOR_DATA_INCONSISTENT"}}}},"\/v1\/anchor\/consistency":{"get":{"summary":"RFC 9162 consistency proof between two committed anchors","operationId":"anchorConsistency","tags":["Anchor"],"parameters":[{"name":"from","in":"query","required":true,"schema":{"type":"integer"}},{"name":"to","in":"query","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Consistency proof (server self-checked)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AnchorConsistency"}}}},"400":{"description":"INVALID_RANGE"},"404":{"description":"UNKNOWN_ANCHOR"},"429":{"description":"TOO_MANY_REQUESTS"},"500":{"description":"ANCHOR_DATA_INCONSISTENT"}}}},"\/v1\/verify\/hash":{"post":{"summary":"Canonical registration check by work_hash (free)","tags":["Verification"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["work_hash"],"properties":{"work_hash":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}}}}},"responses":{"200":{"description":"Registered or not","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/VerifyCanonical"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"429":{"description":"TOO_MANY_REQUESTS (30\/hour, 3\/minute)"}}}},"\/v1\/verify\/file":{"post":{"summary":"Canonical registration check by raw file body (streamed SHA-256)","tags":["Verification"],"requestBody":{"required":true,"content":{"application\/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"Registered or not","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/VerifyCanonical"}}}},"400":{"description":"Empty body"},"411":{"description":"CONTENT_LENGTH required (direct access only \u2014 the public gateway buffers chunked uploads and supplies Content-Length itself)"},"413":{"description":"Body larger than 32 MiB"},"429":{"description":"TOO_MANY_REQUESTS"}}}},"\/menu":{"get":{"summary":"Live JSON price catalog (MCP host; `\/tools` is an alias)","description":"Prices are derived from the same constants as the x402 offers.","operationId":"menu","tags":["Discovery"],"responses":{"200":{"description":"Catalog","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Menu"}}}}}}},"\/health":{"get":{"summary":"Liveness check","operationId":"health","tags":["Discovery"],"responses":{"200":{"description":"Healthy","content":{"application\/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"OK"},"pid":{"type":"integer"}}}}}}}}},"\/openapi.json":{"get":{"summary":"This document","operationId":"openapiJson","tags":["Discovery"],"responses":{"200":{"description":"OpenAPI spec as JSON"}}}},"\/.well-known\/x402":{"get":{"summary":"x402 discovery alias (served at the edge)","operationId":"wellKnownX402","tags":["Discovery"],"responses":{"200":{"description":"x402 discovery document"}}}},"\/.well-known\/x402-discovery.json":{"get":{"summary":"x402 resource catalog (v2 + bazaar extension)","operationId":"wellKnownX402Discovery","tags":["Discovery"],"responses":{"200":{"description":"Catalog","content":{"application\/json":{"schema":{"type":"object","properties":{"x402Version":{"type":"integer","example":2},"name":{"type":"string"},"description":{"type":"string"},"facilitator_url":{"type":"string"},"resources":{"type":"array","items":{"type":"object"}}}}}}}}}},"\/.well-known\/jwks.json":{"get":{"summary":"Notary Ed25519 public key as RFC 7517 JWKS","operationId":"wellKnownJwks","tags":["Discovery"],"responses":{"200":{"description":"JWKS","headers":{"Cache-Control":{"schema":{"type":"string","example":"public, max-age=300"}}},"content":{"application\/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"kty":{"type":"string","example":"OKP"},"crv":{"type":"string","example":"Ed25519"},"x":{"type":"string"},"kid":{"type":"string"},"alg":{"type":"string","example":"EdDSA"},"use":{"type":"string","example":"sig"}}}}}}}}},"500":{"description":"CONFIG_ERROR \u2014 NOTARY_SEED unavailable"}}}},"\/.well-known\/did.json":{"get":{"summary":"Notary public key as a did:web document","operationId":"wellKnownDid","tags":["Discovery"],"responses":{"200":{"description":"DID document","content":{"application\/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"verificationMethod":{"type":"array","items":{"type":"object"}}}}}}}}}},"\/v1\/notary\/pubkey":{"get":{"summary":"Notary public key","operationId":"notaryPubkey","tags":["Discovery"],"responses":{"200":{"description":"Public key","content":{"application\/json":{"schema":{"type":"object","properties":{"pubkey_hex":{"type":"string"},"issuer_id":{"type":"string"},"kid":{"type":"string"},"alg":{"type":"string","example":"EdDSA"}}}}}}}}},"\/v1\/shield\/direct":{"post":{"summary":"RETIRED \u2014 direct USDC transfer (deprecated)","description":"Removed 2026-10-24 (W1-05): no payer binding and swallowed write\nerrors. Every request returns 410 without reading the body.\n","operationId":"shieldDirectDeprecated","deprecated":true,"tags":["Shield"],"responses":{"410":{"description":"DIRECT_TRANSFER_DEPRECATED","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/v1\/notarize":{"post":{"summary":"Partner rail (X-Api-Key + tx_hash)","operationId":"notarizePartner","tags":["Partner"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["tx_hash"],"properties":{"tx_hash":{"type":"string"},"work_hash":{"type":"string"},"payload":{"type":"object"},"agent_sig":{"type":"string"},"agent_pubkey":{"type":"string"},"signing_mode":{"type":"string","enum":["raw_sha256","nep413"]}}}}}},"responses":{"202":{"description":"Accepted (async worker)","content":{"application\/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"}}}}}},"400":{"description":"Invalid or missing tx_hash \/ signing_mode"},"401":{"description":"UNAUTHORIZED"},"402":{"description":"PAYMENT_REQUIRED \u2014 payment gate rejected the tx"},"409":{"description":"Conflict"},"429":{"description":"TOO_MANY_REQUESTS"}}}},"\/v1\/notarize\/quote":{"post":{"summary":"Partner rail price quote","operationId":"notarizeQuote","tags":["Partner"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Quote","content":{"application\/json":{"schema":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid"},"amount":{"type":"string","example":"0.1"}}}}}},"401":{"description":"UNAUTHORIZED"}}}}},"components":{"securitySchemes":{"x402":{"type":"apiKey","in":"header","name":"X-PAYMENT","description":"x402 **v1** payment header (base64 JSON). v2 clients send the same\npayload in `PAYMENT-SIGNATURE`; the server accepts both. v2 clients\nshould read the `PAYMENT-REQUIRED` response header first.\n"},"x402v2":{"type":"apiKey","in":"header","name":"PAYMENT-SIGNATURE","description":"x402 **v2** payment header (base64 JSON). `X-PAYMENT` is the v1 name;\nboth are accepted. Successful paid responses carry both\n`X-PAYMENT-RESPONSE` and `PAYMENT-RESPONSE` (same base64 receipt).\n"},"apiKey":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Partner rail only; self-serve keys do not exist."}},"headers":{"PaymentResponseHeader":{"description":"Base64 JSON settlement receipt (success, network, payer, transaction)","schema":{"type":"string"}},"PaymentResponseHeaderV2":{"description":"Same value as X-PAYMENT-RESPONSE, under the x402 v2 header name","schema":{"type":"string"}}},"responses":{"BadRequest":{"description":"BAD_REQUEST \/ INVALID_WORK_HASH \/ INVALID_PARAM","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"PaymentRequired":{"description":"Payment required. v2 terms are in the `PAYMENT-REQUIRED` header\n(base64 JSON); the v1 body is `{x402Version, accepts[], error}`.\n","headers":{"PAYMENT-REQUIRED":{"description":"Base64 JSON PaymentRequired v2 (`x402Version`, `resource`, `accepts[]`)","schema":{"type":"string"}}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PaymentRequired"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"detail":{"type":"string"},"tx_hash":{"type":"string"},"retry_after":{"type":"integer"}}},"NotFound":{"type":"object","properties":{"found":{"type":"boolean","example":false}}},"PaymentRequired":{"type":"object","required":["x402Version","accepts"],"properties":{"x402Version":{"type":"integer","enum":[1,2]},"error":{"type":"string","example":"Payment required"},"accepts":{"type":"array","items":{"$ref":"#\/components\/schemas\/PaymentRequirements"}}}},"PaymentRequirements":{"type":"object","required":["scheme","network","asset","amount","payTo","maxTimeoutSeconds"],"properties":{"scheme":{"type":"string","example":"exact"},"network":{"type":"string","example":"eip155:8453"},"asset":{"type":"string","example":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},"amount":{"type":"string","description":"micro-USDC (6 decimals)","example":"10000"},"maxAmountRequired":{"type":"string","description":"v1 alias of `amount`"},"payTo":{"type":"string","example":"0x97E9af6B4d8a49f509DA99afaB954429Ab8Cc800"},"maxTimeoutSeconds":{"type":"integer","example":300},"resource":{"type":"string"},"description":{"type":"string"},"mimeType":{"type":"string"},"extra":{"type":"object","properties":{"name":{"type":"string","example":"USD Coin"},"version":{"type":"string","example":"2"}}},"outputSchema":{"type":"object"}}},"PaymentResponse":{"type":"object","properties":{"success":{"type":"boolean"},"network":{"type":"string"},"payer":{"type":"string"},"transaction":{"type":"string"}}},"NotarizeRequest":{"type":"object","required":["work_hash"],"properties":{"work_hash":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"agent_pubkey":{"type":"string","description":"Optional bilateral (v0x04) agent key (hex)"},"agent_sig":{"type":"string","description":"Optional bilateral Ed25519 signature (base64) over work_hash"},"prev_work_hash":{"type":"string","description":"Optional 64-hex previous version (must already exist)"}}},"NotarizeResponse":{"type":"object","required":["status","job_id","pdr_b64","tx_hash"],"properties":{"status":{"type":"string","example":"notarized"},"job_id":{"type":"string","format":"uuid"},"pdr_b64":{"type":"string","description":"External PDR, 239 bytes, base64"},"tx_hash":{"type":"string"},"payment_hash":{"type":"string","description":"Full 32B payment hash (hex, no 0x), same value as the PDR slot"},"work_hash":{"type":"string"},"payment_anchor_type":{"type":"string","example":"X402_BASE"},"network":{"type":"string","example":"eip155:8453"},"payment_unverified":{"type":"boolean","description":"Present and true only when the on-chain receipt check was unavailable"},"registration_role":{"type":"string","enum":["first","reaffirmation"]},"first_seen_at":{"type":"integer"},"first_seen_at_iso":{"type":"string","example":"2026-11-05T10:00:00Z"},"first_pdr_id":{"type":"string","example":"1e2f1f30","description":"shield id of the canonical (first) record; work_hash prefix when the record carries no payment reference"},"registrations":{"type":"integer"}}},"ShieldPaidRequest":{"type":"object","required":["work_hash"],"properties":{"work_hash":{"type":"string"},"agent_pubkey":{"type":"string"},"agent_sig":{"type":"string"}}},"ShieldPaidResponse":{"type":"object","properties":{"status":{"type":"string","example":"shielded"},"job_id":{"type":"string","format":"uuid"},"pdr_b64":{"type":"string"},"tx_hash":{"type":"string"},"payment_hash":{"type":"string"},"payment_anchor_type":{"type":"string","example":"X402_BASE"},"network":{"type":"string"},"payment_unverified":{"type":"boolean"}}},"BundleRequest":{"type":"object","required":["work_hash"],"properties":{"work_hash":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"seq":{"type":"integer","description":"Optional issuance selector; default = earliest issuance"}}},"PdrBundle":{"type":"object","properties":{"work_hash":{"type":"string"},"seq":{"type":"integer"},"picked":{"type":"string","enum":["earliest","requested"]},"selection":{"type":"string","example":"order by created_at ASC, global_seq ASC"},"issuance_count":{"type":"integer"},"first_seq":{"type":"integer","nullable":true},"issuances":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"integer"},"created_at_ns":{"type":"integer"},"status":{"type":"string"},"payment_anchor_type":{"type":"integer"}}}},"shield_id":{"type":"string"},"pdr_b64":{"type":"string"},"pdr_version":{"type":"string","example":"0x03"},"payment_hash":{"type":"string","description":"Full 32B payment hash (Base 64 hex \/ Solana domain hash)"}}},"BundleResponse":{"allOf":[{"$ref":"#\/components\/schemas\/PdrBundle"},{"type":"object","properties":{"anchor":{"$ref":"#\/components\/schemas\/AnchorBlock"},"verify":{"$ref":"#\/components\/schemas\/VerifyRecipe"},"payment_unverified":{"type":"boolean"}}}]},"TransferClaimRequest":{"type":"object","required":["tx_hash","work_hash"],"properties":{"tx_hash":{"type":"string","pattern":"^0x[0-9a-fA-F]{64}$"},"work_hash":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"rail":{"type":"string","enum":["transfer"]},"agent_sig":{"type":"string"},"agent_pubkey":{"type":"string"}}},"TransferClaimResponse":{"type":"object","properties":{"status":{"type":"string","example":"shielded"},"rail":{"type":"string","example":"transfer"},"job_id":{"type":"string","format":"uuid"},"pdr_b64":{"type":"string"},"tx_hash":{"type":"string"},"payment_hash":{"type":"string"},"payment_anchor_type":{"type":"string","example":"X402_BASE"},"network":{"type":"string","example":"Base Mainnet"},"payer":{"type":"string"},"amount_usdc":{"type":"string","example":"0.10"},"confirmations":{"type":"integer","nullable":true},"registration":{"type":"object"}}},"VerifyCanonical":{"type":"object","properties":{"registered":{"type":"boolean"},"first_seen_at":{"type":"integer","description":"Unix seconds"},"first_seen_at_iso":{"type":"string","example":"2026-11-05T10:00:00Z"},"first_pdr_id":{"type":"string","example":"1e2f1f30","description":"shield id of the canonical (first) record; work_hash prefix when the record carries no payment reference"},"registrations":{"type":"integer"},"anchored":{"type":"boolean"},"verify_url":{"type":"string"},"previous_version":{"type":"string","nullable":true,"description":"Previous artifact version recorded in the CANONICAL (first) record; null if no chain."},"payer":{"type":"string","nullable":true},"payer_network":{"type":"string","enum":["base","solana"]},"payer_source":{"type":"string","nullable":true,"enum":["transfer_log","fee_payer","claimed"]},"payer_url":{"type":"string"}}},"LineageEntry":{"type":"object","properties":{"seq":{"type":"integer"},"ts_utc":{"type":"integer"},"class":{"type":"string","enum":["paid","signed","unsigned_free"]},"standing":{"type":"string","enum":["FIRST_ELIGIBLE","ELIGIBLE_LATER","NO_CLAIM"]},"shield_id":{"type":"string"}}},"Lineage":{"type":"object","description":"Submission facts only (existence\/order\/integrity), NOT authorship.\nService metadata: not inside the 239-byte PDR and not anchored.\n","properties":{"this_record":{"allOf":[{"$ref":"#\/components\/schemas\/LineageEntry"},{"type":"object","required":["standing"]}]},"first_record":{"$ref":"#\/components\/schemas\/LineageEntry"},"first_eligible":{"allOf":[{"$ref":"#\/components\/schemas\/LineageEntry"}],"nullable":true},"total_records":{"type":"integer"}}},"VerifyRecipe":{"type":"object","properties":{"jwks":{"type":"string"},"server_url":{"type":"string"},"did":{"type":"string"},"offline":{"type":"string"}}},"AnchorBlock":{"type":"object","properties":{"mode":{"type":"string","enum":["cumulative","batch","pending"]},"anchor_seq":{"type":"integer","nullable":true},"size":{"type":"integer","nullable":true},"root":{"type":"string","nullable":true},"near_tx":{"type":"string","nullable":true},"index":{"type":"integer","nullable":true},"path":{"type":"array","items":{"type":"string"}},"eta_seconds":{"type":"integer"},"recheck_url":{"type":"string"}}},"TimeRequest":{"type":"object","required":["payload_hash"],"properties":{"payload_hash":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"nonce":{"type":"string","pattern":"^[0-9a-fA-F]{32}$","description":"Optional 16-byte nonce (hex); random when omitted"}}},"TimeAttestation":{"type":"object","required":["id","ts","payload_hash","sig_b64","leaf","log_index"],"properties":{"id":{"type":"integer"},"ts":{"type":"integer","description":"Unix seconds (safe for JSON.parse; >2^53 values are NOT sent as numbers)"},"ts_ns":{"type":"string","description":"Exact nanoseconds as a decimal string"},"ts_iso":{"type":"string"},"payload_hash":{"type":"string"},"nonce":{"type":"string"},"kid":{"type":"string"},"alg":{"type":"string","example":"Ed25519"},"sig_b64":{"type":"string"},"leaf":{"type":"string"},"log_index":{"type":"integer"},"payment_unverified":{"type":"boolean"},"verify":{"$ref":"#\/components\/schemas\/VerifyRecipe"},"anchor":{"$ref":"#\/components\/schemas\/AnchorBlock"}}},"ShieldFreeRequest":{"type":"object","description":"Exactly one of work_hash \/ content.","properties":{"work_hash":{"type":"string"},"content":{"type":"string","maxLength":61440},"agent_pubkey":{"type":"string"},"agent_sig":{"type":"string"},"reaffirm":{"type":"boolean","description":"Create a new timestamped PDR instead of replaying"},"metadata":{"type":"string"}}},"ShieldFreeResult":{"type":"object","required":["status","job_id","work_hash","shield_id","pdr_b64"],"properties":{"status":{"type":"string","example":"shielded"},"job_id":{"type":"string","format":"uuid"},"work_hash":{"type":"string"},"hash_source":{"type":"string","enum":["client","server"]},"verify_url":{"type":"string"},"pdr_b64":{"type":"string"},"shield_id":{"type":"string"},"payment_anchor_type":{"type":"string","example":"UNPAID"},"tier":{"type":"string","example":"free"},"provenance":{"type":"object","properties":{"first_seen":{"type":"string","nullable":true},"total":{"type":"integer"}}},"lineage":{"$ref":"#\/components\/schemas\/Lineage"},"already_exists":{"type":"boolean"},"reaffirm_hint":{"type":"string"}}},"ShieldLookupResult":{"type":"object","properties":{"found":{"type":"boolean"},"pdr_b64":{"type":"string"},"shield_id":{"type":"string"},"payment_hash":{"type":"string"},"work_hash":{"type":"string","description":"Artifact SHA-256 from the journal"},"timestamp_utc":{"type":"integer"},"near_anchor_tx":{"type":"string","nullable":true},"file_name":{"type":"string","nullable":true},"author_name":{"type":"string","nullable":true},"lineage":{"$ref":"#\/components\/schemas\/Lineage"},"registration_role":{"type":"string","enum":["first","reaffirmation"]},"first_seen_at":{"type":"integer","description":"Unix seconds"},"first_seen_at_iso":{"type":"string"},"first_pdr_id":{"type":"string"},"registrations":{"type":"integer"},"payer":{"type":"string","nullable":true},"payer_network":{"type":"string","enum":["base","solana"]},"payer_source":{"type":"string","nullable":true,"enum":["transfer_log","fee_payer","claimed"]},"payer_url":{"type":"string"}}},"VerifyResult":{"type":"object","required":["valid","signature_valid"],"properties":{"valid":{"type":"boolean"},"version":{"type":"integer"},"payment_anchor_type":{"type":"string"},"work_hash":{"type":"string","nullable":true,"description":"Artifact SHA-256 from the ledger; null for v0x04 when it cannot be re-derived."},"subject_hash":{"type":"string"},"payload_hash":{"type":"string"},"binding_hash":{"type":"boolean"},"timestamp_utc":{"type":"integer"},"issuer_id":{"type":"string"},"merkle_root":{"type":"string"},"payment_hash":{"type":"string"},"signature_valid":{"type":"boolean"},"tx_verified_on_chain":{"type":"boolean","nullable":true},"tx_verified_cached":{"type":"boolean"},"tx_verification_note":{"type":"string","description":"Populated when the on-chain check was skipped or unavailable"},"near_anchor_tx":{"type":"string","nullable":true},"merkle_proof":{"type":"array","items":{"type":"string"}},"merkle_index":{"type":"integer"},"merkle_tree_size":{"type":"integer"},"merkle_leaf":{"type":"string"},"note":{"type":"string"},"lineage":{"$ref":"#\/components\/schemas\/Lineage"},"payer":{"type":"string","nullable":true},"payer_network":{"type":"string","enum":["base","solana"]},"payer_source":{"type":"string","nullable":true,"enum":["transfer_log","fee_payer","claimed"]},"payer_url":{"type":"string"},"error":{"type":"string","nullable":true}}},"ByTxResult":{"type":"object","required":["found"],"properties":{"found":{"type":"boolean"},"pdr_b64":{"type":"string"},"payment_anchor_type":{"type":"integer"},"payment_hash":{"type":"string"},"work_hash":{"type":"string"},"seq":{"type":"integer"},"payer":{"type":"string","nullable":true},"payer_network":{"type":"string","enum":["base","solana"]},"payer_source":{"type":"string","nullable":true,"enum":["transfer_log","fee_payer","claimed"]},"payer_url":{"type":"string"}}},"ByPayerResult":{"type":"object","required":["address","network","count","receipts"],"properties":{"address":{"type":"string"},"network":{"type":"string","enum":["base","solana"]},"count":{"type":"integer"},"receipts":{"type":"array","items":{"type":"object","properties":{"shield_id":{"type":"string"},"work_hash":{"type":"string"},"created_at":{"type":"integer","description":"Unix seconds"},"payer_source":{"type":"string","nullable":true,"enum":["transfer_log","fee_payer","claimed"]},"verify_url":{"type":"string"}}}},"note":{"type":"string"}}},"PdrByJobResult":{"type":"object","properties":{"pdr":{"type":"string"},"payment_hash":{"type":"string"},"near_anchor_tx":{"type":"string","nullable":true}}},"JobStatus":{"type":"object","properties":{"status":{"type":"string"},"result":{"type":"object","properties":{"pdr_b64":{"type":"string"},"payment_hash":{"type":"string"},"merkle_proof":{"type":"array","items":{"type":"string"}},"near_anchor_tx":{"type":"string","nullable":true},"registration_role":{"type":"string","enum":["first","reaffirmation"]},"first_seen_at":{"type":"integer","description":"Unix seconds"},"first_seen_at_iso":{"type":"string"},"first_pdr_id":{"type":"string"},"registrations":{"type":"integer"}}}}},"AnchorStatus":{"type":"object","properties":{"mode":{"type":"string","enum":["cumulative","batch-only"]},"latest":{"type":"object","nullable":true,"properties":{"anchor_seq":{"type":"integer"},"size":{"type":"integer"},"root":{"type":"string","nullable":true},"near_tx":{"type":"string"},"ts":{"type":"integer"}}},"log_size":{"type":"integer"}}},"AnchorProof":{"type":"object","properties":{"mode":{"type":"string","example":"cumulative"},"seq":{"type":"integer"},"anchor_seq":{"type":"integer"},"size":{"type":"integer"},"root":{"type":"string"},"near_tx":{"type":"string"},"ts":{"type":"integer"},"index":{"type":"integer"},"path":{"type":"array","items":{"type":"string"}},"leaf":{"type":"string"},"how_to_verify":{"type":"string"}}},"AnchorLogProof":{"type":"object","properties":{"log_index":{"type":"integer"},"kind":{"type":"integer","description":"0 = PDR leaf, 1 = time-attestation leaf"},"ref_id":{"type":"integer"},"anchor_seq":{"type":"integer"},"size":{"type":"integer"},"root":{"type":"string"},"near_tx":{"type":"string"},"ts":{"type":"integer","description":"Unix seconds"},"ts_ns":{"type":"string","description":"Exact nanoseconds (decimal string)"},"path":{"type":"array","items":{"type":"string"}},"how_to_verify":{"type":"string"}}},"AnchorConsistency":{"type":"object","properties":{"from":{"type":"object","properties":{"anchor_seq":{"type":"integer"},"size":{"type":"integer"},"root":{"type":"string"}}},"to":{"type":"object","properties":{"anchor_seq":{"type":"integer"},"size":{"type":"integer"},"root":{"type":"string"}}},"proof":{"type":"array","items":{"type":"string"}},"how_to_verify":{"type":"string"}}},"AnchorPending":{"type":"object","properties":{"error":{"type":"string","enum":["NO_CUMULATIVE_ANCHOR","NOT_YET_ANCHORED"]},"eta_seconds":{"type":"integer"},"recheck_url":{"type":"string"}}},"Menu":{"type":"object","properties":{"provider":{"type":"string"},"updated_at":{"type":"string"},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"cost":{"type":"string"},"endpoint":{"type":"string"},"limits":{"type":"string"},"inputs":{"type":"array","items":{"type":"string"}},"rails":{"type":"array","items":{"type":"string"}},"desc":{"type":"string"}}}},"discovery":{"type":"object"}}}}}}