# Onchain Agent Wallets

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 9
- Author: nirholas
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/nirholas/onchain-agent-wallets
- Updated: 2026-10-10
- HTML: https://affpapa.org/en/nevibecode/mcp/onchain-agent-wallets

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `OWNER_SECRET_KEY`, `OAW_NETWORK`, `SOLANA_RPC_URL`, `OAW_STATE_DIR`, `REQUIRE_CONFIRM` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-wallets
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
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-wallets
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-wallets
```
Replace <…> with your own values

## When to use it
- 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
- 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_x402` for `https://api.example.com/premium`.

## Similar
- [agentwallet](https://affpapa.org/en/nevibecode/skills/agentwallet.md) — skill · 2600 installs
- [solana-tx-building](https://affpapa.org/en/nevibecode/skills/solana-tx-building.md) — skill · 441 installs
- [solana-payments-wallets-trading](https://affpapa.org/en/nevibecode/skills/solana-payments-wallets-trading.md) — skill · 475 installs
- [Agent Wormhole](https://affpapa.org/en/nevibecode/mcp/agent-wormhole.md) — MCP server · ★ 5
- [ZendIQ](https://affpapa.org/en/nevibecode/mcp/zendiq.md) — MCP server · ★ 1
- [mpp32-mcp-server](https://affpapa.org/en/nevibecode/mcp/mpp32-mcp-server.md) — MCP server · ★ 221

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md