Yolfi Payments MCP

Yolfi Agent Kit：AIエージェント決済インテグレーション

暗号資産およびステーブルコインの決済向けAIエージェント決済インテグレーションです。@yolfi/agent は、ローカル MCP サーバー、JSON CLI、JavaScript SDK、および Yolfi Payments Agent Skill を提供し、決済リンク、Checkout Sessions、決済ステータスの確認、署名付き Webhook に対応します。

AI インテグレーションでは、連携したいプロジェクト内のエージェントに次のメッセージをコピーしてください。

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

エージェントはプロジェクトを調査し、既存の接続を再利用するか、サポートされている接続方法を選択して、アカウント設定を読み取り、依頼されたインテグレーションを実装します。アカウント所有者は、アカウントの認証を完了し、受取ウォレットや商品の価格など、不足している選択事項のみを指定します。アカウントを接続しただけでは、インテグレーションは完了しません。

ウェブサイト | Agent Kit | AI ガイド | エージェント接続リファレンス | HTTP API | CLI リファレンス | npm | GitHub | MCP ディレクトリ

言語

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

使い始める方法を選択

• **AI インテグレーション：**上記のメッセージを送信してください。エージェントガイドでワークフローを説明しています。SKILL.mdにはパッケージ化された手順が記載されています。
• **HTTP API：**認証、リクエスト本文、チェックアウト、Webhook についてはAPI ガイドを使用してください。
• **ターミナルの自動化：**以下のコマンドとCLI リファレンスを使用してください。
• **JavaScript アプリケーション：**SDK をインストールし、以下のサーバー／ランタイムのガイダンスに従ってください。

暗号資産決済インテグレーションの機能

• SaaS 製品、デジタルダウンロード、クレジット、ゲーム、寄付に対応するホスト型チェックアウトと単発決済リンク。
• Yolfi アカウントがサポートするサブスクリプションのフロー向け定期決済リンク。
• 再試行に使える安定した冪等性キーを備えた、サーバー側で価格を設定する注文向け Checkout Sessions。
• アプリケーション既存のアクセス権およびサブスクリプションのロジックに対応する、決済ステータスの確認と Webhook 署名の検証。
• 既存の Yolfi API を通じた組織設定、選択した決済用ウォレット、独立した Webhook エンドポイント。

Codex、Claude Code、Cursor、ChatGPT、Claude、OpenClaw、Hermes、またはサポート対象の MCP コネクターやローカルツールを備えたその他のエージェントで、インテグレーションのワークフローを使用してください。コマンドを実行できないブラウザー環境やクラウド環境では、サポート対象のリモートコネクターが必要です。各ホストで利用できる接続方法については、接続リファレンスを参照してください。

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

環境でブラウザーを利用できる場合、エージェントは URL を開き、認証後にチェックインを再開します。セットアップを繰り返すと、同じ API 環境の有効期限内の保留中セッションが再利用されます。アカウントへのアクセスは auth:status で確認する必要があります。この確認では、チェックアウトや Webhook のライブ配信は検証されません。

認証情報と保留中の状態は、アトミック書き込みとプロセスロックを使用して ~/.yolfi/config.json に保存されます。サポートされている環境では、ディレクトリとファイルの権限はそれぞれ 0700 と 0600 です。YOLFI_CONFIG_HOME は、分離された設定ディレクトリを指定します。明示的に指定した SDK の認証情報が YOLFI_API_KEY より優先され、YOLFI_API_KEY は保存済みのローカル認証情報より優先されます。ブラウザー認証を使用する場合、プレースホルダーの YOLFI_API_KEY は設定しないでください。

明示的に新しいアカウントを作成する場合、所有者がメールアドレスとプロジェクト名を提示または確認した後、エージェントはメール確認を伴うサインアップを使用できます：

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

最初の呼び出しで確認リンクが送信されます。所有者がリンクを開いた後、エージェントは同じコマンドを再実行します。生成された冪等性キーと保留中のチェックイントークンは永続化されます。省略可能な --idempotency-key は 16～200 文字で、再試行時にも同じ値を使用する必要があります。接続された認証情報は、表示されずに保存されます。既存のメールアドレスには、代わりにブラウザー認証を使用します。最初のサインアップ応答が失われても復旧できます。引き換え後に一度限りの認証情報応答が失われた場合は、auth:status を確認し、必要であればブラウザー認証を再度開始してください。

暗号資産決済用の MCP サーバー

まず、接続済みの Yolfi サーバーを使用してください。接続先の選択は、ブランドだけでなく、エージェント環境で利用できるツールによって決まります。ホストのセットアップ手順全体については、接続リファレンスを参照してください。

認証済みの MCP 接続には、追加の組織 API キーは必要ありません。チェックアウトセッションの作成なども含め、そのツールを引き続き使用してください。別個のローカルワークフローが実際に必要な場合を除き、ローカル 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 を使用します。別途 CLI にログインするのではなく、そのホストで yolfi_auth_status を実行して確認してください。コマンドを実行できない環境では、サポートされているリモートコネクターを使用する必要があります。ホストで自動設定できない場合、エージェントは所有者に必要な操作のみを説明してください。

コアツールには、組織の読み取り／更新、精算設定、Webhook エンドポイントの一覧表示／作成／更新／ローテーション／削除、Paylink の一覧表示／取得／作成／無効化、yolfi_checkout_sessions_create、yolfi_checkout_sessions_get、決済の作成／ステータス確認が含まれます。ツールの利用可否は、接続済みサーバーから確認してください。チェックアウトセッションツールと精算設定のマージには、これらのエンドポイントをサポートするバックエンドが必要です。組織の精算設定の置き換えに、暗黙のうちにフォールバックしないでください。

リソースを作成する前に再利用する

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 を2回作成すると、異なるシークレットを持つ独立したエンドポイントが作成されます。

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 キーやエージェントの認証情報は、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' });

ペイリンクに紐付いたセッションでは、amount と currency の代わりに paylinkId を使用してください。単独のセッションでは、安定した冪等性キーが必要で、一回限りの支払いがサポートされます。公開支払いの作成では、paylinkId または checkoutSessionId に加えて、network と symbol を指定します。顧客のメールアドレスは、直接指定するか、セッションにすでに設定しておく必要があります。支払いのメタデータとペイリンクの paymentMetadata では、フラットな文字列、有限数、またはブール値を使用できます。clientReferenceId には、サブスクリプションの帰属を判定できる、アプリの安定したユーザー ID／顧客 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。ローカルのバージョンやテストの合格は、パッケージの公開やディレクトリの承認を意味するものではありません。