Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

13.9 KB
Raw Blame
<!doctype html>
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1" />
		<title>Onchain Agent Wallets · Spending allowances for AI agents on Solana</title>
		<meta
			name="description"
			content="Give an AI agent a real Solana wallet without giving it your money. An MCP server for spending allowances the SPL Token program enforces on-chain, with guardrails, x402 payments, and revocable custody."
		/>
		<meta property="og:type" content="website" />
		<meta property="og:title" content="Onchain Agent Wallets" />
		<meta
			property="og:description"
			content="Give an AI agent a real Solana wallet without giving it your money. The chain enforces the ceiling; you keep custody."
		/>
		<meta property="og:url" content="https://nirholas.github.io/onchain-agent-wallets/" />
		<meta name="twitter:card" content="summary_large_image" />
		<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🔐</text></svg>" />
		<style>
			:root {
				--bg: #ffffff;
				--fg: #0d1117;
				--muted: #57606a;
				--line: #d8dee4;
				--card: #f6f8fa;
				--code-bg: #f6f8fa;
				--accent: #6d28d9;
				--accent-soft: #f3effd;
				--good: #1a7f37;
				--bad: #cf222e;
				--radius: 12px;
				--mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
				--sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, Helvetica, Arial, sans-serif;
			}
			@media (prefers-color-scheme: dark) {
				:root {
					--bg: #0d1117;
					--fg: #e6edf3;
					--muted: #9198a1;
					--line: #30363d;
					--card: #161b22;
					--code-bg: #161b22;
					--accent: #a78bfa;
					--accent-soft: #1d1b2e;
					--good: #3fb950;
					--bad: #f85149;
				}
			}
			* { box-sizing: border-box; }
			html { -webkit-text-size-adjust: 100%; }
			body {
				margin: 0;
				background: var(--bg);
				color: var(--fg);
				font-family: var(--sans);
				font-size: 17px;
				line-height: 1.65;
			}
			.wrap { max-width: 820px; margin: 0 auto; padding: 0 20px 80px; }
			header { padding: 72px 0 40px; border-bottom: 1px solid var(--line); }
			h1 { font-size: clamp(2rem, 6vw, 2.9rem); line-height: 1.15; margin: 0 0 16px; letter-spacing: -0.025em; }
			.tagline { font-size: clamp(1.05rem, 3vw, 1.3rem); color: var(--muted); margin: 0 0 28px; max-width: 40ch; }
			h2 { font-size: 1.5rem; margin: 56px 0 14px; letter-spacing: -0.015em; }
			h3 { font-size: 1.1rem; margin: 32px 0 8px; }
			p { margin: 0 0 16px; }
			a { color: var(--accent); text-decoration: none; }
			a:hover, a:focus-visible { text-decoration: underline; }
			a:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; border-radius: 3px; }
			code { font-family: var(--mono); font-size: 0.88em; background: var(--code-bg); padding: 0.15em 0.4em; border-radius: 6px; }
			pre {
				background: var(--code-bg);
				border: 1px solid var(--line);
				border-radius: var(--radius);
				padding: 16px 18px;
				overflow-x: auto;
				font-size: 0.85rem;
				line-height: 1.55;
				margin: 0 0 20px;
			}
			pre code { background: none; padding: 0; font-size: inherit; }
			.btns { display: flex; flex-wrap: wrap; gap: 12px; margin-top: 8px; }
			.btn {
				display: inline-block;
				padding: 10px 18px;
				border-radius: 8px;
				border: 1px solid var(--line);
				font-weight: 600;
				font-size: 0.95rem;
				transition: transform 0.12s ease, border-color 0.12s ease, background 0.12s ease;
			}
			.btn:hover { transform: translateY(-1px); text-decoration: none; border-color: var(--accent); }
			.btn.primary { background: var(--accent); color: #fff; border-color: var(--accent); }
			.btn.primary:hover { opacity: 0.92; }
			.lede { font-size: 1.05rem; }
			.diagram { width: 100%; height: auto; display: block; margin: 8px 0 24px; border: 1px solid var(--line); border-radius: var(--radius); background: var(--card); }
			table { width: 100%; border-collapse: collapse; margin: 0 0 24px; font-size: 0.92rem; display: block; overflow-x: auto; }
			th, td { text-align: left; padding: 10px 12px; border-bottom: 1px solid var(--line); vertical-align: top; }
			th { font-weight: 600; white-space: nowrap; }
			td:first-child { white-space: nowrap; font-family: var(--mono); font-size: 0.85em; }
			.callout {
				background: var(--accent-soft);
				border: 1px solid var(--line);
				border-left: 3px solid var(--accent);
				border-radius: var(--radius);
				padding: 16px 18px;
				margin: 0 0 24px;
			}
			.callout p:last-child { margin-bottom: 0; }
			ul { padding-left: 22px; margin: 0 0 18px; }
			li { margin-bottom: 7px; }
			.yes::before { content: "✓ "; color: var(--good); font-weight: 700; }
			.no::before { content: "✗ "; color: var(--bad); font-weight: 700; }
			footer { margin-top: 64px; padding-top: 24px; border-top: 1px solid var(--line); color: var(--muted); font-size: 0.9rem; }
			@media (max-width: 600px) { body { font-size: 16px; } header { padding: 48px 0 32px; } }
		</style>
	</head>
	<body>
		<div class="wrap">
			<header>
				<h1>Give an AI agent a real Solana wallet<br />without giving it your money.</h1>
				<p class="tagline">
					An allowance the SPL Token program enforces on-chain. Guardrails you control. x402 payments. Revocable in one
					instruction.
				</p>
				<div class="btns">
					<a class="btn primary" href="https://github.com/nirholas/onchain-agent-wallets">View on GitHub</a>
					<a class="btn" href="https://www.npmjs.com/package/@three-ws/onchain-agent-wallets">npm</a>
					<a class="btn" href="https://three.ws">three.ws</a>
				</div>
			</header>

			<h2>The problem</h2>
			<p class="lede">
				Every agent wallet today works the same way: you generate a keypair, you hand it to the agent, and now the agent
				has everything in it. No ceiling, no allowlist, no expiry, and no way to take it back short of racing the agent to
				move the funds. People work around this by keeping almost nothing in the wallet, which means the agent cannot do
				anything useful.
			</p>
			<p>
				An allowance is the older, better answer. The money never moves to the agent. The agent gets permission to spend a
				slice of it, and the chain enforces the slice.
			</p>

			<h2>How it works</h2>
			<svg class="diagram" viewBox="0 0 720 340" role="img" aria-labelledby="diagram-title">
				<title id="diagram-title">
					The owner owns a vault token account holding 500 USDC. The agent holds a delegation capped at 100 USDC over
					that vault, enforced by the SPL Token program.
				</title>
				<g font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="13">
					<rect x="30" y="20" width="300" height="66" rx="10" fill="none" stroke="currentColor" stroke-opacity="0.35" />
					<text x="46" y="46" fill="currentColor" font-size="14" font-weight="700">YOU</text>
					<text x="46" y="68" fill="currentColor" fill-opacity="0.7">Phantom · Solflare · Ledger</text>

					<line x1="90" y1="86" x2="90" y2="126" stroke="currentColor" stroke-opacity="0.4" stroke-width="1.5" />
					<polygon points="86,126 94,126 90,134" fill="currentColor" fill-opacity="0.4" />
					<text x="106" y="112" fill="currentColor" fill-opacity="0.65" font-size="12">owns it, can revoke or withdraw any time</text>

					<rect x="30" y="136" width="530" height="112" rx="10" fill="currentColor" fill-opacity="0.04" stroke="currentColor" stroke-opacity="0.35" />
					<text x="46" y="162" fill="currentColor" font-weight="700">vault token account</text>
					<text x="46" y="186" fill="currentColor" fill-opacity="0.8">owner    = you</text>
					<text x="46" y="206" fill="currentColor" fill-opacity="0.8">balance  = 500 USDC</text>
					<text x="46" y="226" fill="currentColor" fill-opacity="0.8">delegate = the agent, capped at 100</text>
					<text x="330" y="226" fill="currentColor" fill-opacity="0.55" font-size="11">← SPL Token enforces this</text>

					<line x1="90" y1="248" x2="90" y2="288" stroke="currentColor" stroke-opacity="0.4" stroke-width="1.5" />
					<polygon points="86,248 94,248 90,240" fill="currentColor" fill-opacity="0.4" />
					<text x="106" y="274" fill="currentColor" fill-opacity="0.65" font-size="12">may spend up to the cap, and not one unit more</text>

					<rect x="30" y="288" width="300" height="42" rx="10" fill="none" stroke="currentColor" stroke-opacity="0.35" />
					<text x="46" y="314" fill="currentColor" font-weight="700">AGENT <tspan font-weight="400" fill-opacity="0.7">· holds only fee SOL</tspan></text>
				</g>
			</svg>

			<p>Two independent layers protect you, and they fail separately:</p>
			<ul>
				<li>
					<strong>On-chain.</strong> The SPL Token program checks every agent-signed transfer against
					<code>delegated_amount</code> and decrements it on each spend. No code in this project can raise it. A single
					<code>revoke</code> sets it to zero. Stock token program behaviour, not a new contract to trust.
				</li>
				<li>
					<strong>Local.</strong> Before signing anything, the server applies your rules: per-transaction cap, rolling
					24-hour cap, recipient allowlist, x402 host allowlist, expiry, pause, and a confirm-above threshold that forces
					a human yes.
				</li>
			</ul>
			<div class="callout">
				<p>
					If the machine running the agent is compromised, the local rules can be bypassed and the on-chain allowance
					still cannot. That is the point of splitting them. Keep the allowance at the smallest number that lets the
					agent work, and top it up.
				</p>
			</div>

			<h2>Install</h2>
			<pre><code>claude mcp add onchain-agent-wallets -- npx -y @three-ws/onchain-agent-wallets</code></pre>
			<p>
				No key required to start. Owner actions come back as an unsigned transaction for your wallet to sign. Set
				<code>OWNER_SECRET_KEY</code> only if you want the server to sign for you.
			</p>

			<h2>Quickstart</h2>
			<p>Give a research agent 100 USDC of spending power, capped at 5 per transaction and 20 per day, for one API only:</p>
			<pre><code>create_agent_wallet
  id: "researcher"
  allowance: "100"
  per_tx: "5"
  daily: "20"
  allow_hosts: ["api.example.com"]
  confirm: true

fund_agent_wallet  id: "researcher"  amount: "500"  sol: "0.02"  confirm: true</code></pre>
			<p>The agent then spends on its own, and you stay in control:</p>
			<pre><code>pay_x402             id: "researcher"  url: "https://api.example.com/premium"  confirm: true
agent_wallet_status  id: "researcher"                    # live balances, remaining allowance
spend_log            id: "researcher"                    # every spend AND every refusal
set_guardrails       id: "researcher"  paused: true      # instant, free, no transaction
revoke_agent_wallet  id: "researcher"  withdraw: true  confirm: true</code></pre>

			<h3>A refusal tells you exactly which rule fired</h3>
			<pre><code>{
  "ok": false,
  "error": "over_daily",
  "message": "20.5 would exceed the 20 daily cap (18 already spent)",
  "checks": [
    { "check": "per_tx", "ok": true,  "detail": "2.5 is within the 5 per-transaction cap" },
    { "check": "daily",  "ok": false, "detail": "20.5 would exceed the 20 daily cap (18 already spent)" }
  ]
}</code></pre>

			<h2>Guardrails</h2>
			<table>
				<thead>
					<tr><th>Rule</th><th>Effect</th><th>Enforced by</th></tr>
				</thead>
				<tbody>
					<tr><td>allowance</td><td>Total the agent may ever spend before a new approval</td><td>SPL Token program</td></tr>
					<tr><td>vault balance</td><td>The agent cannot spend what is not there</td><td>SPL Token program</td></tr>
					<tr><td>per_tx</td><td>Maximum single spend</td><td>this server</td></tr>
					<tr><td>daily</td><td>Maximum per rolling 24 hours</td><td>this server</td></tr>
					<tr><td>allow_recipients</td><td>Only these addresses may receive funds</td><td>this server</td></tr>
					<tr><td>allow_hosts</td><td>Only these hosts may be paid over x402</td><td>this server</td></tr>
					<tr><td>expires_at</td><td>Every spend refused after this timestamp</td><td>this server</td></tr>
					<tr><td>confirm_over</td><td>Spends above this need an explicit human yes</td><td>this server</td></tr>
					<tr><td>paused</td><td>Everything refused, instantly and for free</td><td>this server</td></tr>
				</tbody>
			</table>

			<h2>x402</h2>
			<p>
				<code>pay_x402</code> probes the endpoint unpaid first, so the price is known before anything moves and the
				guardrails see the real number. Then it tops the agent up for exactly that amount out of the vault, pays, and
				leaves the agent empty again. It refuses to pay on a chain other than Solana, on the wrong cluster, in a token the
				allowance is not denominated in, or above the per-call <code>max_price</code>.
			</p>

			<h2>What the agent cannot do</h2>
			<ul>
				<li class="no">Spend more than the allowance, however it is prompted. The token program decides that, not the model.</li>
				<li class="no">Move the vault, close it, or change its owner. It is not the owner.</li>
				<li class="no">Stop you withdrawing, or stop a revoke.</li>
				<li class="no">Raise its own allowance. Only an owner-signed approve does that.</li>
				<li class="no">Touch anything else in your wallet.</li>
			</ul>
			<p>
				<span class="yes"></span>Proven in
				<a href="https://github.com/nirholas/onchain-agent-wallets/blob/main/test/token-delegation.test.mjs"><code>test/token-delegation.test.mjs</code></a
				>, which runs the real SPL Token program in process and asserts that a spend of 61 against a remaining allowance of
				60 fails on-chain, with 460 still sitting in the vault.
			</p>

			<h2>Rehearse for free</h2>
			<pre><code>OAW_NETWORK=devnet npx -y @three-ws/onchain-agent-wallets</code></pre>
			<p>State is kept per network, so a devnet rehearsal never touches your mainnet agents.</p>

			<footer>
				<p>
					Built by <a href="https://three.ws">three.ws</a> ·
					<a href="https://github.com/nirholas/onchain-agent-wallets">GitHub</a> ·
					<a href="https://www.npmjs.com/package/@three-ws/onchain-agent-wallets">npm</a> ·
					<a href="https://github.com/nirholas/metaplex-agent-mcp">metaplex-agent-mcp</a>
				</p>
			</footer>
		</div>
	</body>
</html>