Section 2
Quickstart
Start with the dry run: a full paid request on an in-memory ledger, with no keys and no funds.
2.1Requirements
npm install https://doei.io/sdk/doei-sdk.tgzInstalled with -g, the package also puts two commands on your machine: doei, for the owner, and doei-mcp, the server a model talks to.
npm install -g https://doei.io/sdk/doei-sdk.tgz
doei init # a key, limits, and the MCP config to paste
doei fetch "https://doei.io/api/paid/price?symbol=SOL" # a first paid request, 0.001 USDC
doei history # what moved in and out
doei stop # refuse every payment until "doei resume"The SDK is TypeScript, ESM only, and needs Node 24 or later. It depends on @heliuslabs/spr for Privacy Rings and on @modelcontextprotocol/sdk for the MCP server.
2.2Dry run, no network
This file builds two wallets on a MemoryLedger, puts a paywall in front of a handler, and lets the agent wallet fetch it. The wallet, the policy check, the 402 parsing, the proof and the paywall are the real code. Only the ledger is simulated.
import {
USDC_DEVNET,
createAgentWallet,
createPaywall,
formatAmount,
} from "@doei/sdk";
import { MemoryLedger, MemoryRail, routeFetch } from "@doei/sdk/sim";
const ledger = new MemoryLedger();
const agent = MemoryRail.fromLabel(ledger, "agent");
const provider = MemoryRail.fromLabel(ledger, "provider");
await agent.deposit(USDC_DEVNET, 25_000_000n);
const paywall = createPaywall({
network: ledger.network,
asset: USDC_DEVNET,
payTo: provider.address,
secret: crypto.getRandomValues(new Uint8Array(32)),
incoming: provider,
});
const url = "https://api.example.test/v1/search";
const wallet = createAgentWallet({
rail: agent,
asset: USDC_DEVNET,
policy: {
version: 1,
asset: "USDC",
maxPerPayment: "0.05",
dailyBudget: "2.00",
payees: "any",
expiresAt: null,
},
fetch: routeFetch({
[url]: paywall.protect(4_200n, () => Response.json({ results: 3 })),
}),
});
const response = await wallet.fetch(url, {
trace: (event) => console.log(event.step),
});
console.log(response.status, await response.json());
// What an explorer would show, and what the agent's own keys show.
console.log(ledger.publicView().map((row) => [row.kind, row.amount]));
const own = await agent.entries();
console.log(own.map((row) => [row.kind, formatAmount(row.amount, 6)]));request
challenge
authorized
paid
retry
response
200 { results: 3 }
[ [ 'deposit', 25000000n ], [ 'transfer', null ] ]
[ [ 'deposit', '25.00' ], [ 'transfer', '0.0042' ] ]The last two lines are the point. The public view of the ledger shows the deposit of 25 and a transfer with no amount. The agent's own view, read with its keys, shows 0.0042. The test suite runs this file and compares its output with the block above.
2.3A wallet on Privacy Rings
On a network, swap the memory rail for createRingsRail. It needs the agent's 32-byte seed and a Helius RPC URL, which also serves the Rings indexer and prover. The URL carries an API key, so keep it on a server.
The shortest way to a funded wallet is the wallet page: it makes the key in your browser, waits for funds, registers the wallet and moves the USDC into its private balance. The steps below do the same in code.
import { USDC, createAgentWallet } from "@doei/sdk";
import { createRingsRail } from "@doei/sdk/rings";const rail = await createRingsRail({
network: "solana-mainnet",
ownerSeed: await loadAgentSeed(), // the agent's 32-byte Ed25519 seed
rpcUrl: process.env.HELIUS_RPC_URL!, // carries your API key: keep it server-side
});
const wallet = createAgentWallet({
rail,
asset: USDC,
policy: {
version: 1,
asset: "USDC",
maxPerPayment: "0.50",
dailyBudget: "5.00",
payees: "any",
expiresAt: null,
},
});2.4Fund it
Register once, then deposit. Registration publishes the wallet's shielded address so other wallets can pay it. A deposit is a public transaction: its amount is visible on-chain, and so is the fact that this address funded a private balance.
await rail.register(); // once: lets other wallets pay this one privately
await wallet.deposit("25"); // public: the chain shows a 25 USDC deposit2.5Pay an address
wallet.pay sends a confidential transfer to a registered address. The policy is checked first. The memo is stored in the receipt and goes nowhere else.
const receipt = await wallet.pay({
to: SEARCH_API,
amount: "0.0042",
memo: "search: solana priority fees",
});
console.log(receipt.signature, receipt.total);2.6Pay for a request
wallet.fetch has the signature of fetch. If the server answers 402 with a Doei challenge, the wallet pays the stated price and repeats the request once with proof. Any other response comes back untouched. maxAmount refuses a price before the policy is even asked.
const url = "https://api.example.com/v1/search?q=priority+fees";
const response = await wallet.fetch(url, {
maxAmount: "0.01", // refuse a 402 that asks for more
});
const results = await response.json();2.7Give it to a model
To let a model spend, run the MCP server next to your MCP client. This configuration starts it on the memory rail, which is a dry run with a simulated balance. Set DOEI_RAIL to rings and add the endpoints to use a real balance.
{
"mcpServers": {
"doei": {
"command": "node",
"args": ["packages/sdk/src/mcp/server.ts"],
"env": {
"DOEI_POLICY": "./doei.policy.json",
"DOEI_STATE": "./.doei/state.json",
"DOEI_RAIL": "memory"
}
}
}
}Next: the policy file the server reads, the five tools the model sees, and the privacy model you are relying on.