nexflow-smf

NexFlow Smart Meta-Facilitator (SMF)

面向 Base 上 AI Agent 和 SaaS API 的 x402 原生计量计费与路由大脑。

NexFlow SMF 可在 Base 上路由、验证并结算 x402 小额支付。它是付款方与 Facilitator 之间的智能中介，会根据成本、延迟和可靠性选择最优路由。本仓库包含链上结算合约、TypeScript SDK、Agent 清单规范和集成示例。

🎴 浏览 AgentCard 目录 →

探索通过 NexFlow SMF 进行 x402 支付路由的 AI Agent 服务。提交你的服务至目录。

📦 包含内容

组件	描述
contracts/	用于原子批量结算并验证 Merkle 证明的 Solidity 合约
sdk/	零依赖 TypeScript SDK（@nexflow-smf/smf），用于路由、验证和结算
examples/	可直接运行的示例，展示常见集成模式
examples/workflows/	适用于 NexFlow SMF 工作流主机的 JSON 工作流定义
examples/client/	简洁的 TypeScript 客户端，展示 402 → 支付 → 重试模式

---

🧩 技能（Cursor 和 AI Agent）

NexFlow SMF 技能的权威列表。每项技能都包含一个 SKILL.md（供 Cursor/Agent 使用），并位于 nexflow-smf-skills/ 中。机器可读清单：skills-manifest.json · API：GET https://api.nexflowapp.app/.well-known/skills（重定向至清单）。

技能	描述
列出 Facilitator	在报价或付款前，按网络/资产查找活跃的 x402 Facilitator。
路由矩阵	比较 USDC 在 Base 上各 Facilitator 的定价路由（费用、延迟）。
路由报价	在确认前，获取所选 Facilitator 的单条定价报价。
结算收据	获取已完成 x402 付款的结算收据，用于日志记录或审计。
健康检查	在路由付款前，向 NexFlow SMF 发送请求以检查状态和延迟。
模拟收费	查看 x402 定价标头，而不进行实际付款。
预算规划	将 USDC 预算换算为大致可调用 SMF API 的次数。

---

🎴 浏览 AgentCard 目录

以 AgentCard 的形式探索 NexFlow 服务，适用于 AI Agent 和支持 x402 的客户端：

https://nexflow-agentcards.pages.dev/

---

选择你的路径

在边缘为现有 API 增加变现能力（推荐）

在 CloudFront 前部署一个 Lambda@Edge 函数。对受保护路径的每个请求都必须包含有效的 x402-payment 标头，否则客户端会收到附带付款说明的 402 Payment Required。无需修改后端。

工作原理：

1. viewer-request — Lambda 使用付款证明调用 /x402/verify（不计费）。如果有效，则附加 settlementIntentId 并转发至源站；如果无效，则返回 402。
2. origin-response — Lambda 读取 settlementIntentId。如果源站状态码 < 400，则调用 /x402/settle 确认交付（这是计费事件）。原样返回响应。

15 分钟即可开始：

AWS CloudFront + Lambda@Edge 快速入门 →

直接使用 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...',
});

SDK 完整文档 →

---

此仓库包含的内容

路径	说明
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 参考、facilitator 合约、生产环境检查清单
AGENT_MANIFEST_V1.md	用于机器间发现的 Agent Manifest 规范
nexflow-smf-skills/	Cursor 风格的 Agent 技能（route-matrix、quote、receipt、facilitators、health、simulate、budget）
PRICING.md	定价模型及示例场景

---

服务概览

服务	说明	状态
Smart Meta-Facilitator	智能支付路由、验证和批量结算	已上线
CloudFront Edge Gating	用于通过 CloudFront 按请求付费访问的 Lambda@Edge 适配器	已上线
Agent Manifest & Discovery	供 AI Agent 集成使用的机器可读能力清单	已上线
Pulse Scheduler	使用 x402 计费的计量式任务调度（cron、webhooks、任务）	已上线
Action Catalog	预构建的计量式操作（Shopify、Salesforce、数据丰富）	已上线

---

Base 主网合约

合约	地址	区块浏览器
AtomicBatchSettlement	0x43A04228152115fDd5663B2Aa559Ebd84D17A49D	BaseScan
USDC	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913	BaseScan

---

🔄 Agent 工作流

NexFlow SMF 允许 Agent 定义、发布并变现托管工作流——这些工作流由多个 SMF 核心操作组合而成，其他 Agent 可通过 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 个步骤的工作流：

1. 创建具有指定预算的会话
2. 检查计划费用是否超出该预算
3. 处理费用
4. 配置 90% 预算警报
5. 返回当前会话状态

用量健康检查

examples/workflows/usage_health_check.json

一个包含 3 个步骤的诊断工作流：

1. 获取近期时序支出数据（按小时统计，可配置时间范围）
2. 检查预算状态（零成本探测）
3. 返回活动警报

批量结算运行器

examples/workflows/revenue_share_settlement.json

此工作流包含 5 个步骤，演示完整的支付生命周期：

1. 使用预算创建结算会话
2. 检查计划中的扣款是否在预算范围内
3. 处理一批扣款
4. 结算该批次
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."
}

Agent 通过 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 注册或登录，前往 开发者 → API 密钥，然后点击 创建 API 密钥。在此仓库的示例中使用该密钥。

切勿提交 API 密钥或机密信息。 请使用环境变量或机密管理器。

---

支持的网络和代币

网络	链 ID	状态
Base 主网	eip155:8453	主要

代币	地址	小数位数
USDC	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913	6

---

文档

文档	内容
Facilitator API	/verify 和 /settle 合约、settlementIntentId 生命周期、错误处理、重试指南
API Reference	所有端点（SMF 核心、x402 路由、Agent 发现）、SDK 参考、合约 ABI
Production Checklist	幂等性、延迟、CloudWatch 日志记录、故障模式、密钥轮换
Pricing	Pulse 计量、仅结算的 facilitator 定价、示例场景
Agent Manifest	机器间能力发现规范
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
• Agent 清单：api.nexflowapp.app/.well-known/agent-manifest
• npm 上的 SDK：@nexflow-smf/smf
• 结算合约：BaseScan
• 问题反馈：GitHub Issues
• Optimism RetroPGF：项目

---

专为 Base 上的 x402 生态系统打造