Skip to main content

Nevermined x402

Nevermined provides first-class support for the x402 payment protocol, enabling AI agents, APIs, and services to charge per-request using secure, locally-signed payment authorizations.
For the complete technical specification, see the x402 Smart Accounts Extension Spec.
x402 has a sibling protocol: MPP. Nevermined also speaks the Merchant Payment Protocol (MPP), which settles against the same Payment Plans, credits, and delegation as x402 — a request that costs 2 credits burns 2 either way. The only difference is the wire handshake. A service tells you which it speaks by its 402 response:
  • an x402 accepts / payment-required body → follow the x402 steps on this page;
  • a WWW-Authenticate: Payment … header → follow Paying an MPP-protected service below.
MPP here is the plan-model sibling of x402, offered the same way — not the buyer-side Router MPP rail, which pays external merchants that were never onboarded to Nevermined.

Overview

This section explains:
  • The x402 HTTP 402 handshake and PAYMENT-SIGNATURE retry pattern
  • How Nevermined extends x402 with Smart Account-based settlement
  • How subscribers generate and sign x402 payment proofs
  • How delegations, session keys, and delegated execution work
  • How the facilitator verifies and settles requests
  • How to use the Python and TypeScript x402 client libraries
  • Advanced integration with Google A2A/AP2
For pricing and plan configuration (credits, time-based access, dynamic pricing), see: Nevermined’s x402 implementation is compatible with the standard protocol while adding programmable settlement layers powered by Nevermined smart contracts.

Background: What x402 Solves

The x402 protocol defines a payment-enforced HTTP 402 mechanism:
  1. A client calls an API.
  2. The server responds with HTTP 402 Payment Required and instructions.
  3. The client signs a payment authorization locally (no private key leaves the device).
  4. The signed authorization is included in the next request.
  5. The server forwards it to a facilitator, which:
    • Verifies the signature
    • Checks balance/permissions
    • Settles payment on-chain (EIP-3009 or equivalent)
Nevermined extends this with ERC-4337 Smart Accounts, session keys, and programmable billing models, allowing much more complex behavior than standard EIP-3009-based transfers.

Why Nevermined Extends x402

x402 itself focuses on single ERC-20, pay-per-request flows. Nevermined introduces: This means a subscriber can grant a server the ability to redeem credits or burn usage units while maintaining strict control over what the server can do.

High-Level Architecture

Roles:
  • Subscriber: owns a Smart Account; delegates permissions through smart account policies
  • Server/Agent: exposes an API secured by x402
  • Facilitator: Nevermined component that verifies and settles payments
  • Blockchain: executes credit burns, orders, or other plan-specific actions

The Nevermined x402 Extensions

Nevermined introduces two x402 schemes for different payment rails: For the complete delegation specification, see the Delegation Spec.

nvm:erc4337 — Smart Account Extension

The nvm:erc4337 scheme uses ERC-4337 smart accounts instead of EOA wallets, enabling programmable settlement through session keys and UserOperations. Instead of embedding an EIP-3009 transfer, the payload includes:
  • An EIP-712 signature
  • One or more session keys
  • Encoded UserOperations representing actions like:
    • order (purchase credits if balance is low)
    • burn (burn credits for usage)
    • redeem (convert plan entitlements into usage)

PaymentRequired Response (402)

When a server requires payment, it returns a 402 response with a payment-required header. The scheme depends on the plan’s pricing configuration:
network is the settlement rail, not the environment. Send eip155:<chainId> (e.g. eip155:84532) for a crypto/ERC-4337 plan, or one of stripe / braintree / visa for a card-delegation plan. It is not the environment name — do not put sandbox or live here (that value fails validation). The environment is selected by your API key and base URL, never by this field.
Crypto plan (nvm:erc4337):
Fiat plan (nvm:card-delegation):

PaymentPayload (Client Response)

The client responds with a payment-signature header containing the payment payload:

What the subscriber delegates

Complete Payment & Execution Flow

Below is the Nevermined x402 Smart Account flow (verification + settlement).

Facilitator Responsibilities

Verification

The facilitator validates:
  • x402 envelope structure
  • EIP-712 signature
  • Session key authenticity (data or hash)
  • UserOperation validity (simulation)
  • Permission requirements (e.g., burn MUST be delegated)
  • Subscriber balance and plan state
  • If verification fails, server returns 402 PAYMENT-FAILED.

Settlement

Settlement runs after the server performs the work:
  • Execute order (if needed) to top up credits
  • Execute burn to deduct usage
  • Submit UserOps on-chain
  • Return tx hashes to the server

Developer Guide: Subscriber Flow

Step 1 — Discover payment requirements

When the server returns 402 Payment Required, it includes the payment-required header (base64-encoded) with:
  • Supported schemes (nvm:erc4337)
  • Plan and agent IDs
  • Network information

Step 2 — Build a payment payload

Using Nevermined Payments libraries (Python or TS), you generate an x402 access token. The supported flow is create-first: create a delegation once with createDelegation, then request access tokens by passing its delegationId. A delegation captures the spending limit, duration, provider, and currency; reuse it for every token request until it expires or is exhausted.
The buyer-side getX402AccessToken / get_x402_access_token call does not auto-detect the scheme — it defaults to nvm:erc4337 (crypto). For a fiat plan (isCrypto: false) you must resolve and pass the scheme, and create the delegation with the matching card provider:
  • Detect the scheme with resolveScheme() (TypeScript) / resolve_scheme() (Python), then pass scheme: 'nvm:card-delegation' to the token call.
  • Use provider: 'stripe' (or 'braintree' / 'visa') with currency: 'usd' in the delegation; for crypto plans use provider: 'erc4337' with currency: 'usdc'.
Server-side middleware (Express, FastAPI) and the A2A clients resolve the scheme for you automatically — see the Express.js and FastAPI guides, and Which payment type does this plan need?.
Inline create-on-the-fly is deprecated. Passing creation fields (spendingLimitCents, durationSecs, providerPaymentMethodId, cardId, currency) directly in delegationConfig instead of a delegationId still works but emits a runtime deprecation warning. Create the delegation first (as above) and pass only { delegationId }. Delegations are plan-agnostic by default; pass planId on createDelegation only to bind a delegation to a single plan. provider and currency are required — there is no silent default.
With a delegation in place you can skip the manual order_plan() / orderPlan() step entirely. If the subscriber’s balance is short when a request settles, the facilitator tops up their credits automatically, up to the delegation’s limit. See Automatic Credit Top-Ups.

Step 3 — Submit with HTTP header

Clients include the x402 access token in the payment-signature header:

Developer Guide: Agent Flow

Quick Integration: Framework Middleware

Both TypeScript (Express.js) and Python (FastAPI) have built-in middleware that handles x402 automatically:
For Express.js applications, use the paymentMiddleware from @nevermined-io/payments/express:
See the Express.js Integration Guide for full details.
The middleware handles verification, settlement, and all x402 headers automatically.
The middleware automatically detects the payment scheme from plan metadata. Plans with fiat pricing (isCrypto: false) use nvm:card-delegation (Stripe). No code changes are needed on the agent side. You can explicitly override with the scheme parameter in the route configuration.

Manual Integration

For other frameworks or custom implementations, follow these steps:

Step 1 — Receive and parse

  • Read the x402 token from the payment-signature header (x402 v2).
  • If no token is present, return a 402 response with payment requirements.

Step 2 — Verify with the facilitator

Step 3 — Execute your workload

  • Perform the paid operation only after verification succeeds.

Step 4 — Settle

Paying an MPP-protected service

Some services accept MPP (Merchant Payment Protocol) instead of x402. MPP settles against the same Nevermined Payment Plans as x402 — same credits, same delegation, same meter — so the buyer flow mirrors the one above with /api/v1/mpp/* in place of /api/v1/x402/*. You recognise an MPP service by its 402: it carries a WWW-Authenticate: Payment … header instead of an x402 accepts body.
This is the buyer side. To make your own plan-protected endpoint MPP-payable, see Accepting MPP payments.
The MPP credential is an mppx-serialised structure (the server’s challenge plus your minted access token), not a plain header value — so the practical buyer path is the SDK. payments.mpp.fetch(...) is a drop-in for fetch: it parses the challenge, mints the token, builds the credential, presents it, and reads the Payment-Receipt for you. It uses the same delegation you already created for x402.
settled (a Payment-Receipt came back and did not report failure) is the honest signal that credits were burned — not the HTTP status. A streaming handler can return 200 with no receipt even though the credits were burned, so never read “no receipt” as “not paid” and blindly retry.

Under the hood (raw HTTP)

If you are not using the SDK, the flow is three steps — and you do not pre-buy the plan: the delegation-backed settle in step 3 acquires and burns the credits in one call, exactly like the x402 settle flow above.
1

Call the service unpaid

It replies 402 with a WWW-Authenticate: Payment … challenge that names the planId and the credits the call costs.
2

Mint an MPP access token for that plan

POST /api/v1/mpp/permissions — the counterpart of /api/v1/x402/permissions, with the same body minus tokenVersion:
It returns an accessToken signed under the Nevermined-MPP domain, so it is accepted only on MPP routes (and refused on x402 routes). Use a card-delegation scheme/network instead for a fiat plan, exactly as in x402.
3

Present the credential

Combine the challenge with your access token into an MPP credential and re-send the request with Authorization: Payment <credential>. The service verifies and settles it against your plan credits and returns a Payment-Receipt header as your proof. Settling the same challenge twice burns once — the challenge id is the idempotency key.
Building the credential by hand needs the mppx serialisation library, which is why the SDK is the recommended path above. The raw shape is documented for parity and for non-JS/Python clients.

Summary

This section provides a comprehensive guide for developers integrating Nevermined with x402:
  • x402 gives a universal payment-required protocol
  • Nevermined enriches it with Smart Accounts, UserOps, and advanced billing models using the nvm:erc4337 and nvm:card-delegation schemes
  • Delegations provide a unified permission model for both crypto (nvm:erc4337) and fiat (nvm:card-delegation) schemes, with auto-detection from plan metadata
  • Subscribers delegate controlled permissions using DelegationConfig (spending limits and duration)
  • Servers use payment-signature headers and verify/settle via the facilitator
  • Facilitators verify and settle on-chain
  • MPP is the sibling protocol: the same plans, credits, and delegation over a WWW-Authenticate: Payment / Authorization: Payment handshake — pay it with payments.mpp.fetch(...)
  • Python & TypeScript libraries provide turnkey developer tooling
  • Express.js and FastAPI middleware handle the entire flow automatically