​

Nevermined x402

​

Overview

• How Nevermined extends x402 with Smart Account–based settlement
• How subscribers generate and sign x402 Access Tokens
• How permissions, 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

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)

​

Why Nevermined Extends x402

​

High-Level Architecture

• 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 Smart-Account Extension

extensions.smart-account

• 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)

​

Example Payment Payload

{
  "x402Version": 2,
  "scheme": "exact",
  "network": "base-sepolia",
  "extensions": {
    "smart-account": {
      "signature": "EIP-712 signature",
      "authorization": {
        "provider": "zerodev",
        "sessionKeys": [
          { "id": "order", "data": "base64-session-key" },
          { "id": "redeem", "hash": "keccak-session-key-hash" }
        ]
      }
    }
  },
  "payload": {}
}

​

What the subscriber delegates

​

Complete Payment & Execution Flow

​

Facilitator Responsibilities

​

Verification

• 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

• 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

• Supported schemes (smart-account)
• Required permissions
• Accepted plans / plan IDs

​

Step 2 — Build a payment payload

• Session keys
• Delegated permissions (burn, order, redeem)
• A fully-formed x402 payload with EIP-712 signing

import { Payments } from '@nevermined-io/payments'

const payments = Payments.getInstance({
  nvmApiKey: 'nvm:subscriber-key',
  environment: 'sandbox',
})

// Fetch protected resource to get the Nevermined extension
const requiredRes = await fetch('https://api.example.com/protected')
const paymentRequired = await requiredRes.json()
const { plan_id, agent_id, max_amount, network } = paymentRequired.extensions.nevermined.info

// Generate the x402 session token
const { accessToken } = await payments.x402.getX402AccessToken(plan_id, agent_id)

// Build the payload with the copied extension
const paymentPayload = {
  x402Version: 2,
  scheme: 'contract',
  network,
  payload: { session_key: accessToken },
  extensions: paymentRequired.extensions,
}

import json, requests
from payments_py import Payments, PaymentOptions
from payments_py.x402.extensions.nevermined import extract_nevermined_info

payments = Payments.get_instance(
    PaymentOptions(nvm_api_key="nvm:subscriber-key", environment="sandbox")
)

# Fetch protected resource to get the Nevermined extension
required_res = requests.get("https://api.example.com/protected")
payment_required = required_res.json()
nvm_info = extract_nevermined_info(payment_required, None)

# Generate the x402 session token
token_res = payments.x402.get_x402_access_token(
    nvm_info["plan_id"],
    nvm_info["agent_id"],
)
access_token = token_res["accessToken"]

# Build the payload with the copied extension
payment_payload = {
    "x402Version": 2,
    "scheme": "contract",
    "network": nvm_info["network"],
    "payload": {"session_key": access_token},
    "extensions": payment_required["extensions"],
}

​

Step 3 — Submit with HTTP header

PAYMENT-SIGNATURE: <base64 x402 payload>

​

Developer Guide: Agent Flow

​

Step 1 — Receive and parse

• Read the x402 payload from the request header (e.g., PAYMENT-SIGNATURE).
• Extract the Nevermined extension (plan_id, agent_id, max_amount, network, scheme) and the session_key.

​

Step 2 — Verify with the facilitator

import { Payments } from '@nevermined-io/payments'

const payments = Payments.getInstance({
  nvmApiKey: 'nvm:agent-key',
  environment: 'sandbox',
})

// xPaymentHeader contains the JSON string from the incoming request
const paymentPayload = JSON.parse(xPaymentHeader)
const { plan_id, max_amount } = paymentPayload.extensions.nevermined.info

const verification = await payments.facilitator.verifyPermissions({
  planId: plan_id,
  maxAmount: BigInt(max_amount),
  x402AccessToken: paymentPayload.payload.session_key,
  subscriberAddress: subscriberAddressFromRequest,
})

if (!verification.success) {
  throw new Error('Payment Required')
}

from payments_py.x402 import NeverminedFacilitator, PaymentRequirements
from payments_py.x402.extensions.nevermined import extract_nevermined_info

facilitator = NeverminedFacilitator(
    nvm_api_key="nvm:agent-key",
    environment="sandbox",
)

nvm_info = extract_nevermined_info(payment_payload, None)
requirements = PaymentRequirements(
    plan_id=nvm_info["plan_id"],
    agent_id=nvm_info["agent_id"],
    max_amount=nvm_info["max_amount"],
    extra={"subscriber_address": subscriber_address},
)

verify_result = await facilitator.verify(payment_payload, requirements)
if not verify_result.is_valid:
    raise Exception("Payment Required")

​

Step 3 — Execute your workload

• Perform the paid operation only after verification succeeds.

​

Step 4 — Settle

await payments.facilitator.settlePermissions({
  planId: plan_id,
  maxAmount: BigInt(max_amount),
  x402AccessToken: paymentPayload.payload.session_key,
  subscriberAddress: subscriberAddressFromRequest,
})

await facilitator.settle(payment_payload, requirements)

• Return your response to the client, optionally including the settlement transaction hash.

​

Summary

• x402 gives a universal payment-required protocol
• Nevermined enriches it with Smart Accounts, UserOps, and advanced billing models
• Subscribers delegate controlled permissions using session keys
• Servers simply forward PAYMENT-SIGNATURE headers
• Facilitators verify and settle on-chain
• Python & TS libraries provide turnkey developer tooling
• Google A2A/AP2 flows are supported for enterprise-grade integrations