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.

This guide walks you through running a complete dual-chain payment example using the Shielded x402 protocol. You’ll authorize and execute payments on both Base and Solana relayers using a single sequencer credit balance.
The multi-chain example demonstrates sequencer-authorized fast execution. For anonymous proof-backed payments, see the shielded fetch integration guide.

​
Prerequisites

You need the following installed:
  • Node.js 18+ and pnpm 8+
  • Foundry for Solidity contract tests
  • PostgreSQL 14+ running locally
  • Solana CLI tools (for devnet deployment)

​
Step 1: Clone and Build

Clone the repository and install dependencies: 
git clone https://github.com/your-org/shielded-x402.git
cd shielded-x402

pnpm install
pnpm contracts:deps
pnpm build
Verify the build with a contract test: 
pnpm contracts:test --match-path test/CommitmentRegistryV1.t.sol
Run pnpm typecheck to verify TypeScript types across all packages.

​
Step 2: Start the Local Stack

The development stack includes:
  • Credit Sequencer (port 3200): Authorizes intents and tracks credit balances
  • Base Relayer (port 3100): Executes EVM payments in noop or onchain mode
  • Solana Relayer (port 3101): Executes Solana devnet transactions
Start all services: 
pnpm dev:stack:start
Ensure PostgreSQL is running and accessible at the connection string configured in services/credit-sequencer/.env. The sequencer will fail to start without a database connection.
Verify services are healthy: 
curl http://127.0.0.1:3200/health  # Sequencer
curl http://127.0.0.1:3100/health  # Base relayer
curl http://127.0.0.1:3101/health  # Solana relayer

​
Step 3: Deploy Solana Programs

The Solana relayer requires two onchain programs:
  1. Verifier Program: Groth16 proof verification using Sunspot
  2. Gateway Program: x402 payment settlement with CPI verify
Deploy and initialize:
1

Install Solana client dependencies

pnpm --dir chains/solana/client install
2

Deploy the verifier program

bash chains/solana/scripts/deploy-verifier.sh
Save the printed SOLANA_VERIFIER_PROGRAM_ID for the next step.
3

Deploy the gateway program

bash chains/solana/scripts/deploy-gateway.sh
Save the printed SOLANA_GATEWAY_PROGRAM_ID.
4

Initialize gateway state

pnpm tsx chains/solana/scripts/init-gateway.ts
This creates the PDA state account. Save the SOLANA_STATE_ACCOUNT address.
The deployment scripts use solana config get to determine your keypair and RPC URL. Ensure you’re configured for Solana devnet before deploying.

​
Step 4: Configure Environment

Set required environment variables for the example:
.env
export SEQUENCER_URL=http://127.0.0.1:3200
export BASE_RELAYER_URL=http://127.0.0.1:3100
export SOLANA_RELAYER_URL=http://127.0.0.1:3101
export SEQUENCER_ADMIN_TOKEN=change-me

# From Solana deployment
export SOLANA_GATEWAY_PROGRAM_ID=<your_gateway_program_id>
export SOLANA_VERIFIER_PROGRAM_ID=<your_verifier_program_id>
export SOLANA_STATE_ACCOUNT=<your_state_account>
export SOLANA_PAYER_KEYPAIR_PATH=~/.config/solana/id.json
export SOLANA_RECIPIENT_ADDRESS=<recipient_pubkey>

# Solana RPC endpoints
export SOLANA_RPC_URL=https://api.devnet.solana.com
export SOLANA_WS_URL=wss://api.devnet.solana.com
For local smoke testing, the Base relayer runs in noop mode by default—no onchain transactions required. To test real Base Sepolia payments, see Step 6.

​
Step 5: Run the Multi-Chain Example

Execute the dual-chain payment flow: 
pnpm example:multi-chain:base-solana
The example performs the following operations:
1

Generate agent keypair

Creates an Ed25519 keypair for signing payment intents. The agentId is derived from the public key hash.
2

Credit agent balance

Calls POST /v1/admin/credit to seed the agent’s sequencer balance with 5,000,000 micros ($5.00 USD equivalent).
POST /v1/admin/credit is a test-only endpoint. Production systems must fund balances via shielded settlement outputs.
3

Authorize Base payment

Constructs an IntentV1 for 1,500,000 micros on eip155:8453, signs it with the agent’s private key, and sends AuthorizeRequestV1 to the sequencer.The sequencer validates nonce ordering and balance sufficiency, then returns AuthorizationV1 with a sequencer signature.
4

Execute Base relay payment

Sends RelayPayRequestV1 to the Base relayer with the signed authorization. The relayer:
  • Verifies the sequencer signature
  • Calls the merchant endpoint (noop adapter by default)
  • Reports execution via POST /v1/credit/executions
  • Returns merchant response to agent
5

Authorize Solana payment

Repeats the authorization flow for Solana with agentNonce: '1' (strictly increasing) and 2,500,000 micros.
6

Execute Solana relay payment

The Solana relayer:
  • Builds an SPL transaction with authId and authExpiryUnix
  • Submits to the gateway program for CPI verification
  • Returns the transaction signature as executionTxHash
Successful output: 
=== Multi-chain flow complete ===
agentId: 0xa4f3c8e9d2b7a1f0...
base authId: 0x7b3e9a2f8c1d4e5a...
base relay result: {
  "executionTxHash": "0xnoop-deterministic-hash-base",
  "status": "SUCCESS",
  "merchantResponse": { "flow": "base-payment" }
}
solana authId: 0x9d2e8b3f7a4c1e6d...
solana relay result: {
  "executionTxHash": "5K7Zj3xQw...",  # Real Solana tx signature
  "status": "SUCCESS",
  "merchantResponse": { "confirmed": true }
}

​
Step 6 (Optional): Enable Base Onchain Mode

To execute real EVM transactions on Base Sepolia:
1

Configure Base relayer for EVM mode

Edit services/payment-relayer/.env:
RELAYER_BASE_CHAIN_REF=eip155:84532
RELAYER_BASE_PAYOUT_MODE=evm
RELAYER_EVM_PRIVATE_KEY=0x<your_funded_private_key>
2

Restart the stack

pnpm dev:stack:stop
pnpm dev:stack:start
3

Set Base example environment variables

export BASE_ONCHAIN=true
export BASE_RPC_URL=https://sepolia.base.org
export BASE_CHAIN_ID=84532
export BASE_RECIPIENT_ADDRESS=0x<recipient_address>
export BASE_PAYMENT_WEI=1000000000000  # 0.000001 ETH
4

Run the example

pnpm example:multi-chain:base-solana
The Base relayer will now submit real transactions and return actual transaction hashes.

​
Step 7: Verify Commitments

Enable commitment epoch posting to test auditability: 
export RUN_COMMITMENT_EPOCH=true
pnpm example:multi-chain:base-solana
The example will trigger POST /v1/commitments/run and fetch inclusion proofs: 
base commitment epoch: 1
solana commitment epoch: 1
Manually fetch a proof: 
curl "http://127.0.0.1:3200/v1/commitments/proof?authId=0x7b3e9a2f8c1d4e5a..."
Response: 
{
  "epochId": "1",
  "leafHash": "0x9a3e7f2d8b4c1e6a...",
  "leafIndex": 0,
  "proof": [
    "0x4e8d2a7f3b9c1e6d...",
    "0x7a3f9e2d8b4c1e6a..."
  ],
  "metadata": {
    "root": "0x2f8e9a3d7b4c1e6a...",
    "count": 2,
    "sequencerKeyId": "sequencer-key-1"
  }
}
In production, the sequencer posts commitment roots to CommitmentRegistryV1 on Base mainnet hourly. Anyone can verify authorization inclusion by reconstructing the merkle path.

​
Cleanup

Stop all running services: 
pnpm dev:stack:stop

​
What You Learned

You successfully:
  • Started a local sequencer + dual relayer stack
  • Deployed Solana verification programs to devnet
  • Authorized and executed payments on Base (noop) and Solana (onchain)
  • Verified commitment inclusion proofs

​
Next Steps

SDK Integration

Integrate MultiChainCreditClient into your application

Shielded Fetch

Learn anonymous proof-backed x402 payments

Merchant Setup

Accept x402 payments in your API

API Reference

Explore sequencer and relayer endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us