Payment Plans

Payment plans define how subscribers access your AI agents. The Nevermined Payments Library provides a flexible Plans API for registering different types of plans with various pricing and credit configurations.

Overview of Payment Plans API

The Plans API (payments.plans) allows AI builders to:

Define pricing structures (fiat, crypto, ERC20 tokens, or free)
Configure credit allocation (fixed, dynamic, time-based)
Register plans with the Nevermined protocol
Retrieve and manage existing plans
Associate plans with agents

Types of Payment Plans

Credits Plans

Grant subscribers a specific number of credits to use across multiple requests. Each agent request burns a defined number of credits. Use cases: API calls, LLM queries, data processing tasks

Time Plans

Provide unlimited access for a fixed duration. No per-request credit deduction during the validity period. Use cases: Subscriptions, unlimited access periods, trial memberships

Trial Plans

Free plans with time limitations, perfect for demos and user onboarding. Use cases: Free trials, demonstrations, testing

Pay-As-You-Go Plans

Dynamic pricing where subscribers pay per request without pre-purchasing credits. Use cases: Variable usage patterns, enterprise integrations

Price Configuration

The library provides helper functions for different payment methods:

Crypto Payment (Native Token)

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

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

const builderAddress = payments.getAccountAddress()

// Native token pricing (ETH, MATIC, etc.)
const priceConfig = payments.plans.getCryptoPriceConfig(
  100n,           // Amount in wei
  builderAddress, // Receiver address
  ZeroAddress     // Native token
)

ERC20 Token Payment

// ERC20 token pricing (USDC, DAI, etc.)
const USDC_ADDRESS = '0x036CbD53842c5426634e7929541eC2318f3dCF7e' // USDC on Base Sepolia

const priceConfig = payments.plans.getERC20PriceConfig(
  20n,            // Amount in token's smallest unit
  USDC_ADDRESS,   // Token contract address
  builderAddress  // Receiver address
)

EURC Token Payment (Euro Stablecoin)

// EURC pricing (Euro stablecoin on Base, 6 decimals)
const eurcPriceConfig = payments.plans.getEURCPriceConfig(
  29_000_000n,    // €29.00 in smallest unit (6 decimals)
  builderAddress  // Receiver address
)

// Or use a custom EURC address (e.g., testnet)
import { EURC_TOKEN_ADDRESS_TESTNET } from '@nevermined-io/payments'

const testnetEurcConfig = payments.plans.getEURCPriceConfig(
  29_000_000n,
  builderAddress,
  EURC_TOKEN_ADDRESS_TESTNET
)

Fiat Payment (Stripe)

// Fiat pricing in USD (default)
const priceConfig = payments.plans.getFiatPriceConfig(
  10_000_000n,    // Amount in 6-decimal units ($10.00) — NOT cents
  builderAddress
)

// Fiat pricing in EUR
import { Currency } from '@nevermined-io/payments'

const eurPriceConfig = payments.plans.getFiatPriceConfig(
  29_000_000n,    // Amount in 6-decimal units (€29.00) — NOT cents
  builderAddress,
  Currency.EUR
)

Fiat amounts are in 6-decimal units (the USDC convention used across the Nevermined protocol), not cents — 10_000_000n = $10.00. The server-side minimum is **$ 1.00** (1_000_000n); smaller amounts are rejected with BCK.PROTOCOL.0047.

Free Plans

// Free plan (no payment required)
const priceConfig = payments.plans.getFreePriceConfig()

Pay-As-You-Go Pricing

// Get template address for PAYG plans
const templateAddress = await payments.contracts.getPayAsYouGoTemplateAddress()

const priceConfig = payments.plans.getPayAsYouGoPriceConfig(
  100n,              // Cost per request
  builderAddress,
  ZeroAddress,       // Token address (optional)
  templateAddress
)

Credits Configuration

Fixed Credits

Grants a specific number of credits with a fixed burn rate per request.

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

// Grant 100 credits, burn 1 credit per request
const creditsConfig = payments.plans.getFixedCreditsConfig(
  100n,  // Total credits granted
  1n     // Credits per request
)

Dynamic Credits

Allows variable credit consumption per request within a range.

// Grant 10 credits, burn 1-2 credits per request (agent decides)
const creditsConfig = payments.plans.getDynamicCreditsConfig(
  10n,  // Total credits granted
  1n,   // Minimum credits per request
  2n    // Maximum credits per request
)

Time-Based Credits (Expirable)

Provides unlimited access for a fixed duration.

import { ONE_DAY_DURATION, ONE_WEEK_DURATION, ONE_MONTH_DURATION } from '@nevermined-io/payments'

// Unlimited access for 24 hours
const creditsConfig = payments.plans.getExpirableDurationConfig(
  ONE_DAY_DURATION  // Duration in seconds
)

// Other durations
const weeklyConfig = payments.plans.getExpirableDurationConfig(ONE_WEEK_DURATION)
const monthlyConfig = payments.plans.getExpirableDurationConfig(ONE_MONTH_DURATION)

Non-Expirable Duration

// Unlimited access with no expiration
const creditsConfig = payments.plans.getNonExpirableDurationConfig()

Registering Plans

Register a Credits Plan

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

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

const builderAddress = payments.getAccountAddress()
const ERC20_ADDRESS = '0x036CbD53842c5426634e7929541eC2318f3dCF7e'

// Define plan metadata
const planMetadata: PlanMetadata = {
  name: 'Basic AI Agent Access',
  description: 'Get 100 credits to query our AI agent',
}

// Configure pricing and credits
const priceConfig = payments.plans.getERC20PriceConfig(
  20n,
  ERC20_ADDRESS,
  builderAddress
)

const creditsConfig = payments.plans.getFixedCreditsConfig(100n, 1n)

// Register the plan
const { planId } = await payments.plans.registerCreditsPlan(
  planMetadata,
  priceConfig,
  creditsConfig
)

console.log(`Credits plan registered with ID: ${planId}`)

Register a Time Plan

import { ONE_DAY_DURATION, PlanMetadata } from '@nevermined-io/payments'

const planMetadata: PlanMetadata = {
  name: '24-Hour Unlimited Access',
  description: 'Unlimited queries for 24 hours',
}

const priceConfig = payments.plans.getERC20PriceConfig(
  50n,
  ERC20_ADDRESS,
  builderAddress
)

const creditsConfig = payments.plans.getExpirableDurationConfig(ONE_DAY_DURATION)

const { planId } = await payments.plans.registerTimePlan(
  planMetadata,
  priceConfig,
  creditsConfig
)

console.log(`Time plan registered with ID: ${planId}`)

Register a Trial Plan

import { ONE_DAY_DURATION, PlanMetadata } from '@nevermined-io/payments'

const planMetadata: PlanMetadata = {
  name: 'Free 24-Hour Trial',
  description: 'Try our AI agent free for 24 hours',
}

// Free pricing
const priceConfig = payments.plans.getFreePriceConfig()

// Limited duration
const creditsConfig = payments.plans.getExpirableDurationConfig(ONE_DAY_DURATION)

const { planId } = await payments.plans.registerTimeTrialPlan(
  planMetadata,
  priceConfig,
  creditsConfig
)

console.log(`Trial plan registered with ID: ${planId}`)

Retrieving Plans

Get a Specific Plan

// Retrieve plan details by ID
const plan = await payments.plans.getPlan(planId)

console.log(`Plan: ${plan.name}`)
console.log(`Price: ${plan.price}`)
console.log(`Credits: ${plan.credits}`)

List Your Plans

List the plans you published — the authenticated caller’s own plans. This is account management, not a marketplace search: it never returns other users’ plans. Pass an orgId to list every plan in an organization you belong to.

// Your own plans (paginated: { total, page, offset, plans })
const { plans } = await payments.plans.getPlans()

plans.forEach((plan) => {
  console.log(`${plan.name}: ${plan.planId}`)
})

// Every plan in an organization you belong to
const { plans: orgPlans } = await payments.plans.getPlans(1, 100, 'created', 'desc', 'org-acme')

Get Plans for an Agent

To find plans associated with an agent, use the agents API:

// Get all payment plans associated with an agent
const { plans } = await payments.agents.getAgentPlans(agentId)

plans.forEach(plan => {
  console.log(`Plan: ${plan.name} (${plan.planId})`)
})

Duration Constants

The library provides convenient duration constants:

import {
  ONE_DAY_DURATION,     // 86,400 seconds (24 hours)
  ONE_WEEK_DURATION,    // 604,800 seconds (7 days)
  ONE_MONTH_DURATION,   // 2,629,746 seconds (~30.44 days)
  ONE_YEAR_DURATION     // 31,557,600 seconds (~365.25 days)
} from '@nevermined-io/payments'

Complete Example: Multi-Tier Plans

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

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

const builderAddress = payments.getAccountAddress()
const ERC20_ADDRESS = '0x036CbD53842c5426634e7929541eC2318f3dCF7e'

// Free trial plan
const { planId: trialPlanId } = await payments.plans.registerTimeTrialPlan(
  { name: 'Free Trial', description: '24 hours free access' },
  payments.plans.getFreePriceConfig(),
  payments.plans.getExpirableDurationConfig(ONE_DAY_DURATION)
)

// Basic tier - 100 credits
const { planId: basicPlanId } = await payments.plans.registerCreditsPlan(
  { name: 'Basic Plan', description: '100 credits for basic usage' },
  payments.plans.getERC20PriceConfig(10n, ERC20_ADDRESS, builderAddress),
  payments.plans.getFixedCreditsConfig(100n, 1n)
)

// Pro tier - unlimited monthly access
const { planId: proPlanId } = await payments.plans.registerTimePlan(
  { name: 'Pro Plan', description: 'Unlimited access for 30 days' },
  payments.plans.getERC20PriceConfig(50n, ERC20_ADDRESS, builderAddress),
  payments.plans.getExpirableDurationConfig(ONE_MONTH_DURATION)
)

console.log('Multi-tier plans created:')
console.log(`Trial: ${trialPlanId}`)
console.log(`Basic: ${basicPlanId}`)
console.log(`Pro: ${proPlanId}`)

Agents - Associate plans with agents
Payments and Balance - How subscribers order plans

Source References:

src/plans.ts (helper functions, duration constants)
src/api/plans-api.ts (Plans API methods)
tests/e2e/test_payments_e2e.test.ts (lines 277-369)

​Payment Plans

​Overview of Payment Plans API

​Types of Payment Plans

​Credits Plans

​Time Plans

​Trial Plans

​Pay-As-You-Go Plans

​Price Configuration

​Crypto Payment (Native Token)

​ERC20 Token Payment

​EURC Token Payment (Euro Stablecoin)

​Fiat Payment (Stripe)

​Free Plans

​Pay-As-You-Go Pricing

​Credits Configuration

​Fixed Credits

​Dynamic Credits

​Time-Based Credits (Expirable)

​Non-Expirable Duration

​Registering Plans

​Register a Credits Plan

​Register a Time Plan

​Register a Trial Plan

​Retrieving Plans

​Get a Specific Plan

​List Your Plans

​Get Plans for an Agent

​Duration Constants

​Complete Example: Multi-Tier Plans

​Related Documentation