Meterflow Documentation

Payment Flow

Meterflow separates payment movement from payment operations. Solana moves value; Meterflow explains what happened, who paid, what was served, what failed, which provider earned, and whether the agent stayed inside policy.

1. Meter

A provider registers a route, unit, price, accepted asset, recipient wallet, and customer policy.

2. Quote

A caller receives machine-readable payment terms for the requested capability.

3. Pay

The agent or operator submits a Solana payment and retries with proof.

4. Receipt

Meterflow verifies policy, records request state, attributes revenue, and exposes an audit trail.

Protocol Adapter

Meterflow supports x402 and MPP as payment rails over the same product model. The control plane is intentionally protocol-neutral so future HTTP 402-style rails can normalize into the same Meterflow objects: meter, budget decision, receipt, provider revenue row, webhook event, and registry signal.

x402

Machine-readable 402 quotes, Solana USDC settlement context, retry with proof, and receipt updates after verification.

MPP

Challenge, credential, and payment receipt headers for opt-in callers without changing provider meters or dashboards.

One Ledger

Every rail writes to the same receipt graph with payer, provider, route, amount, policy, response, latency, and settlement metadata.

One Budget

Agent spend caps should apply before any supported rail can spend against a protected route or MCP tool.

MPP Payment Rail

MPP is an open machine-to-machine payment protocol for charging API requests, tool calls, or content in the same HTTP flow. Meterflow mounts MPP beside x402 so a provider can keep one meter while callers choose the payment rail they support.

Opt-In

Callers request MPP with `X-Meterflow-Payment-Protocol: mpp`, `Accept-Payment: mpp`, `paymentProtocol=mpp`, or an `Authorization: Payment` retry.

Solana USDC

The current adapter uses the Solana MPP method with a one-time `charge` intent and USDC-denominated route prices.

Receipts

Verified calls return `Payment-Receipt` and write `paymentProtocol`, `paymentIntent`, `paymentMethod`, and `paymentReference` into the Meterflow ledger.

Fallback

x402 remains the default unless a caller opts into MPP or `METERFLOW_DEFAULT_PAYMENT_PROTOCOL=mpp` is configured.

GET /proxy/gateway/mtr_abc123/wallet/7Kp...
X-Meterflow-Payment-Protocol: mpp
Accept-Payment: mpp

402 response:
WWW-Authenticate: Payment ...
X-Meterflow-Payment-Protocol: mpp

paid retry:
Authorization: Payment ...
X-Meterflow-Payment-Protocol: mpp

success headers:
Payment-Receipt: ...
X-Meterflow-Payment-Protocol: mpp
X-Payment-Transaction: 5h6tx...

Required production config: `MPP_SECRET_KEY`, `MPP_PAY_TO` or `X402_PAY_TO`, and a Solana RPC URL through `MPP_SOLANA_RPC_URL` or `HELIUS_RPC_URL`.

Dashboard

The dashboard is the product surface. It is where providers manage metered products and where agent operators control spend before autonomous workflows run.

MetersDefine the route, billing unit, price, asset, provider, owner wallet, and route status.
ReceiptsVisualize successful and failed paid requests with payer wallet, proof, amount, route, and response status.
Agent BudgetsAttach limits to a wallet, client key, task, route allowlist, and expiration window.
MCP ToolsPackage, price, meter, and monitor MCP tools through hosted gateway paths.
Provider RegistryExpose useful endpoints with price, uptime, latency, receipt volume, and utility-driven ranking signals.
Settlement WalletInspect wallet context for provider funding, settlement operations, and gateway costs.

Meters

A meter describes what is billable. Meterflow treats hosted APIs, MCP tools, data feeds, and provider workflows as products that share one accounting model.

POST /v1/meters
Authorization: Bearer mf_xxxxx
Content-Type: application/json

{
  "route": "/v1/risk-score",
  "unit": "request",
  "price": "0.006",
  "asset": "USDC",
  "network": "solana-mainnet",
  "recipientWallet": "provider_wallet",
  "status": "active"
}

DELETE /v1/meters/:id

Wrap Your API In 10 Minutes

Hosted gateway meters let providers keep their API on their own infrastructure while Meterflow handles payment requirements, budget checks, receipts, failed-payment state, revenue views, and webhook events.

POST /v1/meters
Authorization: Bearer mf_live_xxxxx_secret
Content-Type: application/json

{
  "targetUrl": "https://api.example.com",
  "method": "GET",
  "unit": "lookup",
  "priceUsd": 0.01,
  "providerName": "Example Data API",
  "status": "test"
}

If `route` is omitted, Meterflow generates `/gateway/{meterId}/*`. Callers use `https://meterflow.fun/proxy/gateway/{meterId}/path`. Upstream auth can be attached to the meter, but secret values are never returned by the API.

POST /v1/meters/:id/test

returns:
- generated hosted route
- payment quote preview
- target host
- whether the meter is currently billable

Receipts

Receipts connect payment proof to usage. They are the difference between “money moved” and “this route was served to this agent under this policy.” Wallet-authenticated users can see API-key receipts and x402 receipts paid by their wallet.

{
  "id": "mf_rcpt_41bd",
  "route": "/v1/risk-score",
  "payerWallet": "7Kp...91a",
  "clientKey": "mf_agent_***",
  "baseAmountUsd": "0.006",
  "protocolFeeUsd": "0.00006",
  "protocolFeeBps": 100,
  "amount": "0.00606",
  "asset": "USDC",
  "status": "verified",
  "responseStatus": 200
}

Agent Budgets

Agent budgets let operators approve bounded spend without handing automation unlimited wallet access.

wallet: 7Kp...91a
agent: market-research-bot
client_key: mf_agent_***
daily_cap: 12.00 USDC
per_call_cap: 0.02 USDC
allowed_routes:
  - /mcp/token-risk
  - /gateway/mtr_wallet_trace/*
  - /gateway/mtr_risk_feed/*
on_exhausted: stop_workflow
on_new_route: require_operator_approval

MCP Tools

MCP tools are treated as meters, so budgets, receipts, revenue views, settlement metadata, registry metadata, and exports work the same way as API routes. The built-in token-risk tool is a demo; builders can package their own tools.

POST /v1/mcp-tools
Authorization: Bearer mf_xxxxx
Content-Type: application/json

{
  "name": "Token Risk Score",
  "manifestUrl": "https://example.com/mcp/manifest.json",
  "priceUsd": 0.006,
  "status": "test"
}

DELETE /v1/mcp-tools/:id

Provider Registry

The registry is the distribution layer for paid agent services. A listed provider should be discoverable by route, category, price, protocol support, latency, receipt volume, uptime, and verification status.

{
  "provider": "Example Data API",
  "category": "wallet-intelligence",
  "route": "/gateway/mtr_abc123/*",
  "unit": "lookup",
  "priceUsd": 0.01,
  "protocols": ["x402", "mpp"],
  "receiptVolume24h": 18420,
  "latencyP50Ms": 142,
  "verification": "mflow_verified"
}

Registry ranking is one of the cleanest MFLOW utility surfaces: holders and bonded providers can unlock verification, fee relief, better listing controls, higher route limits, and longer receipt retention without changing USDC settlement.

MFLOW Utility

USDC is the payment asset for request settlement. MFLOW is the utility layer for provider verification, fee relief, registry ranking, higher policy limits, longer receipt retention, premium analytics, and future provider bonding. Non-holders can still use paid Meterflow routes, but their quotes include a protocol fee. Holders can receive reduced or zero protocol fees depending on the configured utility tier.

Provider ReputationMFLOW-backed providers can receive dashboard badges and registry preference.
Non-Holder FeeMetered quotes and receipts track base price, protocol fee, and total USDC amount.
Control LimitsUtility tiers can increase meter counts, budget counts, webhook volume, and receipt retention.
Future BondingProvider bonding is represented in the product model but does not require staking contracts in the current MVP.

Meterflow Routes

Meterflow routes are priced product surfaces. The built-in token-risk tool demonstrates the MCP pattern; hosted gateway routes are how providers wrap their own APIs without moving infrastructure into Meterflow.

Route	Category	Use
/mcp/token-risk	MCP Tool	Built-in paid tool call with budget checks and receipts
/gateway/{meterId}/*	Hosted API	Provider-owned endpoint wrapped with pricing, payment, and accounting
/v1/meters	Control Plane	Create, test, and manage billable product surfaces
/v1/receipts	Ledger	Inspect paid request proof, payer, amount, policy, and response status
/v1/providers/revenue	Provider Revenue	Roll up calls and estimated earnings by meter

Authentication

Operators connect a Solana wallet to create and manage client keys. Registration uses a server-issued nonce so wallet signatures cannot be replayed.

GET /auth/challenge?wallet=YOUR_SOLANA_ADDRESS

POST /auth/register
Content-Type: application/json

{
  "walletAddress": "YOUR_SOLANA_ADDRESS",
  "signature": "BASE58_SIGNATURE",
  "message": "Meterflow Wallet Challenge\nDomain: meterflow.fun\nProduct: Meterflow\nAction: register\nWallet: YOUR_SOLANA_ADDRESS\nNonce: ...\nTimestamp: ..."
}

Use the returned key as a bearer token.

Authorization: Bearer mf_xxxxx

Provider Revenue And Webhooks

Providers can query revenue by meter and subscribe to signed webhook events for receipt creation, verified settlement, payment failure, and budget exhaustion.

GET /v1/providers/revenue
GET /v1/webhooks
POST /v1/webhooks

{
  "url": "https://provider.example.com/meterflow/events",
  "events": ["receipt.created", "receipt.verified", "payment.failed"]
}

Gateway API

The gateway exposes Meterflow-native routes for provider onboarding, hosted route testing, receipt inspection, and paid request delivery.

POST /v1/meters
Authorization: Bearer mf_xxxxx
Content-Type: application/json

{
  "targetUrl": "https://api.provider.com/risk",
  "method": "GET",
  "unit": "risk lookup",
  "priceUsd": 0.006,
  "providerName": "Provider Risk API"
}

GET /proxy/gateway/mtr_abc123/wallet/7Kp...
X-Meterflow-Payment-Protocol: mpp
Accept-Payment: mpp

GET /v1/receipts?limit=25
Authorization: Bearer mf_xxxxx
Accept: application/json

SDK

The JavaScript SDK wraps the control-plane routes for hosted meters, receipts, budgets, MCP tools, revenue views, and webhooks.

npm install @meterflow/sdk

import { MeterflowClient } from '@meterflow/sdk';

const client = new MeterflowClient({ apiKey: 'mf_xxxxx' });

const { meter } = await client.createHostedMeter({
  targetUrl: 'https://api.provider.com/risk',
  method: 'GET',
  unit: 'risk lookup',
  priceUsd: 0.006,
  providerName: 'Provider Risk API'
});

Settlement

Meterflow is designed around USDC-denominated request accounting on Solana. The dashboard treats the wallet as the source of identity, funding, budget approval, and settlement context.

Provider walletReceives revenue for the metered route.
Operator walletControls keys, budgets, and revocation for agents.
Agent client keyIdentifies the automated caller and applies policy before spend.
Receipt ledgerLinks quote, proof, response, amount, route, and payer into one searchable record.

Build with Meterflow.

Payment Flow

Protocol Adapter

MPP Payment Rail

Dashboard

Meters

Wrap Your API In 10 Minutes

Receipts

Agent Budgets

MCP Tools

Provider Registry

MFLOW Utility

Meterflow Routes

Authentication

Provider Revenue And Webhooks

Gateway API

SDK

Settlement