@shroud-fi/agent-runtime

The high-level ShroudFi surface most projects integrate against.

npm i @shroud-fi/agent-runtime viem

What it does

@shroud-fi/agent-runtime composes @shroud-fi/core + @shroud-fi/payments + @shroud-fi/scanning + @shroud-fi/relayer into a single ShroudAgent surface. One createShroudAgent call wires deterministic identity, transport, scanner, and sweep paths.

Most agents only need this package — the lower-level building blocks (core, payments, scanning) are available if you need finer control.

Quick start

import { createShroudAgent } from '@shroud-fi/agent-runtime';

const agent = await createShroudAgent({
  chain: 'base',
  masterSeed: process.env.SHROUDFI_MASTER_SEED!,
  rpcUrl: process.env.SHROUDFI_RPC_URL!,
});

// 1. Register your meta-address (idempotent — no-op on second call)
await agent.register();

// 2. Send to a peer agent (by wallet — SDK looks up the meta-address)
const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
await agent.sendToWallet('0xPeerWallet', { token: USDC }, 25_000_000n); // 25 USDC

// 3. Detect incoming payments
const detections = await agent.receive({ fromBlock: 46_800_000n });

// 4. Sweep to your real wallet (gasless via relayer if ERC-20)
for (const d of detections) {
  await agent.sweep(d, '0xYourMain', { viaRelayer: true });
}

The four operations

Every agent does the same four things:

| Method | Purpose | |---|---| | agent.register() | Publish meta-address into the ERC-6538 registry. Idempotent. | | agent.send(to, asset, amount) | Send to a stealth meta-address (privacy-native) or a wallet (with auto-lookup). | | agent.sendToWallet(wallet, asset, amount) | Convenience: send to a plain wallet via meta-address resolution. | | agent.receive(range) | Scan a block range for inbound payments. | | agent.sweep(detection, destination, opts?) | Direct or relayer-routed sweep. Auto-routes ERC-20 via Gelato, ETH via EIP-7702 when viaRelayer: true. |

Address book (v0.1.1)

Local-only registry of human-friendly labels → wallet addresses or stealth meta-addresses. Persisted at ~/.shroudfi/contacts.json (file mode 0600). Never transmitted, never used by the SDK behind the scenes — you resolve labels yourself.

agent.contacts.add('alice', '0x15019ce49845c71e9db53de2bb92b761ced12240');
agent.contacts.add('bob',   'st:base:0x024fa9bb...');

const alice = agent.contacts.get('alice');
if (alice?.kind === 'wallet') {
  await agent.sendToWallet(alice.value as `0x${string}`, { token: USDC }, 10_000_000n);
}

agent.contacts.list();        // sorted by label
agent.contacts.remove('alice');

Errors are privacy-safe: InvalidContactLabelError, InvalidContactValueError, ContactAlreadyExistsError, UnknownContactError — none of them embed the label or value in the message.

Exports

| Symbol | Purpose | |---|---| | createShroudAgent(cfg) | The one entry point. | | ShroudAgent | Type of the returned object. | | RelayerNotAvailableForETHError | Thrown for sweep({ viaRelayer: true }) when the ETH relayer isn't wired and the asset is native ETH. |

Full API reference: shroudfi.live/sdk#agent-runtime

License

MIT — see LICENSE.

Part of the ShroudFi privacy SDK for AI agents on Base.