Register Plans & Agents

You can create Payment Plans and register AI Agents manually or programatically:

Nevermined App

Go to the Nevermined App and click on “My agents” or “My pricing plans” to crete Payment Plans and register your AI Agents.

Payments Libraries

Use the Payments Libraries to programmatically create Payment Plans and register AI Agents.

In this guide, we will focus on how to register AI Agents and create Payment Plans using the Payments Libraries.

Once you have a Payments instance, you can start creating Plans and registering AI Agents.

Creating a Payment Plan

Payment Plans give AI Builders the ability to control how and when users can use an AI Agent or service. They are entirely controlled and managed by the AI Builder that creates them with no interference from Nevermined. Nevermined Payment Plans enable time-based or request-based gating of an AI Agent.

Creating Credit-Based Plans

Provides user access with per-request pricing. Builders can manage the cost per request to access their AI service. This is done by setting the price to purchase a bundle of credits and the number of credits redeemed for each request (call onfigured during Plan creation). Each time a request is made, user credits are validated and redeemed. If the user does not have enough credits, they will be prompted to purchase more and denied access until they do so.

TypeScript
Python

// This is the USDC ERC20 address in the test network (sandbox)
const USDC_ERC20_TESTING = '0x036CbD53842c5426634e7929541eC2318f3dCF7e'

const planMetadata = {
  name: 'My Credits Plan',
  tags: ['test']
}

// The price is 20 USDC (20_000_000) in the sandbox network
const priceConfig = getERC20PriceConfig(20_000_000n, USDC_ERC20_TESTING, builderAddress)
// The subscriber receives 100 credits upon purchasing the plan
const creditsConfig = getFixedCreditsConfig(100n)
// Register the plan
const { planId } = await payments.plans.registerCreditsPlan(
  planMetadata, 
  priceConfig, 
  creditsConfig
)

# This is the USDC ERC20 address in the test network (sandbox)
USDC_ERC20_TESTING = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"

# Plan metadata
plan_metadata = PlanMetadata(
    name="My Credits Plan",
    tags=["test"]
)

# The price is 20 USDC (20_000_000) in the sandbox network
price_config = get_erc20_price_config(20_000_000, USDC_ERC20_TESTING, builder_address)
# The subscriber receives 100 credits upon purchasing the plan
credits_config = get_fixed_credits_config(100)

# Register the plan
response = payments_builder.plans.register_credits_plan(
    plan_metadata,
    price_config,
    credits_config
)
plan_id = response.get("planId")

Creating a Time-Based Plan

Provides user access on a time-gating basis. Builders can set the time period that a user is allowed access to the AI (e.g. 1 year, 1 month, 1 hour, etc.). When a user makes their first request, the corresponding access credit is redeemed, granting access for the designated period. Once the time period has elapsed, the user will no longer have access and will need to redeem another credit for continued access.

TypeScript
Python

// The price is 5 USDC (5_000_000) in the sandbox network
const priceConfig = getERC20PriceConfig(5_000_000n, ERC20_ADDRESS, builderAddress)
// The plan is valid for 1 day
const oneDayPlanConfig = getExpirableDurationConfig(ONE_DAY_DURATION)
// Register the plan
const { planId } = await payments.plans.registerTimePlan(
  planMetadata, 
  priceConfig, 
  oneDayPlanConfig
)

# The price is 5 USDC (5_000_000) in the sandbox network
price_config = get_erc20_price_config(5_000_000, ERC20_ADDRESS, builder_address)
# The plan is valid for 1 day
one_day_plan_config = get_expirable_duration_config(ONE_DAY_DURATION)
# Register the plan
response = payments_builder.plans.register_time_plan(
    plan_metadata,
    price_config,
    one_day_plan_config
)
plan_id = response.get("planId")

Creating a Trial Plan

A Trial Plan is a special type of Payment Plan that allows users to try out an AI Agent for a limited time (typically for free). A Trial Plan can only be obtained once by each user. There are two types of trial plans:

Credits-Based Trial Plan

Perfect for giving users a fixed number of free credits to test your service:

TypeScript
Python

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

const trialPlanMetadata = {
  name: 'Free Trial - 10 Credits'
}

// The price is free
const freeConfig = getFreePriceConfig()
// Give 10 credits for free
const trialCreditsConfig = getFixedCreditsConfig(10n)

// Register the credits-based trial plan
const { planId } = await payments.plans.registerCreditsTrialPlan(
  trialPlanMetadata,
  freeConfig,
  trialCreditsConfig
)

from payments_py.plans import get_free_price_config, get_fixed_credits_config

trial_plan_metadata = PlanMetadata(
    name="Free Trial - 10 Credits"
)

# The price is free
free_config = get_free_price_config()
# Give 10 credits for free
trial_credits_config = get_fixed_credits_config(10)

# Register the credits-based trial plan
response = payments_builder.plans.register_credits_trial_plan(
    trial_plan_metadata,
    free_config,
    trial_credits_config
)
plan_id = response.get("planId")

Time-Based Trial Plan

Perfect for giving users free access for a limited time period:

TypeScript
Python

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

const trialPlanMetadata = {
  name: 'Try it for one day before you buy it'
}

// The price is free
const freeConfig = getFreePriceConfig()
// The plan is valid for 1 day
const oneDayPlanConfig = getExpirableDurationConfig(ONE_DAY_DURATION)

// Register the time-based trial plan
const { planId } = await payments.plans.registerTimeTrialPlan(
  trialPlanMetadata,
  freeConfig,
  oneDayPlanConfig
)

from payments_py.plans import get_free_price_config, get_expirable_duration_config, ONE_DAY_DURATION

# Plan metadata for the trial plan
trial_plan_metadata = PlanMetadata(
    name="Try it for one day before you buy it"
)

# The price is free
free_config = get_free_price_config()
# The plan is valid for 1 day
one_day_plan_config = get_expirable_duration_config(ONE_DAY_DURATION)

# Register the time-based trial plan
response = payments_builder.plans.register_time_trial_plan(
    trial_plan_metadata,
    free_config,
    one_day_plan_config
)
plan_id = response.get("planId")

Creating a Pay As You Go Plan

Pay As You Go plan is a type of payment plan that allows users to pay for each request they make to an AI Agent without having to purchase a bundle of credits upfront.

TypeScript
Python

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

// USDC on the sandbox network
const USDC_ERC20_TESTING = '0x036CbD53842c5426634e7929541eC2318f3dCF7e'

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

const planMetadata = {
  name: 'My PAYG Plan',
  description: 'Pay per request',
}

// The SDK fetches the PAYG template address from the API info endpoint
const priceConfig = await payments.plans.getPayAsYouGoPriceConfig(
  100n,                 // amount per request (token minor units)
  '0x9dDD02D4E111ab5cE47511987B2500fcB56252c6', // receiver
  USDC_ERC20_TESTING,   // ERC20 token
)

// Credits config is required for validation but not used to mint credits
const creditsConfig = getPayAsYouGoCreditsConfig()

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

from payments_py import Payments
from payments_py.common.types import PaymentOptions, PlanMetadata
from payments_py.plans import get_pay_as_you_go_credits_config

USDC_ERC20_TESTING = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"

payments = Payments(
    PaymentOptions(
        nvm_api_key="YOUR_NVM_API_KEY",
        environment="sandbox",
    )
)

plan_metadata = PlanMetadata(
    name="My PAYG Plan",
    description="Pay per request",
)

# SDK fetches PAYG template address from the API info endpoint
price_config = payments.plans.get_pay_as_you_go_price_config(
    amount=100,
    receiver="0x9dDD02D4E111ab5cE47511987B2500fcB56252c6",
    token_address=USDC_ERC20_TESTING,
)

# Credits config is required for validation but credits are not minted upfront
credits_config = get_pay_as_you_go_credits_config()

response = payments.plans.register_credits_plan(
    plan_metadata,
    price_config,
    credits_config,
)
plan_id = response.get("planId")

Registering an AI Agent

When you register an Agent, you need to provide the API endpoints for accessing the AI Agent, including all relevant HTTP(s) methods, URL patterns and wildcards.

Before registering an AI Agent, you need to have a Payment Plan created.

TypeScript
Python

// When you register an agent, you need to provide the endpoints that the agent exposes and are protected by the Payment Plan
// You must specify the HTTP method and the URL pattern that the agent exposes
// You can use wildcards (like :agentId in the example) to match any string
// See more information about the wildcards supported here: https://github.com/pillarjs/path-to-regexp

const agentMetadata: AgentMetadata = {
  name: 'E2E Payments Agent',
  tags: ['test'],
  dateCreated: new Date(),
  description: 'Description for the E2E Payments Agent'
}

// You can use wildcards (like :agentId in the example) to match any string in your endpoints
const agentApi = {
  endpoints: [
    { 'POST': 'https://example.com/api/v1/agents/:agentId/tasks' },
    { 'GET': 'https://example.com/api/v1/agents/:agentId/tasks/invoke' }
  ],
  openEndpoints: ['https://example.com/api/v1/rest/docs-json'],
  agentDefinitionUrl: 'https://example.com/api/v1/openapi.json' // URL to OpenAPI spec, MCP Manifest, or A2A agent card
}
const paymentPlans = [creditsPlanId, expirablePlanId]

const { agentId } = await payments.agents.registerAgent(
  agentMetadata, 
  agentApi, 
  paymentPlans
)

# When you register an agent, you need to provide the endpoints that the agent exposes and are protected by the Payment Plan
# You must specify the HTTP method and the URL pattern that the agent exposes
# You can use wildcards (like :agentId in the example) to match any string
# See more information about the wildcards supported here: https://github.com/pillarjs/path-to-regexp

from datetime import datetime

agent_metadata = {
    "name": "E2E Payments Agent",
    "tags": ["test"],
    "dateCreated": datetime.now().isoformat(),
    "description": "Description for the E2E Payments Agent"
}

# You can use wildcards (like :agentId in the example) to match any string in your endpoints
agent_api = {
    "endpoints": [
        {"POST": "https://example.com/api/v1/agents/:agentId/tasks"},
        {"GET": "https://example.com/api/v1/agents/:agentId/tasks/invoke"}
    ],
    "openEndpoints": ["https://example.com/api/v1/rest/docs-json"],
    "agentDefinitionUrl": "https://example.com/api/v1/openapi.json"  # URL to OpenAPI spec, MCP Manifest, or A2A agent card
}
payment_plans = [credits_plan_id, expirable_plan_id]

response = payments_builder.agents.register_agent(
    agent_metadata,
    agent_api,
    payment_plans
)
agent_id = response.get("agentId")

Register an AI Agent and Payment Plan in One Step

This method allows you to create the plan and attach the agent to it in one step.

Note: The accessLimit parameter is optional. If not specified, it is automatically inferred based on creditsConfig.durationSecs:

"credits" if durationSecs === 0n (non-expirable plans)
"time" if durationSecs > 0n (expirable plans)

You can explicitly set it if needed:

TypeScript
Python

const agentMetadata = { 
  name: 'My AI Payments Agent', 
  tags: ['test2'], 
  description: 'Description for my AI Payments Agent' 
}
const agentApi = { 
  endpoints: [{ 'POST': 'http://example.com/test/:agentId/tasks' }],
  agentDefinitionUrl: 'http://example.com/test/openapi.json' // URL to OpenAPI spec, MCP Manifest, or A2A agent card
}

const cryptoPriceConfig = getNativeTokenPriceConfig(500n, builderAddress)
// Non expirable payment plan
const nonExpirableConfig = getNonExpirableDurationConfig()

const { agentId, planId } = await paymentsBuilder.agents.registerAgentAndPlan(
  agentMetadata,
  agentApi,
  planMetadata,
  cryptoPriceConfig,
  nonExpirableConfig,
  'credits' // Optional: accessLimit ('credits' or 'time'). Auto-inferred if not specified
)

# Agent metadata and API definition
agent_metadata = {
    "name": "My AI Payments Agent",
    "tags": ["test2"],
    "description": "Description for my AI Payments Agent"
}
agent_api = {
    "endpoints": [
        {"POST": "http://example.com/test/:agentId/tasks"}
    ],
    "agentDefinitionUrl": "http://example.com/test/openapi.json"  # URL to OpenAPI spec, MCP Manifest, or A2A agent card
}

# The price is 500 native tokens
crypto_price_config = get_native_token_price_config(500, builder_address)
# Non expirable payment plan
non_expirable_config = get_non_expirable_duration_config()

response = payments_builder.agents.register_agent_and_plan(
    agent_metadata,
    agent_api,
    plan_metadata,
    crypto_price_config,
    non_expirable_config,
    'credits'  # Optional: access_limit ('credits' or 'time'). Auto-inferred if not specified
)
agent_id = response.get("agentId")
plan_id = response.get("planId")
print('Plan created', response.planDID)
print('Agent attached', response.agentDID)

Key Concepts

Endpoint Protection

When registering an AI Agent, you specify:

Protected Endpoints: Require payment/subscription to access
Open Endpoints: Free to access (e.g., documentation, health checks)
URL Patterns: Support wildcards for dynamic routing

URL Patterns (path-to-regexp)

We use path-to-regexp to define and validate the URL patterns of your agent endpoints. This allows dynamic routing via named parameters and wildcards. See the project documentation for full syntax and options: path-to-regexp.

Wildcard example:

https://example.com/api/v1/agents/*path

Matches one or more segments after agents/ and captures them into the path array.

Parameters example:

https://example.com/api/v1/agents/:agentId/tasks/:taskId

Captures agentId and taskId as named parameters.

Payment Plan Types

Credits-Based

Sets the price per-request. Users buy a bundle of credits that are redeemed against usage.

Time-Based

Users get unlimited access for a specific time period (hours, days, months).

Trial Plans

Free access for limited time or credits to let users test your service.

Pay As You Go

Pay for each request they make to an AI Agent without having to purchase a bundle of credits upfront.

Best Practices

Plan Naming

Use descriptive names that clearly indicate what the plan offers (e.g., “Basic API Access - 1000 requests”).

Pricing Strategy

Start with competitive pricing and adjust based on usage patterns and user feedback.

Endpoint Design

Group related functionality under the same payment plan to provide better value to subscribers.

Trial Plans

Always offer trial plans to reduce barriers to entry and increase conversion rates.

Next Steps

Once you have registered your agents and plans, you can:

Test Purchasing

Learn how users purchase your payment plans

Handle Requests

Implement request validation in your AI agent

Getting Started

Development Guide

Integrations

Nevermined App

Payments Libraries

Creating a Payment Plan

Creating Credit-Based Plans

Creating a Time-Based Plan

Creating a Trial Plan

Credits-Based Trial Plan

Time-Based Trial Plan

Creating a Pay As You Go Plan

Registering an AI Agent

Register an AI Agent and Payment Plan in One Step

Key Concepts

Endpoint Protection

URL Patterns (path-to-regexp)

Payment Plan Types

Credits-Based

Time-Based

Trial Plans

Pay As You Go

Best Practices

Next Steps

Test Purchasing

Handle Requests

Getting Started

Development Guide

Integrations

Nevermined App

Payments Libraries

​Creating a Payment Plan

​Creating Credit-Based Plans

​Creating a Time-Based Plan

​Creating a Trial Plan

​Credits-Based Trial Plan

​Time-Based Trial Plan

​Creating a Pay As You Go Plan

​Registering an AI Agent

​Register an AI Agent and Payment Plan in One Step

​Key Concepts

​Endpoint Protection

​URL Patterns (path-to-regexp)

​Payment Plan Types

Credits-Based

Time-Based

Trial Plans

Pay As You Go

​Best Practices

​Next Steps

Test Purchasing

Handle Requests

Creating a Payment Plan

Creating Credit-Based Plans

Creating a Time-Based Plan

Creating a Trial Plan

Credits-Based Trial Plan

Time-Based Trial Plan

Creating a Pay As You Go Plan

Registering an AI Agent

Register an AI Agent and Payment Plan in One Step

Key Concepts

Endpoint Protection

URL Patterns (path-to-regexp)

Payment Plan Types

Best Practices

Next Steps