PayCheck

npx add-mcp 'https://paycheck.toolweather.workers.dev/mcp'

PayCheck

O PayCheck avalia se um domínio, uma URL https ou uma carteira 0x é segura para pagamento antes de um agente autônomo enviar dinheiro.

Ele faz parte do conjunto Toolweather, na mesma família do Toolweather MCP health, Upstream e SpendGate. O SpendGate é para limites de gastos. O PayCheck é apenas a verificação de confiança do beneficiário. Ele não envia pagamentos, não assina transações e não guarda chaves de carteira. Um pacote Toolweather pode integrar esta API posteriormente com x-tw-bundle-secret e x-tw-bundle-client.

A pontuação é determinística. amount_usd, category e qualquer texto de propósito são descartados. Reformulá-los não pode melhorar o veredito.

Quando usar

Chame o PayCheck uma vez por beneficiário, imediatamente antes de um checkout, fatura ou transferência.

• Use check_merchant para um domínio (api.openai.com), uma URL https ou um endereço 0x com 40 caracteres hexadecimais.
• Use get_quota para ver quantas verificações gratuitas restam hoje.
• Use get_api_key uma vez para gerar uma chave pc_live_… gratuita. Não chame a cada turno.

Não use o PayCheck para enviar dinheiro, guardar chaves ou reverter um block perguntando novamente com uma categoria mais amigável.

Pontuação (política v1)

Regras completas, lista de permissões e tabela de penalidades: GET /v1/policy (ou http://127.0.0.1:8791/v1/policy localmente).

Comece em 100 e subtraia penalidades. policy_version é "1".

Sinal	Resultado
Host na lista de permissões, https, porta 443	trusted, pontuação de pelo menos 92
Domínio maduro que não está na lista de permissões	unknown (nunca trusted)
Falha na consulta de idade RDAP	pequena penalidade, a idade não é inventada
Idade do domínio inferior a 30 dias	suspicious
Idade do domínio inferior a 7 dias	suspicious
Idade do domínio inferior a 2 dias	block
Não-https, IP bruto, localhost, endereço privado, userinfo na URL	block
Lista de bloqueio, padrão de nome de golpe, TLD ruim, typosquat de uma marca na lista de permissões	block
Muitos hífens, punycode ou falsificação de marca	suspicious
Carteira 0x, hex inválido ou endereço burn / zero	block
Qualquer outra carteira 0x	unknown. Sem análise de cadeia na v1

trusted é apenas para a lista de permissões publicada (cerca de 40 hosts conhecidos de API de IA e desenvolvedores, incluindo openai.com, anthropic.com, stripe.com, github.com, cloudflare.com, vercel.com e supabase.com). Um domínio novo ou aleatório nunca é confiável.

Ações recomendadas: proceed, verify_out_of_band, require_human_review, do_not_pay.

A idade do domínio usa RDAP público (https://rdap.org). Consultas bem-sucedidas são armazenadas em cache no D1 por 7 dias. Falhas são armazenadas em cache por 24 horas.

Camada gratuita

Chamador	Verificações por dia UTC	Preço
IP anônimo	100	Grátis
Chave pc_live_… gratuita (POST /v1/keys ou get_api_key)	1.000	Grátis
Cliente do pacote, x-tw-bundle-client é hex (16+ caracteres)	1.000	Grátis
Cliente do pacote, anon ou anon:… (e qualquer outro id não-hex)	100	Grátis
Acima do limite diário	por verificação	$0,001 USDC

O mesmo chamador e o mesmo alvo são idempotentes por 60 segundos e não consomem uma segunda verificação gratuita.

Não cobrado: get_quota, get_api_key, GET /v1/policy, GET /health, documentação e descoberta MCP.

A geração de chaves é limitada a 10 chaves por IP por dia UTC. O PayCheck armazena apenas um hash SHA-256 da chave.

Excedente x402

Verificações acima do limite custam $0,001 USDC (1000 unidades atômicas) na Base (eip155:8453), esquema exact, ativo 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913, facilitador https://facilitator.payai.network.

PAY_TO é o endereço de recebimento. É um segredo do Worker. Se não estiver definido, chamadas acima do limite retornam HTTP 402 com error: "payment_not_configured" e nada é cobrado.

Autenticação do pacote: o cabeçalho x-tw-bundle-secret deve ser igual ao segredo do Worker BUNDLE_PROXY_SECRET, e x-tw-bundle-client identifica o chamador final.

API

Método	Caminho
POST	/v1/check	{ "target", "amount_usd"?, "category"?, "api_key"? }
POST	/v1/keys	Gerar pc_live_…
GET	/v1/quota	Verificações gratuitas restantes
GET	/v1/policy	Política de pontuação v1
GET	/health	Liveness
GET	/openapi.json	OpenAPI
GET	/llms.txt, /llms-full.txt	Documentação do agente
POST	/mcp	MCP streamable HTTP
GET	/.well-known/mcp e /.well-known/mcp.json	Descoberta MCP
GET	/.well-known/x402	Descoberta de pagamento

Versões do protocolo MCP: 2025-06-18 e 2025-03-26. Respostas JSON sem estado (sem sessão). GET /mcp retorna 405.

Ferramentas:

1. check_merchant — pode gravar histórico de verificação. readOnlyHint: false, idempotentHint: true, openWorldHint: true, destructiveHint: false.
2. get_quota — gratuita. readOnlyHint: true, idempotentHint: true.
3. get_api_key — gratuita, gera uma chave. Não é somente leitura. Não chame a cada turno.

curl -s -X POST http://127.0.0.1:8791/v1/check \
  -H 'content-type: application/json' \
  -d '{"target":"https://api.openai.com"}'

{
  "mcpServers": {
    "paycheck": {
      "type": "http",
      "url": "https://paycheck.toolweather.workers.dev/mcp"
    }
  }
}

Entrada stdio do Glama, após npm run build:

node dist/stdio.js

O processo stdio fala JSON-RPC delimitado por nova linha (um objeto JSON por linha) e também aceita quadros Content-Length na entrada. Sua cota e chaves estão na memória. A persistência de produção é o Worker.

Local

npm install
npx wrangler d1 migrations apply paycheck --local
npm run dev
npm test
npm run typecheck

npm run dev serve a API e a página inicial na porta 8791.

.dev.vars opcional (ignorado pelo git; veja .dev.vars.example):

# PAY_TO=0xYourReceivingAddress
# BUNDLE_PROXY_SECRET=replace-with-a-long-random-string

Implantação

A produção está em paycheck.toolweather.workers.dev. wrangler.toml já tem o D1 de produção database_id. PAY_TO e BUNDLE_PROXY_SECRET são segredos do Worker. Não os coloque em [vars] ou no git.

npx wrangler d1 migrations apply paycheck --remote
npx wrangler secret put PAY_TO
npx wrangler secret put BUNDLE_PROXY_SECRET
npx wrangler deploy

Verifique o pacote sem implantar:

npm run dry-run

Estrutura

• src/score.ts — avaliador puro, coberto por testes unitários
• src/http.ts — rotas Hono
• src/mcp.ts — JSON-RPC HTTP streamable
• src/stdio.ts — entrada stdio do Glama (dist/stdio.js)
• migrations/ — esquema D1
• public/ — página inicial
• lhm.plugin.json, glama.json — metadados de listagem de diretório

Licença

MIT. Veja LICENSE.