{ "openapi": "3.1.0", "info": { "title": "Psyseal API", "version": "1", "summary": "Public status of Psyseal seals for AI agents, the signing key, and x402 passes paid by the agent in USDC.", "description": "Psyseal checks, cleans up and seals AI agents. The free scanner runs on the owner's computer (npx psyseal-scan, MIT-0) and is not part of this API. This API serves the public seal pages, their signed JSON and badges, the Ed25519 public key, and the two x402 passes. Reading needs no key. Psyseal signs the results that the owner's program sends and does not verify them on its own; a seal is not an official certification or an audit.", "termsOfService": "https://psyseal.com/terminos", "contact": { "name": "Psyseal", "email": "hola@psyseal.com", "url": "https://psyseal.com/docs" } }, "externalDocs": { "description": "For developers and AI agents", "url": "https://psyseal.com/docs" }, "servers": [ { "url": "https://seal.psyseal.com" } ], "tags": [ { "name": "seals", "description": "Public, read-only." }, { "name": "x402", "description": "Passes paid by the agent in USDC (x402 v2, Base)." }, { "name": "service" } ], "paths": { "/health": { "get": { "tags": [ "service" ], "operationId": "health", "summary": "Service status", "responses": { "200": { "description": "Up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "v": { "type": "string" } }, "required": [ "ok" ] } } } } }, "security": [] } }, "/.well-known/psyseal-seal-key.json": { "get": { "tags": [ "seals" ], "operationId": "getSigningKey", "summary": "Ed25519 public key that signs the seals", "responses": { "200": { "description": "JWK set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeySet" } } } } }, "security": [] } }, "/{id}.json": { "get": { "tags": [ "seals" ], "operationId": "getSeal", "summary": "Signed seal and its current status", "parameters": [ { "$ref": "#/components/parameters/SealId" } ], "responses": { "200": { "description": "The seal. When its public name is under review, only status, reason, key_url and last_check_at are returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Seal" } } } }, "404": { "description": "No seal with that code (HTML page)." } }, "security": [] } }, "/{id}.svg": { "get": { "tags": [ "seals" ], "operationId": "getBadge", "summary": "Badge that follows the seal status", "parameters": [ { "$ref": "#/components/parameters/SealId" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "es" ] }, "description": "Badge language. Default: en." } ], "responses": { "200": { "description": "SVG badge.", "content": { "image/svg+xml": { "schema": { "type": "string" } } } }, "404": { "description": "No seal with that code (grey badge).", "content": { "image/svg+xml": { "schema": { "type": "string" } } } } }, "security": [] } }, "/{id}": { "get": { "tags": [ "seals" ], "operationId": "getSealPage", "summary": "Public seal page", "parameters": [ { "$ref": "#/components/parameters/SealId" }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "es" ] } } ], "responses": { "200": { "description": "HTML page.", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "No seal with that code.", "content": { "text/html": { "schema": { "type": "string" } } } } }, "security": [] } }, "/api/x402/pass": { "post": { "tags": [ "x402" ], "operationId": "buyFullPass", "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "8.99" }, "network": "eip155:8453", "asset": "USDC" }, "summary": "Full pass for one agent: cleanup and seal, 30 days, 8.99 USDC", "description": "Without a valid pass the answer is 402 with the x402 v2 requirements. With PAYMENT-SIGNATURE the payment is verified and settled through the facilitator and the pass starts. If the agent already has a full pass, the answer is 200 with paid false and nothing is charged. Offered only from US, CA, AU, NZ, JP, SG, HK, CH and NO; only with the owner's authorization. The cleanup itself runs on the owner's computer with the Psyseal program (node scripts/psyseal-fix.mjs --apply --x402).", "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment payload, base64-encoded JSON, signed by the paying wallet. Send it after a 402 answer." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "agent" ], "properties": { "agent": { "type": "object", "required": [ "hash", "platform" ], "properties": { "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 fingerprint of the agent, computed by Psyseal's program on the owner's computer." }, "platform": { "type": "string", "enum": [ "openclaw", "hermes", "nanobot", "picoclaw", "zeroclaw", "nanoclaw", "generic" ] }, "label": { "type": "string", "maxLength": 32, "description": "Optional public name shown on the seal page. No personal data." } } }, "tier": { "const": "full", "default": "full" } } } } } }, "responses": { "200": { "description": "Done. The pass (and, for /api/x402/seal, the signed seal) is returned.", "headers": { "PAYMENT-RESPONSE": { "description": "x402 v2 settlement result, base64-encoded JSON. Present only when this call charged a payment.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pass" } } } }, "400": { "description": "Invalid body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "reason": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": true } } } }, "402": { "description": "Payment required. Read the PAYMENT-REQUIRED header, sign the payment and send it again in PAYMENT-SIGNATURE.", "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 payment requirements, base64-encoded JSON (scheme exact, USDC on Base eip155:8453).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "reason": { "const": "payment_required" }, "tier": { "type": "string", "enum": [ "seal", "full" ] }, "price": { "type": "string", "examples": [ "8.99 USDC" ] }, "network": { "type": "string", "examples": [ "eip155:8453" ] }, "days": { "type": "integer", "examples": [ 30 ] }, "renews": { "const": false }, "terms": { "type": "string", "format": "uri" }, "privacy": { "type": "string", "format": "uri" } }, "additionalProperties": true } } } }, "409": { "description": "The agent has an active seal from a card plan, or this payment was already used.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "reason": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": true } } } }, "451": { "description": "x402 is not offered from the country of the request. Use a card plan: https://psyseal.com/#planes", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "reason": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": true } } } }, "503": { "description": "x402 is turned off.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "reason": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": true } } } } } } }, "/api/x402/seal": { "post": { "tags": [ "x402" ], "operationId": "buySealPass", "x-payment-info": { "protocols": [ "x402" ], "price": { "mode": "fixed", "currency": "USD", "amount": "0.99" }, "network": "eip155:8453", "asset": "USDC" }, "summary": "Seal pass for one agent that passes the checks: 30 days, 0.99 USDC", "description": "The body is built by the Psyseal program on the owner's computer (node scripts/psyseal-seal.mjs --x402): the check results and a fingerprint of the files, never their content. A run that does not pass is not charged (422). With any active pass the seal is renewed without a charge.", "parameters": [ { "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "x402 v2 payment payload, base64-encoded JSON, signed by the paying wallet. Send it after a 402 answer." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SealRequest" } } } }, "responses": { "200": { "description": "Done. The pass (and, for /api/x402/seal, the signed seal) is returned.", "headers": { "PAYMENT-RESPONSE": { "description": "x402 v2 settlement result, base64-encoded JSON. Present only when this call charged a payment.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/IssuedSeal" }, { "$ref": "#/components/schemas/Pass" } ] } } } }, "400": { "description": "Invalid body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "reason": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": true } } } }, "402": { "description": "Payment required. Read the PAYMENT-REQUIRED header, sign the payment and send it again in PAYMENT-SIGNATURE.", "headers": { "PAYMENT-REQUIRED": { "description": "x402 v2 payment requirements, base64-encoded JSON (scheme exact, USDC on Base eip155:8453).", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "reason": { "const": "payment_required" }, "tier": { "type": "string", "enum": [ "seal", "full" ] }, "price": { "type": "string", "examples": [ "8.99 USDC" ] }, "network": { "type": "string", "examples": [ "eip155:8453" ] }, "days": { "type": "integer", "examples": [ 30 ] }, "renews": { "const": false }, "terms": { "type": "string", "format": "uri" }, "privacy": { "type": "string", "format": "uri" } }, "additionalProperties": true } } } }, "409": { "description": "The agent has an active seal from a card plan, or this payment was already used.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "reason": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": true } } } }, "451": { "description": "x402 is not offered from the country of the request. Use a card plan: https://psyseal.com/#planes", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "reason": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": true } } } }, "503": { "description": "x402 is turned off.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "reason": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": true } } } }, "422": { "description": "A required check did not pass; nothing was charged and any seal is suspended.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": false }, "reason": { "type": "string" } }, "required": [ "ok", "reason" ], "additionalProperties": true } } } } } } } }, "components": { "parameters": { "SealId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z2-9]{12}$" }, "description": "The 12-character code of the seal." } }, "schemas": { "KeySet": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "kty": { "const": "OKP" }, "crv": { "const": "Ed25519" }, "x": { "type": "string" }, "kid": { "type": "string" } }, "required": [ "kty", "crv", "x" ] } } } }, "SealPayload": { "type": "object", "description": "Signed data. sig = Ed25519 over UTF-8 JSON of this object with sorted keys and no whitespace.", "properties": { "v": { "type": "string" }, "id": { "type": "string" }, "agent": { "type": "string", "description": "Public agent identifier derived from its fingerprint." }, "platform": { "type": "string", "enum": [ "openclaw", "hermes", "nanobot", "picoclaw", "zeroclaw", "nanoclaw", "generic" ] }, "label": { "type": "string" }, "checks": { "type": "object", "description": "Required: secrets, injection, permissions. Optional: memory, schedules.", "additionalProperties": { "type": "string", "enum": [ "pass", "warn", "fail", "na" ] } }, "state": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Fingerprint of the checked files (not their content)." }, "scanner": { "type": "string", "description": "Scanner version that ran the checks." }, "issued_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "issuer": { "type": "string", "format": "uri" } } }, "Seal": { "type": "object", "required": [ "status", "key_url" ], "properties": { "status": { "type": "string", "enum": [ "active", "suspended", "expired", "voided" ], "description": "active: passed the required checks and within its term. suspended: a required check stopped passing, or a report or the public name is under review. expired: past its date or the paid period ended. voided: permanent (the program or its results were altered, or the seal was shown on another agent)." }, "payload": { "$ref": "#/components/schemas/SealPayload" }, "sig": { "type": "string", "description": "base64url, no padding." }, "alg": { "const": "Ed25519" }, "kid": { "type": "string" }, "key_url": { "type": "string", "format": "uri" }, "last_check_at": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "enum": [ "name_suspended" ] } } }, "SealRequest": { "type": "object", "required": [ "agent", "state_hash", "scanner", "checks" ], "properties": { "agent": { "type": "object", "required": [ "hash", "platform" ], "properties": { "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "SHA-256 fingerprint of the agent, computed by Psyseal's program on the owner's computer." }, "platform": { "type": "string", "enum": [ "openclaw", "hermes", "nanobot", "picoclaw", "zeroclaw", "nanoclaw", "generic" ] }, "label": { "type": "string", "maxLength": 32, "description": "Optional public name shown on the seal page. No personal data." } } }, "state_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "scanner": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" }, "checks": { "type": "object", "required": [ "secrets", "injection", "permissions" ], "properties": { "secrets": { "type": "string", "enum": [ "pass", "warn", "fail", "na" ] }, "injection": { "type": "string", "enum": [ "pass", "warn", "fail", "na" ] }, "permissions": { "type": "string", "enum": [ "pass", "warn", "fail", "na" ] }, "memory": { "type": "string", "enum": [ "pass", "warn", "fail", "na" ] }, "schedules": { "type": "string", "enum": [ "pass", "warn", "fail", "na" ] } }, "additionalProperties": false } } }, "IssuedSeal": { "type": "object", "properties": { "ok": { "const": true }, "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "badge": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" }, "payload": { "$ref": "#/components/schemas/SealPayload" }, "sig": { "type": "string" }, "kid": { "type": "string" } } }, "Pass": { "type": "object", "properties": { "ok": { "const": true }, "tier": { "type": "string", "enum": [ "seal", "full" ] }, "paid": { "type": "boolean", "description": "true if this call charged a payment." }, "paid_until": { "type": "string", "format": "date-time" } } } } } }