Onchain Agent Wallets
io.github.nirholasPublished by GitHub account nirholasv0.1.1Updated Oct 27, 2026
Give an AI agent a Solana spending allowance instead of your key. Chain-enforced cap, x402.
Overview
Gives an AI agent a capped Solana spending allowance instead of a private key, with on-chain delegation, local guardrails and x402 payments.
- What you can do
- Create, fund and manage agent wallets: generate keypairs, create a vault, delegate a capped allowance, refill or withdraw, and revoke in one transaction
- Set guardrails such as per-transaction and daily caps, recipient and x402 host allowlists, expiry, pause and a confirm threshold
- Spend from the allowance: send tokens to a recipient or pay an x402 API, with refusals that name the rule that fired
- Inspect state: live balances, remaining allowance, 24h and 7d totals, all agents, and an audit log including refusals
- Deploy and export: mint a Metaplex Agent Registry identity and export the runtime config for running the agent elsewhere
- When to use it
- Use it when you want an agent to pay for APIs or send tokens on Solana without handing over a key that controls your whole balance. It suits research or automation agents that need a small, revocable budget, and teams that want on-chain limits plus local policy and an audit trail.
- Requirements
- Runs locally via npx (Node.js). Needs a Solana RPC endpoint; SOLANA_RPC_URL defaults to the public endpoint, which rate-limits hard, so bring your own for production. OAW_NETWORK selects mainnet or devnet. OWNER_SECRET_KEY is optional: without it, owner actions return unsigned transactions to sign in a wallet. State lives in OAW_STATE_DIR.
Installation
In SourceWeft
- Open Onchain Agent Wallets in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
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.
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
Two independent layers protect you:
- On-chain. The SPL Token program checks every agent-signed transfer against
delegated_amountand decrements it on each spend. Our code cannot raise it. A singlerevokesets it to zero. This is a stock token program feature, not a new contract to trust. - 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
Setup
Claude Code:
Cursor, or any MCP client (mcp.json):
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:
The agent now spends on its own:
And you stay in control:
A refusal tells you exactly which rule fired:
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
approvedoes 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
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:
@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
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-mcpmints agent identities into the Metaplex Agent Registry.deploy_agent_onchainuses it as a library, and itsprepare_agent_mintis 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
Star history
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
Source: README.md at commit 19573a7
Tools
0Version history
2- v0.1.1LatestOct 10, 2026
- v0.1.0Sep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts
