Yolfi Payments MCP

Yolfi Agent Kit：AI Agent 支付集成

面向加密货币和稳定币结账的 AI Agent 支付集成。@yolfi/agent 提供本地 MCP 服务、JSON CLI、JavaScript SDK，以及 Yolfi Payments Agent Skill，可用于支付链接、结账会话、支付状态检查和签名 Webhook。

如需集成 AI，请将这条消息复制给你希望进行集成的项目中的 Agent：

Add Yolfi payments to this project. Follow https://docs.yolfi.com/ai

Agent 会检查项目、复用现有连接或选择受支持的连接方式、读取账户设置，并实现所需的集成。所有者完成账户授权，并仅提供尚缺的决策信息，例如收款钱包或产品价格。仅连接账户并不能完成集成。

网站 | Agent Kit | AI 指南 | Agent 连接参考 | HTTP API | CLI 参考 | npm | GitHub | MCP 目录

语言

English、Español、Deutsch、Français、简体中文、Русский、हिन्दी、Türkçe、한국어、日本語。

选择入口

• **AI 集成：**发送上面的消息。Agent 指南负责工作流；SKILL.md提供打包后的说明。
• **HTTP API：**使用 API 指南了解身份验证、请求正文、结账和 Webhook。
• **终端自动化：**使用下面的命令和 CLI 参考。
• **JavaScript 应用：**安装 SDK，并使用下面的服务端／运行时指南。

加密货币支付集成功能

• 为 SaaS 产品、数字下载、点数、游戏和捐赠提供托管结账和一次性支付链接。
• 为 Yolfi 账户支持的订阅流程提供循环支付链接。
• 为服务端定价的订单提供结账会话，并使用稳定的幂等键进行重试。
• 提供支付状态检查和 Webhook 签名验证，以便接入应用现有的访问和订阅逻辑。
• 通过现有 Yolfi API 管理组织设置、选定的结算钱包和独立的 Webhook 端点。

可将此集成工作流与 Codex、Claude Code、Cursor、ChatGPT、Claude、OpenClaw、Hermes，或其他配备受支持 MCP 连接器或本地工具的 Agent 配合使用。无法运行命令的浏览器和云环境需要使用受支持的远程连接器。请参阅连接参考，了解各主机可用的连接方式。

CLI 安装与授权

需要 Node.js 18 或更高版本。无需全局安装即可运行：

npx -y @yolfi/agent help
npx -y @yolfi/agent auth:status

如果没有本地凭据，请启动浏览器授权：

npx -y @yolfi/agent setup --agent local-agent
# Open the returned loginUrl and complete owner authorization.
npx -y @yolfi/agent checkin --agent local-agent
npx -y @yolfi/agent auth:status

如果 Agent 的环境支持浏览器，应打开该 URL，并在授权后继续完成 check-in。同一 API 环境下重复设置会复用尚未过期的待处理会话。必须使用 auth:status 检查账户访问权限；这不会验证结账或实时 webhook 投递。

凭据和待处理状态使用原子写入和进程锁保存到 ~/.yolfi/config.json。在支持的系统上，目录和文件权限分别为 0700 和 0600。YOLFI_CONFIG_HOME 用于指定隔离的配置目录。显式 SDK 凭据优先于 YOLFI_API_KEY，而 YOLFI_API_KEY 优先于存储的本地凭据。使用浏览器授权时，不要设置占位符 YOLFI_API_KEY。

对于明确的新账户，在所有者提供或确认邮箱和项目名称后，Agent 可以使用邮箱确认注册：

npx -y @yolfi/agent auth:agent-register \
  --email "[email protected]" \
  --project-name "My product" \
  --agent-name "My coding agent" \
  --integration-intent accept_payments

首次调用会发送确认链接。所有者打开链接后，Agent 再次运行相同的命令。生成的幂等键和待处理 check-in 令牌会持久化；可选的 --idempotency-key 必须为 16-200 个字符，并在重试时重复使用。已连接的凭据会被存储，不会打印出来。已存在的邮箱应使用浏览器授权。如果最初的注册响应丢失，可以恢复；如果兑换后一次性凭据响应丢失，请检查 auth:status，并在需要时重新启动浏览器授权。

用于加密货币支付的 MCP 服务

优先使用已连接的 Yolfi 服务。连接选择取决于 Agent 环境中可用的工具，而不只是其品牌。完整的主机设置说明见连接参考。

经过身份验证的 MCP 连接无需额外的组织 API 密钥。请继续使用其工具，包括创建 Checkout Session；除非确实需要单独的本地工作流，否则跳过本地 CLI 设置。本地 MCP 会自动使用其存储的浏览器设置凭据。应用服务凭据是另一项独立配置，见下文。

• 远程 Streamable HTTP：https://app.yolfi.com/mcp，OAuth 由 MCP 主机管理。
• 本地 stdio：npx -y @yolfi/agent mcp，使用受保护的本地凭据。

单一本地服务提供支付工具、知识资源和引导式提示词：

{
  "mcpServers": {
    "yolfi": {
      "command": "npx",
      "args": ["-y", "@yolfi/agent", "mcp"]
    }
  }
}

捆绑的 Codex 和 Claude 插件会启动本地服务。本地专用工具包括 yolfi_agent_setup_start、yolfi_agent_checkin、yolfi_agent_register 和 yolfi_webhooks_verify。远程 MCP 使用主机 OAuth。请在该主机中使用 yolfi_auth_status 验证，而不要使用单独的 CLI 登录。无法运行命令的环境必须使用受支持的远程连接器；如果主机无法自动配置，Agent 只应说明所有者需要执行的操作。

核心工具包括组织读取/更新、结算配置、webhook 端点列表/创建/更新/轮换/移除、paylink 列表/获取/创建/停用、yolfi_checkout_sessions_create、yolfi_checkout_sessions_get，以及支付创建/状态。应从已连接的服务读取工具可用性。Checkout Session 工具和结算合并要求后端支持相应端点；不要悄悄回退为替换组织结算设置。

创建资源前先复用现有资源

npx -y @yolfi/agent organization:get
npx -y @yolfi/agent paylinks:list --page 1 --rows 10
npx -y @yolfi/agent webhooks:list

阅读所有相关页面和项目现有配置。复用已批准的钱包、价格、匹配的付款链接和 Webhook 端点。settlement:configure 会发送 PATCH /api/private/organization/settlement-accounts，仅更新提供的网络，并保留其他网络。更改现有钱包仍需获得所有者批准地址。

在将 JSON 载荷文件传递给 --json 之前，先在目标项目中创建这些文件；软件包示例不会自动复制到那里。例如，确认以下产品值后：

cat > yolfi-paylink.json <<'JSON'
{
  "name": "Premium Download",
  "price": "19",
  "currency": "USD",
  "type": "ONE_TIME",
  "collectEmail": true
}
JSON
npx -y @yolfi/agent paylinks:create --json ./yolfi-paylink.json

载荷格式请参阅示例。如果创建操作超时，请先列出资源再重试。创建 Webhook 不会执行更新或插入操作；两次创建相同 URL 会生成相互独立且密钥不同的端点。

Webhook 密钥与部署

本地 CLI/MCP 创建和轮换操作会将端点签名密钥保存在受保护的本地配置中，并返回带脱敏元数据的结果，其中 signingSecretStored: true。列表和更新操作绝不会返回密钥。使用端点 ID 进行本地验证：

npx -y @yolfi/agent webhooks:verify \
  --endpoint-id <endpointId> \
  --payload ./raw-webhook.json \
  --signature <signature>

YOLFI_WEBHOOK_SECRET 可用于提供服务器/CI 密钥。不支持明文 --secret 标志和 MCP secret 参数；请使用端点 ID 或环境变量。API 密钥或 Agent 凭据绝不能用作 Webhook 签名密钥。

为应用代码安装 SDK：

npm install @yolfi/agent

对于本地配置脚本，readWebhookSigningSecret(endpointId) 可检索已存储的密钥。直接将其传递给目标部署的密钥管理器或现有的被忽略环境文件，不要打印出来。应用应读取部署中的 YOLFI_WEBHOOK_SECRET；不应依赖开发者机器上的 ~/.yolfi。直接 SDK 创建/轮换方法会返回 API 响应，因此受信任的服务器代码可以自行存储密钥。

import { readWebhookSigningSecret, verifyWebhookSignature } from '@yolfi/agent';

// Provisioning script only: pass this value to your existing secret manager.
const signingSecret = readWebhookSigningSecret(endpointId);
if (!signingSecret) throw new Error('Stored endpoint secret is missing');

// Application webhook handler: verify the raw body with the deployed secret.
const valid = verifyWebhookSignature(rawBody, signature, process.env.YOLFI_WEBHOOK_SECRET);
if (!valid) throw new Error('Invalid Yolfi webhook signature');

复用匹配的端点及其已安装的密钥。如果密钥不可用，请说明所需的恢复步骤，而不要悄悄轮换正在使用的密钥或创建重复端点。轮换和移除都需要明确确认。分析端点在没有元数据筛选条件时使用 NONE；通用筛选条件是可选的扁平字符串映射，仅用于明确列出的当前支付类别，绝不能用于授权或租户路由。

JavaScript SDK 与应用运行时

固定金额付款链接结账使用公开结账 URL。创建公开支付和查询支付状态也无需组织 API 密钥。将付款链接 ID 保存在应用配置中，并通过带签名的 Webhook 事件或权威支付状态验证访问授权。

动态定价的订单使用经过身份验证的 Checkout Session 创建流程。后端负责计算金额并使用自己的服务器凭据；MCP 主机的 OAuth 会话不是应用凭据。已部署的服务需要经过有意配置的密钥。绝不要将主机 OAuth 令牌复制到应用中，也不要假设生产环境中存在本地 CLI 登录。

import { YolfiClient } from '@yolfi/agent';

if (!process.env.YOLFI_API_KEY) throw new Error('Server credential is not provisioned');
const yolfi = new YolfiClient({ apiKey: process.env.YOLFI_API_KEY });
const session = await yolfi.createCheckoutSession({
  amount: '19',
  currency: 'USD',
  merchantOrderId: 'order-123',
  clientReferenceId: 'user-123',
}, { idempotencyKey: 'checkout-order-123' });

对于基于付款链接的会话，请使用 paylinkId，而不要使用 amount 和 currency。独立会话需要稳定的幂等键，并支持一次性付款。创建公开支付时可提供 paylinkId 或 checkoutSessionId，以及 network 和 symbol；客户邮箱必须直接提供，或已存在于会话中。支付元数据和付款链接 paymentMetadata 接受扁平的字符串、有限数值或布尔值。对于订阅归因，clientReferenceId 应使用稳定的应用用户/客户 ID。

请从组织或付款链接的受支持代币目录中选择支付网络和代币。Litecoin 使用 network: "LTC" 和 symbol: "LTC"；是否可用取决于部署和组织设置。

经过授权后，SDK 的 getApiKey() 会读取完整的组织 API 密钥。它不是状态检查，不应将其打印为诊断输出。请使用 authStatus() 验证账户。

CLI 命令

npx -y @yolfi/agent organization:update --json ./organization.json
npx -y @yolfi/agent settlement:configure --json ./settlement.json
npx -y @yolfi/agent webhooks:add --name Application --url https://example.com/api/yolfi/webhook --adapter NONE
npx -y @yolfi/agent webhooks:update --id <endpointId> --json ./endpoint.json
npx -y @yolfi/agent webhooks:rotate-secret --id <endpointId> --confirm
npx -y @yolfi/agent webhooks:remove --id <endpointId> --confirm
npx -y @yolfi/agent paylinks:get --id <paylinkId>
npx -y @yolfi/agent paylinks:disable --id <paylinkId> --confirm
npx -y @yolfi/agent checkout-sessions:create --json ./checkout-session.json --idempotency-key <stable-order-key>
npx -y @yolfi/agent checkout-sessions:get --id <checkoutSessionId>
npx -y @yolfi/agent payments:create --json ./payment.json
npx -y @yolfi/agent payments:status --id <paymentId>

运维命令会输出 JSON。help 会输出用法说明；mcp 使用 MCP 协议。负载文件必须存在于当前工作目录中。organization:update 是通用 API 更新；使用 settlement:configure 以保留未提及的网络。

验证

分别报告账户授权、本地测试、部署配置，以及线上支付／webhook 验证情况。重定向、连接成功或本地签名测试，都不能证明完整支付流程有效。保留应用现有的账单和权益逻辑，不要仅为声称已完成验证而创建付费测试活动。

软件包检查：npm run check。本地版本或测试通过，并不意味着软件包已发布或目录已批准。