Yolfi Agent

🤖 Yolfi Agent Kit

為加密結賬打造的 AI Agent 支付集成方案 — 一款 JSON 優先的 SDK、CLI、Agent Skill 與 MCP 服務器，讓 AI 編程智能體能夠通過 Yolfi 為應用快速添加穩定幣結賬、支付鏈接、支付狀態查詢、Webhook 驗證以及基於 Webhook 的訪問控制邏輯。

當 Codex、Claude Code、Cursor、OpenClaw、MCP 宿主或自定義 AI 智能體已經能夠構建產品，但仍需要一個可靠的支付 API 來註冊 Yolfi 工作區、創建支付鏈接、配置 Webhook 並驗證加密貨幣支付狀態時，請使用 @yolfi/agent —— 無需讓用戶手動完成控制檯配置。

官方網站 | Agent Kit | 文檔 | npm | GitHub | Glama | 集成指南

---

🌐 多語言文檔

閱讀本包指南的其他語言版本： English, Español, Deutsch, Français, 簡體中文, Русский, हिन्दी, Türkçe, 한국어, 日本語。

---

💡 為什麼開發者選擇它

• 可為 SaaS 產品、遊戲、市場平臺、捐贈頁面、數字下載、內部工具以及智能體構建的應用添加 AI Agent 支付能力。
• 為編程智能體提供安全的支付工作流：檢查應用 → 註冊或複用工作區 → 詢問錢包與價格決策 → 創建支付鏈接 → 安裝結賬組件 → 驗證 Webhook → 檢查支付狀態。
• 用同一個包即可滿足 MCP 加密支付、JSON CLI 自動化、JavaScript SDK 調用、Webhook 簽名驗證以及智能體可讀指令等需求。
• 基於 Yolfi 現有的 API 構建，無需維護第二套只面向智能體的支付 API。
• 幫助智能體通過 npm、GitHub、MCP 目錄、llms.txt、文檔、示例以及集成指南發現 Yolfi。

🧩 職責劃分

Yolfi 負責：加密貨幣支付基礎設施、託管結賬、支付鏈接、公開支付發票、組織設置、結算錢包配置以及 Webhook 投遞。

你的智能體負責：項目檢查、代碼修改、用戶確認以及目標應用集成。

---

🎁 它可以為應用帶來什麼

• 通過 Yolfi 支付鏈接實現的託管加密貨幣結賬。
• 面向數字產品、積分、文件、工具或遊戲道具的一次性支付鏈接。
• 在 Yolfi 賬戶支持的前提下，可設置循環或訂閱式支付鏈接。
• 捐贈與創作者支持支付頁面。
• 服務端路由，用於基於支付鏈接創建公開支付發票。
• 通過 Yolfi 公開支付接口進行支付狀態輪詢。
• 用於驗證 X-Yolfi-Signature 的 Webhook 處理器。
• 基於 Webhook 的權益邏輯，僅在確認支付事件後才解鎖訪問權限。
• 適用於 Codex、Claude Code、Cursor、OpenClaw 以及自定義自動化的智能體工作流。

---

🧠 Agent Skill

本包在 SKILL.md 中包含了 Yolfi Payments Skill。當用戶要求添加加密貨幣支付、支付鏈接、結賬、訂閱、捐贈、付費下載、付費訪問或基於 Webhook 的權益時，可將其用於編程智能體。

推薦的安全工作流：

inspect app -> check YOLFI_API_KEY -> register if needed -> ask user for wallet and price -> configure organization -> create or reuse paylink -> add checkout -> add webhook verification -> verify status

⚠️ 安全邊界

該技能定義了智能體可以自動執行的操作，以及必須由用戶決定的事項。智能體絕不能憑空捏造錢包地址、價格、套餐、幣種、密鑰存儲位置或破壞性的支付鏈接操作。

---

📦 安裝指南

在項目中安裝：

npm install @yolfi/agent

或者直接運行而無需安裝：

npx -y @yolfi/agent help

啟動 stdio MCP 服務器：

npx -y @yolfi/agent mcp

在本倉庫內進行本地開發：

node packages/yolfi-agent/src/cli.js help

---

🔐 身份認證

私有命令需要使用 Yolfi 組織 API 密鑰：

export YOLFI_API_KEY="yolfi_..."

CLI 和 MCP 服務器默認使用 Yolfi 生產環境 API 與結賬 URL。

如果目標應用尚無 YOLFI_API_KEY，智能體可以通過 agent 註冊端點註冊工作區：

yolfi auth:agent-register \
  --project-name "Space Shop" \
  --agent-name "Codex" \
  --integration-intent accept_payments \
  --ref npm

⚠️ 重要提示

返回的 API 密鑰只展示一次。請將其存儲在已被忽略的 env 文件、部署密鑰或密鑰管理器中。切勿在日誌中打印完整密鑰、將其提交到倉庫，或寫入目標項目的 README 文件中。

---

🚀 快速開始

檢查與 API 密鑰關聯的工作區：

yolfi auth:status

在用戶提供錢包地址後配置結算錢包：

yolfi settlement:configure --json examples/organization.settlement.json

配置 Webhook 投遞：

yolfi webhooks:configure \
  --url https://example.com/api/yolfi/webhook \
  --adapter STRIPE

在創建新的支付鏈接前，先列出已存在的支付鏈接以避免重複：

yolfi paylinks:list --page 1 --rows 10

創建一個一次性支付鏈接：

yolfi paylinks:create --json examples/paylink.one-time.json

基於支付鏈接創建公開支付發票：

yolfi payments:create --json examples/payment.create.json

查詢支付狀態：

yolfi payments:status --id <paymentId>

💡 使用建議

每個 CLI 命令都會輸出 JSON，便於智能體直接解析結果，而無需從終端文本中抓取數據。

---

🛰️ 加密貨幣支付 MCP 服務器

Yolfi Agent Kit 在同一 npm 包中內置了一個 stdio MCP 服務器：

{
  "mcpServers": {
    "yolfi-api": {
      "command": "npx",
      "args": ["-y", "@yolfi/agent", "mcp"],
      "env": {
        "YOLFI_API_KEY": "..."
      }
    },
    "yolfi-knowledge": {
      "command": "npx",
      "args": ["-y", "@yolfi/agent", "mcp"]
    }
  }
}

• yolfi_agent_register 調用公開的 agent 註冊端點，無需 YOLFI_API_KEY。
• 私有 yolfi-api 工具需要註冊後返回的 API 密鑰。
• yolfi-knowledge 資源可幫助智能體在尚未持有密鑰時理解集成路徑。

可用的 MCP 工具：

• yolfi_agent_register
• yolfi_auth_status
• yolfi_organization_get
• yolfi_organization_update
• yolfi_settlement_configure
• yolfi_webhooks_configure
• yolfi_paylinks_create
• yolfi_paylinks_list
• yolfi_paylinks_get
• yolfi_paylinks_disable
• yolfi_payments_create
• yolfi_payments_status
• yolfi_webhooks_verify

⚠️ 重要提示

諸如 yolfi_paylinks_disable 這類破壞性工具，必須在用戶明確確認後才能運行。

---

🧾 面向 Agent 的 JSON 工作流

智能體可以編寫一個 payload 文件並傳給 CLI：

{
  "name": "Premium Download",
  "description": "One-time access to a digital product.",
  "type": "ONE_TIME",
  "price": "19",
  "currency": "USD",
  "collectEmail": true,
  "metadata": {
    "source": "agent",
    "productSlug": "premium-download"
  }
}

然後運行：

yolfi paylinks:create --json ./paylink.json

💡 使用建議

智能體應將返回的支付鏈接 ID 保存在目標應用的 env/config 中，並使用 Yolfi 公開支付端點為面向客戶的結賬和狀態輪詢服務。

---

🧰 命令一覽

yolfi auth:agent-register --project-name "App" --agent-name "Codex" --integration-intent accept_payments
yolfi auth:status
yolfi organization:update --json organization.json
yolfi settlement:configure --json settlement.json
yolfi webhooks:configure --url https://example.com/api/yolfi/webhook --adapter STRIPE
yolfi paylinks:create --json paylink.json
yolfi paylinks:list --page 1 --rows 10
yolfi paylinks:get --id <paylinkId>
yolfi paylinks:disable --id <paylinkId> --confirm
yolfi payments:create --json payment.json
yolfi payments:status --id <paymentId>
yolfi webhooks:verify --payload payload.json --signature <signature>
yolfi mcp

---

🔌 端點適配器矩陣

Yolfi Agent Kit 不會創建第二套 /api/agent/* API，而是將智能體操作映射到現有的 Yolfi API：

智能體操作	後端端點	認證
註冊 Yolfi 工作區	POST /api/auth/agent/register	公開；無需 API 密鑰
檢查賬戶	GET /api/private/organization/current	bearer API 密鑰
配置組織、Webhook、結算錢包	PUT /api/private/organization/current	bearer API 密鑰
獲取 API 密鑰狀態	GET /api/private/organization/api-key	bearer API 密鑰或 cookie
創建支付鏈接	POST /api/private/paylinks/create	bearer API 密鑰
列出支付鏈接	GET /api/private/paylinks	bearer API 密鑰
獲取支付鏈接	GET /api/private/paylinks/:id	bearer API 密鑰
編輯支付鏈接	POST /api/private/paylinks/edit	bearer API 密鑰
禁用支付鏈接	POST /api/private/paylinks/disable	bearer API 密鑰 + 確認
公開支付鏈接結賬信息	GET /api/public/paylinks/:id	公開
創建公開支付發票	POST /api/public/payments	公開
支付狀態	GET /api/public/payments/:id	公開
商戶交易記錄	GET /api/private/transactions	bearer API 密鑰

---

💻 SDK 使用示例

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

const yolfi = new YolfiClient({
  apiKey: process.env.YOLFI_API_KEY,
});

const account = await yolfi.authStatus();

const paylink = await yolfi.createPaylink({
  name: "Premium Download",
  description: "One-time access to a digital product.",
  type: "ONE_TIME",
  price: "19",
  currency: "USD",
  collectEmail: true,
  metadata: {
    source: "agent",
    productSlug: "premium-download",
  },
});

console.log(account.success);
console.log(paylink.data?.id ?? paylink.id);

---

🔒 Webhook 驗證

Yolfi 使用 X-Yolfi-Signature 對 Webhook payload 進行簽名。在解析和信任事件之前，請先驗證原始請求體：

import { verifyWebhookSignature } from "@yolfi/agent";

const valid = verifyWebhookSignature(
  rawBody,
  request.headers["x-yolfi-signature"],
  process.env.YOLFI_API_KEY,
);

if (!valid) {
  throw new Error("Invalid Yolfi webhook signature");
}

⚠️ 重要提示

不要把前端的重定向當作支付成功的憑證。請使用經過驗證的 Webhook 和 Yolfi 支付狀態查詢確認支付結果。

---

🤝 配合 AI 編程智能體使用

Yolfi Agent Kit 專為「智能體驅動的支付工作流」設計 —— 用戶只需給出高級指令，例如「add payments」「sell this digital product」「add a donation button」「charge for this game」或「gate this feature behind payment」。

• Codex：檢查倉庫、添加結賬路由/組件、配置環境變量，並將經過驗證的 Webhook 接入現有權益邏輯。
• Claude Code：使用 MCP 服務器和 Agent Skill 添加支付鏈接、服務端處理器以及狀態查詢，並在錢包與價格決策上獲得用戶批准。
• Cursor：添加支付 UI 和後端處理器，同時確保 Yolfi 密鑰不進入已提交的源代碼。
• OpenClaw 及自定義智能體：通過 CLI、SDK、MCP 工具和 JSON payload，將產品構建工作流接入 Yolfi。

推薦的智能體路徑：

auth:status -> organization:get -> paylinks:list -> user approval -> settlement:configure -> webhooks:configure -> paylinks:create -> install checkout -> verify webhook -> payments:status

---

🍳 Agent 操作示例

examples/ 目錄包含可直接複製粘貼的工作流與 JSON payload：

• examples/codex/add-yolfi-payments.md
• examples/claude-code/add-yolfi-payments.md
• examples/cursor/add-yolfi-payments.md
• examples/paylink.one-time.json
• examples/paylink.recurring.json
• examples/organization.settlement.json
• examples/payment.create.json
• examples/webhook.stripe-adapter.json

---

🚫 本包不是

• 它不是一個獨立的 Yolfi 控制檯。
• 它不是錢包提供商。
• 它不是一套包含重複業務邏輯的第二支付 API。
• 它不會憑空捏造結算錢包、產品名稱、價格、幣種、訂閱或捐贈金額。
• 它不會在未獲得用戶確認的情況下執行破壞性操作。
• 它不會將密鑰存儲於源代碼中。
• 它不會將重定向當作支付確認。

---

⚠️ 當前限制

• MCP 服務器目前使用 stdio 傳輸。
• Webhook 簽名使用當前 Yolfi 簽名約定。若 Yolfi 未來將 Webhook 密鑰與組織 API 密鑰分離，本包將開放新的密鑰配置路徑。
• Agent 註冊僅返回一次 API 密鑰。智能體必須將其存儲於已忽略的 env 文件、部署密鑰或密鑰管理器中。
• 最終支付確認應來源於經驗證的 Webhook 與支付狀態查詢，而不是來自 UI 重定向。
• MCP 目錄審核獨立於本包。在列入被接受前，請勿聲稱已獲得官方目錄批准。

---

🔍 本包服務的目標搜索詞

開發者與智能體構建者常在以下場景中查找：

• AI agent payment integration
• AI coding agent payments
• MCP payment server
• MCP crypto payments
• crypto checkout API for agents
• payment links for AI agents
• stablecoin checkout for apps
• webhook payment verification
• agentic payment workflow
• add crypto payments with Codex, Claude Code, or Cursor

Yolfi Agent Kit 是上述工作流的包入口。

---

🔗 相關鏈接

• Yolfi：https://yolfi.com
• Agent Kit 頁面：https://yolfi.com/ai-agent-kit
• 文檔：https://docs.yolfi.com/en/agent-kit
• LLM 索引：https://docs.yolfi.com/llms.txt
• 完整 LLM 上下文：https://docs.yolfi.com/llms-full.txt
• npm 包：https://www.npmjs.com/package/@yolfi/agent
• GitHub 倉庫：https://github.com/yolfinance/yolfi-agent
• Glama MCP 列表：https://glama.ai/mcp/servers/yolfinance/yolfi-agent
• 集成指南：https://yolfi.com/blog/ai-agent-payment-integration-api