agent-payment-x402

Execução de Pagamento por Agente (x402)

Permite que agentes de IA realizem pagamentos com políticas de controle de gastos integradas. Utiliza o protocolo de pagamento HTTP x402 e ferramentas MCP para que agentes possam pagar por serviços externos, APIs ou outros agentes sem risco de custódia.

Quando Usar

Use quando: seu agente precisar pagar por uma chamada de API, adquirir um serviço, liquidar com outro agente, impor limites de gastos por tarefa ou gerenciar uma carteira sem custódia. Combina naturalmente com as skills cost-aware-llm-pipeline e security-review.

Árvore de Decisão

Escolha o caminho de integração com base em se seu agente está comprando acesso a uma API paga ou cobrando outros por uma:

Necessidade	Caminho recomendado
Agente paga uma API com requisito 402 na Base ou em outra chain suportada pelo agentwallet	Use agentwallet-sdk como servidor de pagamento MCP com política de gastos restrita
Agente paga uma API com requisito 402 na X Layer	Use o OKX Agent Payments Protocol de okx/onchainos-skills; okx-x402-payment é um alias legado obsoleto
API em TypeScript cobra agentes	Use a documentação do SDK de vendedor OKX Payments TypeScript para Express, Hono, Fastify ou Next.js
API em Go cobra agentes	Use a documentação do SDK de vendedor OKX Payments Go para Gin, Echo ou net/http
API em Rust cobra agentes	Use a documentação do SDK de vendedor OKX Payments Rust para Axum
API em Java cobra agentes	Use a documentação do SDK de vendedor OKX Payments Java para Spring Boot 2/3, Java EE ou Jakarta
API em Python cobra agentes	Verifique o repositório atual do OKX Payments antes da implementação; um guia de vendedor Python pode não estar disponível

Redes Suportadas

• agentwallet-sdk: use a documentação do pacote para confirmar a cobertura de rede atual antes da produção. Base Sepolia é o padrão de desenvolvimento mais seguro; Base mainnet é o caminho de produção indicado pela skill original.
• OKX Payments / X Layer: a documentação atual do vendedor tem como alvo X Layer (eip155:196) e liquidação USDT0. Busque a documentação atual do SDK antes de gerar código de produção, pois pacotes de pagamento e comportamento do facilitador podem mudar rapidamente.

Como Funciona

Protocolo x402

O x402 estende o HTTP 402 (Payment Required) para um fluxo negociável entre máquinas. Quando um servidor retorna 402, a ferramenta de pagamento do agente negocia o preço, verifica o orçamento, assina uma transação e tenta novamente apenas dentro do limite de política e confirmação definido pelo orquestrador.

Controles de Gastos

Toda chamada de ferramenta de pagamento aplica uma SpendingPolicy:

• Orçamento por tarefa — gasto máximo para uma única ação do agente
• Orçamento por sessão — limite cumulativo em toda uma sessão
• Destinatários na lista de permissões — restringe quais endereços/serviços o agente pode pagar
• Limites de taxa — máximo de transações por minuto/hora

Carteiras Sem Custódia

Os agentes mantêm suas próprias chaves por meio de contas inteligentes ERC-4337. O orquestrador define a política antes da delegação; o agente só pode gastar dentro dos limites. Sem fundos pooled, sem risco de custódia.

Integração MCP

A camada de pagamento expõe ferramentas MCP padrão que se encaixam em qualquer configuração do Claude Code ou harness de agente.

Nota de segurança: Sempre fixe a versão do pacote. Esta ferramenta gerencia chaves privadas — instalações npx sem fixação introduzem risco de supply-chain.

Opção A: agentwallet-sdk (Base / multi-chain)

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

Ferramentas Disponíveis (chamáveis pelo agente)

Ferramenta	Propósito
get_balance	Verificar saldo da carteira do agente
send_payment	Enviar pagamento para endereço ou ENS
check_spending	Consultar orçamento restante
list_transactions	Trilha de auditoria de todos os pagamentos

Nota: A política de gastos é definida pelo orquestrador antes de delegar ao agente — não pelo próprio agente. Isso impede que agentes aumentem seus próprios limites de gastos. Configure a política via set_policy em sua camada de orquestração ou hook de pré-tarefa, nunca como uma ferramenta chamável pelo agente.

Opção B: OKX Agent Payments Protocol (X Layer)

Use este caminho para fluxos de x402 na X Layer, Multi-Party Payment (MPP), pagamento de sessão, cobrança e fluxos de cobrança A2A.

Para fluxos de agente do lado comprador:

1. Instale ou referencie o repositório atual okx/onchainos-skills.
2. Use skills/okx-agent-payments-protocol/SKILL.md como o despachante.
3. Trate skills/okx-x402-payment/SKILL.md como um alias de compatibilidade obsoleto, não como a skill canônica.
4. Exija confirmação explícita do usuário antes de verificações de status da carteira ou ações de pagamento. Não oculte a execução do pagamento por trás de uma chamada de ferramenta genérica.

Para fluxos de API do lado vendedor, busque o guia mais recente específico do idioma antes de gerar código:

Runtime	Guia atual
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

Não copie exemplos de documentações antigas sem verificar o repositório atual do OKX. A orientação atual do OKX usa okx-agent-payments-protocol como despachante, e a documentação do vendedor Java agora está disponível.

Exemplos

Aplicação de orçamento em um cliente MCP

Ao construir um orquestrador que chama o servidor MCP agentpay, aplique orçamentos antes de despachar chamadas de ferramentas pagas.

Pré-requisitos: Instale o pacote antes de adicionar a configuração MCP — npx sem -y solicitará confirmação em ambientes não interativos, fazendo com que o servidor trave: 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. Valide as credenciais antes de construir o transporte.
  //    Uma chave ausente deve falhar imediatamente — nunca permita que o subprocesso inicie sem autenticação.
  const walletKey = process.env.WALLET_PRIVATE_KEY;
  if (!walletKey) {
    throw new Error("WALLET_PRIVATE_KEY não definida — recusando iniciar servidor de pagamento");
  }

  // Conecte-se ao servidor MCP agentpay via transporte stdio.
  // Permita apenas as variáveis de ambiente que o servidor precisa — nunca encaminhe todo o process.env
  // para um subprocesso de terceiros que gerencia chaves privadas.
  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. Defina a política de gastos antes de delegar ao agente.
  //    Sempre verifique o sucesso — uma falha silenciosa significa que nenhum controle está ativo.
  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(
      `Falha ao definir política de gastos — não delegue: ${JSON.stringify(policyResult.content)}`
    );
  }

  // 3. Use preToolCheck antes de qualquer ação paga
  await preToolCheck(agentpay, 0.01);
}

// Hook de pré-ferramenta: aplicação de orçamento com falha fechada e quatro caminhos de erro distintos.
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
  // Caminho 1: Rejeitar entrada inválida (NaN/Infinity ignoram a comparação <)
  if (!Number.isFinite(apiCost) || apiCost < 0) {
    throw new Error(`apiCost inválido: ${apiCost} — ação bloqueada`);
  }

  // Caminho 2: Falha de transporte/conectividade
  let result;
  try {
    result = await agentpay.callTool({ name: "check_spending" });
  } catch (err) {
    throw new Error(`Serviço de pagamento inatingível — ação bloqueada: ${err}`);
  }

  // Caminho 3: Ferramenta retornou um erro (ex: falha de autenticação, carteira não inicializada)
  if (result.isError) {
    throw new Error(
      `check_spending falhou — ação bloqueada: ${JSON.stringify(result.content)}`
    );
  }

  // Caminho 4: Analisar e validar a forma da resposta
  let remaining: number;
  try {
    const parsed = JSON.parse(
      (result.content as Array<{ text: string }>)[0].text
    );
    if (!Number.isFinite(parsed?.remaining)) {
      throw new TypeError("campo 'remaining' ausente ou não finito");
    }
    remaining = parsed.remaining;
  } catch (err) {
    throw new Error(
      `check_spending retornou formato inesperado — ação bloqueada: ${err}`
    );
  }

  // Caminho 5: Orçamento excedido
  if (remaining < apiCost) {
    throw new Error(
      `Orçamento excedido: necessário $${apiCost} mas restam apenas $${remaining}`
    );
  }
}

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

Melhores Práticas

• Defina orçamentos antes da delegação: Ao gerar subagentes, anexe uma SpendingPolicy por meio de sua camada de orquestração. Nunca dê a um agente gastos ilimitados.
• Fixe suas dependências: Sempre especifique uma versão exata em sua configuração MCP (ex: [email protected]). Verifique a integridade do pacote antes de implantar em produção.
• Trilhas de auditoria: Use list_transactions em hooks de pós-tarefa para registrar o que foi gasto e por quê.
• Falha fechada: Se a ferramenta de pagamento estiver inacessível, bloqueie a ação paga — não recorra ao acesso não medido.
• Combine com security-review: Ferramentas de pagamento são de alto privilégio. Aplique o mesmo escrutínio que ao acesso ao shell.
• Teste primeiro em testnets: Use Base Sepolia para desenvolvimento; mude para Base mainnet em produção.

Referência de Produção

• npm: agentwallet-sdk
• Mesclado no NVIDIA NeMo Agent Toolkit: PR #17 — ferramenta de pagamento x402 para exemplos de agente da NVIDIA
• Especificação do protocolo: x402.org
• SDKs OKX Payments: okx/payments — integrações de vendedor TypeScript, Go, Rust e Java para x402 na X Layer
• Skill do OKX Agent Payments Protocol: okx/onchainos-skills
• Visão geral do OKX Payments: web3.okx.com/onchainos/dev-docs/payments/overview