StealthPay MCP

StealthPay MCP is a hackathon project built for:

• BSA EPFL Hackathon
• DoraHacks - BSA Stablecoins & Payments Track

It is an MCP server that gives AI agents the ability to make contextual, private crypto payments using ENS identity and stealth addresses.

Problem

Agentic crypto payments are still not contextual enough:

1. An agent may know the recipient identity, but not their payment preferences (chain, token, UX constraints).
2. ENS identity is human-readable, but often not structured as machine-usable payment instructions.
3. Reusing one public address for many receipts creates onchain correlation and harms privacy.

StealthPay targets this double problem: smarter machine-readable payment routing, plus private receiving with one-time stealth addresses.

Solution

StealthPay MCP turns an ENS name into a machine-usable payment endpoint:

• reads recipient payment preferences from CAIP-normalized ENS profile data (stealthpay.v1.* namespace)
• builds the payment path for the right chain/token context with stealth/note policy enforcement
• uses stealth-address flow (ERC-5564-style announcements) for private receipt discovery
• encrypts payment notes using recipient viewing keys (ChaCha20-Poly1305)
• enforces agent spend policy controls (per-tx caps, daily limits, chain/token/destination allowlists)

What is MCP?

MCP (Model Context Protocol) is a standard way for AI clients/agents to call external tools.
In this project, MCP tools expose payment capabilities (get-payment-profile, send-stealth-payment, scan-announcements, claim-stealth-payment) in a structured, automatable interface.

What is a stealth address?

A stealth address is a one-time recipient address derived from a published stealth meta-address.
Each payment can use a fresh address, so receipts are harder to correlate publicly while still being recoverable by the intended recipient.

How StealthPay differs from Umbra / Fluidkey

StealthPay is not trying to replace those products. It focuses on a different layer:

1. MCP-native (agentic) interface: StealthPay exposes tools through MCP for AI/agent orchestration; Umbra and Fluidkey are not MCP tool surfaces.
2. Programmable payment profiles: StealthPay routes payments from ENS-stored machine-readable preferences (chain/token/UX policy), not only identity lookup.
3. Centralization model: StealthPay is an open, self-hostable MCP server; Fluidkey is a managed product with centralized service components.
4. Stealth standard positioning: Umbra pioneered stealth payments, but its original architecture predates the latest stealth-address standardization work; StealthPay targets ERC-5564-style announcement/scan flows in an agent-friendly pipeline.
5. End-to-end machine flow: resolve identity -> generate stealth destination -> pay -> scan -> claim, from one MCP surface.

Example use cases

• AI assistant pays a freelancer from a plain request: "Send 50 USDC to alice.eth privately."
• Operations bot executes recurring payouts to contributors while preserving recipient privacy.
• Checkout/commerce assistant generates ENS-based private payment links for one-off customer settlements.
• DAO/grant tooling sends disbursements with identity-level routing and reduced receipt linkage.

Send crypto to anyone with an ENS name — privately. The recipient's address is never reused or publicly linked to their identity.

How it works

Sender (AI agent)                         Recipient
────────────────                          ─────────
1. Look up bob.eth                        (published stealth meta-address)
2. Generate one-time stealth address      ← fresh address, unlinkable to bob.eth
3. Send tokens to stealth address         ← on-chain transfer
4. Announce via ERC-5564                  ← so recipient can discover it
                                          5. Scan announcements → find payment
                                          6. Claim via `claim-stealth-payment`
                                             (derive + withdraw server-side)

Nobody except the recipient can tell they received the payment. The stealth address has never appeared on-chain before and cannot be linked to their public ENS name.

Quick start

Install

git clone https://github.com/mandalito/StealthPay-MCP.git
cd StealthPay-MCP
npm install
npm run build

Configure environment

cp .env.example .env

Edit .env:

# Required: wallet private key for sending payments / registering ENS names
SENDER_PRIVATE_KEY=0x<your-private-key>

# For testnet: set ENS resolution to Sepolia
ENS_CHAIN=sepolia

# Optional: custom RPC endpoints (defaults to public RPCs)
# RPC_URL=https://eth-sepolia.g.alchemy.com/v2/<key>
# ENS_RPC_URL=https://...

# Optional: recipient keys (for scan/claim flows)
# Fill these from `register-stealth-keys` output
# RECIPIENT_SPENDING_PRIVATE_KEY=0x...
# RECIPIENT_SPENDING_PUBLIC_KEY=0x...
# RECIPIENT_VIEWING_PRIVATE_KEY=0x...
# RECIPIENT_VIEWING_PUBLIC_KEY=0x...

# Optional: agent spend policy controls
# POLICY_MAX_PER_TX=0.1                    # Per-transaction cap in ETH (default: 0.1)
# POLICY_MAX_DAILY_SPEND=1.0               # Rolling 24h limit in ETH (default: 1.0)
# POLICY_CHAIN_ALLOWLIST=sepolia,base       # Comma-separated; empty = all allowed
# POLICY_TOKEN_ALLOWLIST=ETH,USDC           # Comma-separated; empty = all allowed
# POLICY_DESTINATION_ALLOWLIST=alice.eth     # Comma-separated; empty = all allowed
# POLICY_ADMIN_ADDRESS=0x...                # Admin key for signed policy updates
# POLICY_IMMUTABLE=false                    # If true, blocks agent policy field changes via set-profile
# POLICY_VERSION=0                          # Policy schema version (for rollback protection)
# POLICY_EFFECTIVE_AT=2026-01-01T00:00:00Z  # ISO 8601 policy effective timestamp

Recipient key handling:

• register-stealth-keys generates recipient keys and saves them directly to local .env.
• Private keys are not returned through MCP output to the AI/client surface.
• Only the stealth meta-address is written on-chain; private keys are never stored on-chain.
• .env is gitignored, so these secrets stay local unless you export them elsewhere.

Security Model

StealthPay MCP follows one non-negotiable rule: private keys must never be exposed to the agent model under any circumstances.

Key philosophy

• Agents can trigger MCP tools, but they must not receive private key material in tool inputs or outputs.
• This includes sender account keys, recipient spending/viewing keys, and derived stealth private keys.
• Secret material should remain inside the MCP runtime boundary only.

Operator responsibilities (install/deploy)

• Store keys in a secure local haven on your device (OS keychain, encrypted secret store, or equivalent).
• Ensure the secret store is reachable by MCP runtime but not directly reachable by the agent process.
• Never paste keys into chat, prompts, or tool arguments.
• Prefer runtime secret injection over plaintext files when possible.
• If you use .env for local development, keep it local, gitignored, permission-restricted, and outside shared/synced folders.
• Rotate any key immediately if exposure is suspected.

Current security controls in this repo

• register-stealth-keys writes generated keys locally and does not return private keys in MCP output.
• scan-announcements and claim-stealth-payment use env-only recipient key paths; key-bearing inputs are not part of tool schemas.
• Derived stealth private keys are used server-side for claim execution and are never returned to agent/client output.
• derive-stealth-key and withdraw-from-stealth are not registered MCP tools.
• Agent spend policy engine (src/lib/policy.ts) enforces per-tx caps, daily limits, and allowlists on every transaction path.
• POLICY_IMMUTABLE=true prevents agents from modifying policy fields via set-profile.
• Signed policy updates require a pinned POLICY_ADMIN_ADDRESS with version monotonicity (rollback protection).
• All policy events (load, check pass/fail, update accept/reject) are audit-logged to stderr.
• A test (test/tools/no-secrets-in-docs.test.ts) scans docs/examples for private-key-like hex strings.

Operational recommendations

• Use dedicated low-fund operational wallets, not personal main wallets.
• Do not run DEBUG=true test flows with real funds/keys.
• Treat logs, chat history, shell history, and screenshots as sensitive channels.
• Set POLICY_MAX_PER_TX and POLICY_MAX_DAILY_SPEND to appropriate limits for your use case.
• Set POLICY_IMMUTABLE=true in production to prevent agents from modifying payment policies.

Add to Claude Code

Global (available in all projects) — add to ~/.claude/.mcp.json:

{
  "mcpServers": {
    "stealthpay": {
      "command": "node",
      "args": ["/absolute/path/to/StealthPay-MCP/dist/index.js"],
      "cwd": "/absolute/path/to/StealthPay-MCP"
    }
  }
}

Project-only — add a .mcp.json in your project root with the same content.

Then restart Claude Code. The 13 registered tools will be available immediately.

Tools

Identity

Tool	Description
get-my-profile	Show current wallet, reverse ENS name, payment profile, and recipient-key status
generate-wallet	Generate and persist a local sender wallet in .env
get-balances	Check native/token balances of your sender wallet on a selected chain

Onboarding & Profile

Tool	Description
register-ens-name	Register a .eth name (commit → wait → register flow, ~65s)
register-stealth-keys	Generate spending/viewing keypairs and set the stealth-meta-address text record on your ENS name
set-profile	Set payment preferences on your ENS name: preferred chain, token, stealth policy, and note preferences. Writes to both stealthpay.v1.* and legacy ENS text records.
set-primary-name	Set the ENS reverse record so your wallet address resolves back to your ENS name.

Sending payments

Tool	Description
get-payment-profile	Resolve ENS name → address, avatar, CAIP-normalized chain/token preferences, stealth meta-address, stealth/note policies
generate-stealth-address	Generate a one-time stealth address from an ENS name
send-stealth-payment	Send ETH / stablecoins / ERC-20 to a stealth address + announce via ERC-5564. Enforces recipient stealth/note policies and agent spend limits. Supports encrypted memos.
create-payment-link	Generate a shareable payment link (web URL + ERC-681 URI)

Receiving payments

Tool	Description
scan-announcements	Scan ERC-5564 events to discover payments addressed to you
claim-stealth-payment	Derive + withdraw in one step using locally stored recipient keys (keys never pass through AI)

Chain support and requirements

StealthPay flows depend on different on-chain requirements depending on the feature:

• ENS onboarding/resolution (register-ens-name, register-stealth-keys, get-payment-profile, generate-stealth-address) requires ENS contracts and an ENS-capable RPC on the selected ENS_CHAIN.
• Stealth payment flows (send-stealth-payment, scan-announcements, claim-stealth-payment) require:
  • ERC-5564 announcer deployment
  • ERC-6538 registry deployment
  • reachable RPC on the payment chain

Live deployment check (via eth_getCode) on 2026-03-21 for configured singleton addresses:

Chain	ERC-5564 announcer (0x5564...5564)	ERC-6538 registry (0x6538...6538)
ethereum	deployed	deployed
base	deployed	deployed
optimism	deployed	deployed
arbitrum	deployed	deployed
polygon	deployed	deployed
gnosis	deployed	deployed
sepolia	deployed	deployed
hoodi	not deployed	not deployed

ENS requirements

• ENS registration and resolver write operations are currently implemented for sepolia and ethereum only (see ENS_CONTRACTS).
• ENS resolution defaults to ethereum unless ENS_CHAIN=sepolia is set.
• Hackathon baseline uses Sepolia for both ENS and payment execution.

Practical support summary

• Operational now: ethereum, base, optimism, arbitrum, polygon, gnosis, sepolia (for stealth announcement/scan primitives).
• Not operational yet: hoodi (contracts missing at configured singleton addresses).

Programmable payment profile

StealthPay implements CAIP-normalized payment profiles using the stealthpay.v1.* ENS text record namespace. The set-profile tool writes both namespaced v1 keys and legacy keys for backwards compatibility. The get-payment-profile tool reads v1 keys first, with legacy fallback.

Canonical keys (stealthpay.v1.*):

Key	Type	Example
stealthpay.v1.profile_version	string	"1"
stealthpay.v1.preferred_chains	CSV	"eip155:8453,eip155:10" (CAIP-2)
stealthpay.v1.preferred_assets	CSV	"eip155:8453/erc20:0x833..." (CAIP-19)
stealthpay.v1.stealth_policy	enum	required | preferred | optional | disabled
stealthpay.v1.stealth_scheme_ids	CSV	"1"
stealthpay.v1.note_policy	enum	required | optional | none
stealthpay.v1.note_max_bytes	number	"140"
stealthpay.v1.note_privacy	enum	plaintext | encrypted | hash_only

Legacy keys (avatar, chain, token, stealth-meta-address, description) are still read as fallbacks and written alongside v1 keys during the migration window.

A machine-readable JSON Schema is published at schemas/payment-profile.schema.json.

Announcement metadata format

Stealth transfer announcement metadata (ERC-5564 event payload) is encoded as:

• viewTag (1 byte)
• selector (4 bytes, ERC-20 transfer selector or 0x00000000 for native)
• tokenAddress (20 bytes, 0x00...00 for native ETH)
• amount (32 bytes, uint256)
• memo (variable bytes, UTF-8 plaintext, encrypted envelope, or keccak256 hash — per recipient notePrivacy preference)

Testing

# Endpoint contract tests (all MCP tools, mocked deps)
npm run test:tools

# Unit tests (stealth math, payment links — no network)
npm run test:unit

# Default deterministic suite (unit + tool tests)
npm test

# ENS integration test (reads mainnet ENS; set ENS_RPC_URL for a reliable run)
npm run test:ens

# Re-check onchain singleton deployments across configured chains
npm run check:deployments

# Sepolia fork integration (on-demand)
# Uses SEPOLIA_FORK_URL (or RPC_URL fallback) as fork upstream.
# Set FORK_REQUIRED=true to fail hard if fork node cannot start.
npm run test:fork

# Full Sepolia E2E (send → announce → scan → claim)
# Requires SENDER_PRIVATE_KEY with Sepolia ETH
npm run test:e2e

# ENS flow E2E (resolve ENS → stealth address → send → scan)
npx tsx test/ens-e2e.ts

# Register ENS name + set stealth keys E2E
npx tsx test/register-e2e.ts <label>

Notes:

• *.test.ts files are deterministic Vitest suites.
• *-e2e.ts files are executable integration runners (live-network utilities), not part of default npm test.

Get Sepolia testnet ETH

1. Go to https://sepoliafaucet.com
2. Paste your wallet address
3. Run npm run test:e2e

Architecture

src/
├── index.ts                 # MCP server entry point (12 registered tools)
├── config.ts                # Chain configs, contract addresses, ABIs, CAIP helpers
├── lib/
│   ├── stealth.ts           # ERC-5564 stealth address math (secp256k1)
│   ├── ens.ts               # ENS resolution + payment profile (dual-read v1/legacy)
│   ├── ens-register.ts      # ENS name registration + text record setting
│   ├── profile.ts           # Payment profile types, ENS key mappings, validation
│   ├── payments.ts          # Token transfer + ERC-5564 announcement + note encryption
│   ├── scanner.ts           # Scan Announcement events, discover payments
│   ├── withdraw.ts          # Withdraw funds from stealth addresses
│   ├── policy.ts            # Agent spend policy engine (caps, limits, allowlists, audit)
│   └── note-encryption.ts   # Encrypted notes (ChaCha20-Poly1305, baseline + dual-envelope)
└── tools/                   # MCP tool wrappers (thin layer over lib/)
    ├── register-ens-name.ts
    ├── register-stealth-keys.ts
    ├── set-profile.ts
    ├── get-payment-profile.ts
    ├── generate-stealth-address.ts
    ├── send-stealth-payment.ts
    ├── create-payment-link.ts
    ├── get-my-profile.ts
    ├── generate-wallet.ts
    ├── get-balances.ts
    ├── scan-announcements.ts
    └── claim-stealth-payment.ts
schemas/
└── payment-profile.schema.json  # Machine-readable JSON Schema for payment profiles

Local Helpers (.local/)

.local/ is a gitignored workspace for local-only artifacts:

• cloned external repos used for reference (for example Umbra SDK source)
• temporary MCP probe scripts (.mjs) used to exercise tools over stdio during debugging

These scripts are not part of the production server and are not committed.

Standards

• ERC-5564 — Stealth Addresses (announcement)
• ERC-6538 — Stealth Meta-Address Registry
• MCP — Model Context Protocol

Dependencies

Package	Purpose
@modelcontextprotocol/sdk	MCP server
@noble/secp256k1	Elliptic curve math (stealth addresses, ECDH)
@noble/hashes	Hashing (HKDF-SHA256, keccak256 peer dep)
@noble/ciphers	Symmetric encryption (ChaCha20-Poly1305 for encrypted notes)
viem	ENS + transactions + keccak256
zod	Input validation
dotenv	Environment variable loading

Known limitations

• Token-only stealth account cannot withdraw without native gas: If a stealth account receives non-native tokens but has 0 native ETH, withdrawal fails until gas is funded. Gasless/paymaster is not in hackathon MVP scope.
• Hoodi testnet status: Chain config exists, but production-grade ERC-5564/6538 readiness remains unvalidated for this repo.
• Metadata format compatibility: Scanner parsing assumes this project's metadata conventions; other ERC-5564 senders may encode differently.
• In-memory spend ledger: Daily spend tracking is in-process only and resets on server restart. Persistent storage is a future enhancement.

Future improvements

• Add ERC-4337/paymaster withdrawal flow so stealth accounts can move token-only balances without pre-funding native gas.
• Add send-stealth-payment mode for unsigned payload generation (build_unsigned_tx) in addition to direct execution.
• Improve scan performance/reliability with indexed backends (subgraph/indexer) and rate-limit-aware pagination.
• Persist spend ledger to disk or external store for daily limit continuity across restarts.
• Complete Umbra SDK integration path where it improves maintainability without breaking current ERC-5564/6538 behavior.

License

MIT