onchain-agent-wallets

Gib einem KI-Agenten eine echte Solana-Wallet, ohne ihm dein Geld zu geben.

Ein MCP-Server, der jedem Agenten ein Ausgabenlimit statt eines privaten Schlüssels gibt. Das Geld bleibt auf einem Konto, das dir gehört. Der Agent erhält eine Delegation, die das SPL-Token-Programm on-chain begrenzt, dazu Schutzmechanismen, die du kontrollierst, und die Möglichkeit, x402-APIs aus diesem Limit zu bezahlen. Du kannst es mit einer einzigen Anweisung widerrufen und das Geld zurückholen, ohne den Agenten zu fragen.

Hier ist nichts vorgetäuscht: echte SPL-Token-Delegationen, echtes Solana, echte x402-Abrechnung.

Übersicht lesen · npm

Das Problem, das das löst

Jede „Agenten-Wallet" funktioniert heute gleich: Du erzeugst ein Schlüsselpaar, übergibst es dem Agenten, und schon hat der Agent alles, was darin ist. Es gibt keine Obergrenze, keine Zulassungsliste, kein Ablaufdatum und keine Möglichkeit, es zurückzubekommen, außer man versucht, den Agenten zu überholen, um die Gelder zu verschieben. Die Leute lösen das, indem sie fast nichts in der Wallet lassen, was bedeutet, dass der Agent nichts Nützliches tun kann.

Ein Limit ist die ältere, bessere Antwort. Das Geld wandert nie zum Agenten. Der Agent erhält die Erlaubnis, einen Teil davon auszugeben, und die Blockchain setzt diesen Teil durch.

Related MCP server: Slug Wallet

So funktioniert es

   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)

Zwei unabhängige Ebenen schützen dich:

1. On-chain. Das SPL-Token-Programm prüft jede vom Agenten signierte Überweisung gegen delegated_amount und verringert es bei jeder Ausgabe. Unser Code kann es nicht erhöhen. Ein einziges revoke setzt es auf null. Das ist eine Standardfunktion des Token-Programms, kein neuer Vertrag, dem man vertrauen muss.

2. Lokal. Bevor dieser Server irgendetwas signiert, wendet er deine Regeln an: Limit pro Transaktion, rollierendes 24-Stunden-Limit, Zulassungsliste für Empfänger, x402-Host-Zulassungsliste, Ablaufdatum, Pause und eine Bestätigungsschwelle, die ein menschliches Ja erzwingt.

Das eigene Schlüsselpaar des Agenten enthält nichts außer ein wenig SOL für Gebühren. Wenn es durchsickert, ist der Schadensradius das verbleibende Limit, und revoke_agent_wallet schließt es in einer Transaktion.

Installation

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

Einrichtung

Claude Code:

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

Cursor oder ein anderer MCP-Client (mcp.json):

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

Zum Starten ist kein Schlüssel erforderlich. Besitzeraktionen werden als unsignierte Transaktion zurückgegeben, die deine Wallet signieren muss und die dann von send_signed_transaction gesendet wird. Wenn du möchtest, dass dieser Server für dich signiert, setze OWNER_SECRET_KEY.

Schnellstart

Gib einem Recherche-Agenten 100 USDC Ausgabevolumen, begrenzt auf 5 pro Transaktion und 20 pro Tag, und nur für eine 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

Der Agent gibt jetzt selbstständig aus:

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

Und du behältst die Kontrolle:

agent_wallet_status  id: "researcher"      # live balances, remaining allowance, warnings
spend_log            id: "researcher"      # every spend AND every refusal, with reasons
set_guardrails       id: "researcher"  paused: true      # instant, free, no transaction
revoke_agent_wallet  id: "researcher"  withdraw: true  confirm: true   # on-chain kill switch

Eine Ablehnung sagt dir genau, welche Regel gegriffen hat:

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

Werkzeuge

Verwahrung (du signierst)

Schutzmechanismen

Ausgaben (der Agent signiert)

Sichtbarkeit

Bereitstellung

Schutzmechanismen

Der Unterschied ist wichtig, wenn etwas schiefgeht. Wenn dieser Rechner kompromittiert ist, können die lokalen Regeln umgangen werden, das On-Chain-Limit jedoch nicht. Deshalb sollte das Limit so klein wie möglich sein, damit der Agent arbeiten kann, und bei Bedarf aufgestockt werden, anstatt den gesamten Kontostand zu verwenden.

x402

pay_x402 fragt den Endpunkt zuerst unentgeltlich ab, sodass der Preis bekannt ist, bevor sich etwas bewegt, und die Schutzmechanismen die echte Zahl sehen. Dann stockt es den Agenten um genau diesen Betrag aus dem Tresor auf, bezahlt und lässt den Agenten wieder leer zurück.

Es weigert sich zu zahlen:

• in einer anderen Kette als Solana (no_solana_option)

• im falschen Cluster, z. B. ein Mainnet-Preis von einer Devnet-Wallet (wrong_cluster)

• in einem Token, auf den das Limit nicht lautet (asset_mismatch)

• über max_price, einer Obergrenze pro Aufruf, unabhängig von den bestehenden Schutzmechanismen (over_max_price)

Wenn der Endpunkt nichts verlangt, kommen die Inhalte zurück und es wird nichts ausgegeben.

Was der Agent nicht kann

• Mehr ausgeben als das Limit, egal wie er dazu aufgefordert wird. Das entscheidet das Token-Programm, nicht das Modell.

• Den Tresor verschieben, schließen oder dessen Besitzer ändern. Er ist nicht der Besitzer.

• Dich davon abhalten, abzuheben oder einen Widerruf durchzuführen.

• Sein eigenes Limit erhöhen. Das kann nur ein vom Besitzer signiertes approve.

• Etwas anderes in deiner Wallet anfassen. Der Tresor ist ein separates Konto, das nur das enthält, was du hineingetan hast.

Belegt in test/token-delegation.test.mjs, das das echte SPL-Token-Programm im Prozess ausführt und prüft, dass eine Ausgabe von 61 bei einem verbleibenden Limit von 60 on-chain fehlschlägt, während 460 im Tresor liegen.

Kostenlos auf Devnet üben

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

Der Zustand wird pro Netzwerk gespeichert, sodass eine Devnet-Probe deine Mainnet-Agenten nie berührt.

Als Bibliothek verwenden

Das Verwahrungsmodell besteht aus schlichtem @solana/web3.js und @solana/spl-token und ist ohne MCP nutzbar:

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 exportiert die Guardrail-Engine eigenständig, falls du dieselben Regeln in einer anderen Laufzeitumgebung verwenden möchtest.

Tests

npm test

Führt die Guardrail-Unit-Tests, die x402-Auswahltests und den Integrations-/Delegationstest gegen das echte SPL-Token-Programm aus.

Verwandtes

• @three-ws/metaplex-agent-mcp prägt Agentenidentitäten in die Metaplex-Agent-Registry. deploy_agent_onchain verwendet es als Bibliothek, und prepare_agent_mint ist der Browser-Wallet-Pfad zum Prägen.

• three.ws ist der Ort, an dem diese Agenten Gesichter, Avatare und ein Zuhause bekommen.

Lizenz

Siehe LICENSE.