callx402
Diagnóstico de pagamento x402 somente leitura: diagnosticar, evidenciar, explicar, recuperar, resolver, status. Zero dependências
Documentação
Payload — Infraestrutura de desenvolvedor para x402, pagamentos de agentes e receita programável. PAYLOAD → VEYLINE (carro-chefe) → CALLX402 (camada de ação) → REVRULE (separado) → produtos para desenvolvedores → utilitários gratuitos. Este repositório: callx402 by Payload — a camada de ação universal para a infraestrutura x402 da Veyline.
Desenvolvido pela Veyline. Quando o x402 falha, chame o callx402.
O callx402 é a camada de ação universal para a infraestrutura x402 da Veyline. Diga o que precisa ser feito em linguagem simples (ou acesse um endpoint HTTP) e o callx402 encaminha para o sistema de produção que faz o trabalho real: diagnosticar um pagamento x402 quebrado, resgatar uma transação com falha, rotear um trabalho de agente para o caminho viável mais barato, resolver o estado de liquidação com base em evidências on-chain ou executar sob um orçamento explícito com regras de segurança de falha fechada.
Por que existe: falhas de x402 são caras e opacas. Uma tentativa de liquidação termina em settlement_pending e ninguém sabe se o dinheiro foi movido. Uma resposta 402 que sua carteira interpreta mal. Uma nova tentativa que assina uma segunda autorização para a mesma intenção e paga duas vezes. O callx402 existe exatamente para esses momentos: diagnose fixa a falha em um estágio, rescue faz a triagem do incidente, resolve resolve a questão com base em evidências, route encontra o caminho viável mais barato, execute executa sob um orçamento rígido.
Experimente (dois minutos, sem configuração, sem conta):
npm install -g callx402
callx402 status
callx402 'complete this job for under $1'
status imprime um relatório honesto de acessibilidade por subsistema, sem precisar de credenciais. A linha de intenção analisa e planeja sua solicitação e depois para antes de executar qualquer coisa: sem um endpoint de ferramenta ativo conectado, ela informa "nenhuma rota executável disponível", então nenhum dinheiro é movido. (Use aspas simples: em aspas duplas, seu shell consumiria o $1.)
Verificações gratuitas somente leitura contra o trilho Payload ativo:
curl https://payload-rail.fly.dev/v1/callx402/actions
curl 'https://payload-rail.fly.dev/v1/callx402/quote?action=diagnose'
O primeiro retorna o catálogo de ações pagas com preços; o segundo retorna uma cotação de preço gratuita para uma ação. Invocar uma ação de trilho é pago por ação via checkout (veja https://payloadhq.github.io/agents.json); estes comandos nunca pagam nada.
Se isso economizar uma sessão de depuração, dê uma estrela no repositório e continue lendo.
Servidor MCP: conecte-se em 60 segundos
Este repositório inclui um servidor MCP somente leitura, sem dependências (mcp/index.js, apenas stdlib do node, transporte stdio) expondo seis ferramentas de diagnóstico x402_*. Nada aqui cobra, executa, tenta novamente ou reembolsa.
git clone https://github.com/Payloadhq/callx402
# no npm install needed for the MCP server
Adicione este bloco à configuração do seu cliente MCP (substitua o caminho) e reinicie o cliente:
| Cliente | Arquivo de configuração |
|---|---|
| Claude Desktop | claude_desktop_config.json (~/Library/Application Support/Claude/ no macOS, %APPDATA%\Claude\ no Windows) |
| Cursor | ~/.cursor/mcp.json (escopo do usuário) ou .cursor/mcp.json (escopo do projeto) |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
{
"mcpServers": {
"callx402": {
"command": "node",
"args": ["/absolute/path/to/callx402/mcp/index.js"]
}
}
}
Peça ao cliente para listar suas ferramentas MCP: as seis ferramentas x402_* devem aparecer. Notas por cliente e o handshake bruto de teste stdio:
integrations/mcp-clients/.
Observação: x402_status funciona sem nenhuma configuração. As outras cinco ferramentas despacham para a árvore de subsistemas v2.0.0, então relatam subsystem_unreachable até que CALLX402_V2_ROOT aponte para a árvore (veja "Comandos completos de subsistema" acima) e a flag correspondente esteja habilitada.
O relacionamento
- PAYLOAD = a empresa controladora.
- VEYLINE = infraestrutura de produção para x402 + MCP. A marca carro-chefe.
- CALLX402 BY PAYLOAD = a camada de resposta/ação x402, desenvolvida pela Veyline. A ação de entrada na infraestrutura de produção da Veyline, não o nome carro-chefe. Nada aqui renomeia a Veyline.
Caminho de descoberta: um desenvolvedor que procura por x402 encontra o callx402, o usa e conhece a Veyline. A Payload não é afiliada à x402 Foundation.
O que faz
- Diagnosticar uma falha de x402 ou MCP
- Resgatar uma transação com falha (protegido por autenticação)
- Roteirizar um trabalho de agente pago para o caminho viável mais barato
- Resolver o estado de liquidação com base em evidências on-chain
- Executar sob um orçamento explícito, com regras de segurança de falha fechada
Linguagem de uso comportamental (não alegações de marca):
- "Precisa diagnosticar x402? callx402."
- "Precisa resgatar uma transação? callx402."
- "Precisa roteirizar um trabalho de agente pago? callx402."
- "Precisa de certeza de liquidação? callx402."
- "Precisa executar sob um orçamento? callx402."
Início rápido
1. Instalação
npm install -g callx402
Ou localmente em um projeto: npm install callx402 (o binário estará então em node_modules/.bin/callx402).
Alternativa, instale diretamente do GitHub:
npm install Payloadhq/callx402
Desenvolvimento local:
git clone https://github.com/Payloadhq/callx402
cd callx402
npm install
npm link # exposes the `callx402` command
2. Primeira execução: o que funciona sem configuração
callx402 status
callx402 'complete this job for under $1'
status é o ponto de partida honesto: um relatório de acessibilidade por subsistema. Em uma instalação npm simples, ele lê 0/15 subsystems reachable, o que é esperado (veja o passo 3). A linha de intenção planeja em linguagem simples e para antes da execução, então é sempre segura de executar; use aspas simples para que seu shell não consuma $1.
Verificações gratuitas somente leitura contra o trilho Payload ativo (sem conta, sem chaves):
curl https://payload-rail.fly.dev/v1/callx402/actions
curl 'https://payload-rail.fly.dev/v1/callx402/quote?action=diagnose'
Elas retornam o catálogo de ações pagas com preços e uma cotação de preço gratuita para uma ação. Invocar uma ação de trilho é pago por ação via checkout (porta da frente da máquina: https://payloadhq.github.io/agents.json); nada aqui paga qualquer coisa.
3. Runtime auto-hospedado (avançado, opcional)
Por padrão, todo comando de subsistema roteia para o trilho hospedado — sem necessidade de configuração. Se preferir executar tudo na sua própria máquina, defina CALLX402_LOCAL=1 e aponte CALLX402_V2_ROOT para a árvore v2.0.0 (o x402 Paid API Starter Kit, um produto separado):
export CALLX402_LOCAL=1
export CALLX402_V2_ROOT=/path/to/x402-paid-api-starter-kit/v2.0.0
callx402 status # now: 15/15 reachable, 0/15 enabled
Sem CALLX402_LOCAL=1, esses comandos usam o trilho hospedado — esse é o caminho padrão e não precisa de nada instalado além do pacote npm.
(O padrão é um diretório x402-paid-api-starter-kit/v2.0.0 ao lado do seu checkout do callx402.)
Os subsistemas estão desabilitados por padrão; status nomeia a flag que habilita cada um. Defina uma flag e execute seu comando:
export PAYLOAD_MCP_DOCTOR=1
callx402 diagnose --target 'https://api.example.com/x402/pay'
Mais exemplos (cada um precisa da flag de subsistema habilitada; execute callx402 status para ver os nomes das flags):
callx402 rescue --incident inc_123
callx402 route --goal 'fetch 100 product prices for under 0.50 USD'
callx402 resolve --evidence '{"txHash":"0xabc..."}'
Observe as aspas simples: o texto do objetivo contém valores no estilo $ que um shell expandiria dentro de aspas duplas.
Alternativa à árvore local: execute em modo remoto contra seu próprio servidor callx402 (server/index.js):
export CALLX402_MODE=remote
export CALLX402_REMOTE_URL=http://127.0.0.1:8787
SDK JavaScript
const { callx402 } = require('callx402');
const result = await callx402({
intent: 'complete this job for under $1',
maxBudget: 1.00,
networks: ['base'],
assets: ['USDC'],
approvalThreshold: 5.00,
idempotencyKey: 'job-42',
});
SDK Python
import callx402
result = callx402.callx402(
intent="complete this job for under $1",
max_budget=1.00,
networks=["base"],
assets=["USDC"],
approval_threshold=5.00,
idempotency_key="job-42",
)
Servidor HTTP
CALLX402_PORT=8787 node server/index.js
curl -X POST http://127.0.0.1:8787/call \
-H 'Content-Type: application/json' \
-d '{"intent":"complete this job for under $1","maxBudget":1.00,"dryRun":true}'
Superfície HTTP completa: server/openapi.yaml (servida ao vivo em GET /openapi.json).
Comandos
| Comando | O que faz |
|---|---|
callx402 "natural language intent" | Modo de intenção: analisar, planejar, verificar orçamento, roteirizar, executar |
callx402 status [--json] | Acessibilidade do subsistema e estado das flags |
callx402 diagnose [--target ...] | Diagnosticar uma falha de x402 / MCP |
callx402 rescue --incident <id> | Resgatar uma transação (protegido por autenticação) |
callx402 route --goal <text> | Roteirizar um trabalho pago para o caminho viável mais barato |
callx402 resolve --evidence <json|@file> | Resolver o estado de liquidação com base em evidências |
callx402 doctor | Executar as verificações do médico MCP |
callx402 execute --intent <text> [--max-budget N] [--dry-run] | Executar sob um orçamento explícito |
callx402 monitor [--once|--watch] | Observar o estado do subsistema/incidente |
callx402 preflight | Verificações de pré-execução antes de uma execução paga |
callx402 inspect [--query <text>] | Inspecionar o grafo de capacidades / estado |
callx402 evidence <operationId> [--dir <path>] | Mostrar evidências registradas para uma operação (somente leitura) — apenas MCP/trilho na 1.0.1, não um comando CLI publicado |
callx402 explain <operationId> [--dir <path>] | Avaliação de estado em linguagem simples para uma operação (somente leitura) — apenas MCP/trilho na 1.0.1, não um comando CLI publicado |
callx402 recover <operationId> [--identity <id> | --evidence <json>] | Decisão segura de recuperação: RECUPERÁVEL / NOVA_TENTATIVA_SEGURA / REVISÃO_HUMANA (somente leitura) — apenas MCP/trilho na 1.0.1, não um comando CLI publicado |
callx402 config list | get <k> | set <k> <v> | Gerenciar configuração local |
Comandos de subsistema (diagnose, rescue, route, resolve, doctor, monitor, preflight, inspect) precisam da árvore v2.0.0 mais a flag de recurso correspondente (veja "Comandos completos de subsistema" acima); sem elas, saem com código 3 e não fazem nada. status, modo de intenção e config funcionam sem configuração.
Modos de execução
O callx402 funciona pronto para uso. Existem dois modos:
| Modo | O que é | Custo | Configuração | O que você obtém |
|---|---|---|---|---|
| CLI callx402 — Hospedado (padrão) | O pacote npm como um cliente leve para o Payload Rail hospedado | Cotação gratuita, depois pague por ação (ex.: diagnose $0,10, resolve $0,25 no caminho x402) | npm install callx402 — zero configuração | diagnose, resolve, recover, preflight, evidence, explain e mais, executados no servidor: cotação gratuita primeiro, pagamento verificado exatamente uma vez on-chain, invocação medida e auditável, resultado retornado. |
| Runtime callx402 — Auto-hospedado (avançado) | CLI + a árvore de runtime v2.0.0 (CALLX402_LOCAL=1, CALLX402_V2_ROOT definidos) | Gratuito | Aponte CALLX402_V2_ROOT para a árvore x402 Paid API Starter Kit v2.0.0 + habilite as flags de recurso | Execução local completa na sua máquina com as evidências que você fornecer. Análise somente leitura; nunca assina, nunca tenta novamente, nunca move dinheiro. |
Um npm install callx402 simples dá a você o modo hospedado — sem árvore separada, sem configuração, sem chaves. A árvore v2 nunca é necessária para uso padrão.
Diagnósticos pagos avulsos (sem assinatura)
As ferramentas CLI e MCP acima são o nível local gratuito: diagnósticos somente leitura que nunca cobram, nunca executam e nunca movem dinheiro. Quando um diagnóstico gratuito não é suficiente — você precisa de uma invocação paga, medida e auditável com cotação antes do pagamento e semântica de pagamento exatamente uma vez — cada ação também está disponível como uma ação de trilho paga avulsa. Sem assinatura, sem conta: cotação, depois pague deliberadamente.
O que pagar compra: o trilho autoriza a ação, valida o pagamento exatamente uma vez on-chain, mede a invocação contra sua organização, registra para auditoria, aplica regras de governador/cota para assinantes — e então executa o diagnóstico somente leitura no servidor e retorna o resultado. Sem configuração local, sem árvore separada, sem chaves. O trilho nunca finge execução: todo resultado é produzido pelos módulos de diagnóstico sobre as evidências que você fornecer.
O fluxo hospedado de cotação antes do pagamento:
# 1. Obtain a free quote. No money moves.
curl "https://payload-rail.fly.dev/v1/callx402/quote?action=resolve&path=x402"
# 2. Run the interactive client. Pay explicitly by card or with USDC.
# For USDC redemption, the paying wallet must EIP-191-sign the exact
# authorization message displayed by the CLI.
callx402 resolve --evidence '{"txHash":"0x..."}'
# 3. Agents with an external wallet-produced signature can redeem the
# ORIGINAL canonical quote with a signed authorization file:
callx402 resolve --evidence '{"txHash":"0x..."}' \
--tx-hash 0xYOUR_SETTLED_PAYMENT_HASH \
--payer-auth @signed-auth.json --approve
Um hash de transação público sozinho nunca autoriza uma ação. A autorização assinada vincula a carteira pagadora, a ação, o hash da transação, a cotação, o destinatário, a rede e as entradas da solicitação. Mantenha o quote_inputs original com a autorização assinada; solicitar uma nova cotação não autoriza um pagamento mais antigo. Nunca dê à Payload uma chave privada, frase-semente ou frase de recuperação de carteira. O resgate de carteira de contrato EIP-1271 não está habilitado atualmente. Créditos Stripe usam um caminho de resgate separado.
Tabela de taxas ao vivo: GET https://payload-rail.fly.dev/v1/callx402/actions (responde "model":"paid on-demand per action; no subscription required"). O preço do caminho x402 é a taxa do caminho Stripe dividida por 20 — por exemplo, resolve é $5,00 via Stripe, $0,25 via caminho x402. Nunca tente novamente às cegas um pagamento para alcançar uma ação paga: obtenha a cotação primeiro.
Mapa de problema para ação (qual ação paga responde a qual falha, com o caminho CLI/MCP gratuito para cada uma): docs/problem-map.md.
Integrações
Pontos de entrada funcionais para frameworks de agentes, automação, clientes MCP e facilitadores x402 — todos em integrations/ e testados contra o trilho ativo:
- LangChain — 9 ferramentas (
integrations/langchain/): diagnosticar, recuperar, resolver, evidenciar, explicar, nova tentativa segura, risco de pagamento duplicado, pré-verificação, além da tabela de tarifas ao vivo gratuita - CrewAI — as mesmas ações das Ferramentas CrewAI (
integrations/crewai/) - n8n — fluxo de trabalho de guarda de incidentes importável (
integrations/n8n/): mapeia um incidente para uma ação callx402, busca a cotação ao vivo gratuita, invoca quando autenticado, caso contrário emite instruções de pagamento — nunca paga automaticamente - Clientes MCP — configuração do Claude Desktop / Cursor / Windsurf para o servidor MCP
gratuito somente leitura (
integrations/mcp-clients/) - Facilitadores x402 —
settle-guard.js(integrations/facilitator/): resolver o estado de liquidação a partir de evidências antes de re-transmitir um pagamento
Mapa de problema → ação: docs/problem-map.md.
Porta de entrada de máquina para agentes: https://payloadhq.github.io/agents.json.
Regras de segurança de dinheiro
- Liquidação DESCONHECIDA nunca é re-tentada automaticamente e nunca é reembolsada.
- Intenções acima do orçamento são recusadas sem efeitos colaterais.
- Limites de aprovação falham de forma fechada.
- Chaves de idempotência deduplicam — repetições retornam o original, nunca re-executam.
- Subsistemas desabilitados ou inacessíveis falham de forma fechada — o sucesso nunca é falsificado.
- Não custodial — callx402 despacha trabalho; nunca detém fundos ou chaves privadas.
O que callx402 não é
- Não é o nome do produto principal. O produto é Veyline.
- Não é um corretor, negociador ou custodiano. Ele despacha; nunca detém fundos.
- As frases acima são linguagem de uso, não alegações de exclusividade.
Links
- Documentação canônica: https://payloadhq.github.io/
- Perfil da organização Payload: https://github.com/Payloadhq/Payloadhq
- RevRule da Payload (produto separado): https://github.com/Payloadhq/revrule-console
Referência completa do subsistema: docs/README.md. Linguagem comportamental: docs/ACTION_LANGUAGE.md.
Especificação de design: SPEC.md.
Licença
MIT. Veja LICENSE.
Mais da Payload · payloadhq.github.io · todos os repositórios da Payload
Relacionados: x402-manifest-check · x402-observatory · flow-agentic-demo