agent-payment-x402

Exécution de Paiements d'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 afin que les agents puissent payer des services externes, des API, ou d'autres agents sans risque de garde.

Quand l'Utiliser

À utiliser 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 skills cost-aware-llm-pipeline et security-review.

Arbre de Décision

Choisissez le chemin d'intégration en fonction du fait que votre agent achète l'accès à une API payante ou facture d'autres pour une API :

Besoin	Chemin Recommandé
L'agent paie une API basée sur 402 sur Base ou une autre chaîne prise en charge par agentwallet	Utilisez agentwallet-sdk comme serveur de paiement MCP avec une politique de dépenses stricte
L'agent paie une API basée sur 402 sur X Layer	Utilisez le protocole OKX Agent Payments depuis okx/onchainos-skills ; okx-x402-payment est un alias hérité déprécié
L'API TypeScript facture les agents	Utilisez la documentation du SDK vendeur OKX Payments TypeScript pour Express, Hono, Fastify, ou Next.js
L'API Go facture les agents	Utilisez la documentation du SDK vendeur OKX Payments Go pour Gin, Echo, ou net/http
L'API Rust facture les agents	Utilisez la documentation du SDK vendeur OKX Payments Rust pour Axum
L'API Java facture les agents	Utilisez la documentation du 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 actuel OKX Payments avant l'implémentation ; un guide vendeur Python peut ne pas être disponible

Réseaux Pris en Charge

• agentwallet-sdk : utilisez la documentation du package pour confirmer la couverture réseau actuelle avant la production. Base Sepolia est la valeur par défaut de développement la plus sûre ; le réseau principal Base est le chemin de production mentionné par le skill original.
• 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 packages de paiement et le comportement du facilitateur peuvent changer rapidement.

Comment Cela Fonctionne

Protocole x402

x402 étend HTTP 402 (Payment Required) 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 l'ensemble d'une session
• Destinataires sur liste blanche — 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 mutualisés, pas de risque de garde.

Intégration MCP

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

Note de sécurité : Épinglez toujours la version du package. Cet outil gère des clés privées — des 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	Historique d'audit de tous les paiements

Note : 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 de pré-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 X Layer, les paiements multi-parties (MPP), les paiements de session, les frais, et les flux de frais A2A.

Pour les flux côté acheteur (agent) :

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é déprécié, pas comme le skill 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 des paiements derrière un appel d'outil générique.

Pour les flux côté vendeur (API), récupérez le dernier guide spécifique à la langue 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 de documentations plus anciennes sans vérifier le dépôt OKX actuel. Les directives OKX actuelles utilisent okx-agent-payments-protocol comme répartiteur, et la documentation vendeur Java est maintenant disponible.

Exemples

Application du budget 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 package avant d'ajouter la config 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éfini — refus de démarrer le serveur de paiement");
  }

  // Connectez-vous au serveur MCP agentpay via le transport stdio.
  // Mettez sur liste blanche uniquement les variables d'environnement dont le serveur a besoin — 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: "orchestrator", 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éguer pas : ${JSON.stringify(policyResult.content)}`
    );
  }

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

// Crochet de pré-outil : application du budget avec échec en cas de problème, avec quatre chemins d'erreur distincts.
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
  // Chemin 1 : Rejeter l'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 injoignable — action bloquée : ${err}`);
  }

  // Chemin 3 : L'outil a renvoyé une erreur (par exemple, échec d'auth, 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 renvoyé 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} restants`
    );
  }
}

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 donnez jamais une dépense illimitée à un agent.
• Épinglez vos dépendances : Spécifiez toujours une version exacte dans votre configuration MCP (par exemple, [email protected]). Vérifiez l'intégrité du package avant de déployer en production.
• Pistes d'audit : Utilisez list_transactions dans les crochets de post-tâche pour journaliser ce qui a été dépensé et pourquoi.
• Échec en cas de problème : Si l'outil de paiement est injoignable, bloquez l'action payante — ne tombez pas en mode accès non mesuré.
• Associez avec security-review : Les outils de paiement sont à privilèges élevés. Appliquez le même niveau d'examen que pour un accès shell.
• Testez d'abord sur des testnets : Utilisez Base Sepolia pour le développement ; passez à Base mainnet 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
• OKX Payments SDKs : okx/payments — Intégrations vendeur TypeScript, Go, Rust et Java pour x402 sur X Layer
• Skill du protocole OKX Agent Payments : okx/onchainos-skills
• Aperçu OKX Payments : web3.okx.com/onchainos/dev-docs/payments/overview