주 콘텐츠로 건너뛰기
학습가이드AI 에이전트에 결제를 추가하세요.
가이드

AI 에이전트에 결제를 추가하는 방법.

10 minutes
짧은 답변

createClient를 사용하여 @blockchain0x/node(또는 Python 클라이언트)로 에이전트를 생성하고, payments.create로 USDC 결제를 전송한 후, webhooks.verify로 서명된 웹후크를 확인하십시오. 지출 제어는 대시보드에서 설정되며 API를 통해 읽기 전용입니다. 에이전트는 개인 키를 직접 다루지 않습니다. 가입 후 10분 이내에 Base에서 첫 번째 USDC 결제를 TypeScript 또는 Python으로 수행할 수 있습니다.

전제 조건

시작하기 전에.

  • Blockchain0x 계정 (무료 가입).
  • 대시보드에서 API 키(이 가이드에는 sk_test_ 키를 사용하십시오; 나중에 sk_live_로 전환할 것입니다).
  • 귀하의 에이전트 런타임에서 Node.js 20+ 또는 Python 3.11+.
  • LangChain, CrewAI, AutoGen, LlamaIndex, OpenAI Agents SDK, MCP 또는 일반 SDK 코드와 같은 어떤 프레임워크에서도 구축된 에이전트. 지침은 프레임워크에 구애받지 않습니다.
  • 웹후크를 수신하기 위해 공용 인터넷에서 접근 가능한 HTTPS 엔드포인트(ngrok 또는 배포 미리보기가 개발에 적합합니다).
5단계 중 1단계

에이전트 프로필을 생성하십시오.

에이전트 프로필은 귀하의 에이전트가 보내거나 받는 모든 결제 뒤에 있는 주소 지정 가능한 신원입니다. 지갑 주소, 공개 페이지, 인증 배지 및 (나중에) 지출 정책을 포함합니다. 논리적 에이전트당 하나를 생성하세요.

TypeScript
import { createClient } from "@blockchain0x/node";

const client = createClient({ apiKey: process.env.BLOCKCHAIN0X_API_KEY! }); // sk_test_ / sk_live_

const agent = await client.agents.create({ name: "research-bot" });

console.log(agent.id); // "agt_..."
// Public page: https://wallet.blockchain0x.com/a/{slug}
Python
from blockchain0x import Client

client = Client()  # reads BLOCKCHAIN0X_API_KEY from the environment

agent = client.agents.create(body={"name": "research-bot"})

print(agent["id"])  # "agt_..."
# Public page: https://wallet.blockchain0x.com/a/{slug}

After this call, the agent has a public page at https://wallet.blockchain0x.com/a/<slug> that any counterparty (human or agent) can hover for verification info. See the agent payment identity glossary entry for what that page exposes.

5단계 중 2단계

결제 전송.

payments.create sends USDC from the agent wallet. amountWei is base units (USDC has 6 decimals), so 0.01 USDC is the string "10000". The SDK auto-stamps an Idempotency-Key, and the call can return 503 until the chain adapter is wired for your network. To RECEIVE instead, settle an invoice you created in the dashboard with paymentRequests.settle - see the payment API page.

TypeScript
// Send a USDC payment from the agent wallet. amountWei is base units
// (USDC has 6 decimals): "10000" is 0.01 USDC. payments.create auto-stamps an
// Idempotency-Key and can return 503 until the chain adapter is wired.
const tx = await client.payments.create({
  agentId: agent.id,
  to: "0xRecipient",
  amountWei: "10000",
});

console.log(tx); // the submitted transfer
Python
# amountWei is USDC base units (6 decimals): "10000" is 0.01 USDC.
tx = client.payments.create(body={
    "agentId": agent["id"],
    "to": "0xRecipient",
    "amountWei": "10000",
})

print(tx)  # the submitted transfer
5단계 중 3단계

웹후크를 처리합니다.

웹훅은 결제가 완료되었는지 확인하는 방법입니다. Node에서는 @blockchain0x/node의 webhooks.verify가 HMAC 검사를 수행하고 구분된 유니온을 반환합니다; 다른 언어에서는 원본 본문에 대해 동일한 HMAC를 계산합니다. 이벤트 유형(수신에 대한 payment.received)에 따라 분기하고, 2xx에 빠르게 응답하며, 2xx 뒤에 더 무거운 작업을 대기시켜 전달이 시간 초과되지 않도록 합니다.

TypeScript (Express)
import express from "express";
import { webhooks } from "@blockchain0x/node";

const app = express();
// Capture the RAW body. The HMAC is over the exact bytes on the wire.
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/payment", (req, res) => {
  const result = webhooks.verify({
    headers: req.headers,
    rawBody: req.body, // Buffer, raw bytes
    secret: process.env.BLOCKCHAIN0X_WEBHOOK_SECRET!,
  });
  if (!result.ok) return res.status(400).json({ code: result.code });

  if (result.eventType === "payment.received") {
    // USDC landed - deliver the work, fulfil the order, etc.
    void deliver(result.eventId);
  }
  res.status(200).send("ok");
});
Python (Flask)
import hmac, hashlib, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["BLOCKCHAIN0X_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/payment")
def webhook():
    raw = request.get_data()  # RAW bytes - do not parse first
    sig = request.headers.get("X-Blockchain0x-Signature", "")
    ts = request.headers.get("X-Blockchain0x-Timestamp", "")
    parts = dict(p.split("=", 1) for p in sig.split(",") if "=" in p)
    t, v1 = parts.get("t", ts), parts.get("v1", sig)
    want = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(want, v1) or abs(time.time() - int(t)) > 300:
        abort(401)
    if request.headers.get("X-Blockchain0x-Event-Type") == "payment.received":
        deliver(request.get_json())  # USDC landed
    return ("ok", 200)
5단계 중 4단계

대시보드에서 지출 제어를 설정하세요.

내 에이전트가 단지 수신만 한다면, 이 부분은 생략할 수 있습니다. 만약 결제도 한다면, 대시보드에서 지출 권한을 설정하세요 - 주기별 할당량과 거래당 한도를 설정합니다. 이는 모든 결제에서 백엔드에 의해 시행되므로, 에이전트 측 규칙이 결코 할 수 없는 방식으로 프롬프트 주입을 견딥니다. 권한을 변경하는 API나 SDK 호출은 없습니다 (에이전트의 키는 자신의 한도를 넓힐 수 없습니다); API는 읽기 전용이므로, 귀하의 코드는 현재 값을 가져와 표시하거나 계획할 수 있습니다.

읽기 (curl)
curl https://api.blockchain0x.com/v1/agents/agt_123/spend-permissions \
  -H "Authorization: Bearer $BLOCKCHAIN0X_API_KEY"
응답
{
  "allowance_wei": "5000000",
  "per_tx_wei": "1000000",
  "period_seconds": 86400,
  "revoked_at": null
}
5단계 중 5단계

Base Sepolia에서 전체 흐름을 테스트하세요.

실제 sk_live_ 키로 전환하기 전에 sk_test_로 전체 경로를 끝까지 실행하십시오. 테스트 키는 모든 것을 Base Sepolia에 유지하며, 여기서 공개 수도꼭지에서 지갑에 자금을 제공하고 응답 형식이 라이브와 일치합니다. 키 접두사는 네트워크를 선택하므로 테스트 키는 메인넷 자금을 이동할 수 없습니다.

세 가지 시나리오를 연습하십시오: payment.received를 발생시키는 정상 경로 결제, 놓친 전송(웹후크를 죽은 URL로 지정한 후 transactions.get로 거래를 가져와 조정), 그리고 웹후크 재시도(첫 번째에는 500을 반환하고 두 번째에는 200을 반환하며 핸들러가 멱등임을 확인합니다). 세 가지 모두 테스트를 통과하면 키를 교체하고 배포하십시오.

일반적인 함정

팀에 일주일을 잃게 하는 다섯 가지 실수.

웹후크 서명 검증 건너뛰기

웹후크 결제에 대한 모든 POST를 권위 있는 것으로 수용하면 공격자가 가짜 결제 이벤트를 생성하고 에이전트를 속여 무료로 작업을 제공하게 할 수 있습니다. 항상 웹후크 비밀로 HMAC 검증을 수행하고, 상수 시간 비교를 사용하세요. 첫 번째 타협은 거의 항상 누락된 검증입니다.

별도의 확인 이벤트를 가정합니다.

전송된 이벤트는 payment.received, payment.sent, wallet.deployed 및 webhook.test입니다 - 별도의 확인 이벤트는 없습니다. payment.received는 전송이 블록에 있을 때 발생합니다. 대부분의 작업에 대해 이는 전달 신호입니다. 비싸거나 되돌릴 수 없는 작업의 경우, transactions.get으로 거래를 폴링하고 행동하기 전에 자신의 확인 임계값을 적용하십시오; 존재하지 않는 이벤트를 기다리지 마십시오.

웹훅 핸들러에 대한 아이템포턴시 없음

웹후크는 비-2xx 응답에 대해 재시도하며, 동일한 이벤트가 부하 하에 여러 번 도착할 것입니다. 여러분의 핸들러는 멱등성을 가져야 합니다: 이미 처리한 이벤트 ID의 작은 테이블을 유지하고 중복을 건너뛰세요. 그렇지 않으면 일시적인 문제로 동일한 작업이 두 번 전달되어 몇 시간 동안 이중 이행을 디버깅하는 데 시간을 낭비하게 됩니다.

테스트 및 라이브 API 키 혼합

테스트 키(sk_test_)는 샌드박스에 도달하고 Base Sepolia를 사용합니다; 라이브 키(sk_live_)는 프로덕션에 도달하고 Base 메인넷을 사용합니다. 환경 구성에서 혼합하는 것은 대부분의 '개발에서는 작동하지만 프로덕션에서는 실패' 티켓의 원인입니다. 런타임 환경과 키 접두사가 일치하지 않으면 시작 시 하드 실패합니다.

누락된 웹훅을 실패한 결제로 처리

실패 이벤트가 없으며, 웹훅이 누락될 수 있습니다(엔드포인트가 다운되었거나, 배달이 누락되었습니다). 에이전트를 '자금을 기다리는' 루프에 갇히게 하지 마십시오. 조정: transactions.get로 거래를 가져와 실제 상태를 확인하고, 대기 흐름에 타임아웃을 설정하여 버려진 결제가 보유된 리소스를 해제하도록 하여 영원히 멈추지 않도록 합니다.

다음 단계

첫 결제가 완료되면.

기본 결제가 작동하면 가장 효과적인 후속 조치는 지출 통제(에이전트가 예산을 도망치지 못하도록), 웹훅 견고성(결제가 부하 하에서 조용히 떨어지지 않도록), 그리고 신원 확인(상대방이 에이전트의 공개 페이지를 신뢰하도록)입니다.

전체 API 참조는 docs.blockchain0x.com에 있습니다. 동일한 API에 대한 제품 표면: 결제 API.

마지막 검토: 2026-05-15. CC BY 4.0에 따라 게시됨.

하나의 POST로 당신의 에이전트가 보수를 받습니다.

시작은 무료입니다. 테스트 키가 포함되어 있습니다. 첫 번째 결제가 10분 이내에 확인됩니다.