Onchain Agent Wallets — Claude Code MCP server: how to install
An MCP server that gives AI agents a capped Solana token allowance instead of private keys. Keeps your main funds safe while enabling automated payments and x402 calls.
claude mcp add --env OWNER_SECRET_KEY=<OWNER_SECRET_KEY> --env OAW_NETWORK=<OAW_NETWORK> --env SOLANA_RPC_URL=<SOLANA_RPC_URL> --env OAW_STATE_DIR=<OAW_STATE_DIR> --env REQUIRE_CONFIRM=<REQUIRE_CONFIRM> --transport stdio onchain-agent-wallets -- npx -y @three-ws/onchain-agent-walletsWhat Onchain Agent Wallets does
The server builds a token vault owned by the user and assigns an allowance via standard SPL Token delegation. The AI agent operates its own keypair containing only small amounts of SOL for transaction fees. On-chain rules enforce the spending cap, ensuring an agent cannot exceed the delegated balance even if prompted to do so.
In addition to on-chain caps, local guardrails check transaction amounts, rolling 24-hour spending limits, and allowlists for recipient addresses or x402 hosts. The owner retains complete custody, holding the power to pause spending or revoke delegations instantly without asking the agent.
A public Solana RPC endpoint rate-limits requests heavily, making a dedicated private RPC URL necessary for stable operations. Providing OWNER_SECRET_KEY is optional — users can leave it unset and sign transactions manually using a browser wallet.
What it helps with
- delegate capped token spending to an AI agent without sharing master keys
- pay for web resources and API endpoints via the x402 payment standard
- restrict agent transactions by daily budgets and approved recipient addresses
- revoke agent spending permissions and reclaim vault balances instantly
Example prompts for the agent
- Set up a new agent wallet researcher with a 100 USDC allowance using
create_agent_wallet. - Check live balances and spending warnings for researcher via
agent_wallet_status. - Execute a paywall transaction via
pay_x402forhttps://api.example.com/premium.
How to install Onchain Agent Wallets
Platform CLI
claude mcp add --env OWNER_SECRET_KEY=<OWNER_SECRET_KEY> --env OAW_NETWORK=<OAW_NETWORK> --env SOLANA_RPC_URL=<SOLANA_RPC_URL> --env OAW_STATE_DIR=<OAW_STATE_DIR> --env REQUIRE_CONFIRM=<REQUIRE_CONFIRM> --transport stdio onchain-agent-wallets -- npx -y @three-ws/onchain-agent-walletsReplace <…> with your own values
Platform CLI
codex mcp add onchain-agent-wallets --env OWNER_SECRET_KEY=<OWNER_SECRET_KEY> --env OAW_NETWORK=<OAW_NETWORK> --env SOLANA_RPC_URL=<SOLANA_RPC_URL> --env OAW_STATE_DIR=<OAW_STATE_DIR> --env REQUIRE_CONFIRM=<REQUIRE_CONFIRM> -- npx -y @three-ws/onchain-agent-walletsReplace <…> with your own values
Config file
{
"mcpServers": {
"onchain-agent-wallets": {
"command": "npx",
"args": [
"-y",
"@three-ws/onchain-agent-wallets"
],
"env": {
"OWNER_SECRET_KEY": "<OWNER_SECRET_KEY>",
"OAW_NETWORK": "<OAW_NETWORK>",
"SOLANA_RPC_URL": "<SOLANA_RPC_URL>",
"OAW_STATE_DIR": "<OAW_STATE_DIR>",
"REQUIRE_CONFIRM": "<REQUIRE_CONFIRM>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"onchain-agent-wallets": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@three-ws/onchain-agent-wallets"
],
"env": {
"OWNER_SECRET_KEY": "<OWNER_SECRET_KEY>",
"OAW_NETWORK": "<OAW_NETWORK>",
"SOLANA_RPC_URL": "<SOLANA_RPC_URL>",
"OAW_STATE_DIR": "<OAW_STATE_DIR>",
"REQUIRE_CONFIRM": "<REQUIRE_CONFIRM>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e OWNER_SECRET_KEY=<OWNER_SECRET_KEY> -e OAW_NETWORK=<OAW_NETWORK> -e SOLANA_RPC_URL=<SOLANA_RPC_URL> -e OAW_STATE_DIR=<OAW_STATE_DIR> -e REQUIRE_CONFIRM=<REQUIRE_CONFIRM> onchain-agent-wallets npx -y @three-ws/onchain-agent-walletsReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Onchain Agent Wallets
How do I install Onchain Agent Wallets in Claude Code?
Run claude mcp add onchain-agent-wallets -e OWNER_SECRET_KEY=<OWNER_SECRET_KEY> -- npx -y @three-ws/onchain-agent-wallets.
What does Onchain Agent Wallets do?
It delegates a restricted spending allowance to an AI agent on Solana using standard SPL Token features, preventing the agent from draining your primary account.
Do I have to expose my owner private key in the configuration?
Setting OWNER_SECRET_KEY is optional. If omitted, the server returns unsigned transactions for you to approve in an external wallet like Phantom.
