Nexflow Smf

NexFlow Smart Meta-Facilitator (SMF)

The x402-native metered billing and routing brain for AI agents and SaaS APIs on Base.

NexFlow SMF routes, verifies, and settles x402 micropayments on Base. It acts as an intelligent intermediary between payers and facilitators, selecting the optimal route based on cost, latency, and reliability. This repository contains the on-chain settlement contracts, TypeScript SDK, agent manifest specification, and integration examples.

🎴 Browse AgentCard Catalog →

Discover AI agent services with x402 payment routing through NexFlow SMF. Submit your service to the catalog.

📦 What's Included

---

🧩 Skills (Cursor & AI agents)

Canonical list of NexFlow SMF skills. Each skill has a SKILL.md (for Cursor/agents) and lives in nexflow-smf-skills/. Machine-readable manifest: skills-manifest.json · API: GET https://api.nexflowapp.app/.well-known/skills (redirects to manifest).

---

🎴 Browse AgentCard Catalog

Discover NexFlow services as AgentCards, ready for AI agents and x402-aware clients:

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

---

Choose Your Path

Monetize an existing API at the edge (recommended)

Drop a Lambda@Edge function in front of CloudFront. Every request to a protected path must include a valid x402-payment header — otherwise the client gets a 402 Payment Required with payment instructions. No backend changes needed.

How it works:

1. viewer-request — Lambda calls /x402/verify with the payment proof (not billed). If valid, attaches a settlementIntentId and forwards to origin. If invalid, returns 402.
2. origin-response — Lambda reads the settlementIntentId. If origin status < 400, calls /x402/settle to confirm delivery (this is the billable event). Returns the response unchanged.

Get started in 15 minutes:

[AWS CloudFront + Lambda@Edge Quickstart →](./examples/aws-cloudfront-lambdaedge/README.md)

Use the NexFlow SMF SDK directly

For server-side integrations where you control the request lifecycle — route payments, verify intents, and trigger batch settlement from your own code.

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...', });

[Full SDK documentation →](./sdk/README.md)

---

What's in This Repo

---

Services Overview

---

Base Mainnet Contracts

---

🔄 Agent Workflows

NexFlow SMF allows agents to define, publish, and monetize hosted workflows — multi-step compositions of core SMF operations that other agents can invoke via the 402/MPP payment gateway.

• Workflow creation and inspection are free.
• Workflow invocation is paid — the price is computed from the sum of step costs plus a creator-defined markup.
• Workflow creators earn rev-share on every invocation.

Available Core Operations

Workflows can compose any of these paid SMF operations:

Example Workflows

Safety-Capped Session Runner

examples/workflows/safety_capped_session_runner.json

A 5-step workflow that:

1. Creates a session with a requested budget
2. Checks a planned charge against that budget
3. Processes the charge
4. Configures a 90% budget alert
5. Returns current session status

Usage Health Check

examples/workflows/usage_health_check.json

A 3-step diagnostic workflow that:

1. Pulls recent spend timeseries (hourly, configurable window)
2. Checks budget status (zero-cost probe)
3. Returns active alerts

Batch Settlement Runner

examples/workflows/revenue_share_settlement.json

A 5-step workflow demonstrating the full payment lifecycle:

1. Creates a settlement session with a budget
2. Checks that planned charges fit within the budget
3. Processes a batch of charges
4. Settles the batch
5. Returns final session status

The workflow creator earns their standard rev-share (set via creatorShareBps) on every invocation. Rev-share credits accumulate per wallet and are batched for payout when they reach $5+.

Input example:

{

"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" }

How to Register a Workflow

# 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"

Response:

{

"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 } }

How to Invoke a Workflow

# 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" } }'

The first call returns HTTP 402 with a payment challenge:

{

"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." }

After the agent pays (via Tempo MPP or x402), it retries with the proof:

# 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: " \ --data '{ "requestedBudget": { "amount": 500000, "currency": "USDC" }, "plannedCost": { "amount": 50000, "currency": "USDC" } }'

TypeScript Client Example

See examples/client/invokeUsageHealthCheck.ts for a runnable demo of the full 402 → proof → retry flow.

export NEXFLOW_SMF_BASE_URL=http://localhost:3001

export WORKFLOW_ID=wf_abc123_1 npx tsx examples/client/invokeUsageHealthCheck.ts

---

Environment Variables

Sign up or log in at [nexflowapp.app](https://n