{"openapi":"3.1.0","info":{"title":"MantisMesh","version":"1.0.0","description":"Portable encrypted checkpoints, wallet-to-wallet handoffs, global logical locks and heartbeat recovery. Deterministic REST API. Authentication uses raw Solana signMessage Ed25519 signatures over exact server-issued UTF-8 bytes (base64 signatures). No wallet private keys are accepted. Protected reads require Idempotency-Key; exact-key retries may replay encrypted cached read-once results until expiry. Expired objects return 410 while tombstones remain, then 404 after cleanup."},"servers":[{"url":"https://api.mantismesh.com"}],"components":{"securitySchemes":{"walletSession":{"type":"http","scheme":"bearer"},"adminBasic":{"type":"http","scheme":"basic"},"adminBearer":{"type":"http","scheme":"bearer"}},"schemas":{"CheckpointInput":{"type":"object","additionalProperties":false,"required":["task_id","payload","retention"],"properties":{"task_id":{"type":"string","minLength":1,"maxLength":200},"payload":{"description":"JSON value; UTF-8 JSON encoding <= 65536 bytes"},"retention":{"type":"string","enum":["1h","24h","7d","30d"]},"delete_after_read":{"type":"boolean","default":false}}},"HandoffInput":{"type":"object","additionalProperties":false,"required":["checkpoint_id","recipient_wallet","retention"],"properties":{"checkpoint_id":{"type":"string"},"recipient_wallet":{"type":"string"},"retention":{"type":"string","enum":["1h","24h","7d","30d"]},"delete_after_read":{"type":"boolean","default":true}}},"LockInput":{"type":"object","additionalProperties":false,"required":["key","ttl_seconds"],"properties":{"key":{"type":"string","minLength":1,"maxLength":200},"ttl_seconds":{"type":"integer","minimum":1,"maximum":2592000}}},"RecoveryInput":{"type":"object","additionalProperties":false,"required":["task_id","checkpoint_id","heartbeat_interval_seconds","missed_heartbeats","callback_url"],"properties":{"task_id":{"type":"string"},"checkpoint_id":{"type":"string"},"heartbeat_interval_seconds":{"type":"integer","minimum":30,"maximum":86400},"missed_heartbeats":{"type":"integer","minimum":1,"maximum":100},"callback_url":{"type":"string","pattern":"^https://","description":"HTTPS origin must be operator-allowlisted"},"retention":{"type":"string","enum":["1h","24h","7d","30d"],"default":"24h"}}},"CheckpointCreated":{"type":"object","required":["checkpoint_id","expires_at","retention"],"properties":{"checkpoint_id":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"retention":{"type":"string"}}},"Checkpoint":{"type":"object","properties":{"checkpoint_id":{"type":"string"},"task_id":{"type":"string"},"payload":{},"retention":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}},"HandoffCreated":{"type":"object","properties":{"handoff_id":{"type":"string"},"checkpoint_id":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"retention":{"type":"string"}}},"Handoff":{"type":"object","properties":{"handoff_id":{"type":"string"},"checkpoint_id":{"type":"string"},"task_id":{"type":"string"},"payload":{},"expires_at":{"type":"string","format":"date-time"}}},"RecoveryCreated":{"type":"object","properties":{"recovery_id":{"type":"string"},"status":{"const":"active"},"expires_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"paths":{"/health":{"get":{"operationId":"health","responses":{"200":{"description":"Healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"ok"}},"required":["status"]}}}}}}},"/pricing":{"get":{"operationId":"pricing","responses":{"200":{"description":"USD prices in integer millionths; retry the same logical operation without another charge","content":{"application/json":{"schema":{"type":"object","examples":[{"currency":"USD","unit":"millionths","prices":{"checkpoint.save":{"1h":10000,"24h":10000,"7d":20000,"30d":50000},"checkpoint.get":5000,"handoff.create":20000,"lock.acquire":5000,"recovery.register":20000}}]}}}}}}},"/capabilities":{"get":{"operationId":"capabilities","responses":{"200":{"description":"Capabilities, when to use each, retention classes and limits","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/openapi.json":{"get":{"operationId":"openapi","responses":{"200":{"description":"This OpenAPI specification","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/mantismesh.json":{"get":{"operationId":"mantismeshDiscovery","responses":{"200":{"description":"MantisMesh capability catalog and Bazaar schemas","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/agent-state.json":{"get":{"operationId":"discovery","responses":{"200":{"description":"Individually discoverable capabilities and validated Bazaar extensions","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/llms.txt":{"get":{"operationId":"llms","responses":{"200":{"description":"Machine-readable plain text service guide","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/v1/auth/challenge":{"post":{"operationId":"authChallenge","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["wallet"],"properties":{"wallet":{"type":"string"}}}}}},"responses":{"200":{"description":"Five-minute single-use challenge","content":{"application/json":{"schema":{"type":"object","properties":{"nonce":{"type":"string"},"message":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"signature_encoding":{"const":"base64"}}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/v1/auth/verify":{"post":{"operationId":"authVerify","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["nonce","wallet","signature"],"properties":{"nonce":{"type":"string"},"wallet":{"type":"string"},"signature":{"type":"string","description":"Base64 Ed25519 signature over the exact challenge message bytes"}}}}}},"responses":{"200":{"description":"One-hour bearer session","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"token_type":{"const":"Bearer"},"expires_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/v1/checkpoints":{"post":{"operationId":"saveCheckpoint","description":"Save portable execution state when a task may outlive the current process, model session, container, or machine.","x-pricing":{"currency":"USD","unit":"millionths","amount":{"1h":10000,"24h":10000,"7d":20000,"30d":50000}},"security":[{"walletSession":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Use a unique key per logical operation. Retries must keep method, path, JSON field order and values identical. Results expire with the object, no later than 30 days."},{"in":"header","name":"PAYMENT-SIGNATURE","required":false,"schema":{"type":"string"},"description":"x402 V2 signed payment; obtain requirements from HTTP 402. Payer must be the authenticated wallet."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckpointInput"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckpointCreated"}}},"headers":{"Idempotency-Replayed":{"schema":{"type":"boolean"}},"PAYMENT-RESPONSE":{"schema":{"type":"string"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"402":{"description":"Payment required; use an x402 V2 client","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/v1/checkpoints/{checkpointId}":{"get":{"operationId":"getCheckpoint","description":"Resume wallet-owned state. Handoff recipients retrieve via the handoff endpoint.","x-pricing":{"currency":"USD","unit":"millionths","amount":5000},"security":[{"walletSession":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Use a unique key per logical operation. Retries must keep method, path, JSON field order and values identical. Results expire with the object, no later than 30 days."},{"in":"header","name":"PAYMENT-SIGNATURE","required":false,"schema":{"type":"string"},"description":"x402 V2 signed payment; obtain requirements from HTTP 402. Payer must be the authenticated wallet."},{"in":"path","name":"checkpointId","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkpoint"}}},"headers":{"Idempotency-Replayed":{"schema":{"type":"boolean"}},"PAYMENT-RESPONSE":{"schema":{"type":"string"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"402":{"description":"Payment required; use an x402 V2 client","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/v1/handoffs":{"post":{"operationId":"createHandoff","description":"Delegate a snapshot to one specified wallet. Source checkpoint must be live and owned. Expiry is capped by source.","x-pricing":{"currency":"USD","unit":"millionths","amount":20000},"security":[{"walletSession":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Use a unique key per logical operation. Retries must keep method, path, JSON field order and values identical. Results expire with the object, no later than 30 days."},{"in":"header","name":"PAYMENT-SIGNATURE","required":false,"schema":{"type":"string"},"description":"x402 V2 signed payment; obtain requirements from HTTP 402. Payer must be the authenticated wallet."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandoffInput"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandoffCreated"}}},"headers":{"Idempotency-Replayed":{"schema":{"type":"boolean"}},"PAYMENT-RESPONSE":{"schema":{"type":"string"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"402":{"description":"Payment required; use an x402 V2 client","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/v1/handoffs/{handoffId}":{"get":{"operationId":"getHandoff","description":"Only the named recipient may retrieve. One-time reads are atomically claimed; same-key retries replay until expiry.","security":[{"walletSession":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Use a unique key per logical operation. Retries must keep method, path, JSON field order and values identical. Results expire with the object, no later than 30 days."},{"in":"path","name":"handoffId","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Handoff"}}},"headers":{"Idempotency-Replayed":{"schema":{"type":"boolean"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/v1/locks":{"post":{"operationId":"acquireLock","description":"Prevent simultaneous actions on a global logical key. A failed contention attempt is also charged. Reacquiring requires a new operation key.","x-pricing":{"currency":"USD","unit":"millionths","amount":5000},"security":[{"walletSession":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Use a unique key per logical operation. Retries must keep method, path, JSON field order and values identical. Results expire with the object, no later than 30 days."},{"in":"header","name":"PAYMENT-SIGNATURE","required":false,"schema":{"type":"string"},"description":"x402 V2 signed payment; obtain requirements from HTTP 402. Payer must be the authenticated wallet."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LockInput"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"acquired":{"const":true},"expires_at":{"type":"string","format":"date-time"}}},{"type":"object","properties":{"acquired":{"const":false},"reason":{"const":"already_locked"}}}]}}},"headers":{"Idempotency-Replayed":{"schema":{"type":"boolean"}},"PAYMENT-RESPONSE":{"schema":{"type":"string"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"402":{"description":"Payment required; use an x402 V2 client","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/v1/locks/{key}":{"delete":{"operationId":"releaseLock","description":"Release an active lock owned by your wallet.","security":[{"walletSession":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Use a unique key per logical operation. Retries must keep method, path, JSON field order and values identical. Results expire with the object, no later than 30 days."},{"in":"path","name":"key","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"released":{"const":true}}}}},"headers":{"Idempotency-Replayed":{"schema":{"type":"boolean"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/v1/recoveries":{"post":{"operationId":"registerRecovery","description":"Register heartbeat and failure instructions for a long-running autonomous task. HTTPS callback origin must be operator-reviewed. Callbacks carry IDs, never checkpoint plaintext.","x-pricing":{"currency":"USD","unit":"millionths","amount":20000},"security":[{"walletSession":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Use a unique key per logical operation. Retries must keep method, path, JSON field order and values identical. Results expire with the object, no later than 30 days."},{"in":"header","name":"PAYMENT-SIGNATURE","required":false,"schema":{"type":"string"},"description":"x402 V2 signed payment; obtain requirements from HTTP 402. Payer must be the authenticated wallet."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryInput"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryCreated"}}},"headers":{"Idempotency-Replayed":{"schema":{"type":"boolean"}},"PAYMENT-RESPONSE":{"schema":{"type":"string"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"402":{"description":"Payment required; use an x402 V2 client","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/v1/recoveries/{recoveryId}/heartbeat":{"post":{"operationId":"recoveryHeartbeat","description":"Advance the last heartbeat of an active registration. Does not extend object retention. Send an empty JSON object and a new idempotency key for each heartbeat.","security":[{"walletSession":[]}],"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":1,"maxLength":128},"description":"Use a unique key per logical operation. Retries must keep method, path, JSON field order and values identical. Results expire with the object, no later than 30 days."},{"in":"path","name":"recoveryId","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"recovery_id":{"type":"string"},"status":{"type":"string"},"last_heartbeat_at":{"type":"string","format":"date-time"}}}}},"headers":{"Idempotency-Replayed":{"schema":{"type":"boolean"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/admin":{"get":{"operationId":"adminDashboard","security":[{"adminBasic":[]},{"adminBearer":[]}],"responses":{"200":{"description":"Protected HTML dashboard"},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/admin/metrics":{"get":{"operationId":"adminMetrics","security":[{"adminBasic":[]},{"adminBearer":[]}],"parameters":[{"in":"query","name":"audience","schema":{"enum":["external","test","all"],"default":"external"}}],"responses":{"200":{"description":"Retained metrics, max 30 days; all_available is not lifetime revenue","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/admin/wallet-labels":{"post":{"operationId":"labelWallet","security":[{"adminBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["wallet","is_test"],"properties":{"wallet":{"type":"string"},"is_test":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Label retained for 30 days","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/admin/treasury-transfers":{"post":{"operationId":"recordManualTransfer","security":[{"adminBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["transaction_hash","amount","network"],"properties":{"transaction_hash":{"type":"string"},"amount":{"type":"integer","minimum":1,"description":"USDC base units"},"network":{"type":"string"}}}}}},"responses":{"200":{"description":"User-reported accounting entry; does not transfer or verify funds","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"409","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"410":{"description":"410","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"413","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"415":{"description":"415","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"429","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"503","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}}}}