agent-payment-x402

Exécution de Paiement Agent (x402)

Permet aux agents IA d'effectuer des paiements régis par des politiques avec des contrôles de dépenses intégrés. Utilise le protocole de paiement HTTP x402 et les outils MCP pour que les agents puissent payer des services externes, des API ou d'autres agents sans risque de garde.

Quand l'utiliser

Utilisez-la lorsque : votre agent doit payer un appel API, acheter un service, régler avec un autre agent, appliquer des limites de dépenses par tâche, ou gérer un portefeuille non-custodial. Se marie naturellement avec les compétences cost-aware-llm-pipeline et security-review.

Arbre de décision

Choisissez le chemin d'intégration selon que votre agent achète un accès à une API payante ou facture d'autres pour une API :

Besoin	Chemin recommandé
L'agent paie une API 402-gated sur Base ou une autre chaîne supportée par agentwallet	Utilisez agentwallet-sdk comme serveur de paiement MCP avec une politique de dépenses stricte
L'agent paie une API 402-gated sur X Layer	Utilisez le protocole OKX Agent Payments depuis okx/onchainos-skills ; okx-x402-payment est un alias hérité obsolète
L'API TypeScript facture les agents	Utilisez la documentation SDK vendeur OKX Payments TypeScript pour Express, Hono, Fastify, ou Next.js
L'API Go facture les agents	Utilisez la documentation SDK vendeur OKX Payments Go pour Gin, Echo, ou net/http
L'API Rust facture les agents	Utilisez la documentation SDK vendeur OKX Payments Rust pour Axum
L'API Java facture les agents	Utilisez la documentation SDK vendeur OKX Payments Java pour Spring Boot 2/3, Java EE, ou Jakarta
L'API Python facture les agents	Vérifiez le dépôt OKX Payments actuel avant l'implémentation ; un guide vendeur Python peut ne pas être disponible

Réseaux supportés

• agentwallet-sdk : utilisez la documentation du paquet pour confirmer la couverture réseau actuelle avant la production. Base Sepolia est la valeur par défaut la plus sûre pour le développement ; le mainnet Base est le chemin de production indiqué par la compétence originale.
• OKX Payments / X Layer : la documentation vendeur actuelle cible X Layer (eip155:196) et le règlement USDT0. Récupérez la documentation SDK actuelle avant de générer du code de production car les paquets de paiement et le comportement du facilitateur peuvent changer rapidement.

Comment ça fonctionne

Protocole x402

x402 étend HTTP 402 (Paiement Requis) en un flux négociable par machine. Lorsqu'un serveur renvoie 402, l'outil de paiement de l'agent négocie le prix, vérifie le budget, signe une transaction, et réessaie uniquement à l'intérieur de la limite de politique et de confirmation définie par l'orchestrateur.

Contrôles de dépenses

Chaque appel d'outil de paiement applique une SpendingPolicy :

• Budget par tâche — dépense maximale pour une seule action d'agent
• Budget par session — limite cumulative sur toute une session
• Destinataires autorisés — restreindre les adresses/services que l'agent peut payer
• Limites de taux — nombre maximal de transactions par minute/heure

Portefeuilles non-custodiaux

Les agents détiennent leurs propres clés via des comptes intelligents ERC-4337. L'orchestrateur définit la politique avant la délégation ; l'agent ne peut dépenser que dans les limites. Pas de fonds mis en commun, aucun risque de garde.

Intégration MCP

La couche de paiement expose des outils MCP standards qui s'intègrent dans toute configuration Claude Code ou harnais d'agent.

Note de sécurité : Épinglez toujours la version du paquet. Cet outil gère des clés privées — les installations npx non épinglées introduisent un risque de chaîne d'approvisionnement.

Option A : agentwallet-sdk (Base / multi-chaîne)

{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["[email protected]"]
    }
  }
}

Outils disponibles (appelables par l'agent)

Outil	Objectif
get_balance	Vérifier le solde du portefeuille de l'agent
send_payment	Envoyer un paiement à une adresse ou un ENS
check_spending	Interroger le budget restant
list_transactions	Piste d'audit de tous les paiements

Remarque : La politique de dépenses est définie par l'orchestrateur avant de déléguer à l'agent — pas par l'agent lui-même. Cela empêche les agents d'augmenter leurs propres limites de dépenses. Configurez la politique via set_policy dans votre couche d'orchestration ou un crochet avant tâche, jamais comme un outil appelable par l'agent.

Option B : Protocole OKX Agent Payments (X Layer)

Utilisez ce chemin pour les flux x402, Paiement Multi-Partie (MPP), paiement de session, charge, et charge A2A sur X Layer.

Pour les flux côté acheteur :

1. Installez ou référencez le dépôt actuel okx/onchainos-skills.
2. Utilisez skills/okx-agent-payments-protocol/SKILL.md comme répartiteur.
3. Traitez skills/okx-x402-payment/SKILL.md comme un alias de compatibilité obsolète, pas comme la compétence canonique.
4. Exigez une confirmation explicite de l'utilisateur avant les vérifications de statut du portefeuille ou les actions de paiement. Ne cachez pas l'exécution du paiement derrière un appel d'outil générique.

Pour les flux côté vendeur, récupérez le guide spécifique au langage le plus récent avant de générer du code :

Runtime	Guide actuel
TypeScript	https://raw.githubusercontent.com/okx/payments/main/typescript/SELLER.md
Go	https://raw.githubusercontent.com/okx/payments/main/go/x402/SELLER.md
Rust	https://raw.githubusercontent.com/okx/payments/main/rust/x402/SELLER.md
Java	https://raw.githubusercontent.com/okx/payments/main/java/SELLER.md

Ne copiez pas d'exemples d'anciennes documentations sans vérifier le dépôt OKX actuel. Les instructions actuelles d'OKX utilisent okx-agent-payments-protocol comme répartiteur, et la documentation vendeur Java est désormais disponible.

Exemples

Application des budgets dans un client MCP

Lors de la construction d'un orchestrateur qui appelle le serveur MCP agentpay, appliquez les budgets avant d'envoyer des appels d'outils payants.

Prérequis : Installez le paquet avant d'ajouter la configuration MCP — npx sans -y demandera une confirmation dans les environnements non interactifs, ce qui fera planter le serveur : npm install -g [email protected]

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() {
  // 1. Validez les identifiants avant de construire le transport.
  //    Une clé manquante doit échouer immédiatement — ne laissez jamais le sous-processus démarrer sans authentification.
  const walletKey = process.env.WALLET_PRIVATE_KEY;
  if (!walletKey) {
    throw new Error("WALLET_PRIVATE_KEY n'est pas définie — refus de démarrer le serveur de paiement");
  }

  // Connectez-vous au serveur MCP agentpay via le transport stdio.
  // Autorisez uniquement les variables d'environnement nécessaires au serveur — ne transmettez jamais tout process.env
  // à un sous-processus tiers qui gère des clés privées.
  const transport = new StdioClientTransport({
    command: "npx",
    args: ["[email protected]"],
    env: {
      PATH: process.env.PATH ?? "",
      NODE_ENV: process.env.NODE_ENV ?? "production",
      WALLET_PRIVATE_KEY: walletKey,
    },
  });
  const agentpay = new Client({ name: "orchestrateur", version: "1.0.0" });
  await agentpay.connect(transport);

  // 2. Définissez la politique de dépenses avant de déléguer à l'agent.
  //    Vérifiez toujours le succès — un échec silencieux signifie qu'aucun contrôle n'est actif.
  const policyResult = await agentpay.callTool({
    name: "set_policy",
    arguments: {
      per_task_budget: 0.50,
      per_session_budget: 5.00,
      allowlisted_recipients: ["api.example.com"],
    },
  });
  if (policyResult.isError) {
    throw new Error(
      `Échec de la définition de la politique de dépenses — ne déléguez pas : ${JSON.stringify(policyResult.content)}`
    );
  }

  // 3. Utilisez preToolCheck avant toute action payante
  await preToolCheck(agentpay, 0.01);
}

// Crochet avant outil : application du budget en échec sécurisé avec quatre chemins d'erreur distincts.
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
  // Chemin 1 : Rejeter une entrée invalide (NaN/Infinity contourne la comparaison <)
  if (!Number.isFinite(apiCost) || apiCost < 0) {
    throw new Error(`apiCost invalide : ${apiCost} — action bloquée`);
  }

  // Chemin 2 : Échec de transport/connectivité
  let result;
  try {
    result = await agentpay.callTool({ name: "check_spending" });
  } catch (err) {
    throw new Error(`Service de paiement inaccessible — action bloquée : ${err}`);
  }

  // Chemin 3 : L'outil a retourné une erreur (par ex., échec d'authentification, portefeuille non initialisé)
  if (result.isError) {
    throw new Error(
      `check_spending a échoué — action bloquée : ${JSON.stringify(result.content)}`
    );
  }

  // Chemin 4 : Analyser et valider la forme de la réponse
  let remaining: number;
  try {
    const parsed = JSON.parse(
      (result.content as Array<{ text: string }>)[0].text
    );
    if (!Number.isFinite(parsed?.remaining)) {
      throw new TypeError("champ 'remaining' manquant ou non fini");
    }
    remaining = parsed.remaining;
  } catch (err) {
    throw new Error(
      `check_spending a retourné un format inattendu — action bloquée : ${err}`
    );
  }

  // Chemin 5 : Budget dépassé
  if (remaining < apiCost) {
    throw new Error(
      `Budget dépassé : besoin de $${apiCost} mais seulement $${remaining} restant`
    );
  }
}

main().catch((err) => {
  console.error(err);
  process.exitCode = 1;
});

Meilleures pratiques

• Définissez les budgets avant la délégation : Lors de la création de sous-agents, attachez une SpendingPolicy via votre couche d'orchestration. Ne laissez jamais un agent avoir une dépense illimitée.
• Épinglez vos dépendances : Spécifiez toujours une version exacte dans votre configuration MCP (par ex., [email protected]). Vérifiez l'intégrité du paquet avant de déployer en production.
• Pistes d'audit : Utilisez list_transactions dans les crochets post-tâche pour journaliser ce qui a été dépensé et pourquoi.
• Échec sécurisé : Si l'outil de paiement est inaccessible, bloquez l'action payante — ne tombez pas en arrière sur un accès non mesuré.
• Associez à security-review : Les outils de paiement sont à haute privilège. Appliquez le même niveau d'examen qu'un accès shell.
• Testez d'abord sur les testnets : Utilisez Base Sepolia pour le développement ; passez au mainnet Base pour la production.

Référence de production

• npm : agentwallet-sdk
• Fusionné dans NVIDIA NeMo Agent Toolkit : PR #17 — outil de paiement x402 pour les exemples d'agents NVIDIA
• Spécification du protocole : x402.org
• SDK OKX Payments : okx/payments — intégrations vendeur TypeScript, Go, Rust et Java pour X Layer x402
• Compétence protocole OKX Agent Payments : okx/onchainos-skills
• Aperçu OKX Payments : web3.okx.com/onchainos/dev-docs/payments/overview