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.

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: 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

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
  • Python & TypeScript libraries provide turnkey developer tooling
  • Express.js and FastAPI middleware handle the entire flow automatically