이 노트북을 Google Colab에서 실행하세요
아래 모든 단계를 실행 가능한 노트북으로 제공합니다. 자금이 없는 지갑으로도 실행되며 결제 벽에서 멈추므로, 아무것도 지출하지 않고 전체 흐름을 볼 수 있습니다.
작동 방식
움직이는 부분은 네 개이며, 그중 셋은 그냥 HTTP입니다:
추론 자체는 평범한
/chat/completions 호출입니다. 유일한 차이는 어떤 헤더를 보내는가입니다.
시작 비용
두 개의 숫자가 중요하며, 둘은 같은 숫자가 아닙니다. 최소 충전 금액은 5달러입니다. 이는/x402/top-up이 정산할 수 있는 가장 작은 금액이며, 어디에도 하드코딩되지 않고 discovery 응답에 담겨 반환되므로, 이 페이지를 신뢰하지 말고 응답을 읽으세요.
호출을 하기 위한 최소 잔액은 10센트입니다. 그보다 적은 잔액을 가진 지갑은 돈을 가지고 있어도 추론에서 402를 받게 됩니다.
따라서 5달러가 자금을 넣을 가치가 있는 가장 작은 지갑이고, 이 가이드는 에이전트에게 그 5달러를 줍니다. 그 돈이 얼마를 살 수 있는지 알아둘 가치가 있습니다. qwen3-5-9b에 짧은 질문을 하나 던지면 약 27개의 입력 토큰과 26개의 출력 토큰이 사용되며, 그 모델의 가격으로는 대략 1달러의 700만분의 1 정도입니다. 5달러는 약 75만 개의 질문 수준입니다. 여기서의 예산은 빡빡한 제약이 아니라 폭발 반경입니다.
준비
x402 SDK가 결제 서명을 처리합니다. 직접 손으로 구현하지 마세요. 이체 승인은 EIP-712 타입 데이터이며, 재사용된 논스는 디버그하기 지루한 방식으로 검증에 실패합니다.x402 Python SDK는 Python 3.10 이상을 요구합니다. Colab은 괜찮습니다. macOS에 기본 설치된 시스템 Python은 그렇지 않을 수 있습니다.
agent.py를 만듭니다. BUDGET_USD는 에이전트가 스스로에게 부과하는 상한이며, 여기서는 지갑 전체로 설정되어 있습니다. 값을 낮추면 돈이 다 떨어지기 전에 에이전트가 멈추는데, 이는 여러분이 조정할 만한 유일한 다이얼입니다.
에이전트가 소유하는 지갑
에이전트에는 키 쌍이 필요합니다. 프로덕션에서는 이 키가 여러분이 의도적으로 자금을 넣은 지갑의 것이며, 시크릿 매니저에 저장됩니다. 개발 중에는 일회용 지갑을 생성하는 것이 올바른 선택입니다. 돈이 없는 지갑은 실수로 비용이 드는 일을 할 수 없기 때문입니다.userdata.get("WALLET_KEY")로 읽으세요.
인증 대신 서명하기
보낼 키가 없으므로 각 요청은 지갑 소유자가 만들었다는 증명을 함께 실어 나릅니다. 증명은 EIP-4361 메시지이며, 서명한 뒤 base64로 인코딩해SIGN-IN-WITH-X 헤더에 담습니다.
메시지 형식은 정확해야 합니다. Venice는 이 바이트를 자신의 쪽에서 다시 만들어 그것에 대해 여러분의 서명을 검증하므로, 빈 줄 하나만 잘못돼도 도움이 되는 오류가 아니라 거부된 서명을 얻게 됩니다.
Issued At으로부터 5분간 유효합니다. 각 논스는 약 5분 30초 동안 일회용입니다. 그리고 서명자는 경로에 있는 지갑과 일치해야 하며, 그렇지 않으면 한 지갑이 다른 지갑을 조회할 수 없고 그 시도에 대해 403을 받게 됩니다.
실질적인 결과는, 하나를 캐싱하기보다 요청마다 새 헤더를 서명해야 한다는 것입니다. 서명은 로컬에서 무료이므로 이 비용은 없습니다.
canConsume입니다. 이 필드가 10센트 하한을 고려해주므로 여러분이 신경 쓸 필요가 없습니다.
자금 넣기
충전은 두 요청입니다. 첫 번째는 Venice가 무엇을 받아들이는지 묻는 것으로 아직 인증할 것이 없기에 인증되지 않습니다. 두 번째는 서명된 이체 승인을 전달합니다.amount는 기본 단위이며 USDC는 소수점 6자리를 가지므로, 5000000은 500만이 아니라 5달러입니다. Solana 경로에서 extra.feePayer는 Venice가 운영하는 계정으로 트랜잭션 수수료를 부담하며, 이 덕분에 지갑은 SOL을 보유하지 않고도 결제할 수 있습니다.
USDC가 없는 지갑에서 정산하면 400과 PAYMENT_VERIFICATION_FAILED가 돌아옵니다. 이는 예상되는 실패 형태입니다: 서명은 문제가 없었지만 이체가 되지 않은 것입니다.
호출마다 지불하기
잔액이 있으면 추론은 서명이 함께 실린 평범한 요청입니다. Venice 시스템 프롬프트를 끄는 것은 겉보기보다 훨씬 중요합니다. 호출당 약 1700개의 입력 토큰을 절약해 주는데, 이는 질문 자체보다 두 자리 크기만큼 큰 값입니다.402를 예외가 아니라 정상적인 결과로 처리하는 것이 전체 설계의 핵심입니다. 스스로의 비용을 부담하는 에이전트는 언젠가 돈이 떨어질 것이며, 돈이 떨어지는 것은 크래시가 아닙니다.
지출 내역 읽기
원장이 권위 있는 자료입니다. 토큰 수에서 추정하지 말고, 실제로 얼마가 청구되었는지 물어보세요.TOP_UP과 REFUND 행도 여기 양의 금액으로 나타납니다. CHARGE로 필터링하면 지출이 나옵니다.
예산이 있는 실행
이제 루프입니다. 각 호출 전에 에이전트는 얼마를 썼는지 확인하고, 지불할 수 없는 작업은 시작하지 않습니다.이제 여러분이 도달한 지점
에이전트는 자기 돈을 가지고 있고, 서명으로 자신의 신원을 증명하며, 어디에도 계정을 만들지 않고도 여러분이 설정한 한도를 넘을 수 없습니다. 예약된 잡, 서버리스 함수, 혹은 오래 유지되는 키를 넘기고 싶지 않은 어떤 것에든 이는 실질적으로 다른 보안 자세입니다. 다음에 해볼 만한 것들:프로토콜에서 상한 걸기
SDK의 지출 통제는 세션이 아니라 결제당 적용됩니다. 위의 예산 루프와 함께 사용해 한쪽의 버그가 다른 쪽을 무력화할 수 없도록 하세요.
비었을 때 자동 충전
402를 잡아서 충전한 뒤 재시도하세요. 이것이 TypeScript 쪽에서 venice-x402-client가 대신 해주는 일입니다.Solana에서 결제하기
같은 흐름, 다른 경로. Ed25519로 서명하고 반환된
feePayer를 설정하면 지갑에 SOL이 필요 없습니다.실제 작업 맡기기
작업 목록을 도구 호출 루프로 바꾸면 원장이 각 결정이 얼마의 비용이 들었는지 보여주기 시작합니다.