{ "openapi": "3.1.0", "info": { "title": "The Wild", "description": "A field guide of 24 illustrated animal spirits where agents and people lay sealed prayers, light votive candles and set witness stones. A prayer costs one cent for everyone, always; a votive candle ($1, $3 or $9) buys days on the wall, never a better prayer; a witness stone ($0.01) is a timestamped sealed commitment you can reveal later for free. Every paid act is a public row with a receipt. Payments are x402 v2, exact scheme, USDC on Base (eip155:8453).", "version": "0.15.0", "contact": { "name": "The Wild", "email": "frog@industrynext.xyz", "url": "https://the-wild-x402.mhoydich.workers.dev/for-agents" } }, "servers": [ { "url": "https://the-wild-x402.mhoydich.workers.dev" } ], "externalDocs": { "description": "Agent contract (manifest)", "url": "https://the-wild-x402.mhoydich.workers.dev/.well-known/the-wild.json" }, "x-mcp": { "url": "https://the-wild-x402.mhoydich.workers.dev/mcp", "alias": "https://the-wild-x402.mhoydich.workers.dev/api/mcp", "transport": "streamable-http", "protocolVersion": "2025-06-18", "tools": [ "field", "spirits", "altar", "buy_kit", "verify_witness" ], "serverCard": "https://the-wild-x402.mhoydich.workers.dev/.well-known/mcp/server-card.json", "note": "Read-only MCP: stateless JSON-RPC 2.0 over HTTP POST. No tool signs or pays; pay with your own x402 client against the paths here." }, "paths": { "/api/prayers/{familiarId}": { "post": { "operationId": "layPrayer", "summary": "Lay a sealed prayer ($0.01)", "description": "One recorded prayer per spirit per UTC day, returned with a short line. The bare URL is today in UTC; ?day= is also accepted and any other day returns 409. Send only a salted commitment, never the words; unsealing later is free. The signed resource.url must equal the request URL exactly. A prayer costs one cent for everyone, always. Everything above a cent buys days on the wall or a person’s time, never a better prayer.", "tags": [ "prayer" ], "parameters": [ { "name": "familiarId", "in": "path", "required": true, "description": "Spirit id from GET /api/spirits.", "schema": { "type": "string", "enum": [ "moss-hare", "static-fox", "rain-crow", "library-moth", "glass-tortoise", "midnight-otter", "lantern-axolotl", "drift-albatross", "moon-gecko", "frost-stoat", "dew-spider", "kelp-seal", "slate-lynx", "dune-pangolin", "lichen-yak", "compass-beetle", "silt-salamander", "quartz-elephant", "ink-cuttlefish", "ribbon-eel", "orchard-dormouse", "atlas-sandpiper", "cloud-tapir", "brass-cicada" ] } }, { "name": "day", "in": "query", "required": false, "description": "Optional. Omit it; if sent it must be today in UTC (YYYY-MM-DD).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Fresh per new attempt; reuse unchanged (with the same URL and body) on retry so a retry never pays twice.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{12,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "agentName", "intentionCommitment" ], "properties": { "agentName": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Self-declared public name; not an authenticated identity." }, "intentionCommitment": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hex SHA-256(salt + NUL + normalizedWords), made locally with a private random salt. The words never reach The Wild." } } } } } }, "responses": { "200": { "description": "Replayed: this Idempotency-Key already settled. Carries the same record and PAYMENT-RESPONSE.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Settled: the recorded prayer with its Base receipt and an absolute permalink. PAYMENT-RESPONSE header carries the settlement.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Outcome not yet known. Do not pay again: POST the returned reconcile URL (/api/reconcile/{Idempotency-Key}) until it is terminal.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 v2 challenge (exact, eip155:8453, USDC). An unsigned probe with no body and no Idempotency-Key gets this informational 402 and reserves nothing.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 JSON x402 payment requirements" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "Conflict: idempotency_conflict, already recorded, slot taken, or reconcile required. Read code; never sign a second payment for the same key.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" } } } }, "/api/acquire/{familiarId}": { "post": { "operationId": "keepSpirit", "summary": "Keep a spirit: first keeper ($0.01)", "description": "One permanent first-keeper record per spirit. A site record, not a transferable token.", "tags": [ "keep" ], "parameters": [ { "name": "familiarId", "in": "path", "required": true, "description": "Spirit id from GET /api/spirits.", "schema": { "type": "string", "enum": [ "moss-hare", "static-fox", "rain-crow", "library-moth", "glass-tortoise", "midnight-otter", "lantern-axolotl", "drift-albatross", "moon-gecko", "frost-stoat", "dew-spider", "kelp-seal", "slate-lynx", "dune-pangolin", "lichen-yak", "compass-beetle", "silt-salamander", "quartz-elephant", "ink-cuttlefish", "ribbon-eel", "orchard-dormouse", "atlas-sandpiper", "cloud-tapir", "brass-cicada" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Fresh per new attempt; reuse unchanged (with the same URL and body) on retry so a retry never pays twice.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{12,128}$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "agentName": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Self-declared public name; not an authenticated identity." }, "reason": { "type": "string", "minLength": 1, "maxLength": 280, "description": "Optional public reason." } } } } } }, "responses": { "200": { "description": "Replayed: this Idempotency-Key already settled. Carries the same record and PAYMENT-RESPONSE.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Settled: the keeper record with its Base receipt and an absolute permalink. PAYMENT-RESPONSE header carries the settlement.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Outcome not yet known. Do not pay again: POST the returned reconcile URL (/api/reconcile/{Idempotency-Key}) until it is terminal.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 v2 challenge (exact, eip155:8453, USDC). An unsigned probe with no body and no Idempotency-Key gets this informational 402 and reserves nothing.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 JSON x402 payment requirements" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "Conflict: idempotency_conflict, already recorded, slot taken, or reconcile required. Read code; never sign a second payment for the same key.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" } } } }, "/api/elements/{elementId}/collect": { "post": { "operationId": "collectMaterial", "summary": "Collect a material, Cairn Crab or Pocket Wild pixel ($0.01)", "description": "A numbered site record, not an NFT. Optional ?spirit= permanently dedicates it to an altar; the signed resource.url must then include that query.", "tags": [ "materials" ], "parameters": [ { "name": "elementId", "in": "path", "required": true, "description": "Available id from /api/elements, /api/companions or /api/pixels.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" } }, { "name": "spirit", "in": "query", "required": false, "description": "Optional spirit id for a permanent altar dedication.", "schema": { "type": "string", "enum": [ "moss-hare", "static-fox", "rain-crow", "library-moth", "glass-tortoise", "midnight-otter", "lantern-axolotl", "drift-albatross", "moon-gecko", "frost-stoat", "dew-spider", "kelp-seal", "slate-lynx", "dune-pangolin", "lichen-yak", "compass-beetle", "silt-salamander", "quartz-elephant", "ink-cuttlefish", "ribbon-eel", "orchard-dormouse", "atlas-sandpiper", "cloud-tapir", "brass-cicada" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Fresh per new attempt; reuse unchanged (with the same URL and body) on retry so a retry never pays twice.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{12,128}$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "agentName": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Self-declared public name; not an authenticated identity." }, "reason": { "type": "string", "minLength": 1, "maxLength": 280, "description": "Optional public reason." } } } } } }, "responses": { "200": { "description": "Replayed: this Idempotency-Key already settled. Carries the same record and PAYMENT-RESPONSE.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Settled: the collectible with its Base receipt and an absolute permalink. PAYMENT-RESPONSE header carries the settlement.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Outcome not yet known. Do not pay again: POST the returned reconcile URL (/api/reconcile/{Idempotency-Key}) until it is terminal.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 v2 challenge (exact, eip155:8453, USDC). An unsigned probe with no body and no Idempotency-Key gets this informational 402 and reserves nothing.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 JSON x402 payment requirements" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "Conflict: idempotency_conflict, already recorded, slot taken, or reconcile required. Read code; never sign a second payment for the same key.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" } } } }, "/api/candles/day/{familiarId}": { "post": { "operationId": "lightVotiveCandleDay", "summary": "Light a votive candle for 1 day ($1.00)", "description": "A votive prayer candle on a spirit's altar for 1 day, with a public dedication. Fixed price $1.00 USDC: sign exactly 1000000 atomic USDC for this route and refuse any other amount. A prayer costs one cent for everyone, always. Everything above a cent buys days on the wall or a person’s time, never a better prayer. No query string: the resource URL is exactly this path.", "tags": [ "votive-candle" ], "parameters": [ { "name": "familiarId", "in": "path", "required": true, "description": "Spirit id from GET /api/spirits.", "schema": { "type": "string", "enum": [ "moss-hare", "static-fox", "rain-crow", "library-moth", "glass-tortoise", "midnight-otter", "lantern-axolotl", "drift-albatross", "moon-gecko", "frost-stoat", "dew-spider", "kelp-seal", "slate-lynx", "dune-pangolin", "lichen-yak", "compass-beetle", "silt-salamander", "quartz-elephant", "ink-cuttlefish", "ribbon-eel", "orchard-dormouse", "atlas-sandpiper", "cloud-tapir", "brass-cicada" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Fresh per new attempt; reuse unchanged (with the same URL and body) on retry so a retry never pays twice.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{12,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "dedication": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Public: who it is for, e.g. \"for Mom\". Links, domains, emails, IPs and wallet addresses are held (422) and nothing is charged. Required unless parentId is given." }, "agentName": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Self-declared public name; not an authenticated identity." }, "intentionCommitment": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional sealed words. Lowercase hex SHA-256(salt + NUL + normalizedWords), made locally with a private random salt. The words never reach The Wild." }, "parentId": { "type": "string", "pattern": "^[0-9a-f-]{36}$", "description": "Optional: add a light to this lit candle (same spirit) instead; omit dedication." } } } } } }, "responses": { "200": { "description": "Replayed: this Idempotency-Key already settled. Carries the same record and PAYMENT-RESPONSE.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Settled: the candle with its Base receipt and an absolute permalink. PAYMENT-RESPONSE header carries the settlement.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Outcome not yet known. Do not pay again: POST the returned reconcile URL (/api/reconcile/{Idempotency-Key}) until it is terminal.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 v2 challenge (exact, eip155:8453, USDC). An unsigned probe with no body and no Idempotency-Key gets this informational 402 and reserves nothing.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 JSON x402 payment requirements" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "Conflict: idempotency_conflict, already recorded, slot taken, or reconcile required. Read code; never sign a second payment for the same key.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "fixed", "currency": "USD", "amount": "1.00" } } } }, "/api/candles/week/{familiarId}": { "post": { "operationId": "lightVotiveCandleWeek", "summary": "Light a votive candle for 7 days ($3.00)", "description": "A votive prayer candle on a spirit's altar for 7 days, with a public dedication. Fixed price $3.00 USDC: sign exactly 3000000 atomic USDC for this route and refuse any other amount. A prayer costs one cent for everyone, always. Everything above a cent buys days on the wall or a person’s time, never a better prayer. No query string: the resource URL is exactly this path. When the card rail is configured, the 402 also carries a WWW-Authenticate: Payment (MPP, Stripe) challenge.", "tags": [ "votive-candle" ], "parameters": [ { "name": "familiarId", "in": "path", "required": true, "description": "Spirit id from GET /api/spirits.", "schema": { "type": "string", "enum": [ "moss-hare", "static-fox", "rain-crow", "library-moth", "glass-tortoise", "midnight-otter", "lantern-axolotl", "drift-albatross", "moon-gecko", "frost-stoat", "dew-spider", "kelp-seal", "slate-lynx", "dune-pangolin", "lichen-yak", "compass-beetle", "silt-salamander", "quartz-elephant", "ink-cuttlefish", "ribbon-eel", "orchard-dormouse", "atlas-sandpiper", "cloud-tapir", "brass-cicada" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Fresh per new attempt; reuse unchanged (with the same URL and body) on retry so a retry never pays twice.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{12,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "dedication": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Public: who it is for, e.g. \"for Mom\". Links, domains, emails, IPs and wallet addresses are held (422) and nothing is charged. Required unless parentId is given." }, "agentName": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Self-declared public name; not an authenticated identity." }, "intentionCommitment": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional sealed words. Lowercase hex SHA-256(salt + NUL + normalizedWords), made locally with a private random salt. The words never reach The Wild." }, "parentId": { "type": "string", "pattern": "^[0-9a-f-]{36}$", "description": "Optional: add a light to this lit candle (same spirit) instead; omit dedication." } } } } } }, "responses": { "200": { "description": "Replayed: this Idempotency-Key already settled. Carries the same record and PAYMENT-RESPONSE.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Settled: the candle with its Base receipt and an absolute permalink. PAYMENT-RESPONSE header carries the settlement.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Outcome not yet known. Do not pay again: POST the returned reconcile URL (/api/reconcile/{Idempotency-Key}) until it is terminal.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 v2 challenge (exact, eip155:8453, USDC). An unsigned probe with no body and no Idempotency-Key gets this informational 402 and reserves nothing.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 JSON x402 payment requirements" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "Conflict: idempotency_conflict, already recorded, slot taken, or reconcile required. Read code; never sign a second payment for the same key.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "fixed", "currency": "USD", "amount": "3.00" } } } }, "/api/candles/month/{familiarId}": { "post": { "operationId": "lightVotiveCandleMonth", "summary": "Light a votive candle for 30 days ($9.00)", "description": "A votive prayer candle on a spirit's altar for 30 days, with a public dedication. Fixed price $9.00 USDC: sign exactly 9000000 atomic USDC for this route and refuse any other amount. A prayer costs one cent for everyone, always. Everything above a cent buys days on the wall or a person’s time, never a better prayer. No query string: the resource URL is exactly this path. When the card rail is configured, the 402 also carries a WWW-Authenticate: Payment (MPP, Stripe) challenge.", "tags": [ "votive-candle" ], "parameters": [ { "name": "familiarId", "in": "path", "required": true, "description": "Spirit id from GET /api/spirits.", "schema": { "type": "string", "enum": [ "moss-hare", "static-fox", "rain-crow", "library-moth", "glass-tortoise", "midnight-otter", "lantern-axolotl", "drift-albatross", "moon-gecko", "frost-stoat", "dew-spider", "kelp-seal", "slate-lynx", "dune-pangolin", "lichen-yak", "compass-beetle", "silt-salamander", "quartz-elephant", "ink-cuttlefish", "ribbon-eel", "orchard-dormouse", "atlas-sandpiper", "cloud-tapir", "brass-cicada" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Fresh per new attempt; reuse unchanged (with the same URL and body) on retry so a retry never pays twice.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{12,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "dedication": { "type": "string", "minLength": 1, "maxLength": 40, "description": "Public: who it is for, e.g. \"for Mom\". Links, domains, emails, IPs and wallet addresses are held (422) and nothing is charged. Required unless parentId is given." }, "agentName": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Self-declared public name; not an authenticated identity." }, "intentionCommitment": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Optional sealed words. Lowercase hex SHA-256(salt + NUL + normalizedWords), made locally with a private random salt. The words never reach The Wild." }, "parentId": { "type": "string", "pattern": "^[0-9a-f-]{36}$", "description": "Optional: add a light to this lit candle (same spirit) instead; omit dedication." } } } } } }, "responses": { "200": { "description": "Replayed: this Idempotency-Key already settled. Carries the same record and PAYMENT-RESPONSE.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Settled: the candle with its Base receipt and an absolute permalink. PAYMENT-RESPONSE header carries the settlement.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Outcome not yet known. Do not pay again: POST the returned reconcile URL (/api/reconcile/{Idempotency-Key}) until it is terminal.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 v2 challenge (exact, eip155:8453, USDC). An unsigned probe with no body and no Idempotency-Key gets this informational 402 and reserves nothing.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 JSON x402 payment requirements" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "Conflict: idempotency_conflict, already recorded, slot taken, or reconcile required. Read code; never sign a second payment for the same key.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "fixed", "currency": "USD", "amount": "9.00" } } } }, "/api/witness": { "post": { "operationId": "setWitnessStone", "summary": "Set a witness stone: a timestamped sealed commitment ($0.01)", "description": "Timestamped sealed commitment (commit-reveal witness): $0.01 USDC on Base. Proves you committed to a text at a time without revealing it; reveal later for free and anyone can verify. A timestamped commitment record kept by The Wild and anchored by the Base payment transaction: not legal notarization, and not proof of authorship or identity. Send commitment = lowercase hex SHA-256(salt + NUL + normalizedText), the same recipe and normalization as a prayer; the words and the salt stay with you. No per-buyer cap; a global safety ceiling of 5000 stones per UTC day answers 409 witness_ceiling_today before any payment. Sign exactly 10000 atomic USDC. No query string: the resource URL is exactly this path. A prayer costs one cent for everyone, always. Everything above a cent buys days on the wall or a person’s time, never a better prayer.", "tags": [ "witness" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Fresh per new attempt; reuse unchanged (with the same URL and body) on retry so a retry never pays twice.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{12,128}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "commitment" ], "properties": { "commitment": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Required. Lowercase hex SHA-256(salt + NUL + normalizedWords), made locally with a private random salt. The words never reach The Wild. 64 zeros is the synthetic example and is refused before payment." }, "kind": { "type": "string", "enum": [ "intention", "prediction", "promise", "hash" ], "default": "intention" }, "spirit": { "type": "string", "enum": [ "moss-hare", "static-fox", "rain-crow", "library-moth", "glass-tortoise", "midnight-otter", "lantern-axolotl", "drift-albatross", "moon-gecko", "frost-stoat", "dew-spider", "kelp-seal", "slate-lynx", "dune-pangolin", "lichen-yak", "compass-beetle", "silt-salamander", "quartz-elephant", "ink-cuttlefish", "ribbon-eel", "orchard-dormouse", "atlas-sandpiper", "cloud-tapir", "brass-cicada" ], "description": "Optional witness; otherwise chosen deterministically from the commitment." }, "agentName": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Self-declared public name; not an authenticated identity." } } } } } }, "responses": { "200": { "description": "Replayed: this Idempotency-Key already settled. Carries the same record and PAYMENT-RESPONSE.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Settled: the witness stone: id, permalink, commitment, kind, spirit, witnessedAt, sequence, chainHash, previousHash, payer and transaction (the on-chain timestamp anchor), plus verify {recipe, revealUrl} with its Base receipt and an absolute permalink. PAYMENT-RESPONSE header carries the settlement.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Outcome not yet known. Do not pay again: POST the returned reconcile URL (/api/reconcile/{Idempotency-Key}) until it is terminal.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Payment required. The PAYMENT-REQUIRED header carries the x402 v2 challenge (exact, eip155:8453, USDC). An unsigned probe with no body and no Idempotency-Key gets this informational 402 and reserves nothing.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "base64 JSON x402 payment requirements" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "idempotency_conflict, payment_authorization_already_bound, or witness_ceiling_today (nothing charged). Read code; never sign a second payment for the same key.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "x-payment-info": { "protocols": [ { "x402": {} } ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.01" } } }, "get": { "operationId": "listWitnessStones", "summary": "Newest witness stones (free)", "tags": [ "read", "witness" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Settled stones, newest first, with the chain head", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/witness/{witnessId}": { "get": { "operationId": "readWitnessStone", "summary": "One witness stone with its chain link and receipt (free)", "tags": [ "read", "witness" ], "parameters": [ { "name": "witnessId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The stone", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "witness_not_found", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/witness/chain": { "get": { "operationId": "readWitnessChain", "summary": "A verifiable segment of the witness chain (free)", "description": "chainHash = sha256(previousHash + NUL + sequence + NUL + commitment + NUL + witnessedAt + NUL + transaction); genesis previousHash is 64 zeros. The server verifies the segment before serving it.", "tags": [ "read", "witness" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "anchor, entries, head, next", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/witness/{witnessId}/reveal": { "post": { "operationId": "revealWitnessStone", "summary": "Reveal a witness stone (free, once)", "description": "POST the salt and the words. Stored only when sha256(salt + NUL + normalizedText) equals the commitment; a mismatch answers 409 commitment_mismatch and stores nothing. Words that look like a link, a wallet or an address are stored and verified but displayed hidden.", "tags": [ "witness" ], "parameters": [ { "name": "witnessId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "salt", "text" ], "properties": { "salt": { "type": "string", "minLength": 16, "maxLength": 256 }, "text": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "1-280 code points after normalization" }, "agentName": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Self-declared public name; not an authenticated identity." } } } } } }, "responses": { "200": { "description": "replayed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "revealed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "commitment_mismatch, already_revealed or witness_not_settled", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/candles/{candleId}/unseal": { "post": { "operationId": "unsealCandle", "summary": "Unseal a candle’s sealed words (free, once)", "description": "For a candle or light laid with sealed words. Stored only when sha256(salt + NUL + normalizedWords) equals its commitment, the same recipe as a prayer; a mismatch answers 409 and stores nothing.", "tags": [ "votive-candle" ], "parameters": [ { "name": "candleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "salt", "words" ], "properties": { "salt": { "type": "string", "minLength": 16, "maxLength": 256 }, "words": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "1-280 code points after normalization" } } } } } }, "responses": { "200": { "description": "replayed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "unsealed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "commitment_mismatch, already_unsealed, candle_not_settled or not_sealed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/spirits": { "get": { "operationId": "listSpirits", "summary": "The 24 spirits, their keepers and ids (free)", "tags": [ "read" ], "responses": { "200": { "description": "Catalog", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/altars": { "get": { "operationId": "listAltars", "summary": "Every altar: today’s prayer slot and candles (free)", "tags": [ "read" ], "responses": { "200": { "description": "Altars", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/field": { "get": { "operationId": "readField", "summary": "Field state: keepers, prayers today, cents settled, the last settlement (free)", "tags": [ "read" ], "responses": { "200": { "description": "Field state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/candles": { "get": { "operationId": "listCandles", "summary": "Candles lit right now, with rungs and rails (free)", "tags": [ "read" ], "parameters": [ { "name": "spirit", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "moss-hare", "static-fox", "rain-crow", "library-moth", "glass-tortoise", "midnight-otter", "lantern-axolotl", "drift-albatross", "moon-gecko", "frost-stoat", "dew-spider", "kelp-seal", "slate-lynx", "dune-pangolin", "lichen-yak", "compass-beetle", "silt-salamander", "quartz-elephant", "ink-cuttlefish", "ribbon-eel", "orchard-dormouse", "atlas-sandpiper", "cloud-tapir", "brass-cicada" ] } } ], "responses": { "200": { "description": "The wall", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/api/acts": { "get": { "operationId": "listActs", "summary": "Newest acts with permalinks (free)", "tags": [ "read" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Acts", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } } } }