> ## 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.

# x402 Micropayments

> Pay-per-API-call using the HTTP 402 protocol — session budgets, automatic negotiation, and settlement.

## What is x402?

x402 is a machine-to-machine payment protocol built around HTTP `402 Payment Required`. It enables AI agents to automatically pay for API access without human intervention. AgentWallex implements x402 v2 with EIP-3009 authorization payloads.

## x402 v2 Headers

The protocol uses three HTTP headers:

| Header              | Direction        | Purpose                         |
| ------------------- | ---------------- | ------------------------------- |
| `PAYMENT-REQUIRED`  | Server to Client | 402 challenge with pricing info |
| `PAYMENT-SIGNATURE` | Client to Server | Signed payment payload          |
| `PAYMENT-RESPONSE`  | Server to Client | Settlement confirmation         |

## Payment Flow

```
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="Agent requests a resource">
    The agent sends a standard HTTP request to a paid API endpoint.
  </Step>

  <Step title="Server returns 402">
    The API responds with HTTP 402 and a `PAYMENT-REQUIRED` header containing pricing details (amount, token, chain, payTo address).
  </Step>

  <Step title="Agent pays via AgentWallex">
    The agent sends the payment details to `POST /x402/pay`. AgentWallex evaluates policies and signs the payment.
  </Step>

  <Step title="Agent retries with payment proof">
    The agent retries the original request with the `PAYMENT-SIGNATURE` header attached.
  </Step>

  <Step title="Server verifies and responds">
    The API verifies the payment signature (via the AgentWallex facilitator) and returns the resource.
  </Step>
</Steps>

## Using x402 APIs

### Check if a URL Supports 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"}'
```

### Create a Session Budget

Sessions let you pre-authorize a spending budget for repeated API calls:

```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"]
  }'
```

### Trigger Payment Negotiation

```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"
  }'
```

The response includes `payment_info` with:

| Field        | Description               |
| ------------ | ------------------------- |
| `ledger_id`  | Internal ledger entry ID  |
| `amount`     | Payment amount            |
| `fee_amount` | Platform fee deducted     |
| `fee_rate`   | Fee percentage applied    |
| `token`      | Token used (e.g., USDC)   |
| `chain`      | Chain used for settlement |
| `status`     | Payment status            |

## SDK Integration

### Automatic HTTP Interceptor

The TypeScript SDK provides an interceptor that handles the full x402 flow automatically:

```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();
```

### Manual Flow

```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",
});
```

## For Service Providers

If you expose paid APIs, your server should return an x402 v2 challenge when payment is missing.

### Return 402 with PAYMENT-REQUIRED

Encode a JSON challenge (base64) into the `PAYMENT-REQUIRED` header:

```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
    }
  ]
}
```

### Verify and Settle

Use the AgentWallex facilitator endpoints:

```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
```

## Operational Defaults

| Parameter            | Value                                                   |
| -------------------- | ------------------------------------------------------- |
| Settlement interval  | 300 seconds                                             |
| Settlement threshold | \$10.00                                                 |
| Max settlement delay | 3,600 seconds                                           |
| Supported chains     | `eip155:84532`, `eip155:8453`, `eip155:1`, `eip155:137` |