Realizar Pagos con Agentes

En resumen
Los agentes de IA pueden pagar APIs y datos por solicitud, en stablecoins, mediante protocolos abiertos de pago para agentes. Con Blockradar, un agente paga desde una billetera cuya clave privada nunca sale de Blockradar, usando el endpoint de Firma de Datos Tipados que usted ya tiene.

Protocolos Compatibles

Protocolo	Redes y tokens
x402	Cadenas EVM, USDC (EIP-3009)

¿Vende a agentes? Consulte Aceptar Pagos de Agentes.

Requisitos Previos

Clave API

Obtenga su clave API desde el Panel de Blockradar. Diríjase a Developers para generar una.

Billetera Principal EVM

Cree una billetera principal en el panel en la cadena en la que cobra la API, como Base (consulte Crear una Billetera Principal). Los pagos de agentes a través de Blockradar son solo EVM.

USDC Habilitado

Habilite USDC en la billetera para que se rastreen los saldos y los depósitos. Consulte Gestión de Activos.

Asigne al Agente Su Propio Presupuesto

La firma no tiene un límite de gasto por pago
Cualquier persona que tenga una clave API con acceso a una billetera puede firmar un pago de cualquier monto desde esa billetera o sus direcciones. Blockradar no limita lo que firma un agente. Limite el daño que puede causar un agente con mal comportamiento o una clave filtrada asignándole al agente una dirección dedicada que contenga solo lo que tiene permitido gastar.

Una dirección hija con el barrido automático desactivado funciona bien como presupuesto de un agente. Recárguela con el monto que el agente puede gastar, y el agente nunca podrá pagar más que ese saldo.

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "name": "Research agent budget",
    "disableAutoSweep": true,
    "metadata": {
      "purpose": "agent-payments"
    }
  }'

const response = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': apiKey
    },
    body: JSON.stringify({
      name: 'Research agent budget',
      disableAutoSweep: true,
      metadata: { purpose: 'agent-payments' }
    })
  }
).then(r => r.json());

console.log('Agent address:', response.data.address);
console.log('Address ID:', response.data.id);

Mantenga disableAutoSweep: true en la dirección de un agente. Con el barrido automático activado, el USDC que envía para financiar al agente se barre a la billetera principal, y los pagos del agente fallan por falta de fondos.

Pagar desde la billetera principal también funciona. Use los endpoints de la billetera principal en los ejemplos siguientes y omita addressId. En ese caso, todo el saldo de la billetera principal queda al alcance del agente, así que hágalo solo con una billetera principal dedicada al agente. En el Plan de Checkout las operaciones con direcciones hijas no están disponibles, así que use una billetera principal dedicada al agente.

Cómo Funciona x402

x402 es un protocolo abierto que permite a una API cobrar por solicitud: responde con HTTP 402 Payment Required, y quien llama reintenta con un pago en USDC firmado. x402 tiene tres partes: el comprador (su agente), el vendedor (la API que recibe el pago) y un facilitador que verifica el pago y lo envía en cadena.

La API solicita el pago

El agente llama a un endpoint de pago. La API responde con 402 Payment Required y un encabezado PAYMENT-REQUIRED que enumera lo que acepta: red, token, monto y la dirección payTo.

Blockradar firma el pago

El agente convierte una de esas opciones en un TransferWithAuthorization de EIP-3009 y lo firma con el endpoint de datos tipados de Blockradar. Todavía no se envía nada en cadena.

El agente reintenta con la firma

El agente repite la solicitud con el pago firmado en el encabezado PAYMENT-SIGNATURE.

El facilitador liquida

El facilitador del vendedor verifica la firma y envía la transferencia en cadena, pagando él mismo el gas. La API devuelve la respuesta, con el resultado de la liquidación en un encabezado PAYMENT-RESPONSE.

La billetera del agente necesita USDC pero no gas. La firma autoriza una única transferencia de un monto exacto a una dirección exacta, y el facilitador no puede cambiar ninguno de los dos.

Pagar con x402

Primero financie la dirección del agente, como se describe en Asigne al Agente Su Propio Presupuesto.

Opción 1: Usar el SDK cliente de x402

El cliente oficial @x402/fetch gestiona el intercambio 402 por usted. Solo necesita un firmante con un address y un método signTypedData. El adaptador siguiente implementa ese firmante sobre el endpoint de datos tipados de Blockradar, de modo que la clave permanece en Blockradar.

npm install @x402/fetch @x402/evm

JavaScript

import { wrapFetchWithPaymentFromConfig, decodePaymentResponseHeader } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm';

// An x402 signer whose key stays in Blockradar. Pass addressId to pay from a child address.
function blockradarSigner({ apiKey, walletId, addressId, address }) {
  const path = addressId
    ? `/wallets/${walletId}/addresses/${addressId}/signing/typed-data`
    : `/wallets/${walletId}/signing/typed-data`;

  return {
    address,
    async signTypedData({ domain, types, message }) {
      // Blockradar derives the domain type from `domain`, so EIP712Domain must not be in `types`
      const { EIP712Domain, ...signTypes } = types;

      const res = await fetch(`https://api.blockradar.co/v1${path}`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
        // x402 passes uint256 values as BigInt, which JSON.stringify cannot serialize
        body: JSON.stringify({ domain, types: signTypes, message }, (_, v) =>
          typeof v === 'bigint' ? v.toString() : v
        ),
      });
      const body = await res.json();
      if (!res.ok) {
        throw new Error(`Blockradar signing failed: ${JSON.stringify(body.message)}`);
      }
      if (body.data.senderAddress.toLowerCase() !== address.toLowerCase()) {
        throw new Error(`Signed by ${body.data.senderAddress}, expected ${address}`);
      }
      return body.data.signedTransaction.signature;
    },
  };
}

const signer = blockradarSigner({
  apiKey: process.env.BLOCKRADAR_API_KEY,
  walletId: process.env.BLOCKRADAR_WALLET_ID,
  addressId: process.env.BLOCKRADAR_ADDRESS_ID, // omit to pay from the master wallet
  address: process.env.AGENT_ADDRESS,           // the address that holds the USDC
});

const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:8453', client: new ExactEvmScheme(signer) }], // Base mainnet
});

const response = await fetchWithPayment('https://api.example.com/premium-data');
console.log(await response.json());

const settlement = response.headers.get('PAYMENT-RESPONSE');
if (settlement) {
  console.log(decodePaymentResponseHeader(settlement)); // { success, transaction, network, payer }
}

Registre un esquema por cada red en la que paga el agente (eip155:84532 para Base Sepolia durante las pruebas), con una billetera en esa cadena detrás de cada uno.

Opción 2: Construir el pago usted mismo

Sin el SDK, o en otro lenguaje, un pago requiere tres llamadas HTTP: la primera solicitud, la llamada de firma a Blockradar y el reintento con pago. Los pasos siguientes pagan 0,01 USDC en Base.

Paso 1: Leer los requisitos de pago

Llame a la API. Una respuesta 402 incluye un encabezado PAYMENT-REQUIRED codificado en base64. Una vez decodificado, se ve así:

{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": {
    "url": "https://api.example.com/premium-data",
    "description": "Access to premium market data",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "maxTimeoutSeconds": 60,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}

Elija una entrada de accepts que su billetera pueda pagar:

scheme es exact.
network es la cadena de la billetera. eip155:8453 es Base mainnet.
extra.assetTransferMethod está ausente o es eip3009. El método permit2 requiere primero una aprobación del token en cadena, que cuesta gas, por lo que esta guía no lo cubre.

amount está expresado en la unidad más pequeña del token. USDC tiene 6 decimales, así que 10000 equivale a 0,01 USDC.

Paso 2: Firmar la autorización

Construya el TransferWithAuthorization a partir de los requisitos y fírmelo desde la dirección del agente:

Campo	Valor
`domain.name`, `domain.version`	`extra.name` y `extra.version`
`domain.chainId`	El número después de `eip155:` en `network`, como número JSON
`domain.verifyingContract`	`asset`, el contrato de USDC
`message.from`	La dirección del agente
`message.to`	`payTo`
`message.value`	`amount`
`message.validAfter`	Una hora Unix ligeramente en el pasado, como la hora actual menos 600 segundos
`message.validBefore`	La hora actual más `maxTimeoutSeconds`
`message.nonce`	32 bytes aleatorios en hexadecimal. Genere uno nuevo para cada pago

curl --request POST \
  --url https://api.blockradar.co/v1/wallets/{walletId}/addresses/{addressId}/signing/typed-data \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "domain": {
      "name": "USD Coin",
      "version": "2",
      "chainId": 8453,
      "verifyingContract": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
    },
    "types": {
      "TransferWithAuthorization": [
        { "name": "from", "type": "address" },
        { "name": "to", "type": "address" },
        { "name": "value", "type": "uint256" },
        { "name": "validAfter", "type": "uint256" },
        { "name": "validBefore", "type": "uint256" },
        { "name": "nonce", "type": "bytes32" }
      ]
    },
    "message": {
      "from": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a",
      "to": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "value": "10000",
      "validAfter": "1791106604",
      "validBefore": "1791107264",
      "nonce": "0x312a453ed3d129ba71de863aa623245c0e5e120bad410d995cea6739aa8ee98b"
    }
  }'

import { randomBytes } from 'node:crypto';

const now = Math.floor(Date.now() / 1000);
const authorization = {
  from: agentAddress,
  to: accepted.payTo,
  value: accepted.amount,
  validAfter: String(now - 600),
  validBefore: String(now + accepted.maxTimeoutSeconds),
  nonce: '0x' + randomBytes(32).toString('hex'),
};

const res = await fetch(
  `https://api.blockradar.co/v1/wallets/${walletId}/addresses/${addressId}/signing/typed-data`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
    body: JSON.stringify({
      domain: {
        name: accepted.extra.name,
        version: accepted.extra.version,
        chainId: Number(accepted.network.split(':')[1]),
        verifyingContract: accepted.asset,
      },
      types: {
        TransferWithAuthorization: [
          { name: 'from', type: 'address' },
          { name: 'to', type: 'address' },
          { name: 'value', type: 'uint256' },
          { name: 'validAfter', type: 'uint256' },
          { name: 'validBefore', type: 'uint256' },
          { name: 'nonce', type: 'bytes32' },
        ],
      },
      message: authorization,
    }),
  }
);
const signed = await res.json();
if (!res.ok) throw new Error(`Signing failed: ${JSON.stringify(signed.message)}`);

const signature = signed.data.signedTransaction.signature;

Para firmar desde la billetera principal, use POST /v1/wallets/{walletId}/signing/typed-data y establezca from en la dirección de la billetera principal. La respuesta es la respuesta de datos tipados estándar; la firma se encuentra en data.signedTransaction.signature.

Paso 3: Reintentar con el pago

Envuelva la firma y la autorización en un payload de pago, codifíquelo en base64 y envíelo en el encabezado PAYMENT-SIGNATURE en la misma solicitud:

JavaScript

const paymentPayload = {
  x402Version: 2,
  resource: paymentRequired.resource,
  accepted,                              // the entry you chose from `accepts`
  payload: { signature, authorization },
};

const paid = await fetch('https://api.example.com/premium-data', {
  headers: {
    'PAYMENT-SIGNATURE': Buffer.from(JSON.stringify(paymentPayload)).toString('base64'),
  },
});

Paso 4: Verificar la liquidación

Una respuesta exitosa incluye un encabezado PAYMENT-RESPONSE codificado en base64:

{
  "success": true,
  "transaction": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
  "network": "eip155:8453",
  "payer": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a"
}

transaction es el hash en cadena de la transferencia de USDC. Si el pago falla, la API vuelve a responder 402, y PAYMENT-RESPONSE incluye un errorReason como insufficient_funds.

Llamar a una API x402 v1

Los servidores con la versión 1 de x402 difieren del flujo anterior en cuatro aspectos:

Los requisitos de pago están en el cuerpo de la respuesta 402, no en un encabezado.
Las redes tienen nombre (base, base-sepolia) en lugar de eip155:<chainId>. Base es el chain ID 8453; Base Sepolia es 84532.
El campo del monto es maxAmountRequired, no amount.
El pago va en el encabezado X-PAYMENT como JSON codificado en base64 con x402Version: 1, scheme, network y el mismo objeto payload, y la liquidación vuelve en X-PAYMENT-RESPONSE.

El paso de firma con Blockradar es idéntico.

Reglas de firma que suelen causar errores en las integraciones

Regla	Qué sucede en caso contrario
`domain.chainId` es un número JSON que coincide con la cadena de la billetera	`400 Chain ID mismatch`. `"8453"` como cadena de texto también falla.
`types` contiene solo `TransferWithAuthorization`	Incluir `EIP712Domain` en `types` falla con un error `ambiguous primary types or unused types`. Blockradar construye el tipo de dominio a partir de `domain`.
`message.from` es la dirección que firma	El facilitador rechaza el pago porque la firma se recupera a una dirección distinta.
Un `nonce` nuevo para cada pago	USDC rechaza un nonce reutilizado, por lo que el pago no puede liquidarse.
La dirección que paga tiene suficiente USDC	El facilitador rechaza el pago indicando saldo insuficiente. No se necesita gas.

Cada firma se registra como una transacción SIGNED y activa un webhook signed.success, lo que le proporciona un registro de auditoría de cada pago que su agente autorizó. Una firma no es un pago: el USDC solo se mueve cuando el facilitador del vendedor lo liquida. Cuando el vendedor está fuera de Blockradar, la liquidación aparece como una transferencia saliente desde la dirección del agente. Para conciliar, compare los webhooks signed.success con la transacción on-chain del encabezado PAYMENT-RESPONSE.

Limitaciones de x402

Solo EVM. Los pagos se firman con datos tipados EIP-712, que Blockradar admite solo en cadenas EVM. Solana y otras redes x402 no EVM no son compatibles.
Solo pagos exact con EIP-3009. Los tokens con transferWithAuthorization, como USDC, funcionan. El método de transferencia permit2 y otros esquemas no están cubiertos.
Sin nanopagos de Circle Gateway. La opción de pagos por lotes de menos de un centavo de Circle no se ha probado con billeteras de Blockradar.

Mejores Prácticas

Aplique límites en su agente. Blockradar firma cualquier solicitud bien formada con una clave API válida. Defina límites por pago y por día en el código de su agente, y limite la exposición total con el saldo de la dirección del agente.
Una dirección por agente. Los presupuestos separados dejan claro qué agente gastó qué, y le permiten cortar a uno vaciando su dirección.
Verifique el precio antes de firmar. Compare amount con lo máximo que su agente debería pagar por ese recurso, y rechace cualquier monto superior.
Verifique el destinatario. Si su agente solo paga APIs conocidas, mantenga una lista de direcciones payTo permitidas.
Use metadata y webhooks. Etiquete las direcciones de los agentes con metadata y concilie los webhooks signed.success con la transacción on-chain de cada PAYMENT-RESPONSE.
Restrinja el acceso a la API. Acepte solicitudes a la API solo desde sus propios servidores con la Lista Blanca de IPs, para que una clave filtrada no pueda usarse en otro lugar.
Pruebe primero en Base Sepolia. Use una billetera de testnet, eip155:84532, y USDC de testnet de los faucets antes de gastar fondos reales.

Referencia API

Endpoint	Descripción
Sign Typed Data (Master Wallet)	Firmar una autorización de pago desde una billetera principal
Sign Typed Data (Child Address)	Firmar una autorización de pago desde una dirección hija
Generate Address	Crear una dirección dedicada para el presupuesto de un agente
Update Address	Activar o desactivar el barrido automático de una dirección

Comenzar

Billeteras

Recibir Pagos

Enviar Pagos

Convertir y Gestionar

Cumplimiento y Recuperación

Integraciones

Realizar Pagos con Agentes

Protocolos Compatibles

Requisitos Previos

Asigne al Agente Su Propio Presupuesto

Cómo Funciona x402

Pagar con x402

Opción 1: Usar el SDK cliente de x402

Opción 2: Construir el pago usted mismo

Paso 1: Leer los requisitos de pago

Paso 2: Firmar la autorización

Paso 3: Reintentar con el pago

Paso 4: Verificar la liquidación

Reglas de firma que suelen causar errores en las integraciones

Limitaciones de x402

Mejores Prácticas

Referencia API

​Protocolos Compatibles

​Requisitos Previos

​Asigne al Agente Su Propio Presupuesto

​Cómo Funciona x402

​Pagar con x402

​Opción 1: Usar el SDK cliente de x402

​Opción 2: Construir el pago usted mismo

​Paso 1: Leer los requisitos de pago

​Paso 2: Firmar la autorización

​Paso 3: Reintentar con el pago

​Paso 4: Verificar la liquidación

​Reglas de firma que suelen causar errores en las integraciones

​Limitaciones de x402

​Mejores Prácticas

​Referencia API

Protocolos Compatibles

Requisitos Previos

Asigne al Agente Su Propio Presupuesto

Cómo Funciona x402

Pagar con x402

Opción 1: Usar el SDK cliente de x402

Opción 2: Construir el pago usted mismo

Paso 1: Leer los requisitos de pago

Paso 2: Firmar la autorización

Paso 3: Reintentar con el pago

Paso 4: Verificar la liquidación

Reglas de firma que suelen causar errores en las integraciones

Limitaciones de x402

Mejores Prácticas

Referencia API