AI 에이전트 코드를 위해 설계된 결제 API입니다.
작은 REST API입니다. 서명된 웹훅. 다섯 가지 언어의 공식 SDK. 귀하의 에이전트가 몇 줄의 코드로 USDC를 전송하고 정산하며 결제를 확인할 수 있도록 구축되었습니다.

Blockchain0x API는 의도적으로 작습니다. 첫 결제를 위해 한 시간을 문서를 읽게 하고 싶지 않습니다. 코드 조각을 복사하고 API 키를 붙여넣고 실행하기를 원합니다.
에이전트 코드를 위해 구축된 작은 인터페이스입니다.
결제 형태의 경로는 아래에 있습니다. 웹훅, API 키 및 읽기 전용 지출 권한이 표면을 완성하며, SDK가 이를 모두 래핑합니다.
/v1/payments에이전트 지갑에서 USDC 결제 전송/v1/transactions/{id}거래의 상태와 해시 가져오기/v1/payment-requests/{id}/settle온체인 증명으로 청구서 정산하기/v1/agents/{id}에이전트 지갑 가져오기/v1/agents에이전트 지갑 생성모두 HMAC-SHA256으로 서명되었습니다.
서명 위치: X-Blockchain0x-Signature 헤더. 5분의 재생 창. 모든 POST에서 idempotency 키.
payment.receivedUSDC가 귀하의 에이전트 지갑 중 하나에 도착했습니다.
payment.sent귀하의 에이전트에서 발신된 결제가 체인에서 정산되었습니다.
wallet.deployed에이전트의 스마트 지갑이 배포되었습니다.
webhook.test대시보드에서 트리거한 테스트 배달
에이전트의 지갑에서 USDC를 전송하세요.
from blockchain0x import Client
client = Client(api_key="sk_test_...") # sk_test_ testnet, sk_live_ mainnet
tx = client.payments.create(body={
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000", # USDC base units (6 decimals): 0.01 USDC
})
print(tx) # may return 503 until the chain adapter is wired for your networkTypeScript 및 Python을 위한 타입 지정된 클라이언트.
npm install @blockchain0x/nodeNode 18+와 호환됩니다. 기본 TypeScript 유형.
pip install blockchain0xPython 3.9+. 동기 및 비동기 클라이언트.
SDK가 래핑하는 요청 본문.
각 경로에 대한 검증된 입력입니다. 응답은 여기서 간단히 표시됩니다; 전체 타입 형상은 SDK 및 API 참조에 있습니다. 금액은 USDC 기본 단위(6자리 소수점)입니다.
/v1/paymentsUSDC 결제 전송 (payments.create). amountWei는 USDC 기본 단위(6자리 소수)입니다. 체인 어댑터가 연결될 때까지 503을 반환할 수 있습니다.
{
"agentId": "agt_123",
"to": "0xRecipient",
"amountWei": "10000",
"metadata": { "reason": "Research report" }
}{
"txHash": "0xff5...e12"
}/v1/payment-requests/{id}/settle대시보드에서 생성된 결제 요청(청구서)을 온체인 증명(paymentRequests.settle)과 함께 정산하세요. 생성 경로는 없으며 - 정산만 가능합니다.
{
"txHash": "0xff5...e12",
"payerAddress": "0xBuyer...",
"amountUsdcVerified": "0.10"
}{
"txHash": "0xff5...e12"
}/v1/transactions/{id}ID로 단일 거래 가져오기 (transactions.get).
(no body){
"id": "tx_01J9...",
"txHash": "0xff5...e12"
}/v1/agents/{id}에이전트 지갑 가져오기 (agents.get). 공개 페이지는 wallet.blockchain0x.com/a/{slug}에 있습니다.
(no body){
"id": "agt_01J9QKE...",
"name": "research-bot",
"public_url": "https://wallet.blockchain0x.com/a/research-bot"
}/v1/agents/{id}/spend-permissions에이전트의 지출 권한을 읽습니다. API를 통해 읽기 전용 - 생성 및 변경은 대시보드 전용입니다.
(no body){
"allowance_wei": "5000000",
"per_tx_wei": "1000000",
"period_seconds": 86400,
"start_at": "2026-05-15T00:00:00Z",
"revoked_at": null
}페이로드를 신뢰하기 전에 항상 서명을 확인하십시오.
누구나 귀하의 콜백 URL에 POST할 수 있습니다. 서명이 이벤트가 실제로 우리에게서 왔음을 증명합니다.
모든 전송은 X-Blockchain0x-Signature 헤더 (t=<unix>,v1=<hex>) - `${t}.${rawBody}` 문자열에 대해 웹훅 비밀을 사용하여 HMAC-SHA256을 계산하며, 5분 재생 창 내에서 수행됩니다. Node에서는 @blockchain0x/node의 webhooks.verify가 이를 수행하고 분기할 수 있는 구별된 유니온을 반환합니다. 다른 언어에서는 동일한 HMAC을 계산하고 상수 시간에 비교합니다. RAW 본문을 읽고, 파싱된 복사본이 아닌 원본을 읽어야 합니다 - 재직렬화는 서명을 깨뜨립니다.
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 });
// result.eventType is "payment.received" | "payment.sent" | ...
handleEvent(result);
res.status(200).send("ok");
});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 receive():
raw = request.get_data() # RAW bytes - do not parse first
sig = request.headers.get("X-Blockchain0x-Signature", "")
ts = request.headers.get("X-Blockchain0x-Timestamp", "")
# Header is "t=<unix>,v1=<hex>"; some proxies send bare hex + the ts header.
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)
handle_event(request.headers.get("X-Blockchain0x-Event-Type"), request.get_json())
return "ok", 200webhook secret는 webhook을 생성하거나 회전할 때(webhooks.rotateSecret) 한 번 반환되며, handler는 BLOCKCHAIN0X_WEBHOOK_SECRET에서 이를 읽습니다. secret을 회전하면 기존 secret은 무효화되므로 배포를 함께 조율하세요: 서버 env에 새 secret을 설정하고, 배포한 다음, 회전하세요. 제공되는 event는 payment.received, payment.sent, wallet.deployed, webhook.test이며 - event type으로 분기하고 나머지는 무시하면 됩니다.
안전하게 재시도하세요. API는 두 번 결제하지 않습니다.
에이전트 코드 재시도. 네트워크가 연결을 끊습니다. LLM이 도구를 두 번 호출하기로 결정합니다. 이를 안전하게 만들기 위해, 다음을 전송하십시오: Idempotency-Key POST의 헤더. SDK의 payments.create가 자동으로 안정적인 것을 생성하므로 재시도된 호출은 두 번 지불하는 대신 단일 온체인 제출로 축소됩니다. 프로세스 간 동일한 논리적 작업을 중복 제거하려면 자신의 키로 재정의하세요.
curl -X POST https://api.blockchain0x.com/v1/payments \
-H "Authorization: Bearer $BLOCKCHAIN0X_API_KEY" \
-H "Idempotency-Key: 8e2c3a40-pay-vendor-once" \
-H "Content-Type: application/json" \
-d '{ "agentId": "agt_123", "to": "0xRecipient", "amountWei": "10000" }'- 첫 번째 호출: 결제를 제출하고 거래를 반환합니다.
- 같은 키로 재시도: 두 번 결제하는 대신 하나의 온체인 제출로 축소됩니다.
- SDK가 처리합니다: payments.create는 안정적인 멱등성 키를 자동으로 발행하므로 재시도된 호출이 기본적으로 안전합니다.
- 재정의하세요: 프로세스 간 동일한 논리적 작업을 중복 제거하고 싶을 때 자신의 키를 전달하세요.
추천되는 패턴은 에이전트 코드에서 논리적 작업당 UUID를 생성하는 것입니다(예: "주문 Y에 대해 공급업체 X에게 지불"당 하나의 UUID) 및 작업이 성공할 때까지 재시도 간에 재사용하는 것입니다. 공식 SDK는 이를 지정하지 않으면 payments.create에 대해 자동으로 UUID를 생성합니다.
테이블이 아닌 응답에서 한도를 읽으세요.
계획에 따라 한계를 조정합니다. 고정된 숫자를 하드코딩하는 대신, 모든 응답이 현재 위치를 알려주고 SDK가 자동으로 백오프를 처리합니다.
모든 성공 응답의 헤더
X-RateLimit-Limit: 귀하의 플랜의 고정 요금X-RateLimit-Remaining: 이 창에서 남은 호출 수X-RateLimit-Reset: 창이 재설정될 때의 유닉스 초
상한에 도달했을 때 (HTTP 429)
- 응답에는 포함됩니다:
Retry-After초 단위로 - 공식 SDK는 429 및 5xx에서 지수 백오프를 사용하여 재시도하며, Retry-After를 준수합니다.
- 대부분의 코드는 SDK가 이미 처리하기 때문에 429를 수동으로 처리하지 않습니다.
x402를 유창하게 사용합니다. 그것 없이도 작동합니다.
x402는 HTTP 네이티브 결제를 위한 개방형 프로토콜입니다. 전제: 402 결제 필요를 반환하는 모든 API는 응답에서 결제 요구 사항을 광고할 수 있으며, 사양을 이해하는 모든 클라이언트는 결제하고 재시도할 수 있습니다 - 가입 필요 없음, API 키 필요 없음, 비대면 협상 필요 없음. Blockchain0x는 실제 x402 패키지를 제공합니다: 결제 측 클라이언트와 수신 측 서버 어댑터. 현재 유일한 스킴은 Base에서 exact-usdc입니다.
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"version": 1,
"resource": "https://api.example.com/paid-endpoint",
"accepts": [
{ "scheme": "exact-usdc", "network": "eip155:8453" }
]
}에이전트 호출자가 수행하는 작업
- 402 본문을 읽습니다: version 1, resource, 그리고 비어 있지 않은 payment requirements의 accepts[] (scheme exact-usdc, Base의 network eip155:8453).
- 결제를 생성한 뒤 X-Payment: exact-usdc:<base64(json)> 헤더와 함께 요청을 다시 전송합니다.
- 결제 측면에서는 @blockchain0x/x402의 createX402Client({ sdk })가 이를 대신 처리합니다 - 402에 자동으로 응답합니다.
- 서버가 X-Payment 헤더를 검증하고 원래 요청을 처리합니다.
양쪽 모두, 실제 패키지
결제 측에서는, createX402Client({ sdk }) @blockchain0x/x402에서 fetch를 감싸고 자동으로 402에 응답합니다. 수신 측에서는 createX402Plugin (Fastify) 및 createX402Middleware (Express) 자신의 엔드포인트를 설정하세요. 또는 x402를 건너뛰고 REST API를 직접 사용하세요 - 두 가지가 결합되므로 준비가 되면 x402를 추가할 수 있습니다.