Cree un agente con createClient de @blockchain0x/node (o el cliente de Python), envíe un pago de USDC con payments.create y verifique el webhook firmado con webhooks.verify. Los controles de gasto se establecen en el panel y son de solo lectura a través de la API. El agente nunca toca las claves privadas directamente. Menos de diez minutos desde el registro hasta su primer pago de USDC en Base, en TypeScript o Python.

Crea el perfil del agente.

El perfil del agente es la identidad direccionable detrás de cada pago que tu agente envía o recibe. Lleva la dirección de la billetera, la página pública, las insignias de verificación y (más adelante) la política de gasto. Crea uno por agente lógico.

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.

Maneja el webhook.

Los webhooks son cómo descubres que un pago se ha liquidado. En Node, webhooks.verify de @blockchain0x/node realiza la verificación HMAC y devuelve una unión discriminada; en otros lenguajes, calcula el mismo HMAC sobre el cuerpo RAW. Ramifica según el tipo de evento (payment.received para entrante), responde 2xx rápidamente y coloca cualquier cosa más pesada detrás del 2xx para que la entrega no se agote.

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)

Prueba todo el flujo en Base Sepolia.

Antes de cambiar a claves sk_live_, ejecuta el camino completo de extremo a extremo con sk_test_. Una clave de prueba mantiene todo en Base Sepolia, donde financias la billetera desde el grifo público y las formas de respuesta coinciden con las de producción. El prefijo de la clave elige la red, así que una clave de prueba no puede mover fondos de la red principal.

Ejercita tres escenarios: un pago en el camino correcto que activa payment.received, una entrega fallida (apunta el webhook a una URL muerta, luego concilia obteniendo la transacción con transactions.get), y un reintento de webhook (devuelve un 500 la primera vez, 200 la segunda, y confirma que tu manejador es idempotente). Cuando los tres pasen la prueba, cambia la clave y envía.

Una vez que tengas tu primer pago.

Con los pagos básicos funcionando, los seguimientos que más valen la pena son los controles de gasto (para que el agente no se lleve el presupuesto), la robustez de los webhooks (para que los pagos no se caigan silenciosamente bajo carga) y la verificación de identidad (para que las contrapartes confíen en la página pública del agente).

La referencia completa de la API se encuentra en docs.blockchain0x.com. Superficie de producto para las mismas APIs: API de Pagos.