How the x402 Facilitator Works - Nevermined Documentation

This guide explains the end-to-end x402 flow from both the subscriber (client) and resource server (API/agent) perspectives.

For the complete technical specification, see the x402 Smart Accounts Extension Spec.

If you’re new to the programmable extension concepts, see:

The Nevermined x402 programmable extension

Nevermined extends x402 with the nvm:erc4337 scheme, enabling programmable settlement (credits/subscriptions/PAYG) using ERC-4337 smart accounts and session keys.

PaymentRequired Response (402)

When a server requires payment, it returns a 402 response with a payment-required header:

{
  "x402Version": 2,
  "error": "Payment required to access resource",
  "resource": {
    "url": "/api/v1/agents/80918427.../tasks",
    "description": "AI agent task execution"
  },
  "accepts": [{
    "scheme": "nvm:erc4337",
    "network": "eip155:84532",
    "planId": "44742763076047497640080230236781474129970992727896593861997347135613135571071",
    "extra": {
      "version": "1",
      "agentId": "80918427023170428029540261117198154464497879145267720259488529685089104529015"
    }
  }],
  "extensions": {}
}

PaymentPayload (Client Response)

The client responds with a payment-signature header containing the x402 access token:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "nvm:erc4337",
    "network": "eip155:84532",
    "planId": "44742763076047497640080230236781474129970992727896593861997347135613135571071",
    "extra": {
      "version": "1",
      "agentId": "80918427023170428029540261117198154464497879145267720259488529685089104529015"
    }
  },
  "payload": {
    "signature": "0x01845ADb2C711129d4f3966735eD98a9F09fC4cE...",
    "authorization": {
      "from": "0xD4f58B60330bC59cB0A07eE6A1A66ad64244eC8c",
      "sessionKeysProvider": "zerodev",
      "sessionKeys": [
        { "id": "order", "data": "0x20a13d82dd9ee289..." },
        { "id": "redeem", "data": "0x68e8e34d65914908..." }
      ]
    }
  },
  "extensions": {}
}

Subscriber flow (client side)

Step 1: Discover payment requirements (HTTP 402)

When calling a protected endpoint, the server returns a 402 Payment Required response with the payment-required header containing the payment requirements.

TypeScript
Python

import { X402_HEADERS } from '@nevermined-io/payments/express'

// Call protected endpoint - get 402 response
const response = await fetch('https://api.example.com/protected')

if (response.status === 402) {
  // Decode the payment-required header
  const paymentRequired = JSON.parse(
    Buffer.from(response.headers.get(X402_HEADERS.PAYMENT_REQUIRED)!, 'base64').toString()
  )

  // Extract planId and agentId from accepts array
  const { planId, extra } = paymentRequired.accepts[0]
  const agentId = extra?.agentId
}

import base64
import json
import requests

response = requests.get('https://api.example.com/protected')

if response.status_code == 402:
    # Decode the payment-required header
    payment_required = json.loads(
        base64.b64decode(response.headers.get('payment-required')).decode()
    )

    # Extract planId and agentId from accepts array
    plan_id = payment_required['accepts'][0]['planId']
    agent_id = payment_required['accepts'][0].get('extra', {}).get('agentId')

Step 2: Generate x402 access token

Use the Nevermined SDK to generate an x402 access token. The supported flow is create-first: create a delegation once with createDelegation (provider and currency are required), then request access tokens by passing its delegationId. Reuse the delegation until it expires or is exhausted.

TypeScript
Python

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

const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY,
  environment: 'sandbox'
})

// 1. Create a delegation once (provider + currency required; 'usdc' for erc4337).
const delegation = await payments.delegation.createDelegation({
  provider: 'erc4337',
  spendingLimitCents: 10000,
  durationSecs: 604800,
  currency: 'usdc'
})

// 2. Request a token by delegationId (reuse it for subsequent requests).
const { accessToken } = await payments.x402.getX402AccessToken(planId, agentId, {
  delegationConfig: { delegationId: delegation.delegationId }
})

import os
from payments_py import Payments, PaymentOptions
from payments_py.x402 import (
    CreateDelegationPayload,
    DelegationConfig,
    X402TokenOptions,
)

payments = Payments.get_instance(
    PaymentOptions(nvm_api_key=os.environ['NVM_API_KEY'], environment='sandbox')
)

# 1. Create a delegation once (provider + currency required; 'usdc' for erc4337).
delegation = payments.delegation.create_delegation(
    CreateDelegationPayload(
        provider='erc4337',
        spending_limit_cents=10000,
        duration_secs=604800,
        currency='usdc',
    )
)

# 2. Request a token by delegationId (reuse it for subsequent requests).
token_res = payments.x402.get_x402_access_token(
    plan_id,
    agent_id,
    token_options=X402TokenOptions(
        delegation_config=DelegationConfig(
            delegation_id=delegation.delegation_id
        )
    ),
)
access_token = token_res['accessToken']

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, then pass only { delegationId }.

Step 3: Retry request with payment header

Send the x402 access token in the payment-signature header:

TypeScript
Python

import { X402_HEADERS } from '@nevermined-io/payments/express'

const result = await fetch('https://api.example.com/protected', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    [X402_HEADERS.PAYMENT_SIGNATURE]: accessToken
  },
  body: JSON.stringify({ prompt: 'Hello' })
})

// Decode the settlement receipt from payment-response header
if (result.ok) {
  const settlement = JSON.parse(
    Buffer.from(result.headers.get(X402_HEADERS.PAYMENT_RESPONSE)!, 'base64').toString()
  )
  console.log('Credits used:', settlement.creditsRedeemed)
}

result = requests.post(
    'https://api.example.com/protected',
    headers={
        'Content-Type': 'application/json',
        'payment-signature': access_token
    },
    json={'prompt': 'Hello'}
)

# Decode the settlement receipt from payment-response header
if result.ok:
    settlement = json.loads(
        base64.b64decode(result.headers.get('payment-response')).decode()
    )
    print('Credits used:', settlement['creditsRedeemed'])

Resource server flow (API/agent side)

Recommended: For Express.js applications, use the paymentMiddleware which handles all of this automatically with one line of code.

Step 1: Return 402 when payment is missing

If the payment header is not present, respond with 402 and set the payment-required header with your payment requirements:

TypeScript
Python

import { X402_HEADERS } from '@nevermined-io/payments/express'

const x402Token = req.headers['payment-signature']

if (!x402Token) {
  const paymentRequired = {
    x402Version: 2,
    error: 'Payment required to access resource',
    resource: { url: req.path },
    accepts: [{
      scheme: 'nvm:erc4337',
      network: 'eip155:84532',
      planId: process.env.NVM_PLAN_ID,
      extra: {
        version: '1',
        agentId: process.env.NVM_AGENT_ID
      }
    }],
    extensions: {}
  }

  res.set(X402_HEADERS.PAYMENT_REQUIRED, Buffer.from(JSON.stringify(paymentRequired)).toString('base64'))
  return res.status(402).json({ error: 'Payment Required' })
}

x402_token = request.headers.get('payment-signature')

if not x402_token:
    payment_required = {
        'x402Version': 2,
        'error': 'Payment required to access resource',
        'resource': {'url': request.path},
        'accepts': [{
            'scheme': 'nvm:erc4337',
            'network': 'eip155:84532',
            'planId': os.environ['NVM_PLAN_ID'],
            'extra': {
                'version': '1',
                'agentId': os.environ.get('NVM_AGENT_ID')
            }
        }],
        'extensions': {}
    }

    response = jsonify({'error': 'Payment Required'})
    response.headers['payment-required'] = base64.b64encode(
        json.dumps(payment_required).encode()
    ).decode()
    return response, 402

Step 2: Verify with the facilitator

Verify the x402 token with the facilitator. The facilitator extracts planId and subscriber address from the token:

TypeScript
Python

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

const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY,
  environment: 'sandbox'
})

// Verify with facilitator - extracts planId/subscriberAddress from token
const verification = await payments.facilitator.verifyPermissions({
  x402AccessToken: x402Token,
  maxAmount: BigInt(creditsRequired)
})

if (!verification.isValid) {
  return res.status(402).json({ error: 'Payment verification failed' })
}

from payments_py import Payments, PaymentOptions

payments = Payments.get_instance(
    PaymentOptions(nvm_api_key=os.environ['NVM_API_KEY'], environment='sandbox')
)

# Verify with facilitator - extracts planId/subscriberAddress from token
verification = payments.facilitator.verify_permissions(
    x402_access_token=x402_token,
    max_amount=credits_required
)

if not verification.is_valid:
    return jsonify({'error': 'Payment verification failed'}), 402

Step 3: Execute Workload

// Only execute after verification succeeds
const result = await processAIRequest(req.body)

Step 4: Settle Payment

Settle after work is complete and return the settlement receipt in the payment-response header:

TypeScript
Python

import { X402_HEADERS } from '@nevermined-io/payments/express'

// Settle after work is complete
const settlement = await payments.facilitator.settlePermissions({
  x402AccessToken: x402Token,
  maxAmount: BigInt(actualCreditsUsed)
})

// Set payment-response header with settlement receipt
const settlementReceipt = {
  success: true,
  creditsRedeemed: actualCreditsUsed,
  transactionHash: settlement.txHash
}
res.set(X402_HEADERS.PAYMENT_RESPONSE, Buffer.from(JSON.stringify(settlementReceipt)).toString('base64'))

// Return response
res.json({ result })

# Settle after work is complete
settlement = payments.facilitator.settle_permissions(
    x402_access_token=x402_token,
    max_amount=actual_credits_used
)

# Set payment-response header with settlement receipt
settlement_receipt = {
    'success': True,
    'creditsRedeemed': actual_credits_used,
    'transactionHash': settlement.tx_hash
}

response = jsonify({'result': result})
response.headers['payment-response'] = base64.b64encode(
    json.dumps(settlement_receipt).encode()
).decode()
return response

Complete Request Lifecycle

Error Handling

Error	HTTP Status	Cause
Missing payment header	402	No `payment-signature` header
Invalid signature	402	Signature verification failed
Insufficient balance	402	User needs to purchase more credits
Expired session	402	Session key has expired
Settlement failed	500	On-chain transaction failed

Next Steps

Express.js Integration

One-line payment protection with Express middleware

Payment Models

Configure credits, subscriptions, and dynamic pricing

x402 Integration

Complete integration guide with code examples

Technical Spec

Full x402 Smart Accounts specification

​The Nevermined x402 programmable extension

​PaymentRequired Response (402)

​PaymentPayload (Client Response)

​Subscriber flow (client side)

​Step 1: Discover payment requirements (HTTP 402)

​Step 2: Generate x402 access token

​Step 3: Retry request with payment header

​Resource server flow (API/agent side)

​Step 1: Return 402 when payment is missing

​Step 2: Verify with the facilitator

​Step 3: Execute Workload

​Step 4: Settle Payment

​Complete Request Lifecycle

​Error Handling

​Next Steps

Express.js Integration

Payment Models

x402 Integration

Technical Spec

The Nevermined x402 programmable extension

PaymentRequired Response (402)

PaymentPayload (Client Response)

Subscriber flow (client side)

Step 1: Discover payment requirements (HTTP 402)

Step 2: Generate x402 access token

Step 3: Retry request with payment header

Resource server flow (API/agent side)

Step 1: Return 402 when payment is missing

Step 2: Verify with the facilitator

Step 3: Execute Workload

Step 4: Settle Payment

Complete Request Lifecycle

Error Handling

Next Steps