@b402ai/sdk

Private on-chain execution for agents. Base, Arbitrum, BSC.

One private key. Anonymous smart wallet. Gasless transactions. ZK-proven privacy. Railgun fork with 0% protocol fees.

Install

npm install @b402ai/sdk

Quick Start

import { B402 } from '@b402ai/sdk'

const b402 = new B402({ privateKey: process.env.WORKER_PRIVATE_KEY! })

// Shield — move USDC into privacy pool (gasless, breaks on-chain link)
await b402.shieldFromEOA({ token: 'USDC', amount: '10' })

// Private swap — atomic via RelayAdapt, zero trace
await b402.privateSwap({ from: 'USDC', to: 'WETH', amount: '5' })

// Private cross-chain — LI.FI routing, destination unlinkable from source
await b402.privateCrossChain({
  toChain: 'arbitrum',
  fromToken: 'USDC',
  toToken: 'USDC',
  amount: '5',
  destinationAddress: '0x...',
})

// Private lend — deposit into Morpho vault from pool
await b402.privateLend({ amount: '10', vault: 'steakhouse' })

// Check status
const s = await b402.status()

No API keys needed. The SDK derives an anonymous smart wallet, and the b402 facilitator sponsors all gas.

For Agents — One Verb

b402.execute({ action, ...args }) is the agent-native entrypoint. Maps 1:1 to the {name, arguments} shape LLMs emit as tool calls. A discriminated union preserves full TypeScript autocomplete — picking an action narrows the rest of the params to that method's shape.

await b402.execute({ action: 'privateSwap', from: 'USDC', to: 'WETH', amount: '10' })
await b402.execute({ action: 'privateLend', token: 'USDC', amount: '100', vault: 'steakhouse' })
await b402.execute({ action: 'privateCrossChain', toChain: 'arbitrum', fromToken: 'USDC', toToken: 'USDC', amount: '50', destinationAddress: '0x...' })
await b402.execute({ action: 'shield',   token: 'USDC', amount: '10' })
await b402.execute({ action: 'unshield', token: 'USDC', amount: '5' })

Under the hood it routes to the typed methods below — use either surface interchangeably.

How It Works

Your Key → Incognito EOA → Anonymous Smart Wallet → DeFi
              (derived)        (gasless, untraceable)

Shield deposits tokens into the Railgun privacy pool. Private operations (privateSwap, privateLend, privateCrossChain) unshield into a RelayAdapt contract, execute DeFi calls, and shield the output — all in one atomic transaction. On-chain observers see the RelayAdapt contract, never your wallet.

Configuration

const b402 = new B402({
  privateKey: '0x...',              // Required. Derives anonymous wallet.
  chainId: 8453,                    // Optional. 8453 Base (default) | 42161 Arbitrum | 56 BSC
  rpcUrl: 'https://...',            // Optional. Override RPC. Set BASE_RPC_URL env for production.
  facilitatorUrl: 'https://...',    // Optional. Default: production facilitator.
  backendApiUrl: 'https://...',     // Optional. Override UTXO/merkle indexer endpoint.
  onProgress: (event) => { ... },   // Optional. Step-by-step progress updates.
})

Default RPC (Alchemy free tier) works for testing. For production, set BASE_RPC_URL / ARB_RPC_URL / BSC_RPC_URL in your environment.

Backend API URL — resolution order

1. config.backendApiUrl — constructor option, highest priority
2. process.env.B402_BACKEND_API_URL — global env override
3. process.env.BASE_BACKEND_API_URL / ARB_BACKEND_API_URL — per-chain env
4. Chain-specific production default

API

Unified Dispatcher

b402.execute(params) — Agent-native entrypoint

One method, tagged by action. Type-safe — the action field narrows params to that method's shape and the return type to that method's result. Routes internally to the typed methods.

import type { ExecuteParams, ExecuteResultMap } from '@b402ai/sdk'

// action narrows params AND the return type
const r = await b402.execute({ action: 'privateLend', token: 'USDC', amount: '100', vault: 'steakhouse' })
// r: { txHash, amount, vault }

Supported actions: privateSwap, privateLend, privateRedeem, privateCrossChain, shield, unshield.

Private DeFi (via RelayAdapt)

All private operations execute atomically through Railgun's RelayAdapt contract. On-chain observers see the contract, never your wallet.

b402.privateSwap({ from, to, amount }) — Private token swap

Routes via Odos aggregator (all Base DEXes). No API key needed.

const result = await b402.privateSwap({ from: 'USDC', to: 'WETH', amount: '0.5' })
// { txHash, amountIn, amountOut, tokenIn, tokenOut }

b402.privateLend({ amount, vault? }) — Private vault deposit

Deposits into Morpho vault from privacy pool. Vault shares shielded back into pool.

await b402.privateLend({ amount: '100', vault: 'steakhouse' })

b402.privateRedeem({ vault? }) — Private vault withdrawal

const { assetsReceived } = await b402.privateRedeem({ vault: 'steakhouse' })

b402.privateCrossChain({ toChain, fromToken, toToken, amount, destinationAddress }) — Private cross-chain

Routes via LI.FI (~30 bridges, ~20 DEXes). Source unlinkable from destination.

const result = await b402.privateCrossChain({
  toChain: 'arbitrum',
  fromToken: 'USDC',
  toToken: 'ARB',
  amount: '1',
  destinationAddress: '0x...',
})
// { txHash, tool, expectedAmountOut, minAmountOut, estimatedDurationSec }

Privacy Pool

b402.shieldFromEOA({ token, amount }) — Enter pool (gasless)

Gasless shield from your EOA using EIP-3009. Best for bootstrapping — no ETH needed.

await b402.shieldFromEOA({ token: 'USDC', amount: '100' })

b402.shield({ token, amount }) — Enter pool (from smart wallet)

Moves tokens from the anonymous smart wallet into the Railgun privacy pool.

const { txHash, indexed } = await b402.shield({ token: 'USDC', amount: '100' })

b402.unshield({ token, amount }) — Exit pool

Generates a ZK proof (Groth16) client-side and withdraws to the anonymous smart wallet.

const { txHash } = await b402.unshield({ token: 'USDC', amount: '50' })

b402.consolidate({ token? }) — Merge UTXOs

Merges fragmented UTXOs into one. Auto-runs before private operations when needed.

b402.status() — Full state

const s = await b402.status()
// s.smartWallet       — anonymous wallet address
// s.balances          — [{ token: 'USDC', balance: '50.0' }]
// s.shieldedBalances  — [{ token: 'USDC', balance: '25.0' }]
// s.positions         — [{ vault: 'steakhouse', assets: '100.5 USDC', apyEstimate: '3.5%' }]
// s.lpPositions       — [{ pool: 'weth-usdc', usdValue: '500', apyEstimate: '7.6%' }]

Yield (Morpho Vaults)

b402.lend({ token, amount, vault? }) — Direct vault deposit

await b402.lend({ token: 'USDC', amount: '100', vault: 'steakhouse' })

Vault	Name	APY
steakhouse	Steakhouse USDC	3-4%
moonwell	Moonwell Flagship USDC	3-4%
gauntlet	Gauntlet USDC Prime	3-4%
steakhouse-hy	Steakhouse High Yield	3-4%

b402.redeem({ vault?, shares? }) — Direct vault withdrawal

b402.rebalance(minApyDiff?) — Move to highest-yield source

Other Operations

b402.transact(calls) — Arbitrary smart contract calls

Execute any calldata through the anonymous smart wallet. Gasless.

await b402.transact([{ to: '0x...', value: '0', data: '0x...' }])

Static Helpers

B402.vaults          // available yield vaults
B402.tokens          // supported tokens per chain
B402.pools           // Aerodrome LP pools (Base)

Chains

Chain	ID	Railgun Fork (0% fees)	Operations
Base	8453	0x26111e2379...	Full DeFi: privateSwap, privateLend, privateCrossChain, LP, perps
Arbitrum	42161	0x9dB0eDC77C...	Privacy: shield, unshield, transact
BSC	56	0x9dB0eDC77C...	Privacy: shield, unshield, transact

Select at runtime: new B402({ chainId: 42161 }). Default is Base.

For Agents

Every method takes plain strings and returns plain objects. No ABI encoding, no gas estimation, no nonce management.

For Claude Desktop / Cursor, install the MCP server:

npx b402-mcp@latest --claude

Error Handling

Error	Cause
privateKey or signer is required	Missing private key
Unknown token: X	Token not supported on this chain
No shielded balance	Called private op without shielding first
Facilitator verify failed	Invalid UserOp or facilitator issue
Unsupported chain	Called DeFi method on non-Base chain

License

MIT