Veyra (veyra.money)

veyra-mcp

Dê ao seu agente de IA uma carteira com limite de gastos.
Servidor MCP + cliente tipado para Veyra: pagamentos USDC não custodiais na Base, com limites por pagamento, limites diários, faixas de aprovação humana e uma lista de destinatários permitidos — tudo aplicado no servidor, nunca pelo modelo.

O problema

Agentes precisam cada vez mais pagar por coisas: uma chamada de API, um conjunto de dados, uma recompensa, outro agente. Hoje as opções são ruins:

• Entregar a chave privada ao agente. A uma injeção de prompt de distância de uma carteira vazia.
• Entregar um cartão. Sem limites por chamada, sem lista de permitidos, e seu banco não vai te dizer qual chamada de ferramenta gastou o dinheiro.
• Aprovar cada pagamento manualmente. Então não é realmente um agente.

Veyra é a camada intermediária. Você conecta uma carteira que já possui, define o que o agente pode gastar e entrega ao agente um endpoint MCP. O agente recebe ferramentas como create_payment. Ele nunca vê uma chave e não pode exceder os limites que você definiu, porque os limites são aplicados pelo servidor da Veyra, não pelo modelo seguindo instruções.

  agent  ──MCP──▶  veyra.money  ──policy──▶  your wallet  ──USDC on Base──▶  recipient
                    │
                    ├─ under auto-max      → executes from your capped on-chain allowance
                    ├─ in the ask band     → you approve in your own wallet (one link)
                    └─ over the limits     → blocked, agent is told why

Configuração em 60 segundos

1. Cadastre-se em veyra.money, conecte uma carteira (ou comece com a fonte simulada, que não movimenta dinheiro).
2. Crie um endpoint MCP com limites. Copie a credencial (ela começa com veyra_).
3. Adicione ao seu host:

claude mcp add --transport http veyra https://veyra.money/api/mcp \
  --header "Authorization: Bearer veyra_..."

{
  "mcpServers": {
    "veyra": {
      "url": "https://veyra.money/api/mcp",
      "headers": { "Authorization": "Bearer veyra_..." }
    }
  }
}

export VEYRA_TOKEN=veyra_...
codex mcp add veyra --url https://veyra.money/api/mcp --bearer-token-env-var VEYRA_TOKEN

{
  "mcpServers": {
    "veyra": {
      "command": "npx",
      "args": ["-y", "veyra-mcp"],
      "env": { "VEYRA_TOKEN": "veyra_..." }
    }
  }
}

curl -s https://veyra.money/api/mcp \
  -H "Authorization: Bearer veyra_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_budget","arguments":{}}}'

Depois, peça ao agente para fazer algo que custe dinheiro e observe a política decidir.

Ferramentas que o agente recebe

Cada pagamento reporta um destes status:

Use a partir do código

npm install veyra-mcp

import {
  VeyraClient,
  VeyraToolError,
  idempotencyKey,
  movedRealMoney,
  paymentOutcome,
} from "veyra-mcp";

const veyra = new VeyraClient({ token: process.env.VEYRA_TOKEN! });

const budget = await veyra.getBudget();
console.log(`spent ${budget.spent_today} of ${budget.daily_limit} USDC today`);

const payment = await veyra.createPayment({
  amount: "1.25",
  recipient: "0x1234…abcd",          // USDC on Base
  reason: "Weather API, 500 calls",
  idempotency_key: idempotencyKey("weather"),
});

switch (paymentOutcome(payment)) {
  case "settled":
    // The only case where value actually moved.
    console.log("paid —", (await veyra.getPayment(payment.payment_id)).tx_ref);
    break;
  case "simulated":
    console.log("settled on the simulated rail; no money moved");
    break;
  case "awaiting_approval": {
    console.log("owner must approve:", payment.next_action?.url);
    const settled = await veyra.waitForPayment(payment.payment_id);
    console.log(movedRealMoney(settled) ? "paid" : paymentOutcome(settled));
    break;
  }
  case "blocked":
    console.log("policy refused it:", payment.policy_reason);
    break;
}

Recusas por política não são exceções

Esta é a única coisa que vale a pena ler duas vezes. Um pagamento que a política recusa retorna como um resultado comum com status: "failed" — a chamada fez o que foi pedido e a resposta foi não. Apenas um argumento malformado, uma credencial inválida ou um id desconhecido lança exceção.

Então try/catch é a ferramenta errada para detectar recusas: ela perde todos os pagamentos bloqueados e os lê como sucesso. Use paymentOutcome, e use movedRealMoney antes de dizer a alguém que o valor foi movido — ele retorna false para uma liquidação simulada mesmo que o status comece com "confirmado".

Reserve catch para o que realmente falhou:

try {
  await veyra.createPayment({ /* … */ });
} catch (e) {
  if (e instanceof VeyraToolError) {
    console.log(e.code, e.message);   // VALIDATION_ERROR, UNKNOWN_CREDENTIAL, NOT_FOUND
  } else throw e;
}

Nunca tente novamente por incerteza

Se você não conseguir saber se um pagamento funcionou, leia-o — não crie outro. getPayment retorna tx_ref assim que um pagamento real é liquidado, o que é tanto sua confirmação quanto o que você mostra ao destinatário como prova. Reutilizar o mesmo idempotency_key retorna o pagamento original; uma nova chave gasta novamente. A Veyra também define possible_duplicate_of quando um pagamento idêntico ao mesmo destinatário já está ativo.

VEYRA_TOOLS exporta as definições de ferramentas como JSON Schema, para que você possa registrá-las com o Vercel AI SDK, LangChain ou chamada de função simples sem uma ida e volta de rede. Veja veyra-examples para agentes completos construídos com o Claude Agent SDK e o Vercel AI SDK.

No que você está confiando

Vale ser direto, porque isso é dinheiro.

• A Veyra nunca detém seus fundos. Os pagamentos vão da sua carteira ao destinatário. Não há saldo da Veyra no meio.
• Acima do seu limite de aprovação automática nada é delegado. Você assina cada transferência na sua própria carteira pelo link de aprovação. A Veyra verifica se o recibo na blockchain corresponde à solicitação.
• Dentro do seu limite de aprovação automática você concede uma permissão ERC-20 limitada a um relayer operado pela Veyra, o mesmo primitivo approve que todo app DeFi usa. O contrato do token aplica o limite. O mecanismo de política da Veyra decide o destino dentro desse limite, então dimensione a permissão como um valor flutuante que você poderia perder e use a lista de destinatários permitidos quando souber quem o agente deve pagar. Revogue a qualquer momento.
• O trilho simulado existe para você conectar tudo antes de tocar em fundos reais. Ele é rotulado em todos os lugares: status confirmed_simulated, simulated: true.
• Cada decisão está no log de auditoria, incluindo mudanças de limite e rotações de credenciais.

Detalhes completos: Como um pagamento realmente se move e No que você está confiando, exatamente.

FAQ

Quais redes e ativos? USDC na Base. Uma stablecoin mantém os limites em dólar exatos sem um feed de preços, e a Base é onde o ecossistema de pagamentos para agentes já liquida. Mais trilhos estão no roadmap; abra uma issue se precisar de um.

Isso funciona com x402 ou APIs de pagamento por chamada? Sim, no sentido que importa: o agente pede à Veyra para pagar o endereço do vendedor e recebe um recibo. A Veyra é a política de gastos, não o protocolo do outro lado.

Posso hospedar por conta própria? Não hoje. Este repositório é o cliente e a ponte; o mecanismo de política é o serviço hospedado em veyra.money. O caminho de aprovação da carteira é totalmente não custodial independentemente disso.

Quanto custa? Há um plano gratuito. Veja preços.

Onde reporto uma decisão de política ruim? Pelo painel, para que o suporte veja seu log de auditoria. As issues deste repositório são para o cliente e a ponte.

Desenvolvimento

npm install
npm test     # builds, then runs the suite against a local mock of the endpoint

Veja CONTRIBUTING.md e SECURITY.md.

Links

• Produto: veyra.money · Docs · Preços
• Exemplos: zapxlabs/veyra-examples
• Nome no Registro MCP: io.github.zapxlabs/veyra

MIT © Veyra