Aifinpay

@aifinpay/mcp

用于持久化 Agent 身份、解析 Agent Passport、发现路由和创建非签名结算发票的 AiFinPay MCP 服务。规范域名： aifinpay.io。

此检出中准备的版本为 2.13.0，基于已发布的 Agent 2.9.0 和规范技能 2.11.0（AiFinPay/skill 0490615，发布于 2026-10-22）。单独的规范生产方最终不可变源代码固定版本是必要的交接内容，不能用动态分支替代。 2026-10-04 检查的已发布基线为 MCP2.5.0。发布软件包以及刷新真实注册表依赖项/锁文件仍是发布门槛；基于源代码批次的构建不能证明这些步骤已完成。启用所有者功能且使用 payable_fetch 的 v1.4 购买已上线：Polygon 自 2.2.0 起支持，Base（ETH 或 USDC）自 2.5.0 起支持；scope: "merchant" 的全站批次自 2.4.1 起支持。自 2.12.1 起，支付默认开启：通过 init 创建的持久化钱包无需任何支付环境变量即可付款，每笔付款上限为 $5、每 24 小时上限为 $20，且仅限向在 AiFinPay 注册的商家付款。临时钱包不会签名，而未注资的钱包没有可用资金。实际限额由所有者在仪表板的 Controls 中设置。

五步完成首次付款

无需修改 MCP 客户端配置即可启用支付。只有第 5 步会进行签名，而且仅使用已注资的持久化钱包，金额绝不超过上限。

1. 查看价格。 对资源发起 GET 请求。402 会列出商家（merchant_id）、每次请求的价格和最小批次（200 个标准请求需 $0.10）。
2. 检查设置。 调用 payment_setup_status。它会返回钱包类型（持久化或临时）、上限及各项限额的来源（default 或所有者的 env）、RPC 响应时的余额、funding（需注入的金额，按当日汇率计价）、所有者在仪表板中的 Controls，以及 next_step：尚缺的第一项内容。
3. 初始化。 如果 wallet.persistent 为 false，则运行 npx @aifinpay/mcp init。如果没有终端，它会输出一个 JSON 文档；将其中的 env（只有这里包含密码短语）复制到 MCP 客户端配置中的 aifinpay 服务条目，然后在同一连接中调用 agent_reload。无需重启：重新加载会为新钱包打开支付日志。切勿向临时地址注资。
4. 注资并关联。 将 addresses.evm 和 payment_setup_status 的 funding 中所列金额告知所有者：按当日汇率计算，最小批次（$0.10）对应的 POL，加上 Gas 上限（默认 0.3 POL；如果最坏情况下的费用超过此上限，SDK 会在签名前拒绝）。汇率会变动——2026-10-19 时，$0.10 相当于 1.08 POL——因此切勿报出记忆中的金额；如果 funding 返回的是 rate_error 而非 amount，请让所有者注入“按当日汇率计算的批次价格所需 POL，加上 Gas 上限”，不要报出具体金额。也请提供仪表板链接：所有者可在 https://dash.aifinpay.io 的 My Agents → Claim via MCP 下生成一次性 URL，然后由 Agent 将其传给 agent_claim_self；此后所有者可在 Controls 中设置实际限额。
5. 付款。 payable_fetch({"url": "https://dev.ratersapp.com/api/agent/genres/list"}) 会在 Polygon 上购买批次（splitter v1.4），并返回内容和收据摘要。后续请求会复用该批次。

目前 Polygon 和 Base 均通过 v1.4 提供服务；settlement_routes 会优先列出它们，并将 live 设为 true。其中的 legacy_v13 部分描述较旧的 splitter v1.3 路由，payable_fetch 不会使用这些路由。

可选的付款覆盖设置

首次付款不需要设置这些选项，而且每项都只会收紧默认允许的范围。init 会打印相同的参考信息块：

{
  "AIFINPAY_GATEWAY_ORIGINS": "https://merchant.example",
  "AIFINPAY_MAX_GAS_POL": "0.3"
}

• AIFINPAY_GATEWAY_ORIGINS：Agent 可以付款的 HTTPS 来源，必须精确匹配，以逗号分隔，不支持通配符。未设置时，Agent 只能向 AiFinPay 报告为已通过 DNS 验证的网站的商家付款，并且必须在该网站本身付款（或通过 AiFinPay 托管网关付款）：收款方来自后端签名的报价，绝不来自 402 响应；如果已验证的网站不是正在访问的主机，则会在签名任何内容之前拒绝付款。设置后，未列出的来源会按名称被拒绝，且只有所有者可以将其添加到列表；此时由列表决定。
• AIFINPAY_MAX_GAS_POL：Polygon 上单笔付款的最坏情况网络费用，会在签名前检查；默认值为 0.3 POL。在约 280 gwei 时，以 POL 付款的最坏情况费用约为 0.10 POL，以 USDC 付款则约为 0.21 POL。使用其他链时，需要以该链自身的货币设置 AIFINPAY_MAX_GAS。
• AIFINPAY_MAX_USD / AIFINPAY_DAILY_USD：降低内置的每笔付款 $5 / 每 24 小时 $20 上限。更高的值会在启动时被拒绝并显示提示，绝不会被静默截断；不要在此处提高上限，请使用控制面板。
• AIFINPAY_GATEWAY_PATH_MODE：未设置时会按 URL 推断（https://gateway.aifinpay.io 使用 gateway，按商家 slug；其他网站使用 direct，即完整路径）。
• AIFINPAY_PAYMENTS_ENABLED=0：关闭付款；服务保持只读。

环境变量会在服务启动时读取；更改后请重启 aifinpay MCP 服务（agent_reload 只会读取密钥库）。

所有者限额：内置上限与控制面板中的实际限额

服务单笔付款绝不会签署超过 $5 的金额，也不会在任意 24 小时内签署超过 $20 的金额（使用本地日志记录，并在任何广播之前于操作锁下检查）。该上限不是预算，无需设置；环境变量只能降低它。日常限额应在控制面板中管理：Agent 通过 agent_claim_self 关联后，所有者可在 https://dash.aifinpay.io 的 Controls 中管理单笔付款上限、每日上限、暂停状态和允许的商家；后端会针对已认领的 Agent，在每次 /v1/quote 和 /v1/pay 请求中强制执行这些策略，无需更改环境变量，也无需重启服务。底层的上限仍然适用；付款必须同时通过两项限制。若要让 Agent 密钥的单笔或每日限额超过 $5 / $20，请使用具有独立限额的 Node SDK。

对于持久化 EVM 钱包，payment_setup_status 会读取这些 Controls 并作为 dashboard 返回：{ linked: true, policy }，其中包含单笔付款上限、每日上限、商家允许列表、过期时间和暂停状态；若所有者尚未认领 Agent，则返回 { linked: false }（此时其 next_step 会提供控制面板链接）；若读取失败，则返回 { linked: "unknown", reason }，但这不会阻止任何操作，因为无论如何后端都会强制执行策略。若 Controls 已暂停或过期，检查清单会停止，并在 next_step 中说明原因。读取请求会发送到配置的后端上的 GET /v1/agents/<address>/policy，并由钱包自己的密钥签名（对 ["AiFinPay agent policy read v1", <backend origin>, <lowercase address>, <expires_at>] 进行 EIP-191 签名，有效期为 60 s）；此操作不会签署付款，也不会更改任何内容。在 payable_fetch 的拒绝路径上、对于临时钱包或在 Solana 上，不会执行此读取。

索引钱包派生

钱包 CLI 和 MCP 可以通过一个恢复种子派生确定性的子钱包。使用 npx @aifinpay/wallet new --index 0 创建兼容 MCP 的钱包；密钥库会保留 根种子，并将索引作为可选元数据添加，而不更改现有字段。MCP 会自动使用存储的索引。若要在另一个 MCP 进程中选择其他子钱包，请将 AIFINPAY_WALLET_INDEX 设为对应的十进制索引；当 SEED_HASH 或 agents.json 记录提供种子时，同一变量也适用。

每条链都会派生自己的索引密钥；例如， EVM = SHA-256("aifinpay:evm:v1\0" || decimalIndex || recoverySeed) 和 Solana = Ed25519(SHA-256("aifinpay:solana:v1\0" || decimalIndex || recoverySeed))。 十进制 UTF-8 索引位于该链的域 NUL 分隔符之后。索引 0 是第一个钱包。 索引必须介于 0 和 4294967295 之间。若未选择索引， 现有身份会保留当前的派生方式。

AIFINPAY_MAX_GAS_POL 限制的是最坏情况，而非预期支付的费用。 签名前，客户端会按 Polygon RPC 报价的每单位 Gas 最高费用，计算预估 Gas 加上 20% 的费用；如果超出上限，则会拒绝并返回 V14_GAS_BUDGET_EXCEEDED。最坏情况会随 Gas 价格变化：在约 280 gwei（2026 年 9 月）时，POL 支付约需 0.10 POL，USDC 支付约需 0.21 POL，因为还需要代币授权和结算。按该价格，0.3 足以覆盖两者；请查看当前 Polygon Gas 价格，并在价格更高时调高上限。实际收取的费用通常只是上限的一部分，但钱包在签名前必须持有批次金额以及最坏情况所需的费用。

若要使用 USDC 而非原生 POL 支付，所有者还需设置 "AIFINPAY_PAY_ASSET": "USDC"。此时钱包需要持有用于批次支付的 USDC 和用于 Gas 的 POL：精确金额的代币授权加上结算，两者合计不得超过 AIFINPAY_MAX_GAS_POL。未设置或设为 "POL" 时，仍使用原生 POL。

在另一条链上付款

AIFINPAY_PAY_CHAIN 用于明确指定 payable_fetch 结算所用的链： 默认为 polygon，也可以使用下方能力列表中的确切支持名称。 只有所有者可以设置此项；只有当商家的报价针对该链时，才会在该链上向商家付款。针对其他任何链的报价都会被拒绝， 绝不会跟随该报价。在 Base 上，批次以 ETH（或 AIFINPAY_PAY_ASSET: "USDC"）付款，Gas 费用也以 ETH 计，因此上限为 AIFINPAY_MAX_GAS，单位为 ETH：

{
  "AIFINPAY_PAY_CHAIN": "base",
  "AIFINPAY_MAX_GAS": "0.0002"
}

AIFINPAY_MAX_GAS 是以付款链的原生货币计价的 Gas 上限； AIFINPAY_MAX_GAS_POL 在 Polygon 上仍受支持，但在 Base 上会被拒绝，不会被当作 ETH 读取（0.3 POL 约合 $0.04；0.3 ETH 则价值数百美元）。 在 Base 上，最坏情况下还会包含 L1 数据费和运营商费用；所有者必须根据当前估算设置上限。钱包的 EVM 地址在每条链上都相同，因此 应向其存入 Base 上的 ETH，而不是以太坊主网上的 ETH。AIFINPAY_RPC_URL 可选地替换该链的公共 RPC（https://mainnet.base.org、 https://polygon.drpc.org）。

某条链上仍处于待处理状态的付款，只能在配置了该链时恢复；切换链不会重新发送或遗忘该付款。

调用 payable_fetch({"url":"https://merchant.example/api/data"})。该工具 使用原始签名的 v1.4 报价、独立的实时原生货币/USD 汇率、SDK 运行时/签名者验证以及所有者限制。它会在发送前持久化已准备好的交易， 验证收据，并重用已购买的批次。不会使用特殊商家脚本、备用合约或 Facilitator 回退机制。仅支持在配置的链上进行 GET；EVM 收据付款仅支持 实时模式，且只能使用原生货币或已配置的稳定币；不支持 Amoy 付款收据。最小批次价格为 $0.10，外加 Gas 费，远低于 每笔付款 $5 的上限。

若要购买整个网站的访问权限，而不是单个端点的访问权限，请调用 payable_fetch({"url":"https://merchant.example/api/data","scope":"merchant"})。 这样，一个批次即可涵盖该商家的所有路径；每个请求仍按其标价收费，因此高级页面会比标准 API 调用消耗更多批次额度。价格、所有者限制和已批准的来源均不会改变。如果所有者设置了 AIFINPAY_GATEWAY_ORIGINS，不在其中的来源会按名称被拒绝；只有所有者可以添加来源。

网络访问

如果沙盒限制了出站主机的访问名单，则必须允许 api.aifinpay.io（报价和 收据）以及付款链的一个 RPC。独立的原生货币/USD 汇率会优先使用 Polygon/Base 上固定的 Chainlink 喂价，然后依次使用 api.coinbase.com、 api.coingecko.com；其他链则使用这些 HTTP 价格来源。 如果没有任何来源提供有效的新鲜汇率，payable_fetch 会在付款前停止，错误信息会列出尝试过的每个主机。

哪个 AI 客户端进行了付款

payable_fetch 会告知商家哪个 AI 客户端正在付款：服务端会将 MCP 客户端在初始化时发送的 clientInfo.name 映射到付款请求（以及恢复待处理付款时）中的 AIFP-Agent-Framework 标头。

clientInfo.name	AIFP-Agent-Framework
claude-ai, claude-code	claude
cursor, cursor-vscode	cursor
windsurf	windsurf
chatgpt, openai	chatgpt
codex-mcp-client	codex
gemini	gemini
perplexity	perplexity

名称必须完全匹配。其他任何客户端都不会发送标头；服务端绝不会猜测。付款、限制或收据均不受此项影响。在 初始化时，服务端会向 stderr 记录一行收到的名称，例如 [aifinpay-mcp] client "codex-mcp-client" → framework codex，因此可以使用客户端的确切名称报告 表格中未列出的客户端。

将 Agent 关联到所有者的仪表板

所有者可在 https://dash.aifinpay.io → My Agents 中查看 Agent 的余额、付款和收据。在那里，Link an agent → Claim via MCP 会生成一个一次性 URL；将其传给 agent_claim_self，该工具会通过向 /api/auth/claim 发送 POST 请求来兑换该 URL。在浏览器中打开该 URL，或将其粘贴到 未连接 AiFinPay MCP 的聊天中，都不会完成关联；这类 Agent 应改为在 My Agents 中通过签名消息完成关联。启用了双重身份验证的账户采用相同的关联方式：该 URL 是在已通过第二重验证的会话中生成的。该工具只会联系 AiFinPay 来源，只会为此 Agent 自己的 地址签署认领质询，不会转移资金。必须成功确认所有者所选的付款类型； 第二个钱包则尽力确认。请使用所选钱包的 Fund 面板查看可用网络和资产；绑定不会启用已停用的网络。 在 init（上文第 4 步）后向所有者提供此功能：从此之后，所有者可在其中的 Controls 下 管理 Agent 的工作限额（参见“所有者限额”）。

所有付款类型的私密恢复状态都存放在 AIFINPAY_HOME/payments/<evm-address>/state.json （默认主目录为 ~/.aifinpay）。状态文件权限为 600，所在目录权限为 700，并且会以原子方式写入并执行 fsync。单个操作锁会在多个进程间串行处理该钱包。 重试时会先恢复待处理收据，然后才允许再次购买。进程崩溃后，锁会保留，供所有者协调处理；系统绝不会自动窃取该锁。 如果已准备好的交易从未广播，或其结果仍不确定，请先核对其确切哈希，再清除任何内容。绝不要在聊天中放入原始交易、收据 JWT 或 状态文件。未确认的付款会以保守方式计入预算。

工具

工具	用途
agent_address	读取当前的 Solana、EVM 和 Casper 地址。
agent_claim_self	将此 Agent 关联到其所有者的控制面板（一次性 URL）。
agent_reload	在当前 MCP 连接中重新加载本地钱包文件。
agent_quota	读取 Agent 的配额。
agent_passport_resolve	解析全局 Agent Passport 身份。
payment_setup_status	设置检查清单、所有者控制面板 Controls、next_step。
settlement_routes	优先使用 Splitter v1.4 路由（当前已上线），然后使用旧版 v1.3。
settlement_invoice	准备不签名的结算发票。
agent_history	读取已索引的结算记录或保留的收据批次。
settlement_solana	构建不签名的 Solana 结算发票。
settlement_casper	构建不签名的 Casper 结算发票。
deployment_info	读取部署信息：地址、资产、结算状态。

payable_fetch 始终会列出。它仅在使用持久钱包时签名；若所有者设置了 AIFINPAY_PAYMENTS_ENABLED=0，则不会签名；否则，它会将 payment_setup_status 检查清单作为工具错误返回，且不会联系任何服务。若付款默认开启但有被拒绝的覆盖设置，服务仍为只读状态，且 payment_setup_status 会指出这一情况；若明确设置了 AIFINPAY_PAYMENTS_ENABLED=1，服务则会像以前一样拒绝启动。超过上限的环境变量限制在这两种情况下都会阻止启动。它仅接受 url、max_amount_usd、scope 和 expected_merchant_id；max_amount_usd 可以降低所有者设置的单笔付款上限，但不能提高上限。

每个网关站点（origin + slug）都会固定到此钱包首次向其付款的商户。Agent SDK 会将这些固定信息保存在 ~/.aifinpay/merchant-pins 或 AIFINPAY_STATE_DIR/merchant-pins 下；AIFINPAY_HOME 不会改变其位置。当站点以另一个商户的身份响应时， payable_fetch 会在获取报价前停止，并指出两个商户 ID。不会进行付款，Agent 也无法自行批准更改。所有者确认新商户后，设置 expected_merchant_id 为该商户的调用会进行付款并重新固定该站点。没有通用的“允许任意商户变更”参数。410 gateway_retired 站点为终止状态： 工具会提示不要重试。仅当 AIFINPAY_MODE=dev 时才会注册 dev_payment_quote。旧版 agent_call、agent_quote、 pay_with_split 和 quote_split 仍不会注册。

只读目录配置

createDirectoryServer() 是另一个独立的服务：它是在 OpenAI ChatGPT App Directory 中列出的服务，地址为 https://mcp.aifinpay.io/directory/mcp。它没有 Agent 身份，无需身份验证，也不涉及资金流动。其九个工具封装了公开的 api.aifinpay.io GET 端点（AIFINPAY_API_BASE 可覆盖基础地址），并且每个工具都设置了 readOnlyHint: true 和一个 outputSchema：list_providers、 provider_info、provider_status、service_coverage、network_stats、 leaderboard、quote_cost（费用明细，不涉及付款）、verify_passport 和 agent_profile。当 AIFINPAY_MCP_PROFILE=directory 时，@aifinpay/mcp-http 会提供此服务。

import { createDirectoryServer } from "@aifinpay/mcp";
const { server } = await createDirectoryServer();

持久化钱包选择

CLI（init 和 stdio）、程序化服务和 agent_reload 使用相同的优先级：

1. SEED_HASH：现有的 32 字节种子，编码为 64 个十六进制字符，可选地带有 0x 前缀。它会直接传入 AiFinPayAgent.fromSeed；不要再次对其进行哈希，也不要提供助记词。
2. 相对于 MCP 进程工作目录的 ./aifinpay/agents.json。如果桌面客户端的工作目录与项目目录不同，请设置绝对路径的 AIFINPAY_AGENTS_FILE。该文件包含一个 agents 数组，其中的记录带有 id 和私有的 seed_hash 字段。如果有多条记录，必须通过 AIFINPAY_AGENT_ID 精确选择一条。
3. AIFINPAY_AGENT_SECRET：旧版 base58 Solana 密钥。
4. ~/.aifinpay/agent.json 或 AIFINPAY_HOME/agent.json：旧版 CLI 密钥库。加密文件需要 AIFINPAY_WALLET_PASSPHRASE。

妥善保管种子和钱包文件，不要将其泄露到聊天中、提交到源代码管理或写入日志。无效或有歧义的已配置输入会导致失败；绝不会生成替代钱包。如果完全没有配置钱包，服务会使用临时身份：不要向其注资。

嵌入外部 EVM 钱包

嵌入宿主可以将 viem WalletClient 直接传给 createServer。这仅适用于程序化调用；npx @aifinpay/mcp 和环境变量无法传递钱包客户端。请继续配置现有的本地身份，以用于 Solana 和其他身份界面。提供客户端后，其账户将成为 EVM 支付身份，支付日志也会以该地址为键。其链必须与所有者选择的 AIFINPAY_PAY_CHAIN 匹配（默认是 Polygon）；SDK 会拒绝不匹配的链，而不会切换提供方或回退到本地 EVM 密钥。

import { createServer, loadConfigFromEnv } from "@aifinpay/mcp";
import type { EvmWalletClient } from "@aifinpay/agent";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Constructed by the host from its chosen external signer/provider.
declare const walletClient: EvmWalletClient;

const { server } = await createServer({
  ...loadConfigFromEnv(),
  evmWalletClient: walletClient,
});
await server.connect(new StdioServerTransport());

宿主必须提供绑定到所选链并带有 signTransaction 的 viem LocalAccount。v1.4 会在 SDK 通过其已验证的 RPC 广播交易前，持久化保存精确的已签名交易字节；SDK 会拒绝 JSON-RPC／仅支持发送的客户端和智能账户客户端，而不会绕过持久化恢复机制。MCP 仍会应用已配置的支出限额、运行时和路由检查、收据验证及恢复机制。在支付恢复待处理期间更换注入的账户，需要先进行协调并重新连接；这不是工具级别的钱包切换。

初始化并连接

报价或发票并不代表支付已完成。payable_fetch 仅会在使用上述所有者配置时付款。

本地配置

AIFINPAY_WALLET_PASSPHRASE='<a long passphrase>' npx @aifinpay/mcp init

密钥库在静态存储时会加密，MCP 服务需要使用相同的 AIFINPAY_WALLET_PASSPHRASE 才能加载它。仅用于一次性测试钱包时，npx @aifinpay/mcp init --plaintext 会以未加密形式写入密钥库（权限模式为 600）；如果两者都没有，在终端中运行 init 时会拒绝操作，而不会创建可能被你充值的未加密钱包。

如果标准输入没有连接终端（例如 Agent 的子进程），或设置了 AIFINPAY_NONINTERACTIVE=1，init 就不会提示输入。它会生成一个 192 位的口令、加密密钥库，并输出一份 JSON 文档：

{
  "keystore": "/home/me/.aifinpay/agent.json",
  "created": true,
  "encrypted": true,
  "source": "legacy-keystore",
  "addresses": { "evm": "0x…", "solana": "…", "casper": "account-hash-…" },
  "env": { "AIFINPAY_WALLET_PASSPHRASE": "<generated>" },
  "passphrase_note": "…",
  "payments": "Payments are on by default within a built-in ceiling of $5 per payment and $20 per 24 hours, …",
  "optional_env_example": { "AIFINPAY_GATEWAY_ORIGINS": "https://merchant.example", "AIFINPAY_MAX_GAS_POL": "0.3" },
  "next_step": "Put \"env\" into the aifinpay server entry of the MCP client config …"
}

口令只会出现在 env 中，因为调用方必须将其放入客户端配置，而且没有其他传递途径；捕获该输出的进程也会捕获口令，因此请将输出视为机密信息。再次运行时，会保留钱包，并以占位符代替口令。如果设置了 AIFINPAY_HOME，env 也会包含该变量（绝对路径），以便服务读取 init 写入的密钥库；出于同样的原因，payment_setup_status 会提供包含服务的 AIFINPAY_HOME 的初始化命令。如果密钥库已存在、已加密，且未设置 AIFINPAY_WALLET_PASSPHRASE，init 会保持原样，输出一行 JSON，指出所需变量，并以状态码 2 退出；其 next_step 会要求在新的空 AIFINPAY_HOME（~/.aifinpay/agent-<yyyymmdd>）中运行 init，并将输出的 env 放入客户端配置。

按以下顺序选择钱包：SEED_HASH → ./aifinpay/agents.json → 旧版 AIFINPAY_AGENT_SECRET → ~/.aifinpay/agent.json。 SEED_HASH 表示 32 字节的十六进制种子，会直接传给 SDK 的 fromSeed。 准确的项目文件架构和多 Agent 选择方式请参阅 skill。 init 会打印所选钱包的公有地址。如果已配置种子或项目钱包，它就不会创建第二个旧版钱包。如果没有钱包，它会创建权限模式为 600 的旧版密钥库；已有密钥库会予以保留。请将该文件私密备份。请使用已发布的版本，或构建此源代码检出副本。

如果主机的工作目录不是你的项目目录，请使用绝对路径设置 AIFINPAY_AGENTS_FILE。不要将种子本身放入共享配置。客户端配置可以使用密钥库，而无需嵌入其机密：

{
  "mcpServers": {
    "aifinpay": {
      "command": "npx",
      "args": ["-y", "@aifinpay/mcp"],
      "env": {
        "AIFINPAY_AGENTS_FILE": "/absolute/project/aifinpay/agents.json",
        "AIFINPAY_AGENT_ID": "research-agent"
      }
    }
  }
}

必须先发布上述版本，才能通过此 npx 命令安装。发布固定版本的依赖项后，源代码检出副本可以在 mcp/ 中运行 npm ci && npm run build，然后配置为 node /absolute/path/to/mcp/bin/aifinpay-mcp.js。

如果使用旧版密钥库，请运行一次 npx @aifinpay/mcp init，并省略项目文件变量。AIFINPAY_WALLET_PASSPHRASE 会在创建时加密该旧版文件，服务的 env 需要相同的值才能打开它；init 会输出一个包含占位符的代码块。对于会在配置中展开变量的客户端（例如 Claude Code 的 .mcp.json），可以使用 "${AIFINPAY_WALLET_PASSPHRASE}"，而不必将口令写入文件。已连接的服务可以通过 agent_reload 加载该文件；无需开始新的对话。更改软件包或启动环境后，需要重新连接服务，具体取决于宿主支持情况。

历史记录

连接 MCP 服务一次。运行 init 或更新钱包文件后，在同一连接中调用 agent_reload；无需开始新的对话。重新加载失败时会保留之前的钱包。Shell 环境变量发生更改后，需要重新连接 MCP 进程，因为它的环境是启动时的快照。请将 agent_address 与你打算使用的钱包进行核对。

其他环境变量

变量	默认值	用途
AIFINPAY_BASE_URL	https://aifinpay.io	后端 URL。未设置时，payable_fetch 会在 https://api.aifinpay.io 获取报价并进行验证。
AIFINPAY_TIMEOUT_MS	30000	请求超时时间。
AIFINPAY_PAYMENTS_ENABLED	on	可选覆盖项：0 会关闭支付。
AIFINPAY_MAX_USD	5	可选覆盖项：降低单笔支付上限；更高的值将被拒绝。
AIFINPAY_DAILY_USD	20	可选覆盖项：降低 24 小时上限；更高的值将被拒绝。
AIFINPAY_GATEWAY_ORIGINS	已验证的商户站点	可选允许列表：以逗号分隔的 HTTPS 来源，Agent 可向其支付。
AIFINPAY_GATEWAY_PATH_MODE	按 URL 推断	gateway（商户 slug）或 direct（完整路径）；未设置时，按 slug 使用托管网关。
AIFINPAY_MAX_GAS_POL	0.3	可选覆盖项：Polygon 上每笔支付的 Gas 上限，单位为 POL。
AIFINPAY_PAY_CHAIN	polygon	所有者选择的支付链；请参阅 the2.8.1 源能力列表。
AIFINPAY_MAX_GAS	—	支付链原生货币（POL、ETH、AVAX、BNB、XRP）计价的每笔支付 Gas 上限。
AIFINPAY_RPC_URL	支付链的公共 RPC	支付链的 HTTPS RPC。
AIFINPAY_CLAIM_ORIGINS	AiFinPay 控制面板	agent_claim_self 可引导 Agent 前往的确切来源。

agent_history({address, source:"transactions", network:"polygon"}) 会在后端的持久化索引器提供相应网络数据时，读取该网络的已索引结算记录。标注日期的生产基线包含 Polygon 索引；仅有另一条客户端链的描述符，并不能证明其历史记录覆盖情况。source:"receipts" 会读取留存批次，包括测试模式下的支付。传入 passport，替代或配合 address，即可先解析公开护照。不具备护照解析器的后端无法满足仅使用护照的查询。读取公开元数据不需要秘密 API 密钥。

响应不包含持有者收据。限制范围为 1..100；请使用 next_offset。历史记录来源／覆盖范围均有明确说明：它不是完整的钱包浏览器。测试模式下的索引取决于后端能力；留存的收据历史记录是单独的数据来源，不能证明主网已启用。

const { server } = await createServer(loadConfigFromEnv());
await server.connect(new StdioServerTransport());

身份环境选项的编程等效项为 seedHash、agentsFile、agentId、agentSecretB58、walletHome 和 walletPassphrase。

• AIFINPAY_BASE_URL：后端来源；默认值为 https://aifinpay.io。

• AIFINPAY_HOME：旧版 agent.json 密钥库所在目录。

• AIFINPAY_MODE=dev：启用 dev_payment_quote；需要单独的开发环境基础 URL。

• AIFINPAY_TIMEOUT_MS：SDK 请求超时时间。

• AIFINPAY_MAX_USD：降低 payable_fetch 的 5 美元单笔支付上限（可选）。

• AIFINPAY_TRUSTED_HOSTS：允许绕过 DNS 预检查的确切主机。

• AIFINPAY_ALLOW_PRIVATE_FETCH=1：显式启用本地开发网络访问。 切勿在公开托管的 MCP 上启用此选项。 自托管的 AIFP-1 网关无需设置：未设置时，除 https://gateway.aifinpay.io 以外的所有来源都使用 direct 路径模式（每个请求的完整路径名都是其 AIFP-1 资源标识）；该网关则使用商户 slug。AIFINPAY_GATEWAY_PATH_MODE 会为所有来源强制使用一种模式；它不会扩大所有者的 AIFINPAY_GATEWAY_ORIGINS 允许列表，也不会在生产 RC 中启用已弃用的签名工具。

开发环境中的报价不会绕过钱包签名、发行方验证或回执计量。后端前置条件请参见随附的技能包。底层 SDK 提供 Amoy 执行器；此 MCP 不提供 Amoy 付费回执购买功能。

许可证

MIT。

2.8.1 源码候选版本中的其他 EVM 网络

所有者配置的 AIFINPAY_PAY_CHAIN 接受 polygon、base、optimism、arbitrum、avalanche、bnb、unichain、xrplevm 和 robinhood。AIFINPAY_MAX_GAS 使用所选链的原生 POL/ETH/AVAX/BNB/XRP 币种计价；旧版 POL 上限仅适用于 Polygon。资产必须针对对应链固定，包括 18 位小数的 BNB USDC/USDT，以及 18 位小数的 Robinhood USDe/6 位小数的 USDG。XRPL EVM 仅支持原生 XRP。元数据来自 agent 2.6.1；后端仍必须授权并服务该商户/网络。源码支持不会在生产环境中激活网络。待处理日志会保留原始链信息，恢复时无需再次结算。只有在所有者配置的链与实际已签名交易的链 ID、付款方、固定目标和精确调用均一致时，才会接管缺少链信息的旧日志。证据不足时，必须手动核对回执。后续报价过期不会使现有付款的回执恢复失效。

通过最终发布门禁后的发布顺序：发布经审核的规范技能包 2.9.0 和 agent 2.6.1，从这些真实的注册表发布版本刷新 MCP 依赖项和锁文件，通过独立 MCP CI，然后发布 MCP 2.8.0。此候选版本需要新鲜的源打包 agent 2.6.0 和技能包 2.9.0，以及精确的 Python 2.5.1 发布目标。发布前，现有注册表中的 agent 2.5.0 / 技能包 2.8.0 条目保持不变；不得伪造 npm integrity/解析结果。旧版 2.3.x agent 无法构建新的描述符/辅助函数导入，旧版技能包 2.6.0 也无法满足精确的发布目标校验。托管源码 CI 使用 scripts/check-mcp-source-cohort.mjs：在临时目录中使用保留字节的补丁版注册表引导程序，以及来自同一提交的真实 Node 和完全固定的规范技能包。Node 生成器的权威源码锁文件会为真实运行时提供种子；它属于单独的解析证据，因为 npm 不会将其打包进 tarball。必须通过精确的包字节、版本、随附技能包、高危/严重级别审计和完整测试；注册表发布门禁仍必须拒绝缺少匹配真实注册表锁文件的源码队列。独立发布 CI 要求刷新后的真实注册表锁文件。绝不可使用旧的注册表依赖锁文件发布此候选版本。

钱包的账本/日志应使用同一共享本地文件系统，并在降级前核对待处理交易。Node 2.4 的预留在结果未知时永不过期；回执失败绝不会退还已确认的支出。旧版 SDK 可能会使此状态过期或重置。自定义的 capped v1.4 账本适配器必须提供新的绑定式准备/恢复/完成钩子；若缺少这些钩子，则会拒绝付款。

Solana 源码候选

Version2.7 以 NodeSDK2.5 和规范 skill2.8 为目标。这些是协调后的发布目标；集成源码并不代表已发布到 npm，也不会激活网络。已发布部署 deployments1.1.3 中的 Solana 条目仍处于禁用状态。payable_fetch 保留 SDK 可用性检查，无法绕过该检查。

对于单独获准并提供服务的 Solana 路由，所有者需设置 AIFINPAY_PAY_CHAIN=solana，明确设置 AIFINPAY_SOLANA_NETWORK=mainnet 并启用 live 模式（或设置 devnet 并启用 dev 模式），以及可信的 HTTPS AIFINPAY_RPC_URL。AIFINPAY_MAX_FEE_LAMPORTS 是交易费用加上所需账户租金的正整数上限；EVM gas 上限不能用于 Solana。原生 SOL 和网络固定的经典 SPL 资产通过 AIFINPAY_PAY_ASSET 选择。仍须启用现有支付、配置获准来源，并设置每笔支付和每日 USD 上限。

在发出 Solana 报价请求前，SDK2.5 会将精确的已签名授权、nonce 和所有者上下文保存到共享的私有账本中。超时或重启后，它会重放该准入记录，而不是生成新的 nonce。对于该准入记录，每笔支付限额在每日限额重置后仍保持不变；MCP 仍会在提交前检查当前每日可用额度。精确且经过身份验证的未准入响应，只能关闭未预留的本地意图，绝不会退还已签发的后端报价预留。升级时保留 2.5 账本状态；降级前先进行对账，绝不要删除状态来重试支付。

私有持久化日志会在提交前保存完整的已签名 Solana 交易和 base58 签名，其中准入金额包含费用和租金。付款方身份会保留大小写。重启或重试时会恢复原始回执；超时或区块哈希过期绝不会触发替代支付。相同的本地钱包预算仍由各类支付共享。

经证实已最终确认的 Solana 交易失败会作为错误返回，不附带回执，也不会发起替代支付。在 SDK 验证精确的已签名交易和规范的最终确认区块，并持久化完成其绑定账本的对账后，MCP 会原子地保留实际费用扣款并清除待处理购买保护。其私有日志会保留原始签名和失败状态。证据缺失或不匹配时会保留完整预留；仅凭过期不能释放预留。持久化失败可以重试，无需重新发送。

发布前，安装实际已发布且经过协调的 Node/skill 版本，并刷新真实的注册表锁文件；本地打包的源码组合只能作为测试证据。不要使用之前的依赖锁文件发布。

Solana agent_history 和 agent_quota 使用大小写敏感的精确本地 Solana 地址，以及由所有者配置的集群和独立固定的程序。它们会请求新程序的索引结算记录和保留的回执；旧程序和其他集群的记录属于不同的历史。显式选择 EVM 历史时，仍会使用钱包的 EVM 地址。