Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nhestrompia/shielded-x402/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The protocol defines typed data structures for shielded payments, X402 payment flows, and agent interactions. All structures use strict TypeScript types with hex-encoded values.

​
Shielded Note

Represents a private note in the shielded payment system.
​
amount
bigint
required
The note’s value in the smallest unit of the asset
​
rho
Hex
required
Random blinding factor for the commitment (32 bytes, hex-encoded)
​
pkHash
Hex
required
Hash of the owner’s public key (32 bytes, hex-encoded)
​
commitment
Hex
required
The note commitment hash (32 bytes, hex-encoded)
​
leafIndex
number
required
Position in the Merkle tree (0-based index)

​
Example

const note: ShieldedNote = {
  amount: 1000000n,
  rho: "0x1234...",
  pkHash: "0xabcd...",
  commitment: "0x5678...",
  leafIndex: 42
};

​
Spend Public Inputs

Public inputs for zero-knowledge spend proofs.
​
nullifier
Hex
required
Unique nullifier preventing double-spends (32 bytes, domain: shielded-x402:v1:nullifier)
​
root
Hex
required
Merkle root proving note existence (32 bytes, hex-encoded)
​
merchantCommitment
Hex
required
Commitment to merchant output (32 bytes, domain: shielded-x402:v1:output)
​
changeCommitment
Hex
required
Commitment to change output (32 bytes, domain: shielded-x402:v1:output)
​
challengeHash
Hex
required
Hash binding payment to merchant challenge (32 bytes, domain: shielded-x402:v1:challenge)
​
amount
bigint
required
Payment amount in smallest unit

​
Shielded Payment Response

Complete payment proof package sent to merchants.
​
proof
Hex
required
ZK-SNARK proof bytes (hex-encoded)
​
publicInputs
Hex[]
required
Array of public inputs (each 32 bytes, hex-encoded)
​
nullifier
Hex
required
The nullifier from public inputs (32 bytes)
​
root
Hex
required
Merkle root from public inputs (32 bytes)
​
merchantCommitment
Hex
required
Merchant output commitment (32 bytes)
​
changeCommitment
Hex
required
Change output commitment (32 bytes)
​
challengeHash
Hex
required
Challenge hash from public inputs (32 bytes)
​
encryptedReceipt
Hex
required
Encrypted payment receipt for the merchant (hex-encoded)
​
txHint
string
Optional transaction hint for off-chain coordination

​
Example

const payment: ShieldedPaymentResponse = {
  proof: "0x1234...",
  publicInputs: ["0xabc...", "0xdef..."],
  nullifier: "0x5678...",
  root: "0x9abc...",
  merchantCommitment: "0xdef0...",
  changeCommitment: "0x1234...",
  challengeHash: "0x5678...",
  encryptedReceipt: "0x9abc...",
  txHint: "batch-42"
};

​
Payment Requirement

X402 payment requirement structure for merchant challenges.
​
x402Version
2
Protocol version (always 2)
​
scheme
string
required
Payment scheme, typically "exact"
​
network
string
required
Target blockchain network identifier
​
asset
Hex | string
required
Asset contract address or identifier
​
payTo
Hex
required
Merchant’s payment recipient address (20 bytes)
​
rail
string
required
Payment rail, typically "shielded-usdc"
​
amount
string
required
Payment amount as decimal string
​
challengeNonce
string
required
Unique challenge nonce (32 bytes, hex-encoded)
​
challengeExpiry
string
required
Challenge expiration timestamp (ISO 8601 or Unix timestamp)
​
merchantPubKey
Hex
required
Merchant’s public key for encryption (hex-encoded)
​
verifyingContract
Hex
required
Contract address for proof verification (20 bytes)
​
maxTimeoutSeconds
number
Maximum timeout for payment completion
​
description
string
Human-readable payment description
​
mimeType
string
MIME type of the expected response
​
outputSchema
string
JSON schema for response validation
​
extra
Record<string, string>
Additional metadata, includes shielded rail parameters

​
X402 Payment Signature Payload

Complete X402 payment package with signature.
​
x402Version
2
required
Protocol version (always 2)
​
accepted
PaymentRequirement
required
The payment requirement being fulfilled
​
payload
ShieldedPaymentResponse
required
The shielded payment proof and data
​
challengeNonce
Hex
required
Challenge nonce from the requirement (32 bytes)
​
signature
Hex
required
Cryptographic signature over the payload (hex-encoded)

​
Relayer Settlement Delta

State update from relayer after settlement.
​
merchantCommitment
Hex
required
Merchant’s new note commitment (32 bytes)
​
changeCommitment
Hex
required
Sender’s change note commitment (32 bytes)
​
merchantLeafIndex
number
Merchant note position in Merkle tree
​
changeLeafIndex
number
Change note position in Merkle tree
​
newRoot
Hex
Updated Merkle root after insertion (32 bytes)

​
Hex Type

All hex-encoded values use the Hex type: 
type Hex = `0x${string}`;

​
Validation

  • isHex: Validates 0x-prefixed hex strings of any length
  • isHex32: Validates exactly 32-byte (64 hex characters) values

​
Canonical Format

  • Always lowercase
  • Always prefixed with 0x
  • 32-byte values padded to 64 hex characters
  • Addresses padded to 64 characters (40 → 64) for word alignment

Build docs developers (and LLMs) love

Get started for freeTalk to us