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.

​
What is the Merchant SDK?

The Merchant SDK enables merchants to accept privacy-preserving x402 payments using zero-knowledge proofs. Customers can pay for API access, services, or content without revealing their identity or payment history.

​
Key Features

Zero-Knowledge Proofs

Verify payments without revealing customer identity or transaction history.

Challenge-Response

Issue payment challenges and verify cryptographic proofs in responses.

Nullifier Protection

Prevent double-spending with cryptographic nullifiers.

On-Chain Settlement

Settle verified payments on-chain for cryptographic guarantees.

​
How It Works

The x402 payment flow follows a challenge-response pattern:
1

Issue Challenge

Merchant issues a payment requirement with a unique challenge nonce.
2

Client Proves Payment

Client generates a zero-knowledge proof and signs the payment.
3

Verify Payment

Merchant verifies the proof, signature, and nullifier uniqueness.
4

Settle On-Chain

Merchant settles the payment on-chain to consume the nullifier.

​
Core SDK Class

The ShieldedMerchantSDK class provides the main interface for accepting payments: 
import { ShieldedMerchantSDK } from '@shielded-x402/merchant';
import type { MerchantConfig, MerchantHooks } from '@shielded-x402/merchant';

const config: MerchantConfig = {
  rail: 'shielded-usdc',
  price: 1000000n, // 1 USDC in micro units
  merchantPubKey: '0x...',
  verifyingContract: '0x...',
  challengeTtlMs: 180000, // 3 minutes
  network: 'eip155:11155111', // Sepolia
  asset: '0x0000...0000' // USDC asset identifier
};

const hooks: MerchantHooks = {
  verifyProof: async (payload) => {
    // Verify zero-knowledge proof on-chain or via verifier
    return true;
  },
  isNullifierUsed: async (nullifier) => {
    // Check if nullifier has been used
    return false;
  }
};

const sdk = new ShieldedMerchantSDK(config, hooks);

​
Configuration Reference

​
MerchantConfig

​
rail
string
required
Payment rail identifier. Currently supports 'shielded-usdc'.
​
price
bigint
required
Price in smallest asset units (e.g., micro-USDC: 1000000n = 1 USDC).
​
merchantPubKey
Hex
required
Merchant’s public key for payment verification.
​
verifyingContract
Hex
required
Address of the shielded pool contract that verifies proofs.
​
challengeTtlMs
number
required
Challenge time-to-live in milliseconds (recommended: 180000).
​
network
string
Network identifier (default: 'eip155:11155111' for Sepolia).
​
asset
Hex
Asset identifier for the payment token.
​
payTo
Hex
Payment recipient address (defaults to verifyingContract).
​
fixedChallengeNonce
Hex
Fixed nonce for testing only. Omit for production.

​
MerchantHooks

​
verifyProof
(payload: ShieldedPaymentResponse) => Promise<boolean>
required
Hook to verify zero-knowledge proofs. Must check both proof validity and merkle root.
​
isNullifierUsed
(nullifier: Hex) => Promise<boolean>
required
Hook to check if a nullifier has been used. Prevents double-spending.

​
Next Steps

Integration Guide

Integrate x402 payments into your application

Payment Verification

Learn how to verify and settle payments

Build docs developers (and LLMs) love

Get started for freeTalk to us