{
  "openapi": "3.0.3",
  "info": {
    "title": "NEUS Public API",
    "version": "1.0.0",
    "description": "Public interface for creating and resolving cryptographic proofs. Includes health checks, verification polling, verifier discovery, and gate evaluation.",
    "contact": {
      "name": "NEUS",
      "url": "https://neus.network",
      "email": "dev@neus.network"
    },
    "license": {
      "name": "Apache-2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "servers": [
    {
      "url": "https://api.neus.network",
      "description": "Production API"
    }
  ],
  "security": [],
  "tags": [
    { "name": "Health", "description": "Health and readiness probes" },
    { "name": "Verification", "description": "Submit verifications and poll status" },
    { "name": "Verifiers", "description": "Deployment verifier discovery" },
    { "name": "Proofs", "description": "Proof reads, gating checks, and revocation" }
  ],
  "components": {
    "schemas": {
      "VerificationRequest": {
        "type": "object",
        "required": [
          "verifierIds",
          "data",
          "walletAddress",
          "signature",
          "signedTimestamp"
        ],
        "properties": {
          "verifierIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "ownership-basic"
            ],
            "description": "Array of verifier IDs to execute"
          },
          "data": {
            "$ref": "#/components/schemas/VerificationData"
          },
          "walletAddress": {
            "type": "string",
            "description": "Signer address/public key (EVM: 0x…; Solana: base58 public key)"
          },
          "signature": {
            "type": "string",
            "description": "Signature of the NEUS Standard Signing String (EVM: 0x… hex; Solana: base58)"
          },
          "signedTimestamp": {
            "type": "number",
            "example": 1678886400000,
            "description": "Unix timestamp in milliseconds"
          },
          "chainId": {
            "type": "integer",
            "example": 84532,
            "description": "EVM chainId for signature context (legacy EVM mode)"
          },
          "chain": {
            "type": "string",
            "description": "CAIP-2 chain reference for universal mode (e.g. eip155:1, solana:mainnet)"
          },
          "signatureMethod": {
            "type": "string",
            "description": "Signature method hint for universal mode (eip191, ed25519, ...)",
            "example": "eip191"
          },
          "options": {
            "type": "object",
            "properties": {
              "privacyLevel": {
                "type": "string",
                "enum": [
                  "private",
                  "public"
                ],
                "default": "private"
              },
              "targetChains": {
                "type": "array",
                "items": {
                  "type": "integer"
                },
                "example": [
                  11155111
                ],
                "description": "Testnet chains for proof storage: 11155111, 80002, 421614, 11155420"
              },
              "enableIpfs": {
                "type": "boolean",
                "default": false
              },
              "publicDisplay": {
                "type": "boolean",
                "default": false
              },
              "storeOriginalContent": {
                "type": "boolean",
                "default": false
              },
              "forceZK": {
                "type": "boolean",
                "default": false,
                "deprecated": true,
                "description": "Deprecated. Bonsai ZK execution is handled internally by specific verifier flows; most deployments ignore this flag."
              },
              "meta": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "StandardizeRequest": {
        "type": "object",
        "required": [
          "walletAddress",
          "verifierIds",
          "data",
          "signedTimestamp"
        ],
        "properties": {
          "walletAddress": {
            "type": "string",
            "description": "Signer address/public key (EVM: 0x…; Solana: base58 public key)"
          },
          "verifierIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "data": {
            "$ref": "#/components/schemas/VerificationData"
          },
          "signedTimestamp": {
            "type": "integer",
            "description": "Unix timestamp in milliseconds"
          },
          "chainId": {
            "type": "integer",
            "default": 84532
          },
          "chain": {
            "type": "string",
            "description": "CAIP-2 chain reference for universal mode (e.g. eip155:1, solana:mainnet)"
          },
          "signatureMethod": {
            "type": "string",
            "description": "Signature method hint for universal mode (eip191, ed25519, ...)"
          }
        }
      },
      "RevokeRequest": {
        "type": "object",
        "required": [
          "walletAddress",
          "signature",
          "signedTimestamp"
        ],
        "properties": {
          "walletAddress": {
            "type": "string",
            "description": "Signer address/public key (EVM: 0x…; Solana: base58 public key)"
          },
          "signature": {
            "type": "string"
          },
          "signedTimestamp": {
            "type": "number"
          }
        }
      },
      "AccessGrantRequest": {
        "type": "object",
        "required": [
          "qHash",
          "ownerWallet",
          "viewerWallet",
          "signature",
          "signedTimestamp"
        ],
        "properties": {
          "qHash": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{64}$",
            "description": "Proof ID (qHash) to grant access to"
          },
          "ownerWallet": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$",
            "description": "Owner wallet (must match proof.walletAddress)"
          },
          "viewerWallet": {
            "type": "string",
            "pattern": "^0x[a-fA-F0-9]{40}$",
            "description": "Viewer wallet to grant access to"
          },
          "signature": {
            "type": "string",
            "description": "Owner signature over Standard Signing String (action=grant_proof_access)"
          },
          "signedTimestamp": {
            "type": "number",
            "description": "Unix timestamp in milliseconds (5-minute freshness window enforced server-side)"
          },
          "expiresInSeconds": {
            "type": "number",
            "description": "Grant TTL in seconds (default 900, min 60, max 86400)",
            "example": 900
          }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object"
          },
          "status": {
            "type": "string"
          },
          "timestamp": {
            "type": "number"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "VALIDATION_ERROR"
              },
              "message": {
                "type": "string",
                "example": "Invalid input"
              },
              "type": {
                "type": "string",
                "example": "ValidationError"
              },
              "details": {
                "description": "Optional structured details (field-level errors, missing fields, etc.)",
                "oneOf": [
                  { "type": "object" },
                  { "type": "array" }
                ]
              }
            }
          },
          "timestamp": {
            "type": "number"
          }
        }
      },
      "VerificationResult": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "example": "verified"
          },
          "data": {
            "type": "object",
            "properties": {
              "qHash": {
                "type": "string",
                "pattern": "^0x[a-fA-F0-9]{64}$",
                "example": "0xabcdef..."
              },
              "status": {
                "type": "string"
              },
              "walletAddress": {
                "type": "string"
              },
              "verifierIds": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "verifiedVerifiers": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/VerifiedVerifier"
                }
              },
              "options": {
                "type": "object"
              },
              "meta": {
                "type": "object"
              },
              "createdAt": {
                "type": "number"
              },
              "completedAt": {
                "type": "number"
              },
              "lastUpdated": {
                "type": "number"
              },
              "revokedAt": {
                "type": "number",
                "nullable": true
              },
              "crosschain": {
                "type": "object"
              },
              "hubTransaction": {
                "type": "object"
              },
              "ipfs": {
                "type": "object"
              }
            }
          }
        }
      },
      "VerificationAccepted": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "status": {
            "type": "string",
            "example": "processing_verifiers"
          },
          "message": {
            "type": "string",
            "example": "Verification accepted for processing"
          },
          "data": {
            "type": "object",
            "properties": {
              "qHash": {
                "type": "string"
              },
              "statusUrl": {
                "type": "string"
              }
            }
          }
        }
      },
      "VerifiedVerifier": {
        "type": "object",
        "properties": {
          "verifierId": { "type": "string" },
          "verified": { "type": "boolean" },
          "status": { "type": "string" },
          "data": { "type": "object" },
          "zkInfo": {
            "type": "object",
            "properties": {
              "zkStatus": { "type": "string" }
            }
          }
        }
      },
      "ProofRecord": {
        "type": "object",
        "properties": {
          "qHash": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$" },
          "status": { "type": "string" },
          "walletAddress": { "type": "string" },
          "verifierIds": { "type": "array", "items": { "type": "string" } },
          "verifiedVerifiers": { "type": "array", "items": { "$ref": "#/components/schemas/VerifiedVerifier" } },
          "options": { "type": "object" },
          "meta": { "type": "object" },
          "createdAt": { "type": "number" },
          "completedAt": { "type": "number" },
          "lastUpdated": { "type": "number" },
          "revokedAt": { "type": "number", "nullable": true }
        }
      },
      "ProofsByWalletData": {
        "type": "object",
        "properties": {
          "proofs": { "type": "array", "items": { "$ref": "#/components/schemas/ProofRecord" } },
          "totalCount": { "type": "integer", "minimum": 0 },
          "hasMore": { "type": "boolean" },
          "nextOffset": { "type": "integer", "minimum": 0, "nullable": true }
        }
      },
      "ProofsByWalletResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "$ref": "#/components/schemas/ProofsByWalletData" }
        }
      },
      "GateCheckData": {
        "type": "object",
        "properties": {
          "eligible": { "type": "boolean" },
          "matchedCount": { "type": "integer", "minimum": 0 },
          "matchedQHashes": { "type": "array", "items": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$" } },
          "matchedTags": { "type": "array", "items": { "type": "string" } },
          "projections": { "type": "array", "items": { "type": "object" }, "nullable": true, "description": "Optional safe projection objects returned by some deployments. Treat as informational only; may be null or omitted." },
          "criteria": { "type": "object" }
        }
      },
      "GateCheckResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "$ref": "#/components/schemas/GateCheckData" }
        }
      },
      "HealthResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": {
            "type": "object",
            "properties": {
              "status": { "type": "string" },
              "timestamp": { "type": "string" },
              "uptime": { "type": "number" },
              "services": { "type": "object" },
              "issues": { "type": "array" }
            },
            "additionalProperties": true
          }
        }
      },
      "HealthReadyResponse": {
        "type": "object",
        "properties": {
          "ready": { "type": "boolean" },
          "timestamp": { "type": "string" },
          "message": { "type": "string" },
          "details": { "type": "object" },
          "error": { "type": "string" }
        },
        "additionalProperties": true
      },
      "HealthLiveResponse": {
        "type": "object",
        "properties": {
          "alive": { "type": "boolean" },
          "timestamp": { "type": "string" },
          "uptime": { "type": "number" },
          "version": { "type": "string" }
        }
      },
      "VerifiersListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "type": "array", "items": { "type": "string" } },
          "meta": {
            "type": "object",
            "properties": {
              "totalCount": { "type": "integer" },
              "accessLevel": { "type": "string" },
              "hubChainId": { "type": "integer" },
              "supportedProtocolChainIds": { "type": "array", "items": { "type": "integer" } },
              "supportedAssetChainIds": { "type": "array", "items": { "type": "integer" } }
            },
            "additionalProperties": true
          }
        }
      },
      "StandardizeResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "signerString": { "type": "string", "description": "Exact string to sign with wallet" },
              "bodyPreview": { "type": "object", "description": "Preview of normalized inputs" }
            }
          }
        }
      },
      "AccessGrantResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "qHash": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$" },
              "viewerWallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
              "expiresAt": { "type": "number" }
            }
          }
        }
      },
      "RevokeSelfResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "alreadyRevoked": { "type": "boolean" },
          "timestamp": { "type": "string" }
        }
      },
      "VerificationData": {
        "type": "object",
        "description": "Verification data (verifier-specific). For multi-verifier requests, prefer namespaced payloads: data[verifierId] = { ... }.",
        "anyOf": [
          { "$ref": "#/components/schemas/VerificationDataFlat" },
          { "$ref": "#/components/schemas/VerificationDataNamespaced" },
          { "type": "object", "additionalProperties": true, "description": "Fallback for custom/verifier-specific payloads not covered by the open-source core verifier set." }
        ],
        "example": {
          "content": "Hello NEUS",
          "owner": "0x742d35Cc6634C0532925a3b8D82AB78c0D73C3Db",
          "reference": { "type": "url", "id": "https://example.com" }
        }
      },
      "VerificationDataFlat": {
        "oneOf": [
          { "$ref": "#/components/schemas/VerifierDataOwnershipBasic" },
          { "$ref": "#/components/schemas/VerifierDataOwnershipPseudonym" },
          { "$ref": "#/components/schemas/VerifierDataOwnershipDnsTxt" },
          { "$ref": "#/components/schemas/VerifierDataContractOwnership" },
          { "$ref": "#/components/schemas/VerifierDataNftOwnership" },
          { "$ref": "#/components/schemas/VerifierDataTokenHolding" },
          { "$ref": "#/components/schemas/VerifierDataWalletRisk" },
          { "$ref": "#/components/schemas/VerifierDataWalletLink" },
          { "$ref": "#/components/schemas/VerifierDataAiContentModeration" },
          { "$ref": "#/components/schemas/VerifierDataAgentIdentity" },
          { "$ref": "#/components/schemas/VerifierDataAgentDelegation" }
        ]
      },
      "VerificationDataNamespaced": {
        "type": "object",
        "description": "Multi-verifier payload: keys are verifier IDs and values are that verifier's input object.",
        "additionalProperties": { "$ref": "#/components/schemas/VerificationDataFlat" }
      },
      "VerifierDataOwnershipBasic": {
        "type": "object",
        "required": ["owner"],
        "properties": {
          "content": { "type": "string", "maxLength": 50000, "description": "Content being claimed (max 50KB inline; use contentHash + IPFS for larger)" },
          "contentHash": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$", "description": "Pre-computed SHA-256 or keccak256 hash (optional if content provided)" },
          "contentType": { "type": "string", "maxLength": 100, "description": "MIME type hint for the content/reference (e.g., image/png, audio/mpeg, application/pdf)" },
          "owner": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Wallet address of the owner (must match request walletAddress)" },
          "reference": {
            "type": "object",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "ipfs",
                  "ipfs-hash",
                  "url",
                  "license-nft",
                  "contract",
                  "qhash",
                  "ethereum-tx",
                  "on-chain-tx",
                  "tx",
                  "file",
                  "doc",
                  "media",
                  "username-claim",
                  "other"
                ],
                "description": "Reference type for traceability"
              },
              "id": { "type": "string", "maxLength": 2048, "description": "Reference identifier (CID, URL, tx hash, chainId:address:tokenId, etc.)" },
              "title": { "type": "string", "maxLength": 200, "description": "Optional display title" },
              "description": { "type": "string", "maxLength": 500, "description": "Optional description" },
              "mime": { "type": "string", "maxLength": 100, "description": "MIME type for file references" },
              "name": { "type": "string", "maxLength": 255, "description": "Original filename for file references" },
              "size": { "type": "integer", "description": "File size in bytes" }
            }
          },
          "provenance": {
            "type": "object",
            "description": "Optional provenance metadata for content origin",
            "properties": {
              "declaredKind": { "type": "string", "enum": ["human", "ai", "mixed", "unknown"], "description": "Content creation type (advisory, not verified)" },
              "aiContext": {
                "type": "object",
                "description": "AI generation context (when declaredKind is ai or mixed)",
                "properties": {
                  "generatorType": { "type": "string", "enum": ["local", "saas", "agent"], "description": "Type of AI generator" },
                  "provider": { "type": "string", "maxLength": 64, "description": "AI provider (e.g., openai, anthropic, other)" },
                  "model": { "type": "string", "maxLength": 128, "description": "Model identifier (opaque string)" },
                  "runId": { "type": "string", "maxLength": 128, "description": "Internal inference/job ID" }
                }
              }
            }
          }
        }
      },
      "VerifierDataOwnershipPseudonym": {
        "type": "object",
        "required": ["pseudonymId"],
        "properties": {
          "pseudonymId": { "type": "string", "pattern": "^[a-z0-9._-]{3,64}$", "description": "Handle within a namespace" },
          "namespace": { "type": "string", "pattern": "^[a-z0-9._-]{1,64}$", "description": "Namespace (default: neus)" },
          "displayName": { "type": "string", "maxLength": 64, "description": "Human-readable display name" },
          "metadata": { "type": "object", "description": "App-specific metadata" }
        }
      },
      "VerifierDataOwnershipDnsTxt": {
        "type": "object",
        "required": ["domain"],
        "properties": {
          "domain": { "type": "string", "format": "hostname", "description": "Domain name to verify (e.g., neus.network)" },
          "walletAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Wallet address to match in DNS TXT record (optional; defaults to signer walletAddress)" }
        }
      },
      "VerifierDataContractOwnership": {
        "type": "object",
        "required": ["contractAddress", "chainId"],
        "properties": {
          "contractAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Contract address to verify" },
          "chainId": { "type": "integer", "description": "Chain ID where the contract is deployed (testnet or mainnet; must be supported/configured server-side)" },
          "walletAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Wallet claiming ownership (optional; defaults to signer walletAddress)" },
          "method": { "type": "string", "enum": ["owner", "admin", "accessControl"], "description": "Optional: specific method to check" }
        }
      },
      "VerifierDataNftOwnership": {
        "type": "object",
        "required": ["contractAddress", "tokenId", "chainId"],
        "properties": {
          "ownerAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "NFT owner address (optional). If omitted, defaults to the signed request walletAddress. Deployments may allow delegated subject checks, but the server will not accept subject overrides that break signature binding." },
          "contractAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "NFT contract address" },
          "tokenId": { "type": "string", "description": "NFT token ID" },
          "tokenType": { "type": "string", "enum": ["erc721", "erc1155"], "description": "Token standard (default: erc721)" },
          "chainId": { "type": "integer", "description": "Chain ID where the NFT contract is deployed (testnet or mainnet; must be supported/configured server-side)" },
          "blockNumber": { "type": "integer", "description": "Optional specific block number for point-in-time ownership checks" }
        }
      },
      "VerifierDataTokenHolding": {
        "type": "object",
        "required": ["contractAddress", "minBalance", "chainId"],
        "properties": {
          "ownerAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Token holder address (optional). If omitted, defaults to the signed request walletAddress. Deployments may allow delegated subject checks, but the server will not accept subject overrides that break signature binding." },
          "contractAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Token contract address" },
          "minBalance": { "type": "string", "description": "Minimum token balance required (human-readable units, e.g., \"10.5\")" },
          "chainId": { "type": "integer", "description": "Chain ID where the token contract is deployed (testnet or mainnet; must be supported/configured server-side)" },
          "blockNumber": { "type": "integer", "description": "Optional specific block number for point-in-time balance checks" }
        }
      },
      "VerifierDataWalletRisk": {
        "type": "object",
        "properties": {
          "provider": { "type": "string", "description": "Risk assessment provider hint. Known value: webacy." },
          "walletAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Wallet address to assess (optional; defaults to signer walletAddress)" },
          "chainId": { "type": "integer", "description": "Chain ID for context" },
          "includeDetails": { "type": "boolean", "description": "Include detailed risk breakdown" }
        }
      },
      "VerifierDataWalletLink": {
        "type": "object",
        "required": ["primaryWalletAddress", "secondaryWalletAddress", "signature", "chainId", "signedTimestamp"],
        "properties": {
          "primaryWalletAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Primary wallet (owner)" },
          "secondaryWalletAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Secondary wallet (must sign)" },
          "signature": { "type": "string", "description": "EIP-191 signature from secondary wallet over canonical message" },
          "chainId": { "type": "integer", "description": "Chain ID for link context" },
          "signedTimestamp": { "type": "integer", "description": "Unix timestamp (ms) when signed" },
          "relationshipType": { "type": "string", "enum": ["primary", "personal", "org", "affiliate", "agent", "linked"], "description": "Relationship type for identity graph categorization" },
          "label": { "type": "string", "maxLength": 64, "description": "Human-readable label for this wallet" }
        }
      },
      "VerifierDataAiContentModeration": {
        "type": "object",
        "required": ["content", "contentType"],
        "properties": {
          "content": { "type": "string", "maxLength": 13653334, "description": "Moderation input. For images: base64 content or an IPFS reference (ipfs://<cid>). For text: raw UTF-8 text (size-limited)." },
          "contentType": {
            "type": "string",
            "enum": [
              "image/jpeg",
              "image/png",
              "image/webp",
              "image/gif",
              "text/plain",
              "text/markdown",
              "text/x-markdown",
              "application/json",
              "application/xml"
            ],
            "description": "MIME type. The server tolerates charset suffixes (e.g., \"text/plain; charset=utf-8\")."
          },
          "provider": { "type": "string", "description": "Moderation provider override. Known values: google-vision, google-perspective." }
        }
      },
      "VerifierDataAgentIdentity": {
        "type": "object",
        "required": ["agentId", "agentWallet"],
        "properties": {
          "agentId": { "type": "string", "maxLength": 128, "description": "Unique string identifier (e.g., neus-bot-1)" },
          "agentWallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Agent wallet address (must match signer)" },
          "agentLabel": { "type": "string", "maxLength": 128, "description": "Human-readable display name" },
          "agentType": { "type": "string", "enum": ["ai", "bot", "service", "automation", "agent"], "description": "Type of agent for categorization" },
          "description": { "type": "string", "maxLength": 500, "description": "Brief description of what this agent does" },
          "capabilities": { "type": "array", "description": "List of capabilities (e.g., trading, posting, payments)" }
        }
      },
      "VerifierDataAgentDelegation": {
        "type": "object",
        "required": ["controllerWallet", "agentWallet"],
        "properties": {
          "controllerWallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Controller wallet (must sign the delegation)" },
          "agentWallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Agent receiving authority" },
          "agentId": { "type": "string", "maxLength": 128, "description": "Agent ID for linking to agent-identity proof" },
          "scope": { "type": "string", "maxLength": 128, "description": "Scope of delegation (e.g., payments:x402, trading, posting, global)" },
          "permissions": { "type": "array", "description": "Granular permission list (e.g., [\"read\", \"write\", \"execute\"])" },
          "maxSpend": { "type": "string", "description": "Maximum spend limit in wei (for payments:x402 scope)" },
          "allowedPaymentTypes": { "type": "array", "description": "Declared allowed payment protocols for this delegation (e.g., [\"x402\"]). Metadata-only.", "items": { "type": "string", "maxLength": 32 } },
          "receiptDisclosure": { "type": "string", "enum": ["none", "summary", "full"], "description": "Receipt disclosure policy for economic actions (metadata-only). Recommended: summary." },
          "expiresAt": { "type": "integer", "description": "Expiration timestamp (ms). Recommended for security." }
        }
      }
    }
  },
  "paths": {
    "/api/v1/health": {
      "get": {
        "tags": ["Health"],
        "operationId": "healthGet",
        "summary": "API health check",
        "description": "Check if the API is operational",
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          },
          "503": {
            "description": "Unhealthy",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/health/ready": {
      "get": {
        "tags": ["Health"],
        "operationId": "healthReadyGet",
        "summary": "Readiness probe",
        "description": "Infrastructure readiness probe. Returns 200 when critical dependencies are ready.",
        "responses": {
          "200": {
            "description": "Ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthReadyResponse"
                }
              }
            }
          },
          "503": {
            "description": "Not ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthReadyResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/health/live": {
      "get": {
        "tags": ["Health"],
        "operationId": "healthLiveGet",
        "summary": "Liveness probe",
        "description": "Infrastructure liveness probe. Returns 200 if the process is alive.",
        "responses": {
          "200": {
            "description": "Alive",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthLiveResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/verification": {
      "post": {
        "tags": ["Verification"],
        "operationId": "verificationSubmit",
        "summary": "Submit verification request",
        "description": "Create cryptographic proof of ownership, assets, or credentials. Signed request-body using the NEUS Standard Signing String (6-line).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerificationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification completed immediately",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResult"
                }
              }
            }
          },
          "202": {
            "description": "Verification accepted for async processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid signature",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/verification/status/{qHash}": {
      "get": {
        "tags": ["Verification"],
        "operationId": "verificationStatusGet",
        "summary": "Get verification status",
        "description": "Check status of a verification by qHash. Public proofs return full data. Private proofs return full data only for the owner when authenticated; otherwise returns a sanitized status.",
        "parameters": [
          {
            "name": "qHash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{64}$"
            },
            "example": "0x57ef6af456233537b63a9afe43dedd02b17d00e0a94b764cf96115bce5260329"
          },
          {
            "name": "x-wallet-address",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Owner wallet address (optional; used for owner checks)"
          },
          {
            "name": "x-signature",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Owner signature over NEUS Standard Signing String with data.action='access_private_proof' and data.qHash (optional; enables private-proof access)"
          },
          {
            "name": "x-signed-timestamp",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Signed timestamp (ms) used in the Standard Signing String (optional)"
          }
        ],
        "responses": {
          "200": {
            "description": "Status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResult"
                }
              }
            }
          },
          "404": {
            "description": "Proof not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid signature (when attempting private access)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/verification/verifiers": {
      "get": {
        "tags": ["Verifiers"],
        "operationId": "verifiersList",
        "summary": "List available verifiers",
        "description": "Get list of public verifier IDs",
        "responses": {
          "200": {
            "description": "Verifiers retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerifiersListResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/verification/standardize": {
      "post": {
        "tags": ["Verification"],
        "operationId": "verificationStandardize",
        "summary": "Build Standard Signing String",
        "description": "Get exact string to sign for verification (troubleshooting)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StandardizeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signing string generated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StandardizeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/verification/access/grant": {
      "post": {
        "tags": ["Verification"],
        "operationId": "verificationAccessGrant",
        "summary": "Grant viewer access to a private proof (owner-signed, short-lived)",
        "description": "Stores a short-lived grant for a viewer wallet to read a private proof record (does not change privacyLevel/publicDisplay). Requires Redis.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccessGrantRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Grant created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccessGrantResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid signature",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Proof not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable (e.g., Redis required)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/proofs/gate/check": {
      "get": {
        "tags": ["Proofs"],
        "operationId": "proofsGateCheckGet",
        "summary": "Gate evaluation (proof presence + criteria matching)",
        "description": "Evaluate whether a wallet satisfies verifier and metadata criteria against PUBLIC/DISCOVERABLE proofs only (privacyLevel=public + publicDisplay=true).",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          },
          {
            "name": "verifierIds",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated verifier IDs"
          },
          {
            "name": "requireAll",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "minCount",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          },
          {
            "name": "sinceDays",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Require proofs created within the last N days"
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0
            },
            "description": "Require proofs created after this unix timestamp (ms)"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            },
            "description": "Max rows to scan (server may clamp)"
          },
          {
            "name": "referenceType",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "referenceId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated reference IDs"
          },
          {
            "name": "content",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contentHash",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{64}$"
            }
          },
          {
            "name": "contentType",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contractAddress",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          },
          {
            "name": "tokenId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chainId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "minBalance",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ownerAddress",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          },
          {
            "name": "provider",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "riskLevel",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sanctioned",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "poisoned",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "primaryWalletAddress",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          },
          {
            "name": "secondaryWalletAddress",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{40}$"
            }
          },
          {
            "name": "verificationMethod",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Contract ownership method (owner/admin/accessControl)"
          },
          {
            "name": "tag",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tags",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated tags"
          }
        ],
        "responses": {
          "200": {
            "description": "Gate result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GateCheckResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/proofs/byWallet/{address}": {
      "get": {
        "tags": ["Proofs"],
        "operationId": "proofsByWalletGet",
        "summary": "Get proofs by wallet",
        "description": "Retrieve verification proofs for a wallet address or DID. Public returns discoverable proofs. Owner access to private proofs requires owner authentication.",
        "parameters": [
          {
            "name": "address",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Wallet address (0x...) or DID (did:pkh:...)"
          },
          {
            "name": "x-wallet-address",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Owner wallet address (optional; must match path address for private access)"
          },
          {
            "name": "x-signature",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Owner signature over NEUS Standard Signing String with data.action='access_private_proofs_by_wallet' (optional; enables private proofs)"
          },
          {
            "name": "x-signed-timestamp",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Signed timestamp (ms) used in the Standard Signing String (optional)"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Proofs retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProofsByWalletResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Invalid signature (when attempting private access)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/proofs/{qHash}/revoke-self": {
      "post": {
        "tags": ["Proofs"],
        "operationId": "proofsRevokeSelf",
        "summary": "Revoke your own proof",
        "description": "Revoke a proof you own using a wallet signature (Standard Signing String).",
        "parameters": [
          {
            "name": "qHash",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^0x[a-fA-F0-9]{64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RevokeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Proof revoked successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RevokeSelfResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid signature",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Not proof owner",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "500": {
            "description": "Internal error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  }
}