onchain-agent-wallets

AI 에이전트에게 여러분의 돈을 넘기지 않고 실제 Solana 지갑을 제공하세요.

비공개 키 대신 지출 허용 한도를 에이전트에 부여하는 MCP 서버입니다. 자금은 여러분이 소유한 계정에 남아 있습니다. 에이전트는 SPL Token 프로그램이 온체인에서 상한을 적용하는 위임을 받고, 여러분이 통제하는 가드레일과 그 허용 한도에서 x402 API 비용을 지불할 수 있는 기능도 갖게 됩니다. 한 번의 지시로 이를 취소할 수 있고, 에이전트에게 묻지 않고 돈을 되찾을 수 있습니다.

여기에는 모의(mock)된 것이 없습니다. 실제 SPL Token 위임, 실제 Solana, 실제 x402 결제입니다.

개요 읽기 · npm

이 문제가 해결하는 것

오늘날 모든 "에이전트 지갑"은 같은 방식으로 작동합니다. 키페어를 생성해 에이전트에게 넘기면, 이제 에이전트는 그 안에 있는 모든 것을 갖게 됩니다. 상한도, 허용 목록도, 만료도 없고, 에이전트보다 먼저 자금을 옮기려고 경쟁하지 않는 한 되돌릴 방법도 없습니다. 사람들은 지갑에 거의 아무것도 넣지 않는 방식으로 이 문제를 해결하지만, 그러면 에이전트는 유용한 일을 할 수 없습니다.

허용 한도는 더 오래되고 더 나은 해답입니다. 돈은 절대 에이전트에게 이동하지 않습니다. 에이전트는 그중 일부를 지출할 권한을 얻고, 체인이 그 일부를 강제합니다.

Related MCP server: Slug Wallet

작동 방식

   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)

두 개의 독립적인 계층이 여러분을 보호합니다.

1. 온체인. SPL Token 프로그램은 에이전트가 서명한 모든 전송을 delegated_amount와 대조해 검사하고, 지출할 때마다 이를 차감합니다. 우리 코드는 이 값을 올릴 수 없습니다. 단 한 번의 revoke로 0이 됩니다. 이는 신뢰해야 할 새 컨트랙트가 아니라 기본 토큰 프로그램 기능입니다.

2. 로컬. 이 서버는 무엇이든 서명하기 전에 여러분의 규칙을 적용합니다. 거래별 상한, 24시간 이동 상한, 수신자 허용 목록, x402 호스트 허용 목록, 만료, 일시 중지, 그리고 특정 금액 이상에서 사람의 승인을 강제하는 확인 임계값이 여기에 해당합니다.

에이전트 자신의 키페어는 수수료를 위한 약간의 SOL만 보관합니다. 키페어가 유출되면 피해 범위는 남은 허용 한도가 전부이며, revoke_agent_wallet이 한 번의 트랜잭션으로 이 지갑을 폐쇄합니다.

설치

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

설정

Claude Code:

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

Cursor 또는 모든 MCP 클라이언트(mcp.json):

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

시작하는 데 키가 필요하지 않습니다. 소유자 작업은 여러분의 지갑이 서명하도록 서명되지 않은 트랜잭션으로 반환되며, 이후 send_signed_transaction이 이를 브로드캐스트합니다. 이 서버가 대신 서명하게 하려면 OWNER_SECRET_KEY를 설정하세요.

빠른 시작

연구 에이전트에게 지출 권한 100 USDC를 부여하되, 거래당 5, 하루 20으로 상한을 두고 하나의 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

이제 에이전트가 스스로 지출합니다:

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

그리고 통제권은 여전히 여러분에게 있습니다:

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

거부가 발생하면 어떤 규칙이 발동했는지 정확히 알려줍니다:

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

도구

보관 (여러분이 서명)

가드레일

지출 (에이전트가 서명)

가시성

배포

가드레일

이 구분은 문제가 생겼을 때 중요합니다. 이 머신이 침해되면 로컬 규칙은 우회될 수 있어도 온체인 허용 한도는 여전히 우회할 수 없습니다. 그래서 허용 한도는 전체 잔액이 아니라 에이전트가 일을 할 수 있는 최소 금액으로 설정하고, 필요할 때 충전하는 것이 옳습니다.

x402

pay_x402는 먼저 요금을 지불하지 않고 엔드포인트를 조회합니다. 그래서 어떤 자금도 움직이기 전에 가격을 알 수 있고, 가드레일은 실제 숫자를 확인합니다. 그런 다음 볼트에서 정확히 그 금액만큼 에이전트를 충전하고, 결제한 뒤 에이전트를 다시 비웁니다.

다음 경우에는 결제를 거부합니다:

• Solana가 아닌 체인에서 지불하려는 경우 (no_solana_option)

• 잘못된 클러스터인 경우, 예를 들어 devnet 지갑에서 mainnet 가격이 반환되는 경우 (wrong_cluster)

• 허용 한도가 설정된 토큰과 다른 토큰으로 결제하려는 경우 (asset_mismatch)

• 기존 가드레일과 무관한 호출별 상한인 max_price를 초과하는 경우 (over_max_price)

엔드포인트가 요금을 부과하지 않으면 콘텐츠는 그대로 돌아오고 아무것도 지출되지 않습니다.

에이전트가 할 수 없는 일

• 어떤 프롬프트가 주어져도 허용 한도를 초과해 지출할 수 없습니다. 이는 모델이 아니라 토큰 프로그램이 결정합니다.

• 볼트를 옮기거나, 닫거나, 소유자를 변경할 수 없습니다. 에이전트는 소유자가 아닙니다.

• 여러분의 출금을 막거나 revoke를 막을 수 없습니다.

• 자신의 허용 한도를 올릴 수 없습니다. 오직 소유자가 서명한 approve만 그렇게 할 수 있습니다.

• 여러분의 지갑에 있는 다른 어떤 것에도 손댈 수 없습니다. 볼트는 여러분이 넣은 것만 보관하는 별도의 계정입니다.

이는 test/token-delegation.test.mjs에서 입증됩니다. 이 테스트는 실제 SPL Token 프로그램을 프로세스 안에서 실행하고, 볼트에 460이 남아 있더라도 잔여 허용 한도 60으로 61을 지출하는 것이 온체인에서 실패함을 검증합니다.

devnet에서 무료로 예행 연습하기

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

상태는 네트워크별로 유지되므로 devnet 예행 연습은 mainnet 에이전트에 절대 영향을 미치지 않습니다.

라이브러리로 사용하기

보관 모델은 순수한 @solana/web3.js와 @solana/spl-token으로 이루어져 있으며 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는 가드레일 엔진을 독립적으로 내보내므로, 동일한 규칙을 다른 런타임에서도 사용할 수 있습니다.

테스트

npm test

가드레일 단위 테스트, x402 선택 테스트, 그리고 실제 SPL Token 프로그램을 대상으로 하는 위임 통합 테스트를 실행합니다.

관련 프로젝트

• @three-ws/metaplex-agent-mcp는 Metaplex Agent Registry에 에이전트 신원을 발급합니다. deploy_agent_onchain은 이를 라이브러리로 사용하며, 이 라이브러리의 prepare_agent_mint는 브라우저 지갑을 통한 발급 경로입니다.

• three.ws는 이 에이전트들이 얼굴, 아바타, 그리고 보금자리를 얻는 곳입니다.

라이선스

LICENSE를 참조하세요.