주 콘텐츠로 건너뛰기
결제 API

AI 에이전트 코드를 위해 설계된 결제 API입니다.

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

거래 보기: Base에서 확인된 수신 USDC 결제

Blockchain0x API는 의도적으로 작습니다. 첫 결제를 위해 한 시간을 문서를 읽게 하고 싶지 않습니다. 코드 조각을 복사하고 API 키를 붙여넣고 실행하기를 원합니다.

핵심 엔드포인트

에이전트 코드를 위해 구축된 작은 인터페이스입니다.

결제 형태의 경로는 아래에 있습니다. 웹훅, API 키 및 읽기 전용 지출 권한이 표면을 완성하며, SDK가 이를 모두 래핑합니다.

POST/v1/payments에이전트 지갑에서 USDC 결제 전송
GET/v1/transactions/{id}거래의 상태와 해시 가져오기
POST/v1/payment-requests/{id}/settle온체인 증명으로 청구서 정산하기
GET/v1/agents/{id}에이전트 지갑 가져오기
POST/v1/agents에이전트 지갑 생성
전송된 웹훅 이벤트

모두 HMAC-SHA256으로 서명되었습니다.

서명 위치: X-Blockchain0x-Signature 헤더. 5분의 재생 창. 모든 POST에서 idempotency 키.

payment.received

USDC가 귀하의 에이전트 지갑 중 하나에 도착했습니다.

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 network
공식 SDK

TypeScript 및 Python을 위한 타입 지정된 클라이언트.

타입스크립트
npm install @blockchain0x/node

Node 18+와 호환됩니다. 기본 TypeScript 유형.

파이썬
pip install blockchain0x

Python 3.9+. 동기 및 비동기 클라이언트.

전체 엔드포인트 스키마

SDK가 래핑하는 요청 본문.

각 경로에 대한 검증된 입력입니다. 응답은 여기서 간단히 표시됩니다; 전체 타입 형상은 SDK 및 API 참조에 있습니다. 금액은 USDC 기본 단위(6자리 소수점)입니다.

POST/v1/payments

USDC 결제 전송 (payments.create). amountWei는 USDC 기본 단위(6자리 소수)입니다. 체인 어댑터가 연결될 때까지 503을 반환할 수 있습니다.

요청
{
  "agentId": "agt_123",
  "to": "0xRecipient",
  "amountWei": "10000",
  "metadata": { "reason": "Research report" }
}
응답
{
  "txHash": "0xff5...e12"
}
POST/v1/payment-requests/{id}/settle

대시보드에서 생성된 결제 요청(청구서)을 온체인 증명(paymentRequests.settle)과 함께 정산하세요. 생성 경로는 없으며 - 정산만 가능합니다.

요청
{
  "txHash": "0xff5...e12",
  "payerAddress": "0xBuyer...",
  "amountUsdcVerified": "0.10"
}
응답
{
  "txHash": "0xff5...e12"
}
GET/v1/transactions/{id}

ID로 단일 거래 가져오기 (transactions.get).

요청
(no body)
응답
{
  "id": "tx_01J9...",
  "txHash": "0xff5...e12"
}
GET/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"
}
GET/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", 200

webhook 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가 자동으로 안정적인 것을 생성하므로 재시도된 호출은 두 번 지불하는 대신 단일 온체인 제출로 축소됩니다. 프로세스 간 동일한 논리적 작업을 중복 제거하려면 자신의 키로 재정의하세요.

BASH
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를 유창하게 사용합니다. 그것 없이도 작동합니다.

x402는 HTTP 네이티브 결제를 위한 개방형 프로토콜입니다. 전제: 402 결제 필요를 반환하는 모든 API는 응답에서 결제 요구 사항을 광고할 수 있으며, 사양을 이해하는 모든 클라이언트는 결제하고 재시도할 수 있습니다 - 가입 필요 없음, API 키 필요 없음, 비대면 협상 필요 없음. Blockchain0x는 실제 x402 패키지를 제공합니다: 결제 측 클라이언트와 수신 측 서버 어댑터. 현재 유일한 스킴은 Base에서 exact-usdc입니다.

호출자가 결제를 하지 않았을 때 서버가 반환하는 402
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" }
  ]
}

에이전트 호출자가 수행하는 작업

  1. 402 본문을 읽습니다: version 1, resource, 그리고 비어 있지 않은 payment requirements의 accepts[] (scheme exact-usdc, Base의 network eip155:8453).
  2. 결제를 생성한 뒤 X-Payment: exact-usdc:<base64(json)> 헤더와 함께 요청을 다시 전송합니다.
  3. 결제 측면에서는 @blockchain0x/x402의 createX402Client({ sdk })가 이를 대신 처리합니다 - 402에 자동으로 응답합니다.
  4. 서버가 X-Payment 헤더를 검증하고 원래 요청을 처리합니다.

양쪽 모두, 실제 패키지

결제 측에서는, createX402Client({ sdk }) @blockchain0x/x402에서 fetch를 감싸고 자동으로 402에 응답합니다. 수신 측에서는 createX402Plugin (Fastify) 및 createX402Middleware (Express) 자신의 엔드포인트를 설정하세요. 또는 x402를 건너뛰고 REST API를 직접 사용하세요 - 두 가지가 결합되므로 준비가 되면 x402를 추가할 수 있습니다.

자주 묻는 질문

개발자들이 가장 먼저 묻는 다섯 가지 API 질문.

SDK 없이 API를 사용할 수 있나요?

네. SDK는 베어러 토큰 인증을 사용하는 HTTPS를 통한 표준 JSON에 대한 얇은 래퍼입니다. HTTP와 HMAC-SHA256을 사용할 수 있는 모든 것은 API를 직접 사용할 수 있습니다. SDK는 인체공학적 타이핑, 재시도 및 멱등성 키 생성을 위해 존재하며; 편리하지만 필수는 아닙니다. 우리는 Node, Python, Ruby, Go 및 JVM용 클라이언트를 제공합니다; 다른 언어에서는 원시 API를 호출하세요.

이벤트가 발생할 때 웹후크 엔드포인트가 다운되면 어떻게 되나요?

전송은 백오프와 함께 재시도되며 각 시도는 대시보드에 HTTP 응답 코드와 함께 기록됩니다. 이벤트를 놓친 경우 API에서 조정할 수 있습니다 - GET /v1/transactions/{id}로 ID로 거래를 가져옵니다 - 웹후크에만 의존하지 마십시오. 신뢰하기 전에 모든 전송을 webhooks.verify(또는 문서화된 HMAC)로 확인하고, 느린 핸들러가 실패처럼 보이지 않도록 2xx로 빠르게 응답하십시오.

내 에이전트가 네트워크 오류로 재시도할 경우 중복 결제를 방지하려면 어떻게 해야 하나요?

POST에서 Idempotency-Key 헤더를 전송하세요. SDK의 payments.create는 귀하를 위해 안정적인 키를 자동으로 생성하므로, 재시도된 호출은 두 번 결제하는 대신 단일 온체인 제출로 축소됩니다. 프로세스 간 동일한 논리 작업을 중복 제거하려면 자신의 키로 이를 재정의하세요. 이 키는 귀하의 에이전트 또는 네트워크가 중간에 재시도하는 경우에 대한 안전망입니다.

요금 제한이 있나요?

네, 그리고 이는 귀하의 계획에 따라 확장됩니다. 변동하는 숫자를 하드코딩하기보다는 응답에서 읽으세요: 모든 호출은 X-RateLimit-Limit, X-RateLimit-Remaining 및 X-RateLimit-Reset을 반환하며, 429는 초 단위로 Retry-After를 포함합니다. 공식 SDK는 이미 429 및 5xx에서 지수 백오프를 사용하여 재시도하며 Retry-After를 존중하므로 대부분의 코드는 이를 수동으로 처리할 필요가 없습니다.

이것은 x402 호환인가요?

네. x402 패키지는 실제입니다: @blockchain0x/x402의 createX402Client({ sdk })는 결제 측에서 402 챌린지에 응답하며, createX402Plugin(Fastify) / createX402Middleware(Express)는 수신 측에서 귀하의 엔드포인트를 게이트합니다. 오늘날 유일한 스킴은 exact-usdc이며, 와이어 형식은 402 본문이 버전 1과 accepts[] 목록을 광고하는 X-Payment: exact-usdc:<base64(json)> 요청 헤더입니다. x402를 무시하고 REST API를 직접 사용할 수도 있습니다.

첫 결제를 진행하세요.

시작은 무료입니다. API 키에서 첫 번째 USDC 전송까지 몇 줄의 코드로 가능합니다.