Genesis402

Issue a signed proof receipt

genesis402_prove

Issue an Ed25519-signed, hash-chained receipt proving a SHA-256 digest existed at payment time, giving a timestamped proof for a document or statement.

Instructions

Paid ($0.25 USDC). Issue one Ed25519-signed, hash-chained receipt recording that a SHA-256 digest existed at the time of payment. Use as a cheap timestamped proof that you held a document or statement. To look the receipt up later use genesis402_receipt (free). Send text (hashed by the rail, labelled OBSERVED) or a sha256 you computed yourself (labelled ATTESTED; keeps the content private), not both. Returns the receipt bound to your payment transaction, with its truth labels and limitations. It verifies offline with the open verifier at github.com/FTHTrading/402-truth. The rail stores the receipt, never your bytes. Not externally anchored on a public blockchain yet. Payment: call once without payment_signature to get the exact price quote (nothing is charged or signed), then call again with the signed payment to receive the result and settlement details.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "genesis402_prove"
  }
}

Input Schema

Name	Required	Description
`text`	No	Raw UTF-8 text to hash and prove, up to 16 KiB (16,384 characters). Provide this or sha256, not both.
`claim`	No	Optional short statement bound into the signed receipt, up to 512 characters, e.g. 'Draft v2 of the purchase agreement'.
`sha256`	No	Lowercase hex SHA-256 digest (64 characters) of the content to prove. Provide this or text, not both.
`payment_signature`	No	Optional. An x402 v2 payment you signed for this call's quote (the PAYMENT-SIGNATURE header value). Omit to get the price quote first; nothing is charged without it.

Output Schema

Name	Required	Description
`mode`	Yes	QUOTE_ONLY: price quote only, nothing signed or charged. PAID: the call was paid and result holds the data. FREE: the endpoint answered without payment.
`paid`	Yes	true only when a payment was settled for this call.
`price`	No	The Base USDC quote. Present on QUOTE_ONLY and on PAID calls made by a local payer; null when the rail offered no Base USDC lane or the caller signed the payment.
`result`	No	PAID or FREE: the endpoint's JSON result.
`resource`	No	QUOTE_ONLY: the full URL of the paid resource.
`how_to_pay`	No	QUOTE_ONLY: how to sign and resend the call.
`settlement`	No	PAID: decoded PAYMENT-RESPONSE settlement (transaction hash, network, payer), or null if the rail sent none.
`what_you_get`	No	QUOTE_ONLY: the rail's description of what the payment buys.
`payment_required_b64`	No	QUOTE_ONLY: the raw base64 PAYMENT-REQUIRED header, to sign with any x402 v2 client.
`also_accepted_networks`	No	QUOTE_ONLY: every network the 402 challenge accepts.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.3.4Sep 29, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "also_accepted_networks": {
+      "description": "QUOTE_ONLY: every network the 402 challenge accepts.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "how_to_pay": {
+      "description": "QUOTE_ONLY: how to sign and resend the call.",
+      "type": "string"
+    },
+    "mode": {
+      "description": "QUOTE_ONLY: price quote only, nothing signed or charged. PAID: the call was paid and result holds the data. FREE: the endpoint answered without payment.",
+      "enum": [
+        "QUOTE_ONLY",
+        "PAID",
+        "FREE"
+      ],
+      "type": "string"
+    },
+    "paid": {
+      "description": "true only when a payment was settled for this call.",
+      "type": "boolean"
+    },
+    "payment_required_b64": {
+      "description": "QUOTE_ONLY: the raw base64 PAYMENT-REQUIRED header, to sign with any x402 v2 client.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "price": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "atomic": {
+              "description": "Price in USDC atomic units (6 decimals), as a decimal string.",
+              "type": "string"
+            },
+            "network": {
+              "description": "CAIP-2 network id of the lane, eip155:8453 (Base).",
+              "type": "string"
+            },
+            "payTo": {
+              "description": "Address the payment settles to.",
+              "type": "string"
+            },
+            "usd": {
+              "description": "Price in US dollars.",
+              "type": "number"
+            }
+          },
+          "required": [
+            "atomic",
+            "usd",
+            "payTo",
+            "network"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The Base USDC quote. Present on QUOTE_ONLY and on PAID calls made by a local payer; null when the rail offered no Base USDC lane or the caller signed the payment."
+    },
+    "resource": {
+      "description": "QUOTE_ONLY: the full URL of the paid resource.",
+      "type": "string"
+    },
+    "result": {
+      "description": "PAID or FREE: the endpoint's JSON result."
+    },
+    "settlement": {
+      "description": "PAID: decoded PAYMENT-RESPONSE settlement (transaction hash, network, payer), or null if the rail sent none."
+    },
+    "what_you_get": {
+      "description": "QUOTE_ONLY: the rail's description of what the payment buys.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "mode",
+    "paid"
+  ],
+  "type": "object"
+}

Changed3 schema fields changedv0.3.3Sep 29, 2026

changedInput schema / properties / claim / description

Previous value: -"Optional short statement bound into the receipt, e.g. 'Draft v2 of the purchase agreement'."New value: +"Optional short statement bound into the signed receipt, up to 512 characters, e.g. 'Draft v2 of the purchase agreement'."

changedInput schema / properties / sha256 / description

Previous value: -"Lowercase hex SHA-256 digest (64 characters) of the content to prove. Provide this or text."New value: +"Lowercase hex SHA-256 digest (64 characters) of the content to prove. Provide this or text, not both."

changedInput schema / properties / text / description

Previous value: -"Raw text to hash and prove, up to 16,384 characters. Provide this or sha256."New value: +"Raw UTF-8 text to hash and prove, up to 16 KiB (16,384 characters). Provide this or sha256, not both."

Changed4 schema fields changedv0.3.2Sep 26, 2026

addedInput schema / properties / claim / description

Added value: +"Optional short statement bound into the receipt, e.g. 'Draft v2 of the purchase agreement'."

changedInput schema / properties / payment_signature / description

Previous value: -"Optional. An x402 v2 payment you signed for this call's quote (the PAYMENT-SIGNATURE header value). Omit to get the price quote first."New value: +"Optional. An x402 v2 payment you signed for this call's quote (the PAYMENT-SIGNATURE header value). Omit to get the price quote first; nothing is charged without it."

addedInput schema / properties / sha256 / description

Added value: +"Lowercase hex SHA-256 digest (64 characters) of the content to prove. Provide this or text."

addedInput schema / properties / text / description

Added value: +"Raw text to hash and prove, up to 16,384 characters. Provide this or sha256."

First observedv0.3.1Sep 26, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only supply readOnlyHint=false and openWorldHint=true, so the description carries the real burden and does: exact price ($0.25 USDC), the quote-then-pay flow, that the rail stores the receipt but never the bytes, that content is labelled OBSERVED vs ATTESTED, and the honest limitation that it is not yet anchored on a public blockchain. This is unusually rich disclosure for a paid write operation.

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 cost and core purpose are front-loaded in the first sentence, and each subsequent sentence carries distinct information (routing, input choice, offline verification, privacy guarantee, limitation, payment flow). It is dense and slightly long, but nothing is clearly redundant.

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?

With an output schema present, the description need not detail return values, yet it still summarizes that the response is bound to the payment transaction and carries truth labels and limitations. Combined with the payment protocol and privacy guarantees, an agent has everything needed to invoke this paid tool correctly.

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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: text is hashed by the rail and labelled OBSERVED, whereas a caller-supplied sha256 is labelled ATTESTED and keeps the content private, and the two are mutually exclusive. That privacy/labelling distinction goes beyond the field descriptions.

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?

States a specific verb and resource: issuing one Ed25519-signed, hash-chained receipt proving a SHA-256 digest existed at payment time. It also explicitly distinguishes itself from the sibling lookup tool ('To look the receipt up later use genesis402_receipt (free)'), so an agent can separate prove-now from look-up-later without opening either schema.

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?

Gives both when-to-use ('cheap timestamped proof that you held a document or statement') and when-to-use-something-else (genesis402_receipt for retrieval). It further routes between the two input modes, text vs sha256, and states they are mutually exclusive, plus the two-call payment protocol for obtaining a quote first.

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