nexflow-smf について
nexflow-smfは、Base上のx402決済をルーティング、検証、精算する仕組みです。従量課金APIやAIエージェントサービスの開発者向けに、TypeScript SDK、オンチェーン一括精算コントラクト、ワークフロー例、エージェントスキルを備えています。
主な機能
- 01コスト・遅延・信頼性で決済経路を選択
- 02決済インテントの検証と精算
- 03Merkle証明対応のアトミック一括精算
- 04TypeScript SDKと連携例
- 05ホスト型従量課金ワークフロー
活用シーン
- 01x402決済でAPIリクエストを制御
- 02サーバー側で決済をルーティング・精算
- 03予算確認と一括請求をワークフロー化
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
ツール
ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。
詳細
NexFlow Smart Meta-Facilitator (SMF)
Base上のAIエージェントとSaaS API向けに、x402ネイティブの従量課金とルーティングを実現する頭脳です。
NexFlow SMFは、Base上でx402マイクロペイメントのルーティング、検証、決済を行います。支払者とファシリテーターの間に立つインテリジェントな仲介役として、コスト、レイテンシ、信頼性に基づいて最適なルートを選択します。このリポジトリには、オンチェーン決済コントラクト、TypeScript SDK、エージェントマニフェスト仕様、統合例が含まれています。
🎴 AgentCardカタログを見る →
NexFlow SMF経由のx402決済ルーティングに対応したAIエージェントサービスをご覧ください。カタログへのサービスの登録もできます。
📦 含まれるもの
| コンポーネント | 説明 |
|---|---|
contracts/ | マークル証明の検証に対応した、アトミックな一括決済用のSolidityコントラクト |
sdk/ | ルーティング、検証、決済を行う、依存関係ゼロのTypeScript SDK（@nexflow-smf/smf） |
examples/ | 一般的な統合パターンを示す、すぐに実行できるサンプル |
examples/workflows/ | NexFlow SMFワークフローホスト用のJSONワークフロー定義 |
examples/client/ | 402 → 支払い → 再試行のパターンを示す、最小構成のTypeScriptクライアント |
🧩 スキル（CursorとAIエージェント）
NexFlow SMFスキルの正式な一覧です。各スキルにはSKILL.md（Cursor／エージェント向け）があり、nexflow-smf-skills/に格納されています。機械可読なマニフェスト：skills-manifest.json · API：GET https://api.nexflowapp.app/.well-known/skills（マニフェストにリダイレクトします）。
| スキル | 説明 |
|---|---|
| ファシリテーター一覧 | 見積もりや支払いの前に、ネットワーク／アセットごとにアクティブなx402ファシリテーターを確認します。 |
| ルートマトリクス | Base上のUSDCについて、ファシリテーター間の料金付きルート（手数料、レイテンシ）を比較します。 |
| ルート見積もり | 選択したファシリテーターの、確定前の単一の料金付き見積もりを取得します。 |
| 決済レシート | 完了したx402決済の決済レシートを取得し、ログや監査に利用します。 |
| ヘルスチェック | 決済のルーティング前に、NexFlow SMFにステータスとレイテンシを問い合わせます。 |
| 課金のシミュレーション | 実際に支払いを行わずに、x402の料金ヘッダーを確認します。 |
| 予算プラン | USDCの予算から、SMF APIをおおよそ何回呼び出せるかを算出します。 |
🎴 AgentCardカタログを見る
AIエージェントとx402対応クライアントがすぐに利用できる、AgentCardとして公開されたNexFlowサービスをご覧ください。
https://nexflow-agentcards.pages.dev/
利用方法を選ぶ
既存APIをエッジで収益化する（推奨）
CloudFrontの前段にLambda@Edge関数を配置します。保護されたパスへのリクエストには、有効なx402-paymentヘッダーが必要です。ヘッダーがない場合、クライアントには支払い手順を含む402 Payment Requiredが返されます。バックエンドの変更は不要です。
仕組み：
- viewer-request — Lambdaが支払い証明を使って
/x402/verifyを呼び出します（課金対象外）。有効な場合はsettlementIntentIdを付与してオリジンに転送し、無効な場合は402を返します。 - origin-response — Lambdaが
settlementIntentIdを読み取ります。オリジンのステータスが400未満の場合、/x402/settleを呼び出して配信を確定します（これが課金対象のイベントです）。レスポンスは変更せずに返します。
15分で始める：
NexFlow SMF SDKを直接使う
リクエストのライフサイクルを制御できるサーバーサイド統合向けです。独自のコードから決済をルーティングし、インテントを検証して、一括決済を実行できます。
npm install @nexflow-smf/smf
import { NexFlowSMFClient } from '@nexflow-smf/smf';
const smf = new NexFlowSMFClient({
baseUrl: 'https://api.nexflowapp.app',
apiKey: process.env.NEXFLOW_API_KEY!,
});
// Route a payment
const route = await smf.route({
amount_wei: '1000000',
token_address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
chain_id: 'eip155:8453',
payment_id: 'order-123',
});
// Verify a payment intent
const result = await smf.verify({
payment_intent: 'x402:1:base:0xabc...',
recipient_address: '0xYourAddress...',
});
このリポジトリの内容
| パス | 説明 |
|---|---|
examples/aws-cloudfront-lambdaedge/ | 15 分で始められる AWS クイックスタート — Lambda@Edge による x402 のリクエストごとのアクセス制御 |
examples/basic-settlement.ts | ルーティング、検証、決済を行う SDK のエンドツーエンドの例 |
sdk/ | 依存関係ゼロの TypeScript SDK（@nexflow-smf/smf） |
contracts/ | Merkle 証明を用いたアトミックなバッチ決済のための Solidity コントラクト |
docs/ | API リファレンス、ファシリテーターコントラクト、本番環境チェックリスト |
AGENT_MANIFEST_V1.md | マシン間での検出に使う Agent Manifest 仕様 |
nexflow-smf-skills/ | Cursor スタイルのエージェントスキル（route-matrix、quote、receipt、facilitators、health、simulate、budget） |
PRICING.md | シナリオ例を含む料金モデル |
サービス概要
| サービス | 説明 | ステータス |
|---|---|---|
| Smart Meta-Facilitator | インテリジェントな決済ルーティング、検証、バッチ決済 | 稼働中 |
| CloudFront Edge Gating | CloudFront 経由でリクエストごとのアクセス制御を行う Lambda@Edge アダプター | 稼働中 |
| Agent Manifest & Discovery | AI エージェントとの連携に使う、機械可読な機能マニフェスト | 稼働中 |
| Pulse Scheduler | x402 課金による従量制ジョブスケジューリング（cron、ウェブフック、タスク） | 稼働中 |
| Action Catalog | 事前構築済みの従量制アクション（Shopify、Salesforce、データエンリッチメント） | 稼働中 |
Base メインネットコントラクト
| コントラクト | アドレス | エクスプローラー |
|---|---|---|
| AtomicBatchSettlement | 0x43A04228152115fDd5663B2Aa559Ebd84D17A49D | BaseScan |
| USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | BaseScan |
🔄 エージェントのワークフロー
NexFlow SMF では、エージェントがホスト型ワークフロー（SMF の中核操作を複数ステップで組み合わせたもの）を定義、公開、収益化でき、他のエージェントは 402/MPP 決済ゲートウェイ経由でそれらを呼び出せます。
- ワークフローの作成と確認は無料です。
- ワークフローの呼び出しは有料です — 料金は各ステップのコストの合計に、作成者が定めた上乗せ額を加えて算出されます。
- ワークフローの作成者は、呼び出しごとに収益分配を受け取ります。
利用可能な中核操作
ワークフローでは、以下の有料 SMF 操作を任意に組み合わせられます。
| 操作 | 説明 |
|---|---|
create_session | 予算を設定して従量制セッションを作成する |
budget_check | 予定されている料金が予算内か確認する |
budget_diagnostics | セッションを分析して予算超過のリスクを調べる |
process_charges | セッションまたは呼び出し元から料金を差し引く |
verify_payment | 決済記述子を検証する |
settle_batch | トランザクションのバッチを決済する |
revenue_share | 期間ごとの収益分配を記録する |
route_quote | 決済ルーティングの見積もりを取得する |
usage_timeseries | 呼び出し元またはセッションの時系列支出データを取得する |
configure_alerts | 予算／利用状況アラートのしきい値を設定する |
monitor_sessions | 予算と支出の状況を含むセッション一覧を取得する |
monitor_alerts | 発生した予算／利用状況アラートを返す |
pricing_estimate | 一連の操作にかかる費用を見積もる |
ワークフローの例
安全上限付きセッションランナー
examples/workflows/safety_capped_session_runner.json
次の 5 ステップで構成されるワークフローです。
- 指定された予算でセッションを作成する
- 予定されている料金が予算内か確認する
- 料金を処理する
- 予算の 90% に達したときのアラートを設定する
- 現在のセッション状況を返す
利用状況のヘルスチェック
examples/workflows/usage_health_check.json
次の 3 ステップで構成される診断ワークフローです。
- 最近の支出の時系列データを取得する（時間単位、期間は設定可能）
- 予算状況を確認する（コストゼロのプローブ）
- 有効なアラートを返す
一括決済ランナー
examples/workflows/revenue_share_settlement.json
決済のライフサイクル全体を示す、5 ステップのワークフローです。
- 予算を設定した決済セッションを作成します
- 予定されている請求額が予算内に収まることを確認します
- 請求を一括処理します
- 一括分を決済します
- 最終的なセッションのステータスを返します
ワークフローの作成者は、呼び出しごとに標準のレベニューシェア（creatorShareBps で設定）を獲得します。レベニューシェアのクレジットはウォレットごとに蓄積され、$5 以上になるとまとめて支払われます。
入力例：
{
"sessionBudget": { "amount": 2000000, "currency": "USDC" },
"charges": [
{ "callerId": "agent_a", "amount": 500000, "description": "API usage week 12" },
{ "callerId": "agent_b", "amount": 300000, "description": "Compute usage week 12" }
],
"settlementPeriod": "2026-03-01/2026-03-31"
}
ワークフローの登録方法
# Register the Safety-Capped Session Runner
curl -X POST "$NEXFLOW_SMF_BASE_URL/nexflow/workflows" \
-H "Content-Type: application/json" \
-H "X-Caller-Id: demo_caller" \
--data-binary "@examples/workflows/safety_capped_session_runner.json"
レスポンス：
{
"workflowId": "wf_abc123_1",
"name": "Safety-Capped Session Runner",
"invokeUrl": "/nexflow/workflows/wf_abc123_1/invoke",
"status": "active",
"steps": 5,
"pricing": { "billingMode": "per_call", "markupBps": 300 }
}
ワークフローの呼び出し方法
# First call — no payment proof → 402 Payment Required
curl -X POST "$NEXFLOW_SMF_BASE_URL/nexflow/workflows/wf_abc123_1/invoke" \
-H "Content-Type: application/json" \
-H "X-Caller-Id: demo_caller" \
--data '{
"requestedBudget": { "amount": 500000, "currency": "USDC" },
"plannedCost": { "amount": 50000, "currency": "USDC" }
}'
最初の呼び出しでは、支払いチャレンジとともに HTTP 402 が返されます。
{
"object": "payment_challenge",
"operation": "workflow_invoke",
"workflow_id": "wf_abc123_1",
"required_amount": 17350,
"currency": "usdc",
"price_breakdown": {
"totalPrice": 17350,
"baseCost": 7000,
"markup": 210,
"platformFee": 149
},
"instructions": "Pay via MPP using the challenge above, then retry with X-PAYMENT-PROOF header."
}
エージェントが（Tempo MPP または x402 を介して）支払いを済ませた後、証明を付けて再試行します。
# Second call — with valid proof → 200 OK
curl -X POST "$NEXFLOW_SMF_BASE_URL/nexflow/workflows/wf_abc123_1/invoke" \
-H "Content-Type: application/json" \
-H "X-Caller-Id: demo_caller" \
-H "X-PAYMENT-PROOF: <base64-encoded-proof-json>" \
--data '{
"requestedBudget": { "amount": 500000, "currency": "USDC" },
"plannedCost": { "amount": 50000, "currency": "USDC" }
}'
TypeScript クライアントの例
examples/client/invokeUsageHealthCheck.ts では、402 → 証明 → 再試行のフロー全体を実行できるデモを確認できます。
export NEXFLOW_SMF_BASE_URL=http://localhost:3001
export WORKFLOW_ID=wf_abc123_1
npx tsx examples/client/invokeUsageHealthCheck.ts
環境変数
| 変数 | 必須 | 説明 |
|---|---|---|
NEXFLOW_API_KEY | はい | NexFlow API キー（nf_live_xxx または nf_test_xxx） |
NEXFLOW_BASE_URL | いいえ | API URL の上書き（デフォルト：https://api.nexflowapp.app） |
NEXFLOW_SMF_BASE_URL | いいえ | ワークフロー呼び出し用の NexFlow SMF ブリッジ URL（デフォルト：http://localhost:3001） |
WORKFLOW_ID | いいえ | クライアントのサンプルスクリプトで使用するワークフロー ID |
nexflowapp.app で登録またはログインし、Developers → API Keys に移動して、Create API key をクリックしてください。このリポジトリのサンプルでは、そのキーを使用します。
API キーやシークレットをコミットしないでください。 環境変数またはシークレットマネージャーを使用してください。
対応ネットワークとトークン
| ネットワーク | チェーン ID | ステータス |
|---|---|---|
| Base メインネット | eip155:8453 | 主要 |
| トークン | アドレス | 小数桁数 |
|---|---|---|
| USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | 6 |
ドキュメント
| ドキュメント | 内容 |
|---|---|
| ファシリテーター API | /verify および /settle のコントラクト、settlementIntentId のライフサイクル、エラー処理、再試行のガイダンス |
| API リファレンス | すべてのエンドポイント（SMF コア、x402 ルーティング、エージェントの検出）、SDK リファレンス、コントラクト ABI |
| 本番環境チェックリスト | 冪等性、レイテンシ、CloudWatch ロギング、障害モード、キーのローテーション |
| 料金 | Pulse の従量課金、ファシリテーターの決済専用料金、シナリオ例 |
| エージェントマニフェスト | マシン間の機能検出仕様 |
| SDK README | SDK の詳細なドキュメント：インストール、メソッド、エラー処理、ユーティリティ |
開発
SDK のビルド
cd sdk
npm install
npm run build # Build for production (CJS + ESM + types)
npm run dev # Watch mode
npm run typecheck # Type checking
サンプルの実行
# SDK example
cd sdk && npm install
npx tsx ../examples/basic-settlement.ts
# Lambda@Edge example
cd examples/aws-cloudfront-lambdaedge
npm install
npm run build # requires NEXFLOW_FACILITATOR_URL and NEXFLOW_API_KEY
貢献
皆さまからの貢献を歓迎します！ガイドラインについては、CONTRIBUTING.md をご覧ください。
セキュリティ
セキュリティに関する懸念については、SECURITY.md をご覧ください。
ライセンス
MIT ライセンス — 詳細は LICENSE をご覧ください。
リンク
- ウェブサイト：nexflowapp.app
- API：api.nexflowapp.app
- スキルマニフェスト（機械可読）：skills-manifest.json · api.nexflowapp.app/.well-known/skills
- エージェントマニフェスト：api.nexflowapp.app/.well-known/agent-manifest
- npm の SDK：@nexflow-smf/smf
- 決済コントラクト：BaseScan
- 課題：GitHub Issues
- Optimism RetroPGF：プロジェクト
Base 上の x402 エコシステム向けに構築
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。