openapi: 3.2.0 info: title: Agent Verification Utility Decision Support API version: 0.4.3 description: A deterministic, x402-paid JSON evidence verification service for external agents. The service attests that declared checks were executed; it does not attest real-world truth. license: name: UNLICENSED servers: - url: / description: Relative to the current deployment origin security: [] tags: - name: decision-support description: Free use-case selection and request validation before payment paths: /verification-recipes.json: get: operationId: getVerificationRecipes summary: Get deterministic verification use-case recipes description: Explains when to use or avoid the utility, the risk each recipe reduces, its limitations, a free precheck, the paid execution path, and result interpretation. Recipe checks operate only over supplied bytes and perform no on-chain lookup. tags: - decision-support responses: '200': description: Stable versioned verification recipe document content: application/json: schema: $ref: '#/components/schemas/VerificationRecipes' '503': $ref: '#/components/responses/Unavailable' /.well-known/verification-recipes.json: get: operationId: getWellKnownVerificationRecipes summary: Get verification recipes from the well-known alias description: Returns HTTP 200 with the same JSON document as /verification-recipes.json; it is not a redirect. tags: - decision-support responses: '200': description: The same verification recipe document as /verification-recipes.json content: application/json: schema: $ref: '#/components/schemas/VerificationRecipes' '503': $ref: '#/components/responses/Unavailable' /validate-request: post: operationId: validateVerificationRequest summary: Validate a verification request for free without executing it description: Checks the verification request and an explicit spend policy containing the maximum atomic price, network, asset, payee, and policy version. It returns an unsigned precheck receipt binding those constraints to the canonical request and evidence hashes. The live x402 manifest and D1 runtime price are not fetched; the paid path recomputes the precheck and refuses stale or incompatible terms before any quote, payment, D1 write, or Verification Core call. This endpoint performs no external fetch, creates no quote, transaction, or payment, executes no assertion, returns no signed evidence, and retains or logs no raw evidence. tags: - decision-support requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VerificationPrecheckIntent' responses: '200': description: Request is structurally valid and supported; verification was not executed content: application/json: schema: $ref: '#/components/schemas/FreeRequestValidation' '400': description: Invalid or unsupported input with a machine-readable reason code content: application/json: schema: $ref: '#/components/schemas/FreeRequestValidationFailure' '503': $ref: '#/components/responses/Unavailable' components: schemas: VerificationSpendPolicy: type: object additionalProperties: false required: - policy_version - max_amount_atomic - network - asset - pay_to properties: policy_version: type: string const: agent-economy/precheck-policy/2.0 max_amount_atomic: type: string maxLength: 16 pattern: ^[1-9][0-9]*$ description: Client-authorized maximum price in atomic USDC units. It must fit in the JavaScript safe-integer range. network: type: string enum: - eip155:84532 - eip155:8453 asset: type: string pattern: ^0x[a-fA-F0-9]{40}$ pay_to: type: string pattern: ^0x[a-fA-F0-9]{40}$ PrecheckReceipt: type: object additionalProperties: false required: - schema_version - policy_version - service_version - attestation - decision - spend_policy - spend_policy_check - request_check - checked_urls - mcp_server_card - a2a - x402_terms - unpaid_status - dropped_evidence - receipt_digest properties: schema_version: type: string const: agent-economy/precheck-receipt/2.0 policy_version: type: string const: agent-economy/precheck-policy/2.0 service_version: type: string attestation: type: object additionalProperties: false required: - level - signed - verification_mode - external_fetch properties: level: type: string const: unsigned_precheck signed: type: boolean const: false verification_mode: type: string const: server_local external_fetch: type: boolean const: false decision: type: object additionalProperties: false required: - recommendation - explicit_payment_authorization_required - refusal_allowed - spend_authorized - refusal_reason properties: recommendation: type: string enum: - review_before_payment - refuse_paid_call explicit_payment_authorization_required: type: boolean const: true refusal_allowed: type: boolean const: true spend_authorized: type: boolean refusal_reason: type: - string - 'null' pattern: ^[A-Z0-9_]+$ spend_policy: oneOf: - $ref: '#/components/schemas/VerificationSpendPolicy' - type: 'null' spend_policy_check: type: object additionalProperties: false required: - allowed - reason_code - configured_amount_atomic - configured_network - configured_asset - configured_pay_to properties: allowed: type: boolean reason_code: type: - string - 'null' pattern: ^[A-Z0-9_]+$ configured_amount_atomic: type: string pattern: ^[1-9][0-9]*$ configured_network: type: string enum: - eip155:84532 - eip155:8453 configured_asset: type: string pattern: ^0x[a-fA-F0-9]{40}$ configured_pay_to: type: string pattern: ^0x[a-fA-F0-9]{40}$ request_check: type: object additionalProperties: false required: - valid - supported - reason_code - request_hash - assertion_count properties: valid: type: boolean supported: type: boolean reason_code: type: - string - 'null' pattern: ^[A-Z0-9_]+$ request_hash: oneOf: - $ref: '#/components/schemas/Sha256Digest' - type: 'null' assertion_count: type: - integer - 'null' minimum: 1 maximum: 16 checked_urls: type: array minItems: 4 maxItems: 4 items: type: object additionalProperties: false required: - role - method - url - check - result properties: role: type: string enum: - free_precheck - mcp_server_card - a2a_agent_card - x402_manifest method: type: string enum: - GET - POST url: type: string format: uri check: type: string enum: - request_contract - server_local_contract - configured_baseline_only result: type: string enum: - pass - fail - not_fetched mcp_server_card: type: object additionalProperties: false required: - url - canonical_sha256 - canonicalization properties: url: type: string format: uri canonical_sha256: $ref: '#/components/schemas/Sha256Digest' canonicalization: type: string const: RFC8785 a2a: type: object additionalProperties: false required: - card_url - endpoint - protocol_binding - protocol_version - streaming - push_notifications - extended_agent_card - paid_execution_automatic properties: card_url: type: string format: uri endpoint: type: string format: uri protocol_binding: type: string const: JSONRPC protocol_version: type: string const: '1.0' streaming: type: boolean const: false push_notifications: type: boolean const: false extended_agent_card: type: boolean const: false paid_execution_automatic: type: boolean const: false x402_terms: type: object additionalProperties: false required: - status - manifest_url - x402_version - scheme - network - asset - amount_atomic - symbol - decimals - pay_to - resources - terms_source - live_manifest_checked - runtime_price_checked - authoritative_terms_source - payment_challenge_must_match properties: status: type: string const: configured_baseline manifest_url: type: string format: uri x402_version: type: integer const: 2 scheme: type: string const: exact network: type: string enum: - eip155:84532 - eip155:8453 asset: type: string pattern: ^0x[a-fA-F0-9]{40}$ amount_atomic: type: string pattern: ^[0-9]+$ symbol: type: string const: USDC decimals: type: integer const: 6 pay_to: type: string pattern: ^0x[a-fA-F0-9]{40}$ resources: type: array minItems: 2 maxItems: 2 items: type: object additionalProperties: false required: - transport - method - url properties: transport: type: string enum: - http - mcp method: type: string const: POST url: type: string format: uri tool: type: string const: verify_evidence terms_source: type: string const: server_configuration live_manifest_checked: type: boolean const: false runtime_price_checked: type: boolean const: false authoritative_terms_source: type: string const: payment_requirement payment_challenge_must_match: type: boolean const: true unpaid_status: type: object additionalProperties: false required: - state - payment_required - payment_authorized - quote_created - transaction_created - verification_executed properties: state: type: string const: unpaid payment_required: type: boolean const: false payment_authorized: type: boolean const: false quote_created: type: boolean const: false transaction_created: type: boolean const: false verification_executed: type: boolean const: false dropped_evidence: type: object additionalProperties: false required: - handling - content_sha256 - decoded_bytes - raw_evidence_retained - raw_evidence_persisted - raw_evidence_logged - raw_evidence_returned properties: handling: type: string enum: - discard_after_validation - not_retained content_sha256: oneOf: - $ref: '#/components/schemas/Sha256Digest' - type: 'null' decoded_bytes: oneOf: - type: integer minimum: 1 maximum: 65536 - type: 'null' raw_evidence_retained: type: boolean const: false raw_evidence_persisted: type: boolean const: false raw_evidence_logged: type: boolean const: false raw_evidence_returned: type: boolean const: false receipt_digest: $ref: '#/components/schemas/Sha256Digest' RefusedPaidVerificationBinding: allOf: - $ref: '#/components/schemas/PaidVerificationBinding' - properties: state: const: refused FreeRequestValidationFailure: type: object additionalProperties: false required: - schema_version - valid - verification_executed - payment_required - supported - reason_code - message - request_id - canonical_offer - machine_quote - precheck_receipt - next_step properties: schema_version: type: string const: agent-economy/request-validation/3.0 valid: type: boolean const: false verification_executed: type: boolean const: false payment_required: type: boolean const: false supported: type: boolean const: false reason_code: type: string pattern: ^[A-Z0-9_]+$ message: type: string request_id: type: string canonical_offer: $ref: '#/components/schemas/CanonicalOffer' machine_quote: $ref: '#/components/schemas/MachineQuote' precheck_receipt: $ref: '#/components/schemas/PrecheckReceipt' next_step: type: string InlineJsonEvidence: type: object additionalProperties: false required: - media_type - content_base64 properties: media_type: type: string const: application/json content_base64: type: string contentEncoding: base64 contentMediaType: application/json maxLength: 87384 description: Strict Base64. Decoded UTF-8 JSON must be between 1 byte and 65536 bytes. Assertion: oneOf: - $ref: '#/components/schemas/Sha256EqualsAssertion' - $ref: '#/components/schemas/JsonPointerExistsAssertion' - $ref: '#/components/schemas/JsonPointerEqualsAssertion' - $ref: '#/components/schemas/JsonTypeIsAssertion' discriminator: propertyName: op Sha256EqualsAssertion: type: object additionalProperties: false required: - op - expected_hex properties: op: type: string const: sha256_equals expected_hex: type: string pattern: ^[a-f0-9]{64}$ ErrorResponse: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - code - message - request_id - retryable properties: code: type: string pattern: ^[A-Z0-9_]+$ message: type: string request_id: type: string retryable: type: boolean details: type: object properties: paid_verification_binding: $ref: '#/components/schemas/RefusedPaidVerificationBinding' additionalProperties: true JsonPointerEqualsAssertion: type: object additionalProperties: false required: - op - path - expected properties: op: type: string const: json_pointer_equals path: $ref: '#/components/schemas/JsonPointer' expected: description: Any JSON value. Equality is deterministic structural JSON equality. CanonicalSchemaReference: type: object additionalProperties: false required: - schema_id - schema_digest properties: schema_id: type: string schema_digest: $ref: '#/components/schemas/Sha256Digest' VerificationRecipes: type: object additionalProperties: false required: - schema_version - service - version - stable_document_marker - recipes - important_notice properties: schema_version: type: string const: agent-economy/verification-recipes/1.0 service: type: string const: agent-verification-utility version: type: string stable_document_marker: type: string important_notice: type: string recipes: type: array minItems: 3 items: type: object additionalProperties: false required: - id - title - description - use_when - do_not_use_when - risk_reduced - limitations - free_precheck - paid_execution - price - network - supported_assertions - request_example - precheck_intent_example - expected_output_summary - mcp_tool - http_endpoint - jwks_url - agent_skill_url properties: id: type: string title: type: string description: type: string use_when: type: array minItems: 1 items: type: string do_not_use_when: type: array minItems: 1 items: type: string risk_reduced: type: string limitations: type: array minItems: 1 items: type: string free_precheck: type: object additionalProperties: true paid_execution: type: object additionalProperties: true price: type: object additionalProperties: true network: type: string enum: - eip155:84532 - eip155:8453 supported_assertions: type: array items: type: string enum: - sha256_equals - json_pointer_exists - json_pointer_equals - json_type_is request_example: $ref: '#/components/schemas/VerifyEvidenceRequest' precheck_intent_example: $ref: '#/components/schemas/VerificationPrecheckIntent' expected_output_summary: type: string mcp_tool: type: string const: verify_evidence http_endpoint: type: string format: uri jwks_url: type: string format: uri agent_skill_url: type: string format: uri JsonTypeIsAssertion: type: object additionalProperties: false required: - op - path - expected_type properties: op: type: string const: json_type_is path: $ref: '#/components/schemas/JsonPointer' expected_type: type: string enum: - 'null' - boolean - number - string - array - object VerifyEvidenceRequest: type: object additionalProperties: false required: - client_request_id - evidence - assertions properties: client_request_id: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z0-9._:-]+$ evidence: $ref: '#/components/schemas/InlineJsonEvidence' assertions: type: array minItems: 1 maxItems: 16 items: $ref: '#/components/schemas/Assertion' JsonPointer: type: string maxLength: 512 description: RFC 6901 JSON Pointer; the empty string addresses the whole document. CanonicalOffer: type: object additionalProperties: false required: - schema_version - service_id - service_version - generation_id - tool - input - output - pricing - free_precheck - facts_only properties: schema_version: type: integer const: 1 service_id: type: string const: dev.kgninja.agent-economy/agent-verification-utility service_version: type: string generation_id: type: string pattern: ^agent-economy/offer-generation/ tool: type: object additionalProperties: false required: - name - summary - use_when - do_not_use_when properties: name: type: string const: verify_evidence summary: type: string use_when: type: array items: type: string do_not_use_when: type: array items: type: string input: $ref: '#/components/schemas/CanonicalSchemaReference' output: type: object additionalProperties: false required: - schema_id - schema_digest - deterministic - signed_evidence - receipt properties: schema_id: type: string schema_digest: $ref: '#/components/schemas/Sha256Digest' deterministic: type: boolean const: true signed_evidence: type: boolean const: true receipt: type: boolean const: true pricing: type: object additionalProperties: false required: - payment_protocol - network - asset - pay_to - amount_base_unit - display_amount properties: payment_protocol: type: string const: x402-v2-exact network: type: string enum: - eip155:84532 - eip155:8453 asset: type: string pattern: ^0x[a-fA-F0-9]{40}$ pay_to: type: string pattern: ^0x[a-fA-F0-9]{40}$ amount_base_unit: type: string pattern: ^[1-9][0-9]*$ display_amount: type: string free_precheck: type: object additionalProperties: false required: - available properties: available: type: boolean const: true facts_only: type: boolean const: true VerificationPrecheckIntent: type: object additionalProperties: false required: - request - spend_policy properties: request: $ref: '#/components/schemas/VerifyEvidenceRequest' spend_policy: $ref: '#/components/schemas/VerificationSpendPolicy' JsonPointerExistsAssertion: type: object additionalProperties: false required: - op - path properties: op: type: string const: json_pointer_exists path: $ref: '#/components/schemas/JsonPointer' PaidVerificationBinding: type: object description: The immutable spend binding. quoted/payment_required have no paid receipt or refusal; refused has a refusal reason and no paid receipt; delivered has a paid receipt and no refusal reason, including when deterministic verification outcome is fail. additionalProperties: false required: - schema_version - binding_digest - precheck_receipt_digest - request_hash - evidence_digest - policy_version - price_cap_atomic - quoted_amount_atomic - network - asset - pay_to - quote_id - expires_at - discovery_survived - state - paid_receipt_id - refusal_reason properties: schema_version: type: string const: agent-economy/paid-verification-binding/1.0 binding_digest: $ref: '#/components/schemas/Sha256Digest' precheck_receipt_digest: $ref: '#/components/schemas/Sha256Digest' request_hash: $ref: '#/components/schemas/Sha256Digest' evidence_digest: $ref: '#/components/schemas/Sha256Digest' policy_version: type: string const: agent-economy/precheck-policy/2.0 price_cap_atomic: type: string maxLength: 16 pattern: ^[1-9][0-9]*$ quoted_amount_atomic: type: string maxLength: 16 pattern: ^[1-9][0-9]*$ network: type: string enum: - eip155:84532 - eip155:8453 asset: type: string pattern: ^0x[a-fA-F0-9]{40}$ pay_to: type: string pattern: ^0x[a-fA-F0-9]{40}$ quote_id: type: string pattern: ^qte_[A-Za-z0-9_-]+$ expires_at: type: string format: date-time discovery_survived: type: boolean const: true state: type: string enum: - quoted - payment_required - delivered - refused paid_receipt_id: oneOf: - type: string pattern: ^rcpt_[A-Za-z0-9_-]+$ - type: 'null' refusal_reason: oneOf: - type: string pattern: ^[A-Z0-9_]+$ - type: 'null' oneOf: - properties: state: enum: - quoted - payment_required paid_receipt_id: type: 'null' refusal_reason: type: 'null' - properties: state: const: delivered paid_receipt_id: type: string pattern: ^rcpt_[A-Za-z0-9_-]+$ refusal_reason: type: 'null' - properties: state: const: refused paid_receipt_id: type: 'null' refusal_reason: type: string pattern: ^[A-Z0-9_]+$ Sha256Digest: type: string pattern: ^sha256:[a-f0-9]{64}$ MachineQuote: type: object additionalProperties: false required: - schema_version - precheck_status - quote_id - quote_expires_at - request_digest - offer_generation_id - exact_price - supported_checks - unsupported_checks - expected_fulfillment - paid_tool - quote_scope - client_echo_required properties: schema_version: type: integer const: 1 precheck_status: type: string enum: - eligible - ineligible - unsupported quote_id: type: - string - 'null' pattern: ^pqt_[a-f0-9]{32}$ quote_expires_at: type: - string - 'null' format: date-time request_digest: oneOf: - $ref: '#/components/schemas/Sha256Digest' - type: 'null' offer_generation_id: type: string pattern: ^agent-economy/offer-generation/ exact_price: type: object additionalProperties: false required: - amount_base_unit - display_amount - asset - pay_to - network - payment_protocol properties: amount_base_unit: type: string pattern: ^[1-9][0-9]*$ display_amount: type: string asset: type: string pattern: ^0x[a-fA-F0-9]{40}$ pay_to: type: string pattern: ^0x[a-fA-F0-9]{40}$ network: type: string enum: - eip155:84532 - eip155:8453 payment_protocol: type: string const: x402-v2-exact supported_checks: type: array items: type: string uniqueItems: true unsupported_checks: type: array items: type: string uniqueItems: true expected_fulfillment: type: object additionalProperties: false required: - result_schema_id - signed_evidence - receipt properties: result_schema_id: type: string const: agent-economy/verify-evidence-response/1.0 signed_evidence: type: boolean const: true receipt: type: boolean const: true paid_tool: type: string const: verify_evidence quote_scope: type: string const: precheck_preview client_echo_required: type: boolean const: false FreeRequestValidation: type: object additionalProperties: false required: - schema_version - valid - verification_executed - payment_required - assertion_count - decoded_evidence_bytes - supported - spend_authorized - refusal_reason - planned_assertions - limitations - paid_execution - canonical_offer - machine_quote - precheck_receipt - next_step properties: schema_version: type: string const: agent-economy/request-validation/3.0 valid: type: boolean const: true verification_executed: type: boolean const: false payment_required: type: boolean const: false assertion_count: type: integer minimum: 1 maximum: 16 decoded_evidence_bytes: type: integer minimum: 1 maximum: 65536 supported: type: boolean const: true spend_authorized: type: boolean refusal_reason: type: - string - 'null' pattern: ^[A-Z0-9_]+$ planned_assertions: type: array minItems: 1 maxItems: 16 items: type: object additionalProperties: false required: - index - op properties: index: type: integer minimum: 0 maximum: 15 op: type: string enum: - sha256_equals - json_pointer_exists - json_pointer_equals - json_type_is path: $ref: '#/components/schemas/JsonPointer' expected_type: type: string enum: - 'null' - boolean - number - string - array - object limitations: type: array items: type: string paid_execution: type: object additionalProperties: false required: - price_atomic - symbol - decimals - asset - network - pay_to - http_endpoint - mcp_tool properties: price_atomic: type: string const: '10000' symbol: type: string const: USDC decimals: type: integer const: 6 asset: type: string pattern: ^0x[a-fA-F0-9]{40}$ network: type: string enum: - eip155:84532 - eip155:8453 pay_to: type: string pattern: ^0x[a-fA-F0-9]{40}$ http_endpoint: type: string format: uri mcp_tool: type: string const: verify_evidence canonical_offer: $ref: '#/components/schemas/CanonicalOffer' machine_quote: $ref: '#/components/schemas/MachineQuote' precheck_receipt: $ref: '#/components/schemas/PrecheckReceipt' next_step: type: string responses: Unavailable: description: Kill switch, maintenance, budget exhaustion, facilitator outage, or unavailable cost basis content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: agentRegistration: type: http scheme: bearer bearerFormat: signed anonymous registration receipt description: Optional 15-minute service-local receipt used only to inspect its own registration claim. It grants no API access and does not authorize payment.