> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Realizar Pagos con Agentes

> Permita que los agentes de IA paguen APIs en stablecoins desde una billetera de Blockradar, sin que la clave privada salga de Blockradar

<Note>
  En resumen<br />
  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](/es/essentials/signing#firma-de-datos-tipados-solo-evm) que usted ya tiene.
</Note>

## Protocolos Compatibles

| Protocolo | Redes y tokens |
| - | - |
| [x402](https://www.x402.org) | Cadenas EVM, USDC (EIP-3009) |

<Tip>
  ¿Vende a agentes? Consulte [Aceptar Pagos de Agentes](/es/use-cases/accept-agent-payments).
</Tip>

## Requisitos Previos

<Steps>
  <Step title="Clave API">
    Obtenga su clave API desde el [Panel de Blockradar](https://dashboard.blockradar.co). Diríjase a **Developers** para generar una.
  </Step>

  <Step title="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](/es/guides/create-master-wallet)). Los pagos de agentes a través de Blockradar son solo EVM.
  </Step>

  <Step title="USDC Habilitado">
    Habilite USDC en la billetera para que se rastreen los saldos y los depósitos. Consulte [Gestión de Activos](/es/use-cases/asset-management).
  </Step>
</Steps>

## Asigne al Agente Su Propio Presupuesto

<Warning>
  La firma no tiene un límite de gasto por pago<br />
  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.
</Warning>

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.

<CodeGroup>
  ```bash Curl theme={null}
  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"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

<Note>
  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.
</Note>

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](/es/use-cases/checkout#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](https://www.x402.org) 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.

<Steps>
  <Step title="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`.
  </Step>

  <Step title="Blockradar firma el pago">
    El agente convierte una de esas opciones en un `TransferWithAuthorization` de [EIP-3009](https://eips.ethereum.org/EIPS/eip-3009) y lo firma con el endpoint de datos tipados de Blockradar. Todavía no se envía nada en cadena.
  </Step>

  <Step title="El agente reintenta con la firma">
    El agente repite la solicitud con el pago firmado en el encabezado `PAYMENT-SIGNATURE`.
  </Step>

  <Step title="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`.
  </Step>
</Steps>

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](#asigne-al-agente-su-propio-presupuesto).

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

El cliente oficial [`@x402/fetch`](https://www.npmjs.com/package/@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.

```bash theme={null}
npm install @x402/fetch @x402/evm
```

```javascript JavaScript theme={null}
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í:

```json theme={null}
{
  "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 |

<CodeGroup>
  ```bash Curl theme={null}
  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"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  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;
  ```
</CodeGroup>

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](/es/essentials/signing#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 JavaScript theme={null}
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:

```json theme={null}
{
  "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`.

<Accordion title="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.
</Accordion>

### 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](/es/essentials/signing#eventos-de-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](/es/use-cases/ip-whitelist), 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](/es/use-cases/supported-assets) antes de gastar fondos reales.

***

## Referencia API

| Endpoint | Descripción |
| - | - |
| [Sign Typed Data (Master Wallet)](/es/api-reference/signing/master-wallet-typed-data) | Firmar una autorización de pago desde una billetera principal |
| [Sign Typed Data (Child Address)](/es/api-reference/signing/child-address-typed-data) | Firmar una autorización de pago desde una dirección hija |
| [Generate Address](/es/api-reference/addresses/generate-address) | Crear una dirección dedicada para el presupuesto de un agente |
| [Update Address](/es/api-reference/addresses/update-address) | Activar o desactivar el barrido automático de una dirección |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.