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.

Introduction

The Shielded x402 Client SDK (@shielded-x402/client) provides two complementary rails for building privacy-preserving payment agents:
  1. ShieldedClientSDK: Anonymous proof-backed x402 payment payload construction using zero-knowledge proofs
  2. MultiChainCreditClient: Sequencer-authorized fast execution across chain-specific relayers

Installation

npm install @shielded-x402/client

Peer Dependencies

For zero-knowledge proof generation (optional):
npm install @noir-lang/noir_js @aztec/bb.js

Key Features

Anonymous Payments

Generate zero-knowledge proofs for privacy-preserving x402 payments without revealing transaction history

Multi-Chain Support

Execute payments across multiple chains (Base, Solana) using sequencer-authorized credit

Note Management

Local indexer for tracking shielded notes and commitments

Plug-and-Play

Drop-in fetch replacement with automatic 402 payment handling

Integration Modes

1. Direct x402 Header Mode (Merchant-Facing)

Use createShieldedFetch for automatic 402 payment handling. The SDK receives 402 PAYMENT-REQUIRED, builds the payment proof, and retries the request:
import { createShieldedFetch, ShieldedClientSDK, LocalNoteIndexer } from '@shielded-x402/client';

const sdk = new ShieldedClientSDK({
  endpoint: RELAYER_URL,
  signer: async (message) => account.signMessage({ message })
});

const shieldedFetch = createShieldedFetch({
  sdk,
  resolveContext: async () => {
    // Return note, witness, and nullifier secret
  }
});

const res = await shieldedFetch('https://api.example.com/paid/data');

2. Relayer-Executed Mode (Agent-Facing)

Use MultiChainCreditClient for sequencer-authorized payments. The relayer executes the payment on behalf of the agent:
import { MultiChainCreditClient } from '@shielded-x402/client';

const client = new MultiChainCreditClient({
  sequencerUrl: 'http://127.0.0.1:3200',
  relayerUrls: {
    'eip155:8453': 'http://127.0.0.1:3100',
    'solana:devnet': 'http://127.0.0.1:3101'
  }
});

const result = await client.pay({
  chainRef: 'eip155:8453',
  amountMicros: '1500000',
  merchant: {
    serviceRegistryId: 'demo/base',
    endpointUrl: 'https://merchant.example/pay'
  },
  merchantRequest: { /* ... */ },
  agent: { /* ... */ }
});

Core Components

ShieldedClientSDK

Build zero-knowledge payment proofs and handle deposits/spends

MultiChainCreditClient

Execute fast credit-based payments across multiple chains

createShieldedFetch

Drop-in fetch replacement with automatic 402 handling

Note Management

Index and manage shielded notes locally

Architecture

The SDK implements the Shielded x402 protocol with:
  • Authoritative sequencer: Real-time nonce/balance enforcement
  • Per-chain relayers: Execute only sequencer-authorized payments
  • Periodic commitments: Base commitment roots for delayed independent auditability
  • Shielded settlement: Onchain settlement as the funding source for credit balances

Protocol Flow

Next Steps

API Reference

Explore detailed API documentation

Quickstart

Build your first shielded payment agent

Build docs developers (and LLMs) love