Veyra

veyra-mcp

为你的 AI Agent 提供带消费限额的钱包。
Veyra 的 MCP 服务 + 类型化客户端：在 Base 上进行非托管 USDC 支付，支持单笔支付上限、每日上限、人工审批区间和收款方允许列表——所有规则均由服务端执行，而非由模型执行。

问题所在

Agent 越来越需要为各种事项付款：API 调用、数据集、悬赏，或另一个 Agent。目前的选择都不理想：

• 把私钥交给 Agent。 一次提示词注入就可能让钱包分文不剩。
• 给它一张卡。 没有单次调用限额，没有允许列表，而且银行不会告诉你是哪次工具调用花掉了钱。
• 手动批准每笔付款。 那它就算不上真正的 Agent。

Veyra 位于两者之间。你连接一个自己已有的钱包，设置 Agent 可以花费的金额，然后为它提供一个 MCP 端点。Agent 可以使用 create_payment 等工具。它永远看不到密钥，也无法超出你设置的限额，因为限额由 Veyra 的服务端执行，而不是依赖模型遵循指令。

  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

60 秒快速设置

1. 在 veyra.money 注册，连接钱包（也可以先选择模拟来源，不会发生实际资金转移）。
2. 创建一个带有限额的 MCP 端点。复制凭证（以 veyra_ 开头）。
3. 将其添加到你的宿主：

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":{}}}'

然后让 Agent 执行一项需要花钱的操作，看看策略如何作出判断。

Agent 可使用的工具

每笔支付都会报告以下状态之一：

在代码中使用

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;
}

策略拒绝不是异常

这一点值得再读一遍。策略拒绝的支付会以普通结果返回，状态为 status: "failed"——调用已按要求执行，只是结果为拒绝。只有参数格式错误、凭据无效或 ID 未知时才会抛出异常。

因此，用 try/catch 检测拒绝是错误的做法：它会漏掉所有被阻止的支付，并将其误判为成功。请使用 paymentOutcome；在告知任何人资金已转移前，请使用 movedRealMoney——即使状态以 "confirmed" 开头，只要是模拟结算，它就会返回 false。

只有确实发生错误时才使用 catch：

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;
}

不确定时，绝不要重试

如果无法判断支付是否成功，请查询状态——不要再创建一笔支付。真实支付结算后，getPayment 会返回 tx_ref；这既是确认凭据，也是向收款方提供的支付证明。重复使用相同的 idempotency_key 会返回原支付；使用新密钥则会再次支出。若向同一收款方发起的相同支付仍在处理中，Veyra 也会设置 possible_duplicate_of。

VEYRA_TOOLS 会以 JSON Schema 格式导出工具定义，因此你可以将其注册到 Vercel AI SDK、LangChain，或通过普通函数调用使用，无需进行网络往返。如需查看使用 Claude Agent SDK 和 Vercel AI SDK 构建的完整 Agent，请参阅 veyra-examples。

你需要信任什么

这是在处理资金，所以有必要直言不讳。

• Veyra 绝不托管你的资金。 支付直接从你的钱包转到收款方。资金不会经过 Veyra 余额。
• 超过自动批准限额后，不会委托任何操作。你需要在自己的钱包中通过批准链接为每笔转账签名。Veyra 会验证链上回执是否与请求相符。
• 在自动批准限额内，你会向 Veyra 运营的中继器授予有额度上限的 ERC-20 授权。这与每个 DeFi 应用使用的 approve 原语相同。代币合约会强制执行额度上限。Veyra 的策略引擎会在该额度内决定收款方，因此请将授权额度设定在你能够承受损失的范围内；如果你知道 Agent 应该向谁付款，请使用收款方允许列表。你可以随时撤销授权。
• 模拟支付轨道可让你在动用真实资金前接好所有流程。它会在所有位置明确标示：状态为 confirmed_simulated，simulated: true。
• 每项决策都会记录在审计日志中，包括限额更改和凭据轮换。

完整详情请参阅：支付实际上如何完成 和 你究竟需要信任什么。

常见问题

支持哪些网络和资产？ Base 上的 USDC。只使用一种稳定币，无需价格预言机即可精准设定美元限额；而 Base 已是 Agent 支付生态的结算网络。更多支付通道已列入路线图；如有需要，请提交 issue。

这能用于 x402 或按调用付费的 API 吗？ 可以，就实际所需而言：Agent 会请求 Veyra 向卖方地址付款，并获取收据。Veyra 负责支出策略，而非对端使用的协议。

可以自行托管吗？ 目前不行。此仓库包含客户端和桥接层；策略引擎是托管在 veyra.money 的服务。无论如何，钱包审批流程都是完全非托管的。

费用是多少？ 提供免费方案。请参阅定价。

如果策略决策有误，应在哪里反馈？ 请通过控制面板反馈，以便支持团队查看你的审计日志。此仓库的 issue 用于反馈客户端和桥接层相关问题。

开发

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

请参阅 CONTRIBUTING.md 和 SECURITY.md。

链接

• 产品：veyra.money · 文档 · 定价
• 示例：zapxlabs/veyra-examples
• MCP Registry 名称：io.github.zapxlabs/veyra

MIT © Veyra