Initializing the Library

This guide shows how to initialize the Nevermined Payments Library in your application. The library supports both server-side (Node.js) and browser environments with different initialization methods.

Get Your NVM API Key

Before initializing the library, you need a Nevermined API key:

Visit nevermined.app
Sign in or create a free account
Navigate to your profile settings
Generate an API key

Important: There are two types of API keys:

Builder Key: For AI builders who register agents and payment plans
Subscriber Key: For users who purchase access and query agents

Most applications will use a builder key for server-side operations.

Server-Side Initialization

For Node.js applications, use the getInstance method:

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

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

The environment is derived automatically from your API key — see Environment derivation below.

Configuration Options

The getInstance method accepts a PaymentOptions object:

interface PaymentOptions {
  nvmApiKey: string           // Your Nevermined API key (required)
  environment?: EnvironmentName  // @deprecated — derived from the API key (optional)
  returnUrl?: string          // OAuth callback URL (optional, for browser)
  appId?: string              // Your application ID (optional)
  version?: string            // Backend API version pin, MAJOR.MINOR (optional)
}

Environment derivation

NVM API keys are prefixed with the environment they belong to (<prefix>:<jwt>), so the SDK resolves the target environment from the key — you no longer need to pass environment. The environment option is deprecated but still accepted:

When the key prefix maps to a known environment, the key always wins and the environment option is ignored (a one-time deprecation warning is logged).
When the key has no recognized prefix (for example a local/custom build), the SDK falls back to the environment option, and finally to custom. This keeps local and custom-backend workflows working unchanged.

Complete Server-Side Example

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

// Initialize with environment variables
const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: process.env.NVM_ENVIRONMENT as EnvironmentName,
})

// Verify connection
const accountAddress = payments.getAccountAddress()
console.log(`Connected as: ${accountAddress}`)

Browser Initialization

For browser-based applications, use the getBrowserInstance method:

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

const payments = Payments.getBrowserInstance({
  returnUrl: 'https://myapp.example/callback',
  environment: 'sandbox',
  appId: 'my-app',
  // Optional: pin the backend API version (MAJOR.MINOR). Defaults to the
  // version this SDK release targets — omit unless you must pin an older one.
  version: '1.1',
})

Browser Authentication Flow

The browser instance supports OAuth-style authentication:

// Check if user is logged in
if (!payments.isLoggedIn) {
  // Redirect to Nevermined login
  payments.connect()
}

// After login, use the payments instance
const balance = await payments.plans.getPlanBalance(planId)

// Logout when needed
payments.logout()

Environments

The Nevermined protocol supports multiple environments:

Production Environments

Environment	Description	Usage
`sandbox`	Production testing environment	Development and testing with real blockchain
`live`	Production environment	Live agents and real payments

Choosing an Environment

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

// Production deployment
const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: 'live',
})

Important: Agents and plans registered in one environment cannot be accessed from another. Always use the same environment throughout your application.

Environment Configuration Details

Each environment has specific API endpoints:

// Example environment structure
interface EnvironmentInfo {
  frontend: string   // Nevermined App URL
  backend: string    // API URL
  proxy: string      // Proxy service URL
  heliconeUrl: string // Observability service URL
}

The library automatically configures these endpoints based on your chosen environment.

Verify Connection

After initialization, verify the connection is working:

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

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

// Get account address from API key
const accountAddress = payments.getAccountAddress()
console.log(`Initialized for account: ${accountAddress}`)

// For browser instances
if (payments.isLoggedIn) {
  console.log('User authenticated successfully')
}

Best Practices

Environment Variables: Always store API keys in environment variables, never hardcode them
Singleton Pattern: Create one Payments instance per application
Environment Consistency: Use the same environment for all operations in a session
Error Handling: Wrap initialization in try-catch blocks for production apps

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

let payments: Payments

try {
  payments = Payments.getInstance({
    nvmApiKey: process.env.NVM_API_KEY!,
    environment: process.env.NVM_ENVIRONMENT as EnvironmentName,
  })
  console.log('✓ Nevermined Payments initialized')
} catch (error) {
  console.error('Failed to initialize Payments:', error)
  process.exit(1)
}

Source References:

src/payments.ts (getInstance, getBrowserInstance methods)
src/environments.ts (environment configurations)
tests/e2e/fixtures.ts (createPaymentsBuilder, createPaymentsSubscriber)

TypeScript SDK

Python SDK

CLI

OpenClaw Plugin

Getting Started

Initializing the Library

Get Your NVM API Key

Server-Side Initialization

Configuration Options

Environment derivation

Complete Server-Side Example

Browser Initialization

Browser Authentication Flow

Environments

Production Environments

Choosing an Environment

Environment Configuration Details

Verify Connection

Best Practices

​Initializing the Library

​Get Your NVM API Key

​Server-Side Initialization

​Configuration Options

​Environment derivation

​Complete Server-Side Example

​Browser Initialization

​Browser Authentication Flow

​Environments

​Production Environments

​Choosing an Environment

​Environment Configuration Details

​Verify Connection

​Best Practices

​Related Documentation

Initializing the Library

Get Your NVM API Key

Server-Side Initialization

Configuration Options

Environment derivation

Complete Server-Side Example

Browser Initialization

Browser Authentication Flow

Environments

Production Environments

Choosing an Environment

Environment Configuration Details

Verify Connection

Best Practices

Related Documentation