Payment Models

The x402 Facilitator supports multiple payment models to match your product needs across APIs, agents/tools, and protected resources. These models are enabled by Nevermined’s programmable x402 settlement layer (smart accounts + policies + contracts), not just single-transfer pay-per-request flows. If you’re looking for the HTTP handshake details (402 discovery → retry with PAYMENT-SIGNATURE), see:

Nevermined x402

Payment Model Types

Credits-Based

Charge per request or API call. Users purchase credits and consume them with each query.

Time-Based

Subscription access for specific durations. Unlimited usage within the time period.

Dynamic

Variable pricing based on request complexity, token count, or custom metrics.

Hybrid

Combine time-based access with credit limits for balanced monetization.

Credits-Based Plans

Charge users based on actual usage. Each request consumes a configurable number of credits.

TypeScript
Python

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

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

// Price: 10 USDC for 100 credits
const priceConfig = getERC20PriceConfig(
  10_000_000n,                    // 10 USDC (6 decimals)
  '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC address
  process.env.BUILDER_ADDRESS     // Your receiving address
)

// Credits: 100 total, 1 per request
const creditsConfig = getFixedCreditsConfig(
  100n,  // Total credits
  1n     // Credits per request
)

const { planId } = await payments.plans.createPlan({
  agentId: 'did:nv:agent-123',
  name: 'Pro Plan - 100 Queries',
  description: 'Access to AI assistant with 100 queries',
  priceConfig,
  creditsConfig,
  accessLimit: 'credits'
})

from payments_py import Payments, PaymentOptions
from payments_py.plans import get_erc20_price_config, get_fixed_credits_config

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

# Price: 10 USDC for 100 credits
price_config = get_erc20_price_config(
    10_000_000,                    # 10 USDC (6 decimals)
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',  # USDC address
    os.environ['BUILDER_ADDRESS']  # Your receiving address
)

# Credits: 100 total, 1 per request
credits_config = get_fixed_credits_config(
    100,  # Total credits
    1     # Credits per request
)

plan = payments.plans.create_plan(
    agent_id='did:nv:agent-123',
    name='Pro Plan - 100 Queries',
    description='Access to AI assistant with 100 queries',
    price_config=price_config,
    credits_config=credits_config,
    access_limit='credits'
)

Time-Based Plans

Provide unlimited access for a specific duration. Great for subscription models.

TypeScript
Python

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

// Price: 50 USDC for 30 days access
const priceConfig = getERC20PriceConfig(
  50_000_000n,
  '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  process.env.BUILDER_ADDRESS
)

// Duration: 30 days (in seconds)
const timeConfig = getTimeBasedConfig(
  30 * 24 * 60 * 60  // 30 days in seconds
)

const { planId } = await payments.plans.createPlan({
  agentId: 'did:nv:agent-123',
  name: 'Monthly Subscription',
  description: 'Unlimited access for 30 days',
  priceConfig,
  timeConfig,
  accessLimit: 'time'
})

from payments_py.plans import get_time_based_config

# Price: 50 USDC for 30 days access
price_config = get_erc20_price_config(
    50_000_000,
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    os.environ['BUILDER_ADDRESS']
)

# Duration: 30 days (in seconds)
time_config = get_time_based_config(
    30 * 24 * 60 * 60  # 30 days in seconds
)

plan = payments.plans.create_plan(
    agent_id='did:nv:agent-123',
    name='Monthly Subscription',
    description='Unlimited access for 30 days',
    price_config=price_config,
    time_config=time_config,
    access_limit='time'
)

Dynamic Pricing

Charge variable amounts based on request complexity. The x402 max_amount field controls the maximum charge per request.

TypeScript
Python

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

// Dynamic: charge 1-10 credits based on request
const creditsConfig = getDynamicCreditsConfig(
  1n,   // Minimum credits per request
  10n   // Maximum credits per request
)

const { planId } = await payments.plans.createPlan({
  agentId: 'did:nv:agent-123',
  name: 'Pay As You Go',
  description: 'Variable pricing based on complexity',
  priceConfig,
  creditsConfig,
  accessLimit: 'credits'
})

// During settlement, specify actual amount
await payments.facilitator.settlePermissions({
  planId,
  maxAmount: BigInt(actualCreditsUsed), // 1-10 based on request
  x402AccessToken: token,
  subscriberAddress: address
})

from payments_py.plans import get_dynamic_credits_config

# Dynamic: charge 1-10 credits based on request
credits_config = get_dynamic_credits_config(
    1,   # Minimum credits per request
    10   # Maximum credits per request
)

plan = payments.plans.create_plan(
    agent_id='did:nv:agent-123',
    name='Pay As You Go',
    description='Variable pricing based on complexity',
    price_config=price_config,
    credits_config=credits_config,
    access_limit='credits'
)

# During settlement, specify actual amount
await payments.facilitator.settle_permissions(
    payment_required=payment_required,
    x402_access_token=access_token,
    max_amount=str(actual_credits_used),  # 1-10 based on request
)

Trial Plans

Offer free trials to attract new users.

TypeScript
Python

// Free credits trial
const { planId } = await payments.plans.registerCreditsTrialPlan({
  agentId: 'did:nv:agent-123',
  name: 'Free Trial',
  description: '10 free queries to try the service',
  credits: 10n,
  creditsPerRequest: 1n
})

// Free time-based trial
const { planId: timePlanId } = await payments.plans.registerTimeTrialPlan({
  agentId: 'did:nv:agent-123',
  name: '7-Day Trial',
  description: 'Unlimited access for 7 days',
  duration: 7 * 24 * 60 * 60  // 7 days in seconds
})

# Free credits trial
plan = payments.plans.register_credits_trial_plan(
    agent_id='did:nv:agent-123',
    name='Free Trial',
    description='10 free queries to try the service',
    credits=10,
    credits_per_request=1
)

# Free time-based trial
time_plan = payments.plans.register_time_trial_plan(
    agent_id='did:nv:agent-123',
    name='7-Day Trial',
    description='Unlimited access for 7 days',
    duration=7 * 24 * 60 * 60  # 7 days in seconds
)

Multi-Tier Pricing

Create multiple plans for different user segments:

// Basic tier
const basicPlan = await payments.plans.createPlan({
  agentId,
  name: 'Basic',
  priceConfig: getERC20PriceConfig(5_000_000n, usdcAddress, builderAddress),
  creditsConfig: getFixedCreditsConfig(50n, 1n)
})

// Pro tier
const proPlan = await payments.plans.createPlan({
  agentId,
  name: 'Pro',
  priceConfig: getERC20PriceConfig(20_000_000n, usdcAddress, builderAddress),
  creditsConfig: getFixedCreditsConfig(250n, 1n)  // Better value
})

// Enterprise tier
const enterprisePlan = await payments.plans.createPlan({
  agentId,
  name: 'Enterprise',
  priceConfig: getERC20PriceConfig(100_000_000n, usdcAddress, builderAddress),
  creditsConfig: getFixedCreditsConfig(2000n, 1n)  // Best value
})

Payment Currencies

Cryptocurrency (ERC-20)

Accept any ERC-20 token on supported networks:

// USDC
const usdcConfig = getERC20PriceConfig(
  10_000_000n,
  '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  builderAddress
)

// USDT
const usdtConfig = getERC20PriceConfig(
  10_000_000n,
  '0xdAC17F958D2ee523a2206206994597C13D831ec7',
  builderAddress
)

Fiat (Stripe, Braintree, or Visa)

Accept credit card payments via Stripe, Braintree, or the Visa Trusted Agent Protocol. The active provider is selected per plan via the seller’s fiatPaymentProvider metadata at registration time; all three providers settle x402 charges through the same nvm:card-delegation scheme. Visa delegations add a per-delegation WebAuthn/passkey approval enforced by Visa VTS and settle through Stripe Connect — see the Visa subsection on the card enrollment page.

const fiatConfig = await payments.plans.getFiatPriceConfig({
  amount: 1000,      // $10.00
  currency: 'USD'
})

// One-time fiat purchase via the SDK (Stripe-priced plans only):
const { url } = await payments.plans.orderFiatPlan(planId)
// Redirect user to Stripe checkout URL

orderFiatPlan returns a Stripe checkout URL and is only available for Stripe-priced plans. Braintree-priced plans are purchased through the Nevermined App’s Braintree Drop-in checkout. Both Stripe and Braintree plans support per-request x402 settlement against credit-card delegations — see Braintree onboarding for the seller-side requirements (per-currency merchant accounts).

Choosing the Right Model

Model	Best For	Example
Credits-based	API calls, queries, transactions	AI chatbot, image generation
Time-based	Continuous access, subscriptions	SaaS tools, monitoring
Dynamic	Variable workloads, token-based	LLM inference, batch processing
Hybrid	Balanced usage with limits	Enterprise subscriptions

Payment Model Types

Credits-Based

Time-Based

Dynamic

Hybrid

Credits-Based Plans

Time-Based Plans

Dynamic Pricing

Trial Plans

Multi-Tier Pricing

Payment Currencies

Cryptocurrency (ERC-20)

Fiat (Stripe, Braintree, or Visa)

Choosing the Right Model

Next Steps

Register Your Agent

Validate Requests

Documentation Index

​Payment Model Types

Credits-Based

Time-Based

Dynamic

Hybrid

​Credits-Based Plans

​Time-Based Plans

​Dynamic Pricing

​Trial Plans

​Multi-Tier Pricing

​Payment Currencies

​Cryptocurrency (ERC-20)

​Fiat (Stripe, Braintree, or Visa)

​Choosing the Right Model

​Next Steps

Register Your Agent

Validate Requests

Payment Model Types

Credits-Based Plans

Time-Based Plans

Dynamic Pricing

Trial Plans

Multi-Tier Pricing

Payment Currencies

Cryptocurrency (ERC-20)

Fiat (Stripe, Braintree, or Visa)

Choosing the Right Model

Next Steps