Agent Payment X402

에이전트는 ERC-4337 스마트 계정을 통해 자신의 키를 직접 보유합니다. 오케스트레이터가 위임 전에 정책을 설정하고, 에이전트는 그 범위 안에서만 지출할 수 있습니다. 공동 자금도 없고 수탁 위험도 없습니다.

MCP 통합

결제 레이어는 어떤 Claude Code 또는 에이전트 하니스 구성에도 끼워 넣을 수 있는 표준 MCP 도구를 노출합니다.

보안 참고: 패키지 버전은 항상 고정하세요. 이 도구는 개인 키를 다루므로, 버전 고정 없는 npx 설치는 공급망 위험을 만듭니다.

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["[email protected]"]
    }
  }
}

사용 가능한 도구(에이전트 호출 가능)

참고: 지출 정책은 에이전트 자신이 아니라 오케스트레이터가 위임 전에 설정합니다. 이렇게 해야 에이전트가 자신의 지출 한도를 스스로 늘리지 못합니다. 정책은 오케스트레이션 레이어나 작업 전 훅에서 set_policy로 설정하고, 에이전트 호출 가능 도구로 노출하지 마세요.

예시

MCP 클라이언트에서 예산 강제

agentpay MCP 서버를 호출하는 오케스트레이터를 만들 때는, 유료 도구 호출을 보내기 전에 예산을 강제합니다.

사전 조건: MCP 설정을 추가하기 전에 패키지를 먼저 설치하세요. -y 없는 npx는 비대화형 환경에서 확인을 요구해 서버를 멈추게 할 수 있습니다. npm install -g [email protected]

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() {
  // 1. Validate credentials before constructing the transport.
  //    A missing key must fail immediately — never let the subprocess start without auth.
  const walletKey = process.env.WALLET_PRIVATE_KEY;
  if (!walletKey) {
    throw new Error("WALLET_PRIVATE_KEY is not set — refusing to start payment server");
  }

  // Connect to the agentpay MCP server via stdio transport.
  // Whitelist only the env vars the server needs — never forward all of process.env
  // to a third-party subprocess that manages private keys.
  const transport = new StdioClientTransport({
    command: "npx",
    args: ["[email protected]"],
    env: {
      PATH: process.env.PATH ?? "",
      NODE_ENV: process.env.NODE_ENV ?? "production",
      WALLET_PRIVATE_KEY: walletKey,
    },
  });
  const agentpay = new Client({ name: "orchestrator", version: "1.0.0" });
  await agentpay.connect(transport);

  // 2. Set spending policy before delegating to the agent.
  //    Always verify success — a silent failure means no controls are active.
  const policyResult = await agentpay.callTool({
    name: "set_policy",
    arguments: {
      per_task_budget: 0.50,
      per_session_budget: 5.00,
      allowlisted_recipients: ["api.example.com"],
    },
  });
  if (policyResult.isError) {
    throw new Error(
      `Failed to set spending policy — do not delegate: ${JSON.stringify(policyResult.content)}`
    );
  }

  // 3. Use preToolCheck before any paid action
  await preToolCheck(agentpay, 0.01);
}

// Pre-tool hook: fail-closed budget enforcement with four distinct error paths.
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
  // Path 1: Reject invalid input (NaN/Infinity bypass the < comparison)
  if (!Number.isFinite(apiCost) || apiCost < 0) {
    throw new Error(`Invalid apiCost: ${apiCost} — action blocked`);
  }

  // Path 2: Transport/connectivity failure
  let result;
  try {
    result = await agentpay.callTool({ name: "check_spending" });
  } catch (err) {
    throw new Error(`Payment service unreachable — action blocked: ${err}`);
  }

  // Path 3: Tool returned an error (e.g., auth failure, wallet not initialised)
  if (result.isError) {
    throw new Error(
      `check_spending failed — action blocked: ${JSON.stringify(result.content)}`
    );
  }

  // Path 4: Parse and validate the response shape
  let remaining: number;
  try {
    const parsed = JSON.parse(
      (result.content as Array<{ text: string }>)[0].text
    );
    if (!Number.isFinite(parsed?.remaining)) {
      throw new TypeError("missing or non-finite 'remaining' field");
    }
    remaining = parsed.remaining;
  } catch (err) {
    throw new Error(
      `check_spending returned unexpected format — action blocked: ${err}`
    );
  }

  // Path 5: Budget exceeded
  if (remaining < apiCost) {
    throw new Error(
      `Budget exceeded: need $${apiCost} but only $${remaining} remaining`
    );
  }
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

모범 사례

• 위임 전 예산 설정: 서브에이전트를 띄울 때 오케스트레이션 레이어를 통해 SpendingPolicy를 붙입니다. 무제한 지출 권한을 주지 마세요.
• 의존성 버전 고정: MCP 설정에는 항상 정확한 버전을 적습니다. 예: [email protected]. 운영 반영 전에 패키지 무결성을 확인하세요.
• 감사 추적: 작업 후 훅에서 list_transactions를 사용해 무엇에 왜 비용이 나갔는지 기록합니다.
• 실패 시 차단: 결제 도구에 접근할 수 없으면 유료 작업을 차단해야 합니다. 무계량 접근으로 우회하지 마세요.
• security-review와 함께 사용: 결제 도구는 고권한 기능입니다. 셸 접근과 같은 수준의 검토가 필요합니다.
• 먼저 테스트넷에서 검증: 개발에는 Base Sepolia를 쓰고, 운영에서는 Base 메인넷으로 전환합니다.

운영 참고 자료

• npm: agentwallet-sdk
• NVIDIA NeMo Agent Toolkit 반영: PR #17 — NVIDIA 에이전트 예제를 위한 x402 결제 도구
• 프로토콜 명세: x402.org