onchain-agent-wallets

Dale a un agente de IA una cartera real de Solana sin darle tu dinero.

Un servidor MCP que le da a cualquier agente un límite de gasto en lugar de una clave privada. Los fondos permanecen en una cuenta que tú posees. El agente recibe una delegación que el programa SPL Token limita en cadena, más salvaguardas que tú controlas, más la capacidad de pagar APIs x402 con ese límite. Puedes revocarla con una sola instrucción y recuperar el dinero sin pedirle permiso al agente.

Nada aquí es simulado: delegaciones reales de SPL Token, Solana real, liquidación x402 real.

Lee la descripción general · npm

El problema que resuelve

Toda "cartera de agente" de hoy funciona igual: generas un par de claves, se lo das al agente, y ahora el agente tiene todo lo que hay en ella. No hay techo, ni lista blanca, ni caducidad, ni forma de recuperarla salvo competir con el agente para mover los fondos. La gente lo resuelve manteniendo casi nada en la cartera, lo que significa que el agente no puede hacer nada útil.

Un límite de gasto es la respuesta más antigua y mejor. El dinero nunca se mueve al agente. El agente obtiene permiso para gastar una parte, y la cadena hace cumplir esa parte.

Related MCP server: Slug Wallet

Cómo funciona

   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)

Dos capas independientes te protegen:

1. En cadena. El programa SPL Token comprueba cada transferencia firmada por el agente contra delegated_amount y lo decrementa en cada gasto. Nuestro código no puede aumentarlo. Un solo revoke lo pone a cero. Esta es una característica estándar del programa de tokens, no un contrato nuevo en el que confiar.

2. Local. Antes de que este servidor firme cualquier cosa, aplica tus reglas: límite por transacción, límite móvil de 24 horas, lista blanca de destinatarios, lista blanca de hosts x402, caducidad, pausa y un umbral de confirmación que obliga a un sí humano.

El propio par de claves del agente no contiene nada más que un poco de SOL para las comisiones. Si se filtra, el radio de explosión es el límite restante, y revoke_agent_wallet lo cierra en una sola transacción.

Instalación

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

Configuración

Claude Code:

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

Cursor, o cualquier cliente MCP (mcp.json):

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

No se requiere ninguna clave para empezar. Las acciones del propietario vuelven como una transacción sin firmar para que tu cartera la firme, que send_signed_transaction luego transmite. Si prefieres que este servidor firme por ti, establece OWNER_SECRET_KEY.

Inicio rápido

Dale a un agente de investigación 100 USDC de poder de gasto, con un límite de 5 por transacción y 20 por día, y solo para una 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

El agente ahora gasta por su cuenta:

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

Y tú mantienes el control:

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

Una negativa te dice exactamente qué regla se activó:

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

Herramientas

Custodia (tú firmas)

Salvaguardas

Gasto (el agente firma)

Visibilidad

Despliegue

Salvaguardas

La distinción importa cuando algo sale mal. Si esta máquina se ve comprometida, las reglas locales pueden ser eludidas, pero el límite en cadena no. Por eso el límite debe ser el número más pequeño que permita al agente trabajar, recargado según sea necesario, en lugar de todo el saldo.

x402

pay_x402 sondea el endpoint sin pagar primero, para que el precio se conozca antes de que se mueva cualquier cosa y las salvaguardas vean el número real. Luego recarga al agente exactamente con esa cantidad desde la bóveda, paga y deja al agente vacío de nuevo.

Se niega a pagar:

• en una cadena que no sea Solana (no_solana_option)

• en el clúster equivocado, por ejemplo un precio de mainnet desde una cartera de devnet (wrong_cluster)

• en un token en el que el límite no está denominado (asset_mismatch)

• por encima de max_price, un techo por llamada independiente de las salvaguardas vigentes (over_max_price)

Si el endpoint no cobra, el contenido vuelve y no se gasta nada.

Lo que el agente no puede hacer

• Gastar más que el límite, sin importar cómo se le pida. El programa de tokens decide eso, no el modelo.

• Mover la bóveda, cerrarla o cambiar su propietario. No es el propietario.

• Evitar que retires fondos o que revoques.

• Aumentar su propio límite. Solo un approve firmado por el propietario hace eso.

• Tocar cualquier otra cosa en tu cartera. La bóveda es una cuenta separada que contiene solo lo que pones en ella.

Probado en test/token-delegation.test.mjs, que ejecuta el programa SPL Token real en proceso y afirma que un gasto de 61 contra un límite restante de 60 falla en cadena, con 460 en la bóveda.

Ensaya gratis en devnet

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

El estado se mantiene por red, así que un ensayo en devnet nunca toca tus agentes de mainnet.

Úsalo como biblioteca

El modelo de custodia es @solana/web3.js y @solana/spl-token simples, usable sin 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 exporta el motor de salvaguardas por sí solo, si quieres las mismas reglas en un runtime diferente.

Pruebas

npm test

Ejecuta las pruebas unitarias de salvaguardas, las pruebas de selección x402 y la prueba de integración de delegación contra el programa SPL Token real.

Relacionado

• @three-ws/metaplex-agent-mcp acuña identidades de agente en el Registro de Agentes de Metaplex. deploy_agent_onchain lo usa como biblioteca, y su prepare_agent_mint es la ruta de cartera de navegador para acuñar.

• three.ws es donde estos agentes obtienen caras, avatares y un hogar.

Licencia

Ver LICENSE.