Confidential agentic payments stack for AI agents.

x402fhe gives agents the primitives they need to participate in a real economy:

• pay websites and APIs through FHEx402
• own an on-chain identity
• pay humans and other agents through encrypted escrow and settlement
• build reputation from paid interactions
• operate with private amounts using Zama fhEVM

The repo is live on Sepolia today with Zama's canonical wrapper stack and includes the full operator surface: core SDK, Express paywall, OpenClaw skill, frontend UI, facilitator, DFNS MPC, direct Ledger, supervised Ledger bridge, and live demo flows.

• FHEx402 is only one layer: the repo is not just an API payment client, it is a broader agentic commerce stack.
• Agents can do real economic work: identity, confidential balances, website payments, escrow, settlement, and proof-linked reputation all live in one system.
• Private payments, standard shape: the HTTP protocol still looks like x402, but the transfer amount stays encrypted on-chain.
• Real deployment, not just mocks: the repo ships local mock-FHE tests and a separate live Sepolia verification story.
• Multiple operator surfaces: core SDK, Express paywall, OpenClaw skill, browser UI, and supervised signing paths.

Node.js >= 22 required. The fast local suites are healthy, the live Sepolia path is documented separately in docs/SEPOLIA-E2E.md, and standards alignment is tracked in docs/ERC-COMPLIANCE.md.

With this stack, an agent can:

1. Pay a website or API through FHEx402 using confidential on-chain payments.
2. Own an identity through the on-chain agent identity registry.
3. Fund a job and pay a human or another agent through encrypted escrow and settlement.
4. Collect reputation from paid work through proof-linked feedback.
5. Choose the right signing model using local keys, DFNS MPC, browser wallets, direct Ledger, or supervised Ledger approvals.

x402fhe is best understood as five layers working together:

• Payment rail: FHEx402 for confidential website and API payments.
• Wallet layer: user keys, DFNS MPC, browser wallets, Ledger, and Ledger bridge.
• Identity layer: portable on-chain agent identity.
• Commerce layer: encrypted escrow, job funding, and settlement.
• Reputation layer: proof-linked feedback for paid interactions.

If you want the quickest honest "this works" path as an agent operator:

git clone [email protected]:bea7892046/fhex402.git && cd fhex402
pnpm install

export WALLET_MODE=user
export USER_PRIVATE_KEY=0x...
export RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
export CHAIN=sepolia

pnpm exec tsx packages/openclaw-skill/scripts/info.ts

Success looks like:

• JSON output
• walletType: "user"
• chainId: 11155111
• Sepolia contract addresses for cUSDC, verifier, identity, reputation, and escrow

If you are evaluating the repo itself rather than using it yet:

pnpm exec tsc --noEmit
pnpm --filter @x402fhe/core test
pnpm --filter @x402fhe/sdk test

Not every signer mode is meant for every runtime:

• Use USER_PRIVATE_KEY for local development and quick scripts.
• Use DFNS MPC for unattended agent runtimes.
• Use direct Ledger when the human is using the browser UI directly.
• Use WALLET_MODE=ledger-bridge when OpenClaw should stay headless but a human still approves every signature locally.

Short mental model:

• DFNS = unattended production signer
• User private key = simplest local dev signer
• Browser wallet = injected wallet like MetaMask or Rabby in the reference frontend
• Direct Ledger = human uses the frontend directly
• Ledger bridge = agent proposes, human approves, Ledger signs

Important frontend note:

• The current reference frontend does not use Privy yet.
• Connect browser wallet means an injected EIP-1193 wallet exposed as window.ethereum.
• If you usually onboard wallets with Privy, treat apps/frontend as a lower-level reference shell, not the final production auth UX.

export WALLET_MODE=user
export USER_PRIVATE_KEY=0x...
export RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
export CHAIN=sepolia
pnpm exec tsx packages/openclaw-skill/scripts/info.ts

export WALLET_MODE=dfns
export DFNS_WALLET_ID=...
export DFNS_AUTH_TOKEN=...
export DFNS_CREDENTIAL_ID=...
export DFNS_CREDENTIAL_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----\n...'
export RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
export CHAIN=sepolia
pnpm exec tsx packages/openclaw-skill/scripts/info.ts

export WALLET_MODE=ledger-bridge
export LEDGER_BRIDGE_TOKEN=replace-with-a-long-random-secret
export LEDGER_BRIDGE_URL=http://127.0.0.1:4555
export RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
export CHAIN=sepolia

LEDGER_BRIDGE_TOKEN="$LEDGER_BRIDGE_TOKEN" pnpm --filter @x402fhe/ledger-bridge dev
VITE_LEDGER_BRIDGE_TOKEN="$LEDGER_BRIDGE_TOKEN" pnpm --filter @x402fhe/ledger-bridge-ui dev

Then open the browser UI, connect the Ledger, verify the address on-device, and only then run the OpenClaw command you want to supervise.

1. A paid API returns HTTP 402 Payment Required.
2. The client encrypts the amount locally with the Zama SDK.
3. The client sends one on-chain confidentialTransferAndCall(...) transaction.
4. The verifier records the nonce and relays the encrypted funds to the seller.
5. The client retries with an X-Payment header.
6. The facilitator verifies the on-chain receipt and the server returns 200.

In other words: standard x402 request/response shape, but confidential on-chain payment execution.

For the full contract walkthrough, privacy boundary, and protocol detail, use:

• docs/ARCHITECTURE.md
• docs/PROTOCOL.md
• docs/SECURITY.md

Start with examples/basic-payment/index.ts:

import { JsonRpcProvider } from 'ethers';
import { createUserWallet, ZamaFheSession } from '@x402fhe/core';
import { createFheFetch } from '@x402fhe/sdk';

const provider = new JsonRpcProvider(process.env.RPC_URL!);
const wallet = createUserWallet(process.env.USER_PRIVATE_KEY!, provider);
const session = await ZamaFheSession.create({
  rpcUrl: process.env.RPC_URL!,
  chain: 'sepolia',
});

const fheFetch = createFheFetch({
  wallet,
  session,
  verifierAddress: '0xD46E80E1d37116B44c7Bfd845A110FCbB93d3E9F',
  tokenAddress: '0x7c5BF43B851c1dff1a4feE8dB225b87f2C223639',
  maxPayment: 100_000n,
});

Note: this example uses USER_PRIVATE_KEY because it is a runtime signer example. The root-level PRIVATE_KEY env is mostly for deployment and Hardhat tasks.

Start with examples/express-server/index.ts:

import express from 'express';
import { fhePaywall } from '@x402fhe/sdk';

const app = express();

app.post('/api/chat', fhePaywall({
  price: 10_000n,
  recipientAddress: SERVER_ADDRESS,
  tokenAddress: CUSDC_ADDRESS,
  verifierAddress: VERIFIER_ADDRESS,
  facilitatorUrl: FACILITATOR_URL,
  chainId: 11155111,
}), (req, res) => {
  res.json({ message: 'Paid and verified!' });
});

Start with packages/openclaw-skill/README.md:

skill.run("wrap", { amount: "5.00" })
skill.run("pay", { to: "0xServer...", amount: "0.01" })
skill.run("register-agent", { uri: "https://agent.example/meta.json" })
skill.run("grant-view", { delegate: "0xAgentB..." })

This repo is Sepolia-first today. If you are checking the intended production token layer, these are the canonical Zama mainnet references:

The x402fhe application contracts are not deployed on mainnet yet:

Repository verification surface:

• fast local contract tests under Hardhat
• package tests across core, sdk, ui, facilitator, and OpenClaw skill
• dedicated daemon/UI tests for the supervised Ledger bridge apps
• a dated live-network verification snapshot in docs/SEPOLIA-E2E.md
• repo-wide type-checking via pnpm exec tsc --noEmit

# All contract tests
npx hardhat test

# Package tests
pnpm --filter @x402fhe/core test
pnpm --filter @x402fhe/sdk test
pnpm --filter @x402fhe/openclaw-skill test
pnpm --filter @x402fhe/ui test
pnpm --filter @x402fhe/facilitator test
pnpm --filter @x402fhe/ledger-bridge test
pnpm --filter @x402fhe/ledger-bridge-ui test

# Type-check the full monorepo
pnpm exec tsc --noEmit

# Sepolia integration (requires funded accounts + real FHE coprocessor)
# Prerequisites: PRIVATE_KEY, SEPOLIA_RPC_URL, SERVER_ADDRESS in .env
RUN_SEPOLIA_TESTS=1 npx hardhat test scripts/sepolia-tests/*.sepolia.ts --network sepolia

# Individual Sepolia test suites:
RUN_SEPOLIA_TESTS=1 npx hardhat test scripts/sepolia-tests/wrap-transfer.sepolia.ts --network sepolia
RUN_SEPOLIA_TESTS=1 npx hardhat test scripts/sepolia-tests/verifier-relay.sepolia.ts --network sepolia
RUN_SEPOLIA_TESTS=1 npx hardhat test scripts/sepolia-tests/escrow-lifecycle.sepolia.ts --network sepolia

# Full HTTP x402 flow (facilitator + seller + buyer — real on-chain FHE):
RPC_URL=$SEPOLIA_RPC_URL NODE_ENV=test pnpm exec tsx scripts/test-http-e2e.ts

Notes:

• The package suites are fast and deterministic.
• The live Sepolia flows require funded wallets and a working public Zama path.
• The default facilitator test suite is socket-free and should run in restricted environments.
• The Sepolia HTTP E2E flow still launches local facilitator/seller servers; in restricted sandboxes that specific flow may fail with listen EPERM even when the code is otherwise correct.

# 1. Create .env with your funded Sepolia account
cat > .env << 'EOF'
PRIVATE_KEY=0xYOUR_SEPOLIA_PRIVATE_KEY
SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
ETHERSCAN_API_KEY=YOUR_ETHERSCAN_KEY
EOF

# 2. Deploy (uses Zama's canonical cUSDCMock at 0x7c5B...3639)
pnpm deploy:sepolia

# 3. The script prints all deployed addresses — update .env and types.ts

Uses Zama's canonical cUSDCMock (0x7c5BF43B851c1dff1a4feE8dB225b87f2C223639) on Sepolia. The cUSDCMock wraps Zama's mock USDC (0x9b5Cd13b8eFbB58Dc25A05CF411D8056058aDFfF) — NOT Circle USDC. The mock USDC has a public mint() function for testing:

# In Hardhat console (--network sepolia):
const mockUsdc = new ethers.Contract('0x9b5Cd13b8eFbB58Dc25A05CF411D8056058aDFfF',
  ['function mint(address,uint256)', 'function approve(address,uint256) returns (bool)'], signer);
await mockUsdc.mint(yourAddress, 10_000_000);              // mint 10 mock USDC
await mockUsdc.approve('0x7c5BF43B851c1dff1a4feE8dB225b87f2C223639', 10_000_000);
const cUSDC = new ethers.Contract('0x7c5BF43B851c1dff1a4feE8dB225b87f2C223639',
  ['function wrap(address,uint256)'], signer);
await cUSDC.wrap(yourAddress, 10_000_000);                 // wrap into cUSDC

The live Sepolia snapshot covers the major production-shape flows: wrapping, relay payments, escrow lifecycle, identity, reputation, unwrap/finalize, delegation, amount verification, ERC-1271 linking, and the HTTP x402 path. See docs/SEPOLIA-E2E.md for the dated breakdown and transaction references.

pnpm deploy:local     # Local Hardhat (deploys MockUSDC + MockConfidentialERC20)
pnpm deploy:mainnet   # Ethereum mainnet (uses canonical cUSDC at 0xe978...)

Start from .env.example, then pick one of these bundles.

export WALLET_MODE=user
export USER_PRIVATE_KEY=0x...
export RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
export CHAIN=sepolia

export WALLET_MODE=dfns
export DFNS_WALLET_ID=...
export DFNS_AUTH_TOKEN=...
export DFNS_CREDENTIAL_ID=...
export DFNS_CREDENTIAL_PRIVATE_KEY='-----BEGIN PRIVATE KEY-----\n...'
export RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
export CHAIN=sepolia

Optional DFNS convenience variables:

• DFNS_PRIVATE_KEY_PATH instead of inline DFNS_CREDENTIAL_PRIVATE_KEY
• DFNS_API_URL if you are not using the default https://api.dfns.io

export WALLET_MODE=ledger-bridge
export LEDGER_BRIDGE_URL=http://127.0.0.1:4555
export LEDGER_BRIDGE_TOKEN=replace-with-a-long-random-secret
export RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
export CHAIN=sepolia

The same LEDGER_BRIDGE_TOKEN must be used by:

• the OpenClaw runtime
• apps/ledger-bridge
• apps/ledger-bridge-ui

Copy .env.example:

Wallet-specific notes:

• DFNS: the runtime resolves the wallet address from DFNS_WALLET_ID automatically, so you do not need to duplicate it elsewhere.
• DFNS: you can supply the credential signer either inline with DFNS_CREDENTIAL_PRIVATE_KEY or from disk with DFNS_PRIVATE_KEY_PATH.
• Ledger bridge: OpenClaw never talks to the Ledger directly; it talks to a localhost daemon, while a local browser approval UI owns the WebHID session.
• Ledger bridge: use one shared LEDGER_BRIDGE_TOKEN value in all three places: the skill runtime, the daemon, and the browser UI.

BUSL-1.1 (Business Source License v1.1)