Tạo một tác nhân với createClient từ @blockchain0x/node (hoặc khách hàng Python), gửi một khoản thanh toán USDC với payments.create, và xác minh webhook đã ký với webhooks.verify. Các kiểm soát chi tiêu được thiết lập trong bảng điều khiển và chỉ đọc qua API. Tác nhân không bao giờ chạm vào khóa riêng trực tiếp. Dưới mười phút từ khi đăng ký đến khoản thanh toán USDC đầu tiên của bạn trên Base, bằng TypeScript hoặc Python.

Tạo hồ sơ đại lý.

Hồ sơ tác nhân là danh tính có thể truy cập đứng sau mỗi khoản thanh toán mà tác nhân của bạn gửi hoặc nhận. Nó chứa địa chỉ ví, trang công khai, huy hiệu xác minh, và (sau này) chính sách chi tiêu. Tạo một cái cho mỗi tác nhân logic.

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}

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.

Xử lý webhook.

Webhooks là cách bạn tìm ra một khoản thanh toán đã được giải quyết. Trong Node, webhooks.verify từ @blockchain0x/node thực hiện kiểm tra HMAC và trả về một hợp nhất phân biệt; trong các ngôn ngữ khác, tính toán cùng một HMAC trên thân dữ liệu thô. Phân nhánh theo loại sự kiện (payment.received cho inbound), phản hồi 2xx nhanh chóng, và xếp hàng bất kỳ thứ gì nặng hơn phía sau 2xx để giao hàng không bị hết thời gian.

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");
});

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)

Kiểm tra toàn bộ quy trình trên Base Sepolia.

Trước khi chuyển sang khóa sk_live_, hãy chạy toàn bộ đường dẫn từ đầu đến cuối với khóa sk_test_. Một khóa thử nghiệm giữ mọi thứ trên Base Sepolia, nơi bạn cấp vốn cho ví từ vòi công cộng và các hình dạng phản hồi khớp với trực tiếp. Tiền tố khóa chọn mạng, vì vậy một khóa thử nghiệm không thể di chuyển quỹ mainnet.

Thực hiện ba kịch bản: một khoản thanh toán theo đường hạnh phúc phát ra payment.received, một lần giao hàng bị bỏ lỡ (chỉ định webhook đến một URL chết, sau đó đối chiếu bằng cách lấy giao dịch với transactions.get), và một lần thử lại webhook (trả về 500 lần đầu tiên, 200 lần thứ hai, và xác nhận rằng trình xử lý của bạn là idempotent). Khi cả ba đều vượt qua bài kiểm tra, hãy thay đổi khóa và phát hành.

Khi bạn có thanh toán đầu tiên.

Khi thanh toán cơ bản đã hoạt động, các việc tiếp theo mang lại giá trị lớn nhất là kiểm soát chi tiêu (để agent không vượt khỏi ngân sách), độ bền webhook (để thanh toán không bị rơi âm thầm dưới tải cao), và xác minh danh tính (để đối tác tin vào trang công khai của agent).

Tài liệu API đầy đủ nằm tại docs.blockchain0x.com. Bề mặt sản phẩm cho cùng các API: API Thanh toán.