X402 Protocol

The X402 protocol is a payment-aware HTTP extension that enables AI agents to require and verify payments for API access. This guide provides a complete overview of X402 implementation in the Nevermined Payments Library.

🔐 Bearer-token hygiene. The payment-signature header is a bearer credential — anyone holding it can spend the associated plan’s credits until it expires. Send it only over HTTPS, never log the full value, and configure your log/trace exporters (pino, winston, OpenTelemetry) to redact payment-signature, authorization, and cookie headers by default.

Overview of X402

X402 is an HTTP-based protocol for payment-protected resources:

402 Payment Required: HTTP status code for payment requests
payment-signature: Header containing payment credentials (X402 v2)
PAYMENT-REQUIRED: Header with payment requirements in 402 responses
PAYMENT-RESPONSE: Header with payment settlement details in success responses
Cryptographic Signatures: ERC-4337 account abstraction for secure payments

Supported Schemes

Nevermined supports two x402 payment schemes:

Scheme	Network	Use Case	Settlement
`nvm:erc4337`	`eip155:84532`	Crypto payments	ERC-4337 UserOps + session keys
`nvm:card-delegation`	`stripe` \| `braintree` \| `visa`	Fiat/credit card	Provider charge + credit burn

The scheme is determined by the plan’s pricing configuration. Plans with isCrypto: false use nvm:card-delegation; all others use nvm:erc4337. The SDK auto-detects the scheme via resolveScheme(). The network value within nvm:card-delegation is determined by which provider issued the delegation being consumed (stripe, braintree, or visa).

Visa support

Visa delegations use the same nvm:card-delegation scheme and SDK surface as Stripe and Braintree, but two steps must happen in a browser before the SDK can consume them:

Card enrolment — the cardholder enrols a Visa card through VGS Collect (PCI-compliant iframe) in the Nevermined webapp. The card is bound to a Visa Agentic Token via the VGS Credential Management Platform.
Delegation creation — the cardholder approves a delegation via a WebAuthn/passkey (FIDO) device-binding ceremony embedded by Visa VTS. This produces a single-use assuranceData blob bound to the spending limit + duration + merchant context.

Both steps require a real DOM and a user gesture, so the SDK cannot perform them programmatically. Once a Visa delegation exists, the SDK consumes it identically to Stripe/Braintree — see Reusing Existing Delegations.

X402 Version 2 Specification

The Nevermined Payments Library implements X402 v2, which uses:

payment-signature header for access tokens (replaces Authorization)
PAYMENT-REQUIRED header for payment requirements (replaces custom formats)
PAYMENT-RESPONSE header for settlement receipts
Structured payment credentials with cryptographic signatures

Generate X402 Access Tokens

The supported flow is create-first: create a delegation once with payments.delegation.createDelegation(...), then request access tokens by passing only its delegationId. Both schemes (nvm:erc4337 and nvm:card-delegation) require a delegationConfig — the older “just pass planId + agentId” shape no longer mints a token and surfaces BCK.X402.0030 (“Required token-generation input is missing or incomplete”; the details field names the missing input) at the backend.

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

const subscriberPayments = Payments.getInstance({
  nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
  environment: 'sandbox' as EnvironmentName,
})

// 1. Create a delegation once. `currency` is required: 'usdc' for the
//    crypto (erc4337) scheme, 'usd'/'eur'/… for card providers.
const { delegationId } = await subscriberPayments.delegation.createDelegation({
  provider: 'erc4337',
  spendingLimitCents: 1000, // $10 cap
  durationSecs: 86_400, // 1 day
  currency: 'usdc',
})

// 2. Request a token by delegationId. Reuse this delegation for every
//    subsequent token request until it expires or is exhausted.
const tokenOptions: X402TokenOptions = {
  scheme: 'nvm:erc4337',
  delegationConfig: { delegationId },
}

const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
  planId, // Required: Plan ID
  agentId, // Optional: Agent ID (restricts token to specific agent)
  tokenOptions, // Required: scheme + delegationConfig
)

console.log('X402 access token generated')

⚠️ Inline create-on-the-fly is deprecated. Passing creation fields (spendingLimitCents, durationSecs, providerPaymentMethodId, cardId, currency, merchantAccountId, maxTransactions) directly in delegationConfig instead of a delegationId still works, but getX402AccessToken now emits a runtime deprecation warning. Create the delegation first (above) and pass only { delegationId }.

Generate Tokens via Nevermined App

Users can also generate X402 access tokens through the Nevermined App:

Visit nevermined.app/permissions/agent-permissions
Select the plan you’ve purchased
Configure token parameters (agent, expiration, limits)
Generate and copy the X402 access token
Use the token in API requests

This provides a user-friendly interface for non-technical users to generate tokens without code.

Generate Card-Delegation Tokens

For fiat plans using nvm:card-delegation, create the delegation first with createDelegation (passing the card’s providerPaymentMethodId), then request tokens by its delegationId. currency is required on creation:

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

// 1. Create a USD card delegation once.
const { delegationId: usdDelegationId } =
  await subscriberPayments.delegation.createDelegation({
    provider: 'stripe',
    providerPaymentMethodId: 'pm_1AbCdEfGhIjKlM',
    spendingLimitCents: 10000, // $100.00
    durationSecs: 2592000, // 30 days
    currency: 'usd',
    maxTransactions: 100,
  })

// 2. Request a token by delegationId (reuse for every subsequent request).
const tokenOptions: X402TokenOptions = {
  scheme: 'nvm:card-delegation',
  delegationConfig: { delegationId: usdDelegationId },
}

const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
  planId,
  agentId,
  tokenOptions,
)

A EUR delegation is the same call with currency: 'eur'. The delegation’s currency is fixed at creation, so you create one delegation per currency and reuse each by its delegationId.

Reusing Existing Delegations

Passing delegationConfig: { delegationId } is the supported pattern for every provider, and the only supported pattern for Visa delegations (which cannot be created from the SDK). Reuse one delegation across multiple agents that share a single spending budget:

const tokenOptions: X402TokenOptions = {
  scheme: 'nvm:card-delegation',
  delegationConfig: {
    delegationId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  }
}

const { accessToken } = await subscriberPayments.x402.getX402AccessToken(
  planId,
  agentId,
  tokenOptions,
)

When delegationId is provided, the backend verifies that the delegation is active and that the requesting API key has access, then returns its existing token without creating a new delegation. The provider (stripe, braintree, or visa) is inferred from the delegation record on the server. To scope a token request to a specific NVM API key, add apiKeyId alongside delegationId — both fields stay active (non-deprecated):

delegationConfig: { delegationId: '…', apiKeyId: 'key-uuid' }

Deprecated: inline create-on-the-fly

⚠️ Deprecated. Supplying creation fields directly in delegationConfig instead of a delegationId (e.g. providerPaymentMethodId + spendingLimitCents, a bare cardId, or an identifier-less “auto-select” shape) still creates a delegation on the fly, but getX402AccessToken now emits a runtime deprecation warning. Use the create-first pattern above (createDelegation → { delegationId }); inline creation will be removed in a future major release.

CardDelegationConfig Reference

Field	Type	Status	Description
`delegationId`	`string`	Active	Existing delegation UUID to reuse — the supported path
`apiKeyId`	`string`	Active	NVM API Key ID to scope the token request to
`cardId`	`string`	Deprecated	Payment method UUID to target (inline create)
`providerPaymentMethodId`	`string`	Deprecated	Stripe payment method ID (e.g., `pm_...`) (inline create)
`spendingLimitCents`	`number`	Deprecated	Max spending in cents (inline create)
`durationSecs`	`number`	Deprecated	Duration in seconds (inline create)
`currency`	`string`	Deprecated	Currency code (inline create)
`planId`	`string`	Deprecated	Plan ID to scope a new delegation to (inline create)
`merchantAccountId`	`string`	Deprecated	Stripe Connect account ID (inline create)
`maxTransactions`	`number`	Deprecated	Max transactions allowed (inline create)

The deprecated fields apply only to inline create-on-the-fly. Create the delegation with createDelegation and pass only delegationId (optionally apiKeyId) here.

Auto Scheme Resolution

Use resolveScheme() to auto-detect the correct scheme from plan metadata:

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

// Auto-detect scheme from plan metadata (cached for 5 minutes)
const scheme = await resolveScheme(payments, planId)
// Returns "nvm:erc4337" for crypto plans, "nvm:card-delegation" for fiat plans

// Explicit override
const scheme = await resolveScheme(payments, planId, 'nvm:card-delegation')

DelegationAPI

Manage payment methods and delegations for card delegation:

import { DelegationAPI, PaymentMethodSummary } from '@nevermined-io/payments'

const delegationApi = DelegationAPI.getInstance(payments.options)

// List enrolled payment methods (every provider)
const methods: PaymentMethodSummary[] = await delegationApi.listPaymentMethods()

// Restrict the result to a single provider with the optional `provider` filter
const stripeMethods: PaymentMethodSummary[] = await delegationApi.listPaymentMethods({
  provider: 'stripe',
})

for (const method of methods) {
  console.log(`${method.brand} ****${method.last4} (expires ${method.expMonth}/${method.expYear})`)
  if (method.allowedApiKeyIds) {
    console.log(`  Restricted to API keys: ${method.allowedApiKeyIds.join(', ')}`)
  }
}

listPaymentMethods accepts an optional ListOptions:

Option	Type	Description
`provider`	`DelegationProvider` (`'stripe' \| 'braintree' \| 'visa' \| 'erc4337'`)	Server-side filter that restricts the result to payment methods backed by this provider. Omit it (the default) to return methods from every provider.
`accessible`	`boolean`	When `true`, return only methods accessible to the requesting API key.

Update Payment Method

Restrict a card to specific NVM API Keys so only designated agents can use it:

await delegationApi.updatePaymentMethod('pm-uuid-here', {
  alias: 'Production Card',
  allowedApiKeyIds: ['sk-agent-1', 'sk-agent-2'],  // Only these API keys can use this card
})

// Remove restrictions (any API key can use the card)
await delegationApi.updatePaymentMethod('pm-uuid-here', {
  allowedApiKeyIds: null,
})

List Delegations

Retrieve all delegations for the authenticated user:

const { delegations, totalResults } = await delegationApi.listDelegations()

console.log(`Total delegations: ${totalResults}`)
for (const d of delegations) {
  console.log(`${d.delegationId} - ${d.status} (${d.remainingBudgetCents} cents remaining)`)
  if (d.apiKeyId) {
    console.log(`  Restricted to API key: ${d.apiKeyId}`)
  }
}

createDelegation

Create a delegation once, then reuse it across token requests by its delegationId (the create-first pattern). This is the supported way to provision spending authority for nvm:erc4337 and nvm:card-delegation — prefer it over inline create-on-the-fly in getX402AccessToken.

// Crypto (erc4337): currency must be 'usdc'.
const { delegationId } = await delegationApi.createDelegation({
  provider: 'erc4337',
  spendingLimitCents: 100000, // $1000 cap
  durationSecs: 604800, // 1 week
  currency: 'usdc',
})

// Card (stripe / braintree): pass the enrolled card's providerPaymentMethodId.
const { delegationId: cardDelegationId } = await delegationApi.createDelegation({
  provider: 'stripe',
  providerPaymentMethodId: 'pm_1AbCdEfGhIjKlM',
  spendingLimitCents: 10000,
  durationSecs: 2592000,
  currency: 'usd',
})

CreateDelegationPayload fields:

Field	Type	Required	Description
`provider`	`'stripe' \| 'braintree' \| 'visa' \| 'erc4337'`	Yes	Delegation provider
`spendingLimitCents`	`number`	Yes	Maximum spending limit in cents
`durationSecs`	`number`	Yes	Delegation lifetime in seconds
`currency`	`DelegationCurrency` (`'usd' \| 'eur' \| 'usdc' \| 'eurc'`)	Yes	Currency code — `'usdc'`/`'eurc'` for erc4337, `'usd'`/`'eur'` for card providers. No silent default; the backend requires it.
`providerPaymentMethodId`	`string`	Card only	Payment method ID (Stripe `pm_...`, Braintree vault token, Visa Agentic token id)
`planId`	`string`	No	Optional and additive — delegations are plan-agnostic by default; supply `planId` to bind the delegation to a single plan. (Visa is always plan-specific and requires it.)
`merchantAccountId`	`string`	No	Stripe Connect account ID or Braintree merchantId
`maxTransactions`	`number`	No	Maximum number of transactions allowed
`apiKeyId`	`string`	No	NVM API Key ID to scope the delegation to

Visa delegations require a browser-side device-binding ceremony and cannot be created from the SDK — see Visa support. Create them in the Nevermined webapp, then consume them here by delegationId.

DelegationListResponse Fields

listDelegations() resolves to a DelegationListResponse object:

Field	Type	Description
`delegations`	`DelegationSummary[]`	Array of delegation records
`totalResults`	`number`	Total number of delegations
`page`	`number`	Current page number
`offset`	`number`	Offset into the full result set

DelegationSummary Fields

Each item in the delegations array is a DelegationSummary:

Field	Type	Description
`delegationId`	`string`	Unique delegation identifier
`provider`	`string`	Payment provider (`stripe`, `braintree`, or `visa`)
`providerPaymentMethodId`	`string`	Provider-side payment method ID
`status`	`string`	Delegation status (`Active`, `Revoked`, etc.)
`spendingLimitCents`	`string`	Maximum spendable amount in cents
`amountSpentCents`	`string`	Amount already spent in cents
`remainingBudgetCents`	`string`	Remaining budget in cents
`currency`	`string`	Currency code (e.g., `usd`)
`transactionCount`	`number`	Number of transactions made
`expiresAt`	`string`	Expiry timestamp (ISO 8601)
`createdAt`	`string`	Creation timestamp (ISO 8601)
`apiKeyId`	`string \| null`	API key this delegation is restricted to, or `null` if unrestricted

PaymentMethodSummary Fields

Field	Type	Description
`id`	`string`	Payment method ID (e.g., `pm_...`)
`brand`	`string`	Card brand (e.g., `visa`, `mastercard`)
`last4`	`string`	Last 4 digits of the card number
`expMonth`	`number`	Card expiration month
`expYear`	`number`	Card expiration year
`allowedApiKeyIds`	`string[] \| null`	API keys allowed to use this card (`null` = unrestricted)

X402 Access Token Structure

The access token is a JWT containing an X402 v2 payment credential:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "nvm:erc4337",           // Payment scheme
    "network": "eip155:84532",         // Blockchain network (Base Sepolia)
    "planId": "plan-123",              // Payment plan ID
    "extra": {
      "version": "1",                  // Extra version info
      "agentId": "did:nv:agent-456"    // Optional agent restriction
    }
  },
  "payload": {
    "signature": "0x...",              // Cryptographic signature
    "authorization": {
      "from": "0xSubscriberAddress",   // Subscriber's wallet address
      "sessionKeysProvider": "zerodev", // Session key provider
      "sessionKeys": []                // Session keys for gasless transactions
    }
  },
  "extensions": {}                     // Optional extensions
}

Card-Delegation Token Structure

For fiat plans using nvm:card-delegation, the token contains a JWT-based delegation authorization:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "nvm:card-delegation",
    "network": "stripe",
    "planId": "plan-123",
    "extra": {
      "version": "1",
      "agentId": "did:nv:agent-456"
    }
  },
  "payload": {
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "authorization": {
      "from": "0xSubscriberAddress",
      "sessionKeys": [{ "id": "redeem", "data": "0xabc123..." }]
    }
  },
  "extensions": {}
}

Token Components

x402Version: Protocol version (2 for current spec)
accepted: Payment method specification
- scheme: nvm:erc4337 for crypto or nvm:card-delegation for fiat
- network: eip155:84532 (Base Sepolia) for crypto, one of stripe, braintree, or visa for fiat
- planId: The payment plan being used
- extra: Additional metadata (version, agentId, etc.)
payload: Payment authorization
- signature (erc4337): Cryptographic proof of payment authorization
- token (card-delegation): Signed JWT encoding the delegation claims
- authorization: Subscriber identity and session keys
extensions: Optional protocol extensions

Verify X402 Permissions

Agents verify tokens before executing requests:

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

const agentPayments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,  // Builder/agent API key
  environment: 'sandbox' as EnvironmentName,
})

// Build payment required specification
const paymentRequired = buildPaymentRequired(planId, {
  endpoint: '/api/v1/tasks',
  agentId: agentId,
  httpVerb: 'POST',
  network: 'eip155:84532',
  description: 'Task execution API',
})

// Verify subscriber permissions
const verification = await agentPayments.facilitator.verifyPermissions({
  paymentRequired,
  x402AccessToken: accessToken,
  maxAmount: 2n,  // Max credits to verify
})

if (verification.isValid) {
  console.log('✓ Permissions verified')
  console.log(`Payer: ${verification.payer}`)
} else {
  console.log(`✗ Verification failed: ${verification.invalidReason}`)
}

Verification Response

interface VerifyPermissionsResult {
  isValid: boolean           // True if token is valid
  invalidReason?: string     // Reason for invalidity (if isValid is false)
  payer?: string             // Address of the payer's wallet
  agentRequestId?: string    // Agent request ID for observability tracking (Nevermined extension)
  urlMatching?: string       // URL pattern that matched the endpoint (Nevermined extension)
  agentRequest?: StartAgentRequest  // Agent request context for observability (Nevermined extension)
}

interface StartAgentRequest {
  agentRequestId: string     // Unique request identifier
  agentName: string          // Name of the agent
  agentId: string            // Agent identifier
  balance: PlanBalance       // Current plan balance (planId, balance, pricePerCredit, etc.)
  urlMatching: string        // URL pattern that was matched
  verbMatching: string       // HTTP verb that was matched
  batch: boolean             // Whether this is a batch request
}

Settle X402 Permissions

After successful execution, burn credits:

// Settle permissions (burn credits)
const settlement = await agentPayments.facilitator.settlePermissions({
  paymentRequired,
  x402AccessToken: accessToken,
  maxAmount: 2n,  // Credits to burn
  batch: false,   // Batch settlement (optional)
  marginPercent: 5,  // Add 5% margin (optional)
  agentRequestId: verification.agentRequest?.agentRequestId,  // From verification
})

console.log(`✓ Settlement successful`)
console.log(`Transaction: ${settlement.transaction}`)
console.log(`Credits burned: ${settlement.creditsRedeemed}`)
console.log(`Remaining balance: ${settlement.remainingBalance}`)

Settlement Response

interface SettlePermissionsResult {
  success: boolean          // True if settlement succeeded
  transaction: string       // Blockchain transaction hash
  creditsRedeemed: string   // Credits burned
  remainingBalance: string  // Subscriber's remaining credits
  network: string          // Blockchain network
}

HTTP Headers (X402 v2)

payment-signature Header

Subscribers include this header in requests:

POST /api/v1/tasks HTTP/1.1
Host: agent.example.com
Content-Type: application/json
payment-signature: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{"prompt": "Hello"}

PAYMENT-REQUIRED Header (402 Response)

Agents return this header when payment is required:

HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwicmVzb3VyY2UiOnsidXJsIjoiL2FwaS92MS90YXNrcyJ9...

{"error": "Payment required"}

The header contains base64-encoded payment requirement JSON. The scheme and network vary by plan type: Crypto plan:

{
  "x402Version": 2,
  "resource": {
    "url": "/api/v1/tasks",
    "description": "Task execution API",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "nvm:erc4337",
      "network": "eip155:84532",
      "planId": "plan-123",
      "extra": {
        "version": "1",
        "agentId": "did:nv:agent-456"
      }
    }
  ],
  "extensions": {}
}

Fiat plan:

{
  "x402Version": 2,
  "resource": {
    "url": "/api/v1/tasks",
    "description": "Task execution API",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "nvm:card-delegation",
      "network": "stripe",
      "planId": "plan-123",
      "extra": {
        "version": "1",
        "agentId": "did:nv:agent-456"
      }
    }
  ],
  "extensions": {}
}

PAYMENT-RESPONSE Header (Success)

Agents include this header in successful responses:

HTTP/1.1 200 OK
Content-Type: application/json
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4Li4uIn0=

{"result": "Task completed"}

The header contains base64-encoded settlement details:

{
  "success": true,
  "network": "eip155:84532",
  "transaction": "0x...",
  "creditsRedeemed": "2",
  "remainingBalance": "98"
}

Complete X402 Flow

Subscriber Side

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

const subscriberPayments = Payments.getInstance({
  nvmApiKey: process.env.SUBSCRIBER_API_KEY!,
  environment: 'sandbox' as EnvironmentName,
})

// 1. Create a delegation once (currency required; 'usdc' for erc4337),
//    then generate an access token by its delegationId.
const { delegationId } = await subscriberPayments.delegation.createDelegation({
  provider: 'erc4337',
  spendingLimitCents: 1000,
  durationSecs: 86_400,
  currency: 'usdc',
})
const { accessToken } = await subscriberPayments.x402.getX402AccessToken(planId, agentId, {
  scheme: 'nvm:erc4337',
  delegationConfig: { delegationId },
})

// 2. Make request with payment-signature header
const response = await fetch('https://agent.example.com/api/v1/tasks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'payment-signature': accessToken,
  },
  body: JSON.stringify({ prompt: 'Hello, agent!' }),
})

// 3. Handle response
if (response.status === 402) {
  // Payment required - need to purchase plan or top up
  const paymentRequired = response.headers.get('PAYMENT-REQUIRED')
  console.error('Payment required:', paymentRequired)
} else {
  const result = await response.json()
  const paymentResponse = response.headers.get('PAYMENT-RESPONSE')
  console.log('Success:', result)
  console.log('Payment:', paymentResponse)
}

Agent Side

import express from 'express'
import { Payments, EnvironmentName } from '@nevermined-io/payments'
import { buildPaymentRequired } from '@nevermined-io/payments'

const app = express()
app.use(express.json())

const agentPayments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: 'sandbox' as EnvironmentName,
})

app.post('/api/v1/tasks', async (req, res) => {
  // 1. Extract token
  const accessToken = req.headers['payment-signature'] as string

  if (!accessToken) {
    const paymentRequired = buildPaymentRequired(planId, {
      endpoint: req.url,
      agentId: agentId,
      httpVerb: req.method,
    })

    return res
      .status(402)
      .set('PAYMENT-REQUIRED', Buffer.from(JSON.stringify(paymentRequired)).toString('base64'))
      .json({ error: 'Payment required' })
  }

  // 2. Build payment required
  const paymentRequired = buildPaymentRequired(planId, {
    endpoint: req.url,
    agentId: agentId,
    httpVerb: req.method,
  })

  try {
    // 3. Verify permissions
    const verification = await agentPayments.facilitator.verifyPermissions({
      paymentRequired,
      x402AccessToken: accessToken,
      maxAmount: 2n,
    })

    if (!verification.isValid) {
      return res
        .status(402)
        .set('PAYMENT-REQUIRED', Buffer.from(JSON.stringify(paymentRequired)).toString('base64'))
        .json({ error: 'Insufficient credits' })
    }

    // 4. Execute task
    const result = await processTask(req.body)

    // 5. Settle permissions
    const settlement = await agentPayments.facilitator.settlePermissions({
      paymentRequired,
      x402AccessToken: accessToken,
      maxAmount: 2n,
    })

    // 6. Return response with PAYMENT-RESPONSE header
    const paymentResponse = {
      success: settlement.success,
      network: settlement.network,
      transaction: settlement.transaction,
      creditsRedeemed: settlement.creditsRedeemed,
    }

    return res
      .status(200)
      .set('PAYMENT-RESPONSE', Buffer.from(JSON.stringify(paymentResponse)).toString('base64'))
      .json({ result })

  } catch (error) {
    res.status(500).json({ error: error.message })
  }
})

app.listen(3000)

buildPaymentRequired Helper

Simplifies creating X402PaymentRequired objects:

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

// Scheme auto-detected from plan metadata when omitted
const paymentRequired = buildPaymentRequired(
  planId,
  {
    endpoint: '/api/v1/tasks',      // Resource URL
    agentId: 'did:nv:agent-456',    // Agent ID
    httpVerb: 'POST',               // HTTP method
    network: 'eip155:84532',        // Blockchain (default for nvm:erc4337)
    description: 'Task execution',  // Description
    scheme: 'nvm:erc4337'           // Optional: omit to auto-detect from plan metadata
  }
)

When scheme is set to 'nvm:card-delegation', the network is automatically set to 'stripe'.

Best Practices

Always Verify Before Execute: Never skip token verification
Settle After Success: Only burn credits after successful execution
Use X402 v2 Headers: Prefer payment-signature over Authorization
Return 402 Properly: Include PAYMENT-REQUIRED header with details
Log Transactions: Record settlement transaction hashes
Handle Errors: Provide clear error messages in 402 responses
Token Reuse: Subscribers can reuse tokens for multiple requests
Restrict Cards to API Keys: When running multiple agents, restrict each card to specific NVM API Keys using allowedApiKeyIds to prevent unauthorized spending
Reuse Delegations: Pass delegationId to reuse existing delegations instead of creating new ones on each request — this avoids delegation sprawl and keeps spending consolidated

Querying an Agent - How subscribers use X402 tokens
Validation of Requests - How agents verify and settle
MCP Integration - Automatic X402 handling in MCP
A2A Integration - Automatic X402 handling in A2A

Source References:

src/x402/token.ts (getX402AccessToken)
src/x402/delegation-api.ts (DelegationAPI: listPaymentMethods, listDelegations, updatePaymentMethod)
src/x402/facilitator-api.ts (verifyPermissions, settlePermissions, buildPaymentRequired)
tests/e2e/test_x402_e2e.test.ts (complete X402 flow)

TypeScript SDK

Python SDK

CLI

OpenClaw Plugin

X402 Protocol

X402 Protocol

Overview of X402

Supported Schemes

Visa support

X402 Version 2 Specification

Generate X402 Access Tokens

Generate Tokens via Nevermined App

Generate Card-Delegation Tokens

Reusing Existing Delegations

Deprecated: inline create-on-the-fly

CardDelegationConfig Reference

Auto Scheme Resolution

DelegationAPI

Update Payment Method

List Delegations

createDelegation

DelegationListResponse Fields

DelegationSummary Fields

PaymentMethodSummary Fields

X402 Access Token Structure

Card-Delegation Token Structure

Token Components

Verify X402 Permissions

Verification Response

Settle X402 Permissions

Settlement Response

HTTP Headers (X402 v2)

payment-signature Header

PAYMENT-REQUIRED Header (402 Response)

PAYMENT-RESPONSE Header (Success)

Complete X402 Flow

Subscriber Side

Agent Side

buildPaymentRequired Helper

Best Practices

​X402 Protocol

​Overview of X402

​Supported Schemes

​Visa support

​X402 Version 2 Specification

​Generate X402 Access Tokens

​Generate Tokens via Nevermined App

​Generate Card-Delegation Tokens

​Reusing Existing Delegations

​Deprecated: inline create-on-the-fly

​CardDelegationConfig Reference

​Auto Scheme Resolution

​DelegationAPI

​Update Payment Method

​List Delegations

​createDelegation

​DelegationListResponse Fields

​DelegationSummary Fields

​PaymentMethodSummary Fields

​X402 Access Token Structure

​Card-Delegation Token Structure

​Token Components

​Verify X402 Permissions

​Verification Response

​Settle X402 Permissions

​Settlement Response

​HTTP Headers (X402 v2)

​payment-signature Header

​PAYMENT-REQUIRED Header (402 Response)

​PAYMENT-RESPONSE Header (Success)

​Complete X402 Flow

​Subscriber Side

​Agent Side

​buildPaymentRequired Helper

​Best Practices

​Related Documentation

X402 Protocol

Overview of X402

Supported Schemes

Visa support

X402 Version 2 Specification

Generate X402 Access Tokens

Generate Tokens via Nevermined App

Generate Card-Delegation Tokens

Reusing Existing Delegations

Deprecated: inline create-on-the-fly

CardDelegationConfig Reference

Auto Scheme Resolution

DelegationAPI

Update Payment Method

List Delegations

createDelegation

DelegationListResponse Fields

DelegationSummary Fields

PaymentMethodSummary Fields

X402 Access Token Structure

Card-Delegation Token Structure

Token Components

Verify X402 Permissions

Verification Response

Settle X402 Permissions

Settlement Response

HTTP Headers (X402 v2)

payment-signature Header

PAYMENT-REQUIRED Header (402 Response)

PAYMENT-RESPONSE Header (Success)

Complete X402 Flow

Subscriber Side

Agent Side

buildPaymentRequired Helper

Best Practices

Related Documentation