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-SIGNATUREretry 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
Background: What x402 Solves
The x402 protocol defines a payment-enforced HTTP 402 mechanism:- A client calls an API.
- The server responds with HTTP 402 Payment Required and instructions.
- The client signs a payment authorization locally (no private key leaves the device).
- The signed authorization is included in the next request.
- The server forwards it to a facilitator, which:
- Verifies the signature
- Checks balance/permissions
- Settles payment on-chain (EIP-3009 or equivalent)
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 a402 response with a payment-required header. The scheme depends on the plan’s pricing configuration:
Crypto plan (nvm:erc4337):
nvm:card-delegation):
PaymentPayload (Client Response)
The client responds with apayment-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 thepayment-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 withcreateDelegation, 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.
- TypeScript
- Python
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 passscheme: 'nvm:card-delegation'to the token call. - Use
provider: 'stripe'(or'braintree'/'visa') withcurrency: 'usd'in the delegation; for crypto plans useprovider: 'erc4337'withcurrency: 'usdc'.
Step 3 — Submit with HTTP header
Clients include the x402 access token in thepayment-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:- Express.js (TypeScript)
- FastAPI (Python)
For Express.js applications, use the See the Express.js Integration Guide for full details.
paymentMiddleware from @nevermined-io/payments/express: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-signatureheader (x402 v2). - If no token is present, return a 402 response with payment requirements.
Step 2 — Verify with the facilitator
- TypeScript
- Python
Step 3 — Execute your workload
- Perform the paid operation only after verification succeeds.
Step 4 — Settle
- TypeScript
- Python
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:erc4337andnvm:card-delegationschemes - 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-signatureheaders 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