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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(onchain-agent-wallets): publish the custody model as a GitHub Pages overview
nirholas2400eaabff23
diff --git a/packages/onchain-agent-wallets/README.md b/packages/onchain-agent-wallets/README.mdindex c676bf14a..e72b6752d 100644--- a/packages/onchain-agent-wallets/README.md+++ b/packages/onchain-agent-wallets/README.md@@ -6,6 +6,8 @@ An MCP server that hands any agent a spending allowance instead of a private keyNothing here is mocked: real SPL Token delegations, real Solana, real x402 settlement.+**[Read the overview](https://nirholas.github.io/onchain-agent-wallets/)** · [npm](https://www.npmjs.com/package/@three-ws/onchain-agent-wallets)+## The problem this solvesEvery "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. There is no ceiling, no allowlist, no expiry, and no way to take it back short of racing the agent to move the funds. People solve this by keeping almost nothing in the wallet, which means the agent cannot do anything useful.diff --git a/packages/onchain-agent-wallets/docs/.nojekyll b/packages/onchain-agent-wallets/docs/.nojekyllnew file mode 100644index 000000000..e69de29bbdiff --git a/packages/onchain-agent-wallets/docs/index.html b/packages/onchain-agent-wallets/docs/index.htmlnew file mode 100644index 000000000..a7ef6c849--- /dev/null+++ b/packages/onchain-agent-wallets/docs/index.html@@ -0,0 +1,288 @@+<!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>