Skip to main content
Glama

Verify Paxiom Receipt (Structured JSON)

verify_receipt
Read-onlyIdempotent

Validate an Ed25519-signed paxiom.receipt.v0 API delivery receipt (JSON Schema, Ed25519 signature, signer authorization via expectedIssuerPublicKeys / expectedPayTo, JCS or raw SHA-256 output binding, expiry, and settlement trust state) and return structured JSON fields. Use this instead of explain_receipt when automated code branches on valid or trustState; use explain_receipt when presenting human-readable guidance, or get_x402_verifier_info for live on-chain settlement endpoints. Deterministic, offline, and free with no auth: invalid or tampered receipts return isError=false with valid=false and the failing trustState, omitting output caps trustState at valid_signature_only, and omitting trustedVerifierPublicKeys trusts the host counter-attestation key by default.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "receipt": "<receipt>"
    },
    "name": "verify_receipt"
  }
}

Input Schema

NameRequiredDescriptionDefault
outputNoOptional delivered HTTP response payload (JSON value for jcs-sha256, or UTF-8 string for raw-sha256); required to reach trustState="verified".
receiptYesParsed paxiom.receipt.v0 JSON envelope (decoded from Payment-Receipt or X-Paxiom-Receipt HTTP header).
expectedPayToNoOptional expected seller payTo address from the 402 quote. Mismatch returns trustState="unauthorized_issuer".
trustedPaxiomPublicKeysNoBackward-compatible alias for trustedVerifierPublicKeys.
expectedIssuerPublicKeysNoOptional pinned base64 Ed25519 seller public keys (e.g. from /.well-known/x402-keys.json). Mismatch returns trustState="unauthorized_issuer".
trustedVerifierPublicKeysNoOptional canonical base64 32-byte Ed25519 public keys trusted to assert settlement.checkedByVerifier=true (defaults to the host key).

Output Schema

NameRequiredDescriptionDefault
validYesTrue only when trustState is "verified" (valid signature, authorized signer if pinned, matching outputHash, non-expired, and confirmed or verify_only settlement).
checksYesPer-stage cryptographic and structural check statuses.
summaryYesOne-sentence diagnostic summary of the verification outcome.
trustStateYesMachine-readable verification outcome classification.
receiptHashYesHex SHA-256 digest of the canonical signing input, or null if schema validation failed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changed
    • addedInput schema / properties / expectedIssuerPublicKeys
      Added value: +{
      +  "description": "Optional pinned base64 Ed25519 seller public keys (e.g. from /.well-known/x402-keys.json). Mismatch returns trustState=\"unauthorized_issuer\".",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / expectedPayTo
      Added value: +{
      +  "description": "Optional expected seller payTo address from the 402 quote. Mismatch returns trustState=\"unauthorized_issuer\".",
      +  "type": "string"
      +}
    • changedInput schema / properties / output / description
      Previous value: -"Optional delivered HTTP response JSON body; required to verify SHA-256 JCS outputHash binding and reach trustState=\"verified\"."New value: +"Optional delivered HTTP response payload (JSON value for jcs-sha256, or UTF-8 string for raw-sha256); required to reach trustState=\"verified\"."
    • changedInput schema / properties / receipt / description
      Previous value: -"Parsed paxiom.receipt.v0 JSON envelope (or base64url-decoded X-Paxiom-Receipt HTTP header)."New value: +"Parsed paxiom.receipt.v0 JSON envelope (decoded from Payment-Receipt or X-Paxiom-Receipt HTTP header)."
    • changedInput schema / properties / trustedPaxiomPublicKeys / description
      Previous value: -"Optional canonical base64 32-byte Ed25519 public keys trusted to assert settlement.checkedByPaxiom=true (defaults to the host Paxiom key)."New value: +"Backward-compatible alias for trustedVerifierPublicKeys."
    • addedInput schema / properties / trustedVerifierPublicKeys
      Added value: +{
      +  "description": "Optional canonical base64 32-byte Ed25519 public keys trusted to assert settlement.checkedByVerifier=true (defaults to the host key).",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / checks / properties / issuerAuthorization
      Added value: +{
      +  "description": "Seller key / payTo authorization status (pass, fail, unpinned, not_checked).",
      +  "type": "string"
      +}
    • changedOutput schema / properties / checks / properties / outputHash / description
      Previous value: -"RFC 8785 JCS SHA-256 payload hash check (pass, fail, not_provided, not_checked, error)."New value: +"JCS or raw SHA-256 payload hash check (pass, fail, not_provided, not_checked, error)."
    • changedOutput schema / properties / checks / required
      Previous value: -[
      -  "schema",
      -  "signature",
      -  "outputHash",
      -  "requestBinding",
      -  "paymentBinding",
      -  "settlement",
      -  "proof"
      -]New value: +[
      +  "schema",
      +  "signature",
      +  "issuerAuthorization",
      +  "outputHash",
      +  "requestBinding",
      +  "paymentBinding",
      +  "settlement",
      +  "proof"
      +]
    • changedOutput schema / properties / trustState / enum
      Previous value: -[
      -  "verified",
      -  "valid_signature_only",
      -  "settlement_claimed_not_checked",
      -  "unsupported_format",
      -  "schema_invalid",
      -  "invalid_signature",
      -  "expired",
      -  "output_hash_mismatch",
      -  "settlement_failed",
      -  "proof_invalid",
      -  "proof_unavailable",
      -  "error"
      -]New value: +[
      +  "verified",
      +  "valid_signature_only",
      +  "settlement_claimed_not_checked",
      +  "unsupported_format",
      +  "schema_invalid",
      +  "invalid_signature",
      +  "unauthorized_issuer",
      +  "expired",
      +  "output_hash_mismatch",
      +  "settlement_failed",
      +  "proof_invalid",
      +  "proof_unavailable",
      +  "error"
      +]
    • changedOutput schema / properties / valid / description
      Previous value: -"True only when trustState is \"verified\" (valid signature, matching outputHash, non-expired, and confirmed or verify_only settlement)."New value: +"True only when trustState is \"verified\" (valid signature, authorized signer if pinned, matching outputHash, non-expired, and confirmed or verify_only settlement)."
  2. Changed4 schema fields changed
    • changedInput schema / properties / output / description
      Previous value: -"Optional delivered API response JSON to verify payment-to-output SHA-256 hash binding."New value: +"Optional delivered HTTP response JSON body; required to verify SHA-256 JCS outputHash binding and reach trustState=\"verified\"."
    • changedInput schema / properties / receipt / description
      Previous value: -"Parsed paxiom.receipt.v0 JSON object (or decoded X-Paxiom-Receipt header)."New value: +"Parsed paxiom.receipt.v0 JSON envelope (or base64url-decoded X-Paxiom-Receipt HTTP header)."
    • changedInput schema / properties / trustedPaxiomPublicKeys / description
      Previous value: -"Optional base64 32-byte Ed25519 public keys trusted to assert checkedByPaxiom=true."New value: +"Optional canonical base64 32-byte Ed25519 public keys trusted to assert settlement.checkedByPaxiom=true (defaults to the host Paxiom key)."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "checks": {
      +      "description": "Per-stage cryptographic and structural check statuses.",
      +      "properties": {
      +        "outputHash": {
      +          "description": "RFC 8785 JCS SHA-256 payload hash check (pass, fail, not_provided, not_checked, error).",
      +          "type": "string"
      +        },
      +        "paymentBinding": {
      +          "description": "Payment metadata binding check (pass, not_checked).",
      +          "type": "string"
      +        },
      +        "proof": {
      +          "description": "Evidence array status summary (provided, not_provided, invalid, unavailable).",
      +          "type": "string"
      +        },
      +        "requestBinding": {
      +          "description": "Request method and resource binding check (pass, not_checked).",
      +          "type": "string"
      +        },
      +        "schema": {
      +          "description": "Draft-07 schema check status (pass, fail, not_checked).",
      +          "type": "string"
      +        },
      +        "settlement": {
      +          "description": "Reported settlement state from the receipt payload.",
      +          "type": "string"
      +        },
      +        "signature": {
      +          "description": "Ed25519 signature and keyId consistency status (pass, fail, not_checked).",
      +          "type": "string"
      +        }
      +      },
      +      "required": [
      +        "schema",
      +        "signature",
      +        "outputHash",
      +        "requestBinding",
      +        "paymentBinding",
      +        "settlement",
      +        "proof"
      +      ],
      +      "type": "object"
      +    },
      +    "receiptHash": {
      +      "description": "Hex SHA-256 digest of the canonical signing input, or null if schema validation failed.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "summary": {
      +      "description": "One-sentence diagnostic summary of the verification outcome.",
      +      "type": "string"
      +    },
      +    "trustState": {
      +      "description": "Machine-readable verification outcome classification.",
      +      "enum": [
      +        "verified",
      +        "valid_signature_only",
      +        "settlement_claimed_not_checked",
      +        "unsupported_format",
      +        "schema_invalid",
      +        "invalid_signature",
      +        "expired",
      +        "output_hash_mismatch",
      +        "settlement_failed",
      +        "proof_invalid",
      +        "proof_unavailable",
      +        "error"
      +      ],
      +      "type": "string"
      +    },
      +    "valid": {
      +      "description": "True only when trustState is \"verified\" (valid signature, matching outputHash, non-expired, and confirmed or verify_only settlement).",
      +      "type": "boolean"
      +    }
      +  },
      +  "required": [
      +    "valid",
      +    "trustState",
      +    "checks",
      +    "receiptHash",
      +    "summary"
      +  ],
      +  "type": "object"
      +}
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, the description discloses deterministic offline behavior, no auth and no cost, invalid/tampered receipt return semantics, the effect of omitting output, and the default trusted verifier key behavior. These are important operational traits not covered by the readOnly/idempotent annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and usage guidance, and every sentence provides useful information. It is dense and packs many parenthetical details, but it avoids outright repetition and remains scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a verification tool with an output schema and full annotations, the description covers purpose, alternatives, error behavior, trust-state implications, and key defaults. An agent has enough context to invoke it correctly without needing additional explanation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already carries most parameter meaning. The description adds value by explaining that omitting output caps trustState at valid_signature_only and that omitting trustedVerifierPublicKeys trusts the host counter-attestation key by default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: validate an Ed25519-signed paxiom.receipt.v0 API delivery receipt. It also names the validation dimensions and distinguishes the tool from explain_receipt and get_x402_verifier_info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing guidance: use verify_receipt when automated code branches on valid or trustState, explain_receipt for human-readable guidance, and get_x402_verifier_info for live on-chain settlement endpoints. The conditions for choosing alternatives are clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.