ShroudFi documentation

#Introduction

ShroudFi lets an AI agent receive and move funds on Base without exposing the link between its payments and its operating wallet. It implements the EIP-5564 stealth address standard and the EIP-6538 meta-address registry, wraps them in a TypeScript SDK, and extends the same surface through an MCP server and a REST API so any agent runtime can call it.

The design goal is narrow and concrete: break the on-chain link between an agent’s public identity and the addresses it transacts with, while preserving the operator’s ability to audit every payment. ShroudFi is not a mixer and does not pool funds. Each payment is a directed one-to-one stealth transfer, independently recoverable with a viewing key held by the operator.

What you get

• Single-use receiving addresses derived per payment — no address reuse, no clustering.
• Client-side cryptography — keys never leave the agent’s process; no ShroudFi server sees them.
• Gasless sweeps — ERC-20 via EIP-2612 permit, ETH via EIP-7702 delegated relayer.
• x402 stealth payments — HTTP 402 challenges settled into stealth addresses; USDC or EURC on Base.
• Three surfaces — TS SDK, MCP server, REST API. Same on-chain guarantees underneath.
• Viewing keys — operators export a complete, attributable audit trail on demand.

#The agentic economy

The agent economy is being built in public on rails that publish every payment forever. Humans tolerate this because most personal transactions are low-frequency and low-signal. Agents do the opposite — they transact continuously, with strategy encoded in every move.

What today’s public-by-default ledger looks like for an autonomous agent:

• Every fill, rebalance, and hedge published to a queryable graph.
• Every API call paid for revealed as this wallet bought from that wallet at this price.
• Every counterparty, settlement timing, and amount permanently linkable.

ShroudFi closes the address-layer leak so the agent can keep operating on public infrastructure (Base, USDC, standard wallets) without surrendering its strategy to anyone with a block explorer. Critically, none of this requires a new chain, a new mempool, or a new wallet standard — only EIP-5564, ERC-6538, and the SDK that turns them into one-line operations.

The longer-term thesis is simple: agent-to-agent commerce becomes a real economy only when each payment doesn’t doxx the routing graph. ShroudFi makes that the default on Base.

#Stealth addresses 101

A stealth address is a one-time destination only the recipient can spend from, derived freshly for each payment. The recipient publishes a single, long-lived meta-address; senders use it to compute unique destinations that cannot be correlated to one another or back to the meta-address.

The protocol, briefly

1. The recipient generates two keypairs — a spending key and a scanning key — and publishes their public halves as a meta-address (st:base:0x…).
2. To pay, the sender generates an ephemeral keypair and combines its private half with the recipient’s public keys to derive a unique stealth address.
3. The sender publishes the ephemeral public key in an on-chain announcement and sends funds to the stealth address.
4. The recipient scans announcements with their scanning key, recognises payments meant for them, and derives the matching private key to spend.

// recipient: publish a meta-address once
await agent.register()
// → st:base:0x03a1...c9 — safe to post publicly

// sender: derive a fresh stealth address for this payment
await agent.sendToWallet(peer, { token: USDC }, 25_000000n)

View tags

Scanning every announcement on chain would be expensive. EIP-5564 includes a one-byte view tag derived alongside each payment. A recipient first checks the tag — a single byte comparison — and only performs full key derivation on the ~1-in-256 announcements that match. ShroudFi’s @shroud-fi/scanning package handles this filtering automatically.

#x402 stealth payments

HTTP 402 (“Payment Required”) was reserved in the original spec and stayed effectively unused for decades. With on-chain stablecoins (USDC, EURC) + EIP-3009 transferWithAuthorization, it has become the natural way for one agent to charge another over plain HTTP. ShroudFi adds the missing privacy layer: the payment lands at a stealth address, not at a fixed treasury wallet — and settles through PayAI’s facilitator (gasless for the payer), proven on Base mainnet.

The flow

1. Buyer agent calls a seller endpoint.
2. Seller responds 402 Payment Required with a typed-data challenge: amount, asset, valid window, EIP-3009 domain.
3. Buyer signs the EIP-3009 authorisation in-memory; no broadcast yet.
4. Buyer re-calls with the signed envelope in the X-PAYMENT header.
5. Seller derives a fresh stealth address from its meta-address, broadcasts transferWithAuthorization into that stealth address, and unlocks the body.

The on-chain footprint is one USDC Transfer event from buyer to a random-looking stealth address. The buyer’s wallet is visible (it signed the auth), but the recipient — the seller’s treasury — is not. Run this at scale and the seller’s customer graph becomes unindexable.

import { createX402Server } from '@shroud-fi/x402'

const server = createX402Server(({
  transport, recipientMetaAddress: agent.metaAddressEncoded,
  asset: USDC_BASE, defaultPriceAtomic: 10_000n
})

// in your HTTP handler
if (!req.headers['x-payment']) return server.challenge()
const ok = await server.verify(req.headers['x-payment'])
if (ok.verified) return unlockedBody

The same primitives are available as payX402 on the client side, as shroud_x402_pay + shroud_x402_serve tools in the MCP server, and as POST /v1/x402-pay + /v1/x402-serve in the REST API. Try the live two-panel demo at app.shroudfi.live/x402.

#Threat model

ShroudFi is designed against a specific adversary: a passive on-chain observer with full visibility of Base’s public ledger and unlimited analysis budget. This is the realistic threat for an autonomous agent — competitors, MEV searchers, and analysts who reconstruct strategy from the transaction graph.

ShroudFi addresses linkability at the address layer. It does not anonymise the network layer (RPC, mempool submission IP) and does not hide that some stealth payment occurred. See Limitations for the full boundary.

#Privacy invariants

These properties are guaranteed by construction. They hold as long as the underlying cryptographic assumptions (secp256k1 ECDH, keccak-256, EIP-712 / EIP-3009 domain separation) hold and key material is not exfiltrated from the agent host.

• Unlinkability. No two stealth addresses derived for the same recipient can be linked to each other, or to the recipient’s meta-address, without the scanning key.
• Non-custody. ShroudFi never holds, escrows, or pools user funds. Spending authority for every stealth address remains solely with the recipient’s spending key.
• Operator auditability. The holder of the scanning key can deterministically recover the complete set of payments to a meta-address — nothing is hidden from the operator.
• Selective disclosure. A viewing key can be shared with an auditor to reveal incoming payments without granting spend authority and without revealing live strategy.
• Relayer blindness to amounts. The relayer pays gas and broadcasts the sweep; it never reads or surfaces the transfer amount in any log, error string, or telemetry channel.
• No plaintext amounts in error strings. SDK error classes are constructed without amount bytes, address bytes, or signature bytes.
• Spend key never serialises. No JSON.stringify path in any package reaches a spending key; static greps in CI fail the build if a violation lands.

#Architecture

ShroudFi is three layers: a thin on-chain contract set, a pure-TypeScript privacy engine, and three surfaces your agent can call. Everything cryptographic happens client-side.

Contracts

Four immutable contracts on Base mainnet:

• ShroudFiStealth — EIP-5564 announcer. Emits an event with the ephemeral pubkey + view tag per payment.
• ShroudFiRegistrar — EIP-6538 registry. Maps a wallet address to a published meta-address.
• ShroudFiRelayer — ERC-2771 trusted-forwarder. Routes gasless ERC-20 sweeps through Gelato 1Balance.
• ShroudFiEthRelayer — EIP-7702 delegated code on a relayer EOA. Routes gasless native-ETH sweeps.

All four are source-verified on Blockscout and Etherscan V2. Addresses are on the Status page.

Privacy engine

Nine packages compose into the engine: key derivation, view-tag computation, announcement scanning, gasless sweep planning, x402 client / server. No network dependencies of their own beyond a Base RPC endpoint; everything runs inside the agent process.

Three surfaces

Same engine, three integration shapes — pick the one that matches your runtime.

contracts  →  engine  →  { SDK, MCP, REST }

// immutable             pure TS                  TypeScript
// on Base mainnet       view-tag scanning,       Claude/Cursor MCP,
//                       sweep planning,          api.shroudfi.live
//                       x402 client+server

For full package surface — install commands, signatures, types — see the SDK Reference.

#SDK · MCP · REST

The on-chain guarantees are identical underneath. Pick the surface that fits your agent:

• SDK — @shroud-fi/agent-runtime + companions. The most direct integration for any TS / JS agent. Lives inside your process.
• MCP server — @shroud-fi/mcp-server. 9 tools exposed over stdio or HTTP. Drop into Claude Code, Cursor, Windsurf, Zed AI, or any custom MCP host.
• REST API — apps/api (self-host) or api.shroudfi.live (hosted). 7 v1 endpoints, OpenAPI 3.1 schema, EIP-191 challenge-response auth. Language-agnostic.

Set SHROUDFI_MASTER_SEED the same way across surfaces and the agent identity / meta-address resolves identically — no re-onboarding, no drift.

#Limitations

ShroudFi is deliberate about its boundary. The following are out of scope and should be addressed separately in any production deployment.

• Network-layer privacy. ShroudFi does not anonymise the IP or RPC endpoint submitting transactions. Pair with a private mempool or transaction relay for network-layer protection.
• Timing correlation. A large, isolated payment immediately followed by a sweep can still be correlated by timing. Relayer batching + log-normal sweep delay reduce but do not eliminate this.
• Amount fingerprinting. Unusual or round amounts may narrow the anonymity set. Amount privacy is a research item — EVM has no native equivalent to Solana’s Token-2022 confidential transfers yet.
• Host security. ShroudFi protects on-chain linkability, not a compromised agent runtime. Secure key storage is the operator’s responsibility.
• Independent audit in progress. All four contracts are immutable and source-verified on Base mainnet. A third-party audit is underway; results published on the status page when complete.