agent-payment-x402

Execução de Pagamentos por Agente (x402)

Permite que agentes de IA façam pagamentos com controle de gastos baseado em políticas. 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 não custodial. Combina naturalmente com as habilidades 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 gate 402 na Base ou outra cadeia suportada pelo agentwallet	Use agentwallet-sdk como um servidor de pagamento MCP com política de gastos restrita
Agente paga uma API com gate 402 na X Layer	Use OKX Agent Payments Protocol de okx/onchainos-skills; okx-x402-payment é um alias legado obsoleto
API TypeScript cobra agentes	Use a documentação do SDK vendedor OKX Payments TypeScript para Express, Hono, Fastify ou Next.js
API Go cobra agentes	Use a documentação do SDK vendedor OKX Payments Go para Gin, Echo ou net/http
API Rust cobra agentes	Use a documentação do SDK vendedor OKX Payments Rust para Axum
API Java cobra agentes	Use a documentação do SDK vendedor OKX Payments Java para Spring Boot 2/3, Java EE ou Jakarta
API Python cobra agentes	Verifique o repositório atual do OKX Payments antes da implementação; um guia 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 os pacotes de pagamento e o comportamento do facilitador podem mudar rapidamente.

Como Funciona

Protocolo x402

x402 estende o HTTP 402 (Payment Required) em um fluxo negociável por máquina. 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

Cada chamada de ferramenta de pagamento impõe 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ão — restringe quais endereços/serviços o agente pode pagar
• Limites de taxa — máximo de transações por minuto/hora

Carteiras Não Custodiais

Os agentes mantêm suas próprias chaves através 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 em pool, 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 fixar a versão introduzem risco de supply-chain.

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

{
  "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 pré-tarefa, nunca como uma ferramenta chamável pelo agente.

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

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

Para fluxos de agente comprador:

1. Instale ou referencie o repositório atual okx/onchainos-skills.
2. Use skills/okx-agent-payments-protocol/SKILL.md como o dispatcher.
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 esconda a execução do pagamento por trás de uma chamada de ferramenta genérica.

Para fluxos de API 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 dispatcher, e a documentação do vendedor Java agora está disponível.

Exemplos

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

Ao construir um orquestrador que chama o servidor MCP agentpay, imponha 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 deixe o subprocesso iniciar sem autenticação.
  const walletKey = process.env.WALLET_PRIVATE_KEY;
  if (!walletKey) {
    throw new Error("WALLET_PRIVATE_KEY não está 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 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 pré-ferramenta: imposição de orçamento fail-closed com quatro caminhos de erro distintos.
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
  // Caminho 1: Rejeitar entrada inválida (NaN/Infinity contornam 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 inacessí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: preciso de $${apiCost} mas tenho apenas $${remaining} restantes`
    );
  }
}

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 através de sua camada de orquestração. Nunca dê a um agente gasto ilimitado.
• 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 pós-tarefa para registrar o que foi gasto e por quê.
• Fail closed: 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 o acesso ao shell.
• Teste com testnets primeiro: Use Base Sepolia para desenvolvimento; mude para Base mainnet para 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 vendedor TypeScript, Go, Rust e Java para x402 na X Layer
• Skill OKX Agent Payments Protocol: okx/onchainos-skills
• Visão geral OKX Payments: web3.okx.com/onchainos/dev-docs/payments/overview