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

# Micropaiements x402

> Paiement par appel d'API via le protocole HTTP 402 — budgets de session, negociation automatique et reglement.

## Qu'est-ce que x402 ?

x402 est un protocole de paiement machine-a-machine construit autour du HTTP `402 Payment Required`. Il permet aux agents IA de payer automatiquement l'acces aux API sans intervention humaine. AgentWallex implemente x402 v2 avec des charges utiles d'autorisation EIP-3009.

## En-tetes x402 v2

Le protocole utilise trois en-tetes HTTP :

| En-tete             | Direction           | Objectif                                        |
| ------------------- | ------------------- | ----------------------------------------------- |
| `PAYMENT-REQUIRED`  | Serveur vers Client | Challenge 402 avec informations de tarification |
| `PAYMENT-SIGNATURE` | Client vers Serveur | Charge utile de paiement signee                 |
| `PAYMENT-RESPONSE`  | Serveur vers Client | Confirmation de reglement                       |

## Flux de paiement

```
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="L'agent demande une ressource">
    L'agent envoie une requete HTTP standard a un point de terminaison d'API payant.
  </Step>

  <Step title="Le serveur renvoie 402">
    L'API repond avec HTTP 402 et un en-tete `PAYMENT-REQUIRED` contenant les details de tarification (montant, jeton, chaine, adresse payTo).
  </Step>

  <Step title="L'agent paie via AgentWallex">
    L'agent envoie les details de paiement a `POST /x402/pay`. AgentWallex evalue les politiques et signe le paiement.
  </Step>

  <Step title="L'agent retente avec la preuve de paiement">
    L'agent retente la requete originale avec l'en-tete `PAYMENT-SIGNATURE` joint.
  </Step>

  <Step title="Le serveur verifie et repond">
    L'API verifie la signature de paiement (via le facilitateur AgentWallex) et renvoie la ressource.
  </Step>
</Steps>

## Utilisation des API x402

### Verifier si une URL supporte 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"}'
```

### Creer un budget de session

Les sessions vous permettent de pre-autoriser un budget de depenses pour des appels d'API repetes :

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

### Declencher la negociation de paiement

```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 reponse inclut `payment_info` avec :

| Champ        | Description                       |
| ------------ | --------------------------------- |
| `ledger_id`  | ID d'entree du registre interne   |
| `amount`     | Montant du paiement               |
| `fee_amount` | Frais de plateforme deduits       |
| `fee_rate`   | Pourcentage de frais applique     |
| `token`      | Jeton utilise (par ex., USDC)     |
| `chain`      | Chaine utilisee pour le reglement |
| `status`     | Statut du paiement                |

## Integration SDK

### Intercepteur HTTP automatique

Le SDK TypeScript fournit un intercepteur qui gere automatiquement le flux x402 complet :

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

### Flux manuel

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

## Pour les fournisseurs de services

Si vous exposez des API payantes, votre serveur doit renvoyer un challenge x402 v2 lorsque le paiement est manquant.

### Renvoyer 402 avec PAYMENT-REQUIRED

Encodez un challenge JSON (base64) dans l'en-tete `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
    }
  ]
}
```

### Verifier et regler

Utilisez les points de terminaison du facilitateur 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
```

## Parametres operationnels par defaut

| Parametre                  | Valeur                                                  |
| -------------------------- | ------------------------------------------------------- |
| Intervalle de reglement    | 300 secondes                                            |
| Seuil de reglement         | 10,00 \$                                                |
| Delai maximal de reglement | 3 600 secondes                                          |
| Chaines supportees         | `eip155:84532`, `eip155:8453`, `eip155:1`, `eip155:137` |