agent-payment-x402

name	agent-payment-x402
description	AI 에이전트에 x402 결제 실행을 추가합니다. MCP 도구를 통해 작업별 예산, 지출 통제, 비수탁형 지갑을 제공합니다. 에이전트가 API, 서비스, 다른 에이전트에 비용을 지불해야 할 때 사용합니다.
origin	community

에이전트 결제 실행(x402)

내장 지출 통제를 사용해 AI 에이전트가 자율적으로 결제할 수 있게 합니다. x402 HTTP 결제 프로토콜과 MCP 도구를 사용하므로, 에이전트가 외부 서비스, API, 다른 에이전트에 비용을 지불하면서도 수탁 위험을 피할 수 있습니다.

사용 시점

에이전트가 API 호출 비용을 결제해야 하거나, 서비스를 구매해야 하거나, 다른 에이전트와 정산해야 하거나, 작업별 지출 한도를 강제해야 하거나, 비수탁형 지갑을 관리해야 할 때 사용합니다. cost-aware-llm-pipeline, security-review와 함께 쓰기 좋습니다.

동작 방식

x402 프로토콜

x402는 HTTP 402(Payment Required)를 기계 간 협상 가능한 흐름으로 확장합니다. 서버가 402를 반환하면 에이전트의 결제 도구가 자동으로 가격을 협상하고, 예산을 확인하고, 거래에 서명한 뒤 재시도합니다. 사람 개입은 필요하지 않습니다.

지출 통제

모든 결제 도구 호출은 SpendingPolicy를 강제합니다.

• 작업별 예산: 단일 에이전트 작업에서 허용되는 최대 지출
• 세션별 예산: 전체 세션 누적 한도
• 허용 목록 수신자: 에이전트가 결제할 수 있는 주소/서비스 제한
• 속도 제한: 분/시간당 최대 거래 수

비수탁형 지갑

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

MCP 통합

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

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

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["agentwallet-sdk@6.0.0"]
    }
  }
}

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

Tool	Purpose
get_balance	에이전트 지갑 잔액 확인
send_payment	주소 또는 ENS로 결제 전송
check_spending	남은 예산 조회
list_transactions	전체 결제 감사 기록 조회

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

예시

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

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

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

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: ["agentwallet-sdk@6.0.0"],
    env: {
      PATH: process.env.PATH ?? "",
      NODE_ENV: process.env.NODE_ENV ?? "production",
      WALLET_PRIVATE_KEY: walletKey,
    },
  });
  const agentpay = new Client({ : , :  });
   agentpay.(transport);

  
  
   policyResult =  agentpay.({
    : ,
    : {
      : ,
      : ,
      : [],
    },
  });
   (policyResult.) {
      (
      
    );
  }

  
   (agentpay, );
}


  (): <> {
  
   (!.(apiCost) || apiCost < ) {
      ();
  }

  
   result;
   {
    result =  agentpay.({ :  });
  }  (err) {
      ();
  }

  
   (result.) {
      (
      
    );
  }

  
   : ;
   {
     parsed = .(
      (result.  <{ :  }>)[].
    );
     (!.(parsed?.)) {
        ();
    }
    remaining = parsed.;
  }  (err) {
      (
      
    );
  }

  
   (remaining < apiCost) {
      (
      
    );
  }
}

().( {
  .(err);
  process. = ;
});

모범 사례

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

운영 참고 자료

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