Onchain Agent Wallets

onchain-agent-wallets

[GitHub stars] [License] [Last commit] [PRs welcome] [AI agent friendly]

Give an AI agent a real Solana wallet without giving it your money.

An MCP server that hands any agent a spending allowance instead of a private key. The funds stay in an account you own. The agent gets a delegation the SPL Token program caps on-chain, plus guardrails you control, plus the ability to pay x402 APIs out of that allowance. You can revoke it in one instruction, and take the money back without asking the agent.

Nothing here is mocked: real SPL Token delegations, real Solana, real x402 settlement.

Read the overview · npm

The problem this solves

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. 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.

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.

How it works

   YOU (Phantom, Solflare, Ledger)    │  owns the vault, holds the money, can revoke or withdraw at any time    ▼  ┌──────────────────────────────────────────┐  │  vault token account                     │   derived from your address:  │  owner    = you                          │   createWithSeed(you, "oaw1:<agent>")  │  balance  = 500 USDC                     │  │  delegate = the agent  ← capped at 100   │   SPL Token enforces this number  └──────────────────────────────────────────┘    ▲    │  may spend up to the cap, and not one unit more   AGENT (its own keypair, holds only fee SOL)

Two independent layers protect you:

1. On-chain. The SPL Token program checks every agent-signed transfer against delegated_amount and decrements it on each spend. Our code cannot raise it. A single revoke sets it to zero. This is a stock token program feature, not a new contract to trust.
2. Local. Before this server signs anything it applies your rules: per-transaction cap, rolling 24-hour cap, recipient allowlist, x402 host allowlist, expiry, pause, and a confirm-above-this threshold that forces a human yes.

The agent's own keypair holds nothing but a little SOL for fees. If it leaks, the blast radius is the remaining allowance, and revoke_agent_wallet closes it in one transaction.

Install

npm install -g @three-ws/onchain-agent-wallets# or run it ad hocnpx -y @three-ws/onchain-agent-wallets

Setup

Claude Code:

claude mcp add onchain-agent-wallets -- npx -y @three-ws/onchain-agent-wallets

Cursor, or any MCP client (mcp.json):

{	"mcpServers": {		"onchain-agent-wallets": {			"command": "npx",			"args": ["-y", "@three-ws/onchain-agent-wallets"],			"env": {				"OAW_NETWORK": "mainnet"			}		}	}}

No key is required to start. Owner actions come back as an unsigned transaction for your wallet to sign, which send_signed_transaction then broadcasts. If you would rather this server sign for you, set OWNER_SECRET_KEY.

Quickstart

Give a research agent 100 USDC of spending power, capped at 5 per transaction and 20 per day, and only for one API:

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

The agent now spends on its own:

pay_x402  id: "researcher"  url: "https://api.example.com/premium"  confirm: trueagent_pay id: "researcher"  to: "<address>"  amount: "2.50"  confirm: true

And you stay in control:

agent_wallet_status  id: "researcher"      # live balances, remaining allowance, warningsspend_log            id: "researcher"      # every spend AND every refusal, with reasonsset_guardrails       id: "researcher"  paused: true      # instant, free, no transactionrevoke_agent_wallet  id: "researcher"  withdraw: true  confirm: true   # on-chain kill switch

A refusal tells you exactly which rule fired:

{	"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)" }	]}

Tools

Custody (you sign)

Guardrails

Spending (the agent signs)

Visibility

Deployment

Guardrails

The distinction matters when it goes wrong. If this machine is compromised, the local rules can be bypassed, and the on-chain allowance still cannot. That is why the allowance should be the smallest number that lets the agent work, topped up as needed, rather than the whole balance.

x402

pay_x402 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 (no_solana_option)
• on the wrong cluster, for instance a mainnet price from a devnet wallet (wrong_cluster)
• in a token the allowance is not denominated in (asset_mismatch)
• above max_price, a per-call ceiling independent of the standing guardrails (over_max_price)

If the endpoint is not charging, the content comes back and nothing is spent.

What the agent cannot do

• Spend more than the allowance, however it is prompted. The token program decides that, not the model.
• Move the vault, close it, or change its owner. It is not the owner.
• Stop you withdrawing, or stop a revoke.
• Raise its own allowance. Only an owner-signed approve does that.
• Touch anything else in your wallet. The vault is a separate account holding only what you put in it.

Proven in test/token-delegation.test.mjs, 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 sitting in the vault.

Rehearse for free on devnet

OAW_NETWORK=devnet npx -y @three-ws/onchain-agent-wallets

State is kept per network, so a devnet rehearsal never touches your mainnet agents.

Use it as a library

The custody model is plain @solana/web3.js and @solana/spl-token, usable without MCP:

import { createVaultInstructions, readVault, spendableUnits } from '@three-ws/onchain-agent-wallets/lib/vault';
const { vault, instructions } = await createVaultInstructions({	connection,	owner: ownerPubkey,	agentId: 'researcher',	mint: usdcMint,	delegate: agentPubkey,	allowance: 100_000_000n, // 100 USDC	decimals: 6,});// sign `instructions` with the owner, then:const state = await readVault({ connection, vault });console.log(spendableUnits(state)); // what the agent may spend right now

@three-ws/onchain-agent-wallets/lib/policy exports the guardrail engine on its own, if you want the same rules in a different runtime.

Tests

npm test

Runs the guardrail unit tests, the x402 selection tests, and the delegation integration test against the real SPL Token program.

Related

• @three-ws/metaplex-agent-mcp mints agent identities into the Metaplex Agent Registry. deploy_agent_onchain uses it as a library, and its prepare_agent_mint is the browser-wallet path for minting.
• three.ws is where these agents get faces, avatars, and a home.

License

See LICENSE.

Support the project

If onchain-agent-wallets saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/onchain-agent-wallets and it has the context it needs.

More from the same author

• All repositories by nirholas: the full catalog, grouped by topic
• three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
• Questions or ideas: open an issue or start a discussion

Contributors

[Contributors]

Star history

[Star History Chart]

Part of three.ws

three.ws is a platform for 3D AI agents with Solana wallets: avatars, a skill marketplace, x402 payments and more than seventy MCP servers. @three-ws/onchain-agent-wallets is one package from it.

• Documentation site: https://nirholas.github.io/onchain-agent-wallets/
• npm: https://www.npmjs.com/package/@three-ws/onchain-agent-wallets
• Canonical source: https://github.com/nirholas/three.ws (this repository is a generated mirror of packages/onchain-agent-wallets)
• Agent-readable summary: llms.txt and AGENTS.md
• Issues and ideas: https://github.com/nirholas/onchain-agent-wallets/issues