inflow-node

Official Node.js SDKs for the InFlow payments platform.

Accounts & environments

Choose the account for the APIs your application calls:

• @inflowpayai/x402-seller and @inflowpayai/mpp-seller call Seller-only configuration and settlement endpoints. They require a Seller account and reject other account roles with SELLER_ACCOUNT_REQUIRED.
• @inflowpayai/x402-buyer and @inflowpayai/mpp-buyer call authenticated buyer transaction endpoints. Any authenticated InFlow account can buy, including a Seller account. Use a Developer account for a buyer-only API-key integration; do not create a second account when an existing Seller account also needs to buy.

Pass the selected environment to the SDK. The SDK resolves the corresponding API endpoint internally; applications do not set baseUrl.

environment	Register / get your API key at
sandbox (testing)	https://sandbox.inflowpay.ai
production (live)	https://app.inflowpay.ai

For network egress allowlisting only: the SDK makes its outbound API calls to https://sandbox.inflowpay.ai (sandbox) and https://api.inflowpay.ai (production). You never set these yourself.

Create the account and credential in the environment where the integration runs. Sandbox credentials do not authorize production requests, and production credentials do not authorize sandbox requests.

What's here

This monorepo houses InFlow's open-source Node.js packages, organized by product. Every package, example, and product doc folder uses a product prefix (x402-, …) so multiple products can coexist without ambiguity.

Product	What it does	Docs
x402	x402 protocol integration — facilitator client, seller helpers, buyer wrappers.	overview · architecture · wire format · extensions
mpp	MPP (Machine Payments Protocol) integration — InFlow and Tempo methods, seller/buyer drivers.	overview · architecture · wire format · extensions

Packages

All packages publish under the @inflowpayai scope on npm and depend on @x402/core@^2.22.0 as a peer.

Package	npm	Role
@inflowpayai/x402		Core types + HTTP client
@inflowpayai/x402-seller		Facilitator client + seller client + inflowAccepts helper
@inflowpayai/x402-buyer		InflowClient — foundation x402Client subclass for buyers

The MPP packages publish under the same scope but declare mppx@^0.6.28 as their peer instead of @x402/core:

Package	npm	Role
@inflowpayai/mpp		Core: MPP Method definitions, wire types, codec, HTTP client
@inflowpayai/mpp-seller		Method.toServer + InFlow redeem/settle driver — accepting MPP
@inflowpayai/mpp-buyer		Method.toClient + InFlow buyer-endpoint driver — paying via MPP

# Seller accepting MPP payments
pnpm add @inflowpayai/mpp-seller mppx

# Buyer paying via MPP
pnpm add @inflowpayai/mpp-buyer mppx

See the MPP product docs for the seller/buyer integration shape.

Sellers integrate via the foundation V2 middleware (paymentMiddlewareFromConfig from @x402/express, @x402/hono, @x402/fastify, or @x402/next) and pass InFlow's facilitator client into its facilitatorClients array. See the x402 quickstart for the integration shape.

Common installs:

# Seller in Express (foundation middleware + InFlow facilitator)
pnpm add @inflowpayai/x402-seller @x402/express @x402/core express

# Seller in Fastify
pnpm add @inflowpayai/x402-seller @x402/fastify @x402/core fastify

# Seller in Next 16 App Router
pnpm add @inflowpayai/x402-seller @x402/next @x402/core next

# Buyer (InFlow-signed paths only)
pnpm add @inflowpayai/x402-buyer @x402/core

# Buyer composing InFlow with foundation EVM and/or SVM signing
pnpm add @inflowpayai/x402-buyer @x402/core @x402/evm @x402/svm

See the x402 product docs for quickstarts.

Examples

Runnable end-to-end examples live in examples/. Start a seller, then run a buyer against it.

x402:

• x402-seller-express — Express server with three protected routes.
• x402-seller-hono — same shape on Hono via @hono/node-server.
• x402-seller-fastify — same shape on Fastify; @x402/fastify mutates the Fastify instance in place rather than returning middleware.
• x402-seller-next — Next 16 App Router; proxy.ts carries the InFlow wiring and Route Handlers stay x402-free.
• x402-buyer-fetch — paying a protected endpoint with @inflowpayai/x402-buyer + native fetch.
• x402-buyer-axios — paying a protected endpoint with @inflowpayai/x402-buyer + axios.
• x402-buyer-x402-evm — foundation-only EVM buyer (no @inflowpayai/* imports) paying an InFlow seller.
• x402-buyer-x402-svm — foundation-only SVM buyer paying an InFlow seller; same idea on Solana devnet.
• x402-facilitator — InFlow facilitator as a foundation drop-in: vanilla @x402/express seller + foundation-only EVM buyer, with no INFLOW_API_KEY (uses createUnauthenticatedInflowFacilitator).

MPP:

• mpp-aep-seller-express — Express server applying AEP API-key authentication before MPP payment enforcement on the same protected routes.
• mpp-seller-express — Express server accepting MPP payments via mppx's Express adapter + InFlow's inflow seller method, plus a multi-currency /api/checkout route via inflowChargesNodeListener.
• mpp-seller-hono — same shape on Hono via mppx/hono and @hono/node-server; the multi-currency /api/checkout route uses inflowCharges on the core mppx/server instance.
• mpp-buyer-fetch — paying via MPP through a transparently polyfilled global fetch.
• mpp-buyer-manual — paying via MPP through the explicit, non-polyfill mppx.fetch.

Supported runtimes

Node 22 LTS or newer at runtime; the packages ship engines.node: >=22.0.0. CI exercises Node 22 (maintenance LTS until April 2027) and Node 24 (active LTS, April 2028 EOL). Node 20 went EOL on 2026-04-30 and is no longer supported.

Troubleshooting Authentication

InflowApiError exposes the HTTP status, endpoint, response body, and request identifier when available. The x402 client also promotes the InFlow error-envelope code to error.code; the MPP client retains the structured envelope in error.body. Handle structured fields rather than parsing the message:

import { InflowApiError } from '@inflowpayai/x402';

try {
  await startSeller();
} catch (error) {
  if (error instanceof InflowApiError && error.code === 'SELLER_ACCOUNT_REQUIRED') {
    throw new Error('Configure a Seller account API key for this integration.');
  }
  throw error;
}

Common authorization failures:

HTTP status	Server response code	Meaning
401	No structured body	The credential is missing, invalid, expired, or belongs to another environment.
403	SELLER_ACCOUNT_REQUIRED	The credential is valid, but the account is not a Seller account.

Monorepo

For a tour of the monorepo itself — tooling, contributing, publishing — see docs/monorepo:

• contributing — workflow, branch model, commit conventions.
• tooling — pnpm, Turborepo, tsup, Vitest, MSW, ESLint, Prettier.
• publishing — Changesets flow and npm provenance.
• documentation — TSDoc, README, and docs/ style guide.

Security

See SECURITY.md for disclosure. Examples under examples/ are illustrative and out of scope.

License

MIT.