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.
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
Requisitos Previos
1
Clave API
Obtenga su clave API desde el Panel de Blockradar. Diríjase a Developers para generar una.
2
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.
3
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
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.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.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 HTTP402 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.
1
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.2
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.3
El agente reintenta con la firma
El agente repite la solicitud con el pago firmado en el encabezado
PAYMENT-SIGNATURE.4
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.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.
JavaScript
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 respuesta402 incluye un encabezado PAYMENT-REQUIRED codificado en base64. Una vez decodificado, se ve así:
accepts que su billetera pueda pagar:
schemeesexact.networkes la cadena de la billetera.eip155:8453es Base mainnet.extra.assetTransferMethodestá ausente o eseip3009. El métodopermit2requiere 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 elTransferWithAuthorization a partir de los requisitos y fírmelo desde la dirección del agente:
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 encabezadoPAYMENT-SIGNATURE en la misma solicitud:
JavaScript
Paso 4: Verificar la liquidación
Una respuesta exitosa incluye un encabezadoPAYMENT-RESPONSE codificado en base64:
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
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 deeip155:<chainId>. Base es el chain ID8453; Base Sepolia es84532. - El campo del monto es
maxAmountRequired, noamount. - El pago va en el encabezado
X-PAYMENTcomo JSON codificado en base64 conx402Version: 1,scheme,networky el mismo objetopayload, y la liquidación vuelve enX-PAYMENT-RESPONSE.
Reglas de firma que suelen causar errores en las integraciones
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.
Cómo Funciona MPP
MPP (Machine Payments Protocol) es un protocolo abierto para pagar por solicitud a través de HTTP. Su cargo EVM funciona como x402: el agente firma con Blockradar el mismoTransferWithAuthorization de EIP-3009, el servidor lo liquida en cadena y paga el gas, y la billetera del agente necesita USDC pero no gas. Lo que cambia es el envoltorio de la firma:
Pagar con MPP
El cliente oficialmppx gestiona el intercambio de MPP, incluido el nonce vinculado al desafío, y firma credenciales authorization de EIP-3009. Recibe una cuenta de viem, por lo que el adaptador siguiente expone como tal el endpoint de datos tipados de Blockradar. La solicitud de firma que envía es la misma que para x402.
JavaScript
maxAmount es un límite por pago que aplica el cliente: por encima de él, mppx rechaza el pago antes de llamar a Blockradar, así que no se firma nada. Blockradar no limita lo que firma, así que configúrelo.
Para conciliar, compare los webhooks signed.success con el reference de cada Payment-Receipt, que es el hash en cadena de la transacción.
Construir el pago MPP usted mismo
Construir el pago MPP usted mismo
La solicitud de firma a Blockradar es la del Paso 2, con tres diferencias:
- Lea el desafío del encabezado
WWW-Authenticate: Payment. Su parámetrorequestes JSON codificado en base64url conamount,currency,recipientymethodDetails.chainId. - Establezca
nonceenkeccak256(abi.encodePacked(challenge.id, challenge.realm))yvalidBeforeen la horaexpiresdel desafío. Tomedomain.nameydomain.versiondel contrato del token. - Envíe la credencial como
Authorization: Payment <base64url JSON>, con el desafío devuelto tal cual y unpayloadcontype: "authorization"más los campos firmados.
Limitaciones
- Solo EVM. Los pagos se firman con datos tipados EIP-712, que Blockradar admite solo en cadenas EVM. Solana y otras redes no EVM no son compatibles.
- Solo pagos con EIP-3009. Los tokens con
transferWithAuthorization, como USDC, funcionan. El método de transferenciapermit2de x402 y las credencialespermit2,transactionyhashde MPP no son compatibles. - MPP en Tempo llegará pronto. Hasta entonces, los cargos en Tempo y las sesiones de MPP no son compatibles.
- Sin nanopagos de Circle Gateway. La opción de pagos por lotes de menos de un centavo de Circle no es compatible.
- Pagar a otro negocio de Blockradar. Cuando el vendedor también recibe en una dirección de Blockradar, el pago saliente del agente normalmente no aparece en su historial de transacciones y no dispara ningún webhook. Los saldos son correctos. Concilie con el hash de la transacción en
PAYMENT-RESPONSEoPayment-Receipt.
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 (con MPP,
maxAmountcubre el límite por pago), 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
amountcon 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(x402) orecipient(MPP) permitidas. - Use
metadatay webhooks. Etiquete las direcciones de los agentes conmetadatay concilie los webhookssigned.successcon la transacción on-chain de cadaPAYMENT-RESPONSEoPayment-Receipt. - 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.

