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.

---

🧩 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).

Skill	Description
List Facilitators	Discover active x402 facilitators by network/asset before quoting or paying.
Route Matrix	Compare priced routes (fees, latency) across facilitators for USDC on Base.
Route Quote	Get a single priced quote for a chosen facilitator before committing.
Settlement Receipt	Fetch a settlement receipt for a completed x402 payment for logs or audits.
Healthcheck	Ping NexFlow SMF for status and latency before routing payments.
Simulate Charge	See x402 pricing headers without performing a real payment.
Budget Plan	Turn a USDC budget into an approximate number of SMF API calls.

---

🎴 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 →

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 →

---

What's in This Repo

Path	Description
examples/aws-cloudfront-lambdaedge/	15-minute AWS quickstart — Lambda@Edge x402 pay-per-request gating
examples/basic-settlement.ts	End-to-end SDK example: route, verify, settle
sdk/	Zero-dependency TypeScript SDK (@nexflow-smf/smf)
contracts/	Solidity contracts for atomic batch settlement with Merkle proofs
docs/	API reference, facilitator contract, production checklist
AGENT_MANIFEST_V1.md	Agent Manifest spec for machine-to-machine discovery
nexflow-smf-skills/	Cursor-style agent skills (route-matrix, quote, receipt, facilitators, health, simulate, budget)
PRICING.md	Pricing model with example scenarios

---

Services Overview

Service	Description	Status
Smart Meta-Facilitator	Intelligent payment routing, verification, and batch settlement	Live
CloudFront Edge Gating	Lambda@Edge adapter for pay-per-request access via CloudFront	Live
Agent Manifest & Discovery	Machine-readable capability manifest for AI agent integration	Live
Pulse Scheduler	Metered job scheduling with x402 billing (cron, webhooks, tasks)	Live
Action Catalog	Pre-built metered actions (Shopify, Salesforce, data enrichment)	Live

---

Base Mainnet Contracts

Contract	Address	Explorer
AtomicBatchSettlement	0x43A04228152115fDd5663B2Aa559Ebd84D17A49D	BaseScan
USDC	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913	BaseScan

---

Environment Variables

Variable	Required	Description
NEXFLOW_API_KEY	Yes	Your NexFlow API key (nf_live_xxx or nf_test_xxx)
NEXFLOW_BASE_URL	No	Override API URL (default: https://api.nexflowapp.app)

Sign up or log in at nexflowapp.app, go to Developers → API Keys, and click Create API key. Use that key with the examples in this repo.

Never commit API keys or secrets. Use environment variables or a secrets manager.

---

Supported Networks & Tokens

Network	Chain ID	Status
Base mainnet	eip155:8453	Primary

Token	Address	Decimals
USDC	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913	6

---

Documentation

Doc	What's inside
Facilitator API	/verify and /settle contracts, settlementIntentId lifecycle, error handling, retry guidance
API Reference	All endpoints (SMF core, x402 routing, agent discovery), SDK reference, contract ABI
Production Checklist	Idempotency, latency, CloudWatch logging, failure modes, key rotation
Pricing	Pulse metering, facilitator settle-only pricing, example scenarios
Agent Manifest	Machine-to-machine capability discovery spec
SDK README	Full SDK docs: installation, methods, error handling, utilities

---

Development

Building the SDK

cd sdk
npm install
npm run build       # Build for production (CJS + ESM + types)
npm run dev         # Watch mode
npm run typecheck   # Type checking

Running Examples

# 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

We welcome contributions! See CONTRIBUTING.md for guidelines.

Security

For security concerns, see SECURITY.md.

License

MIT License — see LICENSE for details.

---

Links

• Website: nexflowapp.app
• API: api.nexflowapp.app
• Skills manifest (machine-readable): skills-manifest.json · api.nexflowapp.app/.well-known/skills
• Agent Manifest: api.nexflowapp.app/.well-known/agent-manifest
• SDK on npm: @nexflow-smf/smf
• Settlement Contract: BaseScan
• Issues: GitHub Issues
• Optimism RetroPGF: Project

---

Built for the x402 ecosystem on Base