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

# Micropagos x402

> Pago por llamada a API mediante el protocolo HTTP 402 — presupuestos de sesión, negociación automática y liquidación.

## ¿Qué es x402?

x402 es un protocolo de pagos máquina a máquina construido alrededor de HTTP `402 Payment Required`. Permite a los agentes de IA pagar automáticamente por el acceso a APIs sin intervención humana. AgentWallex implementa x402 v2 con payloads de autorización EIP-3009.

## Encabezados x402 v2

El protocolo utiliza tres encabezados HTTP:

| Encabezado          | Dirección          | Propósito                              |
| ------------------- | ------------------ | -------------------------------------- |
| `PAYMENT-REQUIRED`  | Servidor a cliente | Desafío 402 con información de precios |
| `PAYMENT-SIGNATURE` | Cliente a servidor | Payload de pago firmado                |
| `PAYMENT-RESPONSE`  | Servidor a cliente | Confirmación de liquidación            |

## Flujo de pago

```
Client Agent               Paid API               AgentWallex
    |                        |                         |
    |-- GET /resource ------>|                         |
    |<-- 402 + PAYMENT-REQUIRED                        |
    |                        |                         |
    |-- POST /api/v1/x402/pay -----------------------> |
    |                        |     (sign + policy)     |
    |<-- payment_info        |                         |
    |                        |                         |
    |-- GET /resource + PAYMENT-SIGNATURE -----------> |
    |<-- 200 + PAYMENT-RESPONSE                        |
```

<Steps>
  <Step title="El agente solicita un recurso">
    El agente envía una solicitud HTTP estándar a un endpoint de API de pago.
  </Step>

  <Step title="El servidor devuelve 402">
    La API responde con HTTP 402 y un encabezado `PAYMENT-REQUIRED` que contiene detalles de precios (monto, token, cadena, dirección payTo).
  </Step>

  <Step title="El agente paga mediante AgentWallex">
    El agente envía los detalles del pago a `POST /x402/pay`. AgentWallex evalúa las políticas y firma el pago.
  </Step>

  <Step title="El agente reintenta con prueba de pago">
    El agente reintenta la solicitud original con el encabezado `PAYMENT-SIGNATURE` adjunto.
  </Step>

  <Step title="El servidor verifica y responde">
    La API verifica la firma de pago (mediante el facilitador de AgentWallex) y devuelve el recurso.
  </Step>
</Steps>

## Uso de APIs x402

### Verificar si una URL soporta x402

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/x402/check \
  -H "X-API-Key: awx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://paid-api.example.com/v1/data"}'
```

### Crear un presupuesto de sesión

Las sesiones le permiten preautorizar un presupuesto de gasto para llamadas repetidas a la API:

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/x402/sessions \
  -H "X-API-Key: awx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_uuid",
    "budget_limit": "100.00",
    "chain": "eip155:84532",
    "ttl_seconds": 3600,
    "allowed_urls": ["https://paid-api.example.com/v1/data"]
  }'
```

### Activar negociación de pago

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/x402/pay \
  -H "X-API-Key: awx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_uuid",
    "target_url": "https://paid-api.example.com/v1/data",
    "session_id": "optional_session_uuid",
    "chain": "eip155:84532"
  }'
```

La respuesta incluye `payment_info` con:

| Campo        | Descripción                           |
| ------------ | ------------------------------------- |
| `ledger_id`  | ID de entrada del libro mayor interno |
| `amount`     | Monto del pago                        |
| `fee_amount` | Tarifa de plataforma deducida         |
| `fee_rate`   | Porcentaje de tarifa aplicado         |
| `token`      | Token utilizado (por ejemplo, USDC)   |
| `chain`      | Cadena utilizada para la liquidación  |
| `status`     | Estado del pago                       |

## Integración con SDK

### Interceptor HTTP automático

El SDK de TypeScript proporciona un interceptor que maneja el flujo completo x402 automáticamente:

```typescript theme={null}
const fetchWithPayment = aw.x402.httpInterceptor({
  agentId: "agent_abc123",
  chain: "eip155:84532",
});

// This automatically handles 402 challenges
const response = await fetchWithPayment("https://paid-api.example.com/v1/data");
const data = await response.json();
```

### Flujo manual

```typescript theme={null}
// 1. Create a session budget
const session = await aw.x402.createSession({
  agentId: "agent_abc123",
  budgetLimit: "100.00",
  chain: "eip155:84532",
  ttlSeconds: 3600,
  allowedUrls: ["https://paid-api.example.com/v1/data"],
});

// 2. Pay for an API call
const result = await aw.x402.pay({
  agentId: "agent_abc123",
  targetUrl: "https://paid-api.example.com/v1/data",
  sessionId: session.id,
  chain: "eip155:84532",
});

// 3. Or pay using the session directly
await aw.x402.sessionPay(session.id, {
  targetUrl: "https://paid-api.example.com/v1/data",
});
```

## Para proveedores de servicios

Si usted expone APIs de pago, su servidor debe devolver un desafío x402 v2 cuando falte el pago.

### Devolver 402 con PAYMENT-REQUIRED

Codifique un desafío JSON (base64) en el encabezado `PAYMENT-REQUIRED`:

```json theme={null}
{
  "x402Version": 2,
  "resource": "https://your-api.com/v1/data",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "0.10",
      "asset": "USDC",
      "payTo": "0xYourAddress",
      "maxTimeoutSeconds": 300
    }
  ]
}
```

### Verificar y liquidar

Use los endpoints del facilitador de AgentWallex:

```bash theme={null}
# Verify a payment signature
POST /api/v1/x402/facilitator/verify

# Settle a verified payment
POST /api/v1/x402/facilitator/settle

# Query supported chains
GET /api/v1/x402/facilitator/supported
```

## Valores operativos predeterminados

| Parámetro                     | Valor                                                   |
| ----------------------------- | ------------------------------------------------------- |
| Intervalo de liquidación      | 300 segundos                                            |
| Umbral de liquidación         | \$10.00                                                 |
| Retraso máximo de liquidación | 3,600 segundos                                          |
| Cadenas compatibles           | `eip155:84532`, `eip155:8453`, `eip155:1`, `eip155:137` |