Private constructorInitializes the Payments class.
The options to initialize the payments class.
Whether this instance is for browser usage.
Private Optional _a2aPrivate Optional _mcpCached MCP integration to preserve configuration (e.g., agentId, serverName) across multiple getter accesses. This ensures callers do not need to retain a reference to a previously configured instance.
Attach paywall protection to an MCP server. Returns a registrar with protected register methods.
The MCP server instance
Protected registrar
Optional extra: anyOptional context: PaywallContextOptional options: Omit<PromptOptions, "kind" | "name">Optional extra: anyOptional context: PaywallContextOptional options: Omit<ResourceOptions, "kind" | "name">Optional extra: anyOptional context: PaywallContextOptional options: Omit<ToolOptions, "kind" | "name">Authenticate meta MCP operations (initialize, tools/list, etc.).
The extra parameter from MCP
Optional planThe MCP method being called
Authentication result
Configure the MCP integration. This sets up the agent ID, server name, and optional HTTP settings.
Configuration options
payments.mcp.configure({
agentId: 'agent_123',
serverName: 'my-mcp-server',
baseUrl: 'http://localhost:5001',
environment: 'staging_sandbox',
tools: ['hello_world', 'weather']
})
Create an Express app pre-configured with OAuth discovery endpoints. Use this when you want more control over the app before starting.
Note: Authentication is handled by withPaywall() on each tool, not by HTTP middleware.
App configuration
Configured Express app with OAuth endpoints
const app = payments.mcp.createApp({
baseUrl: 'http://localhost:5001',
serverName: 'my-mcp-server'
})
// Add your MCP handler - auth via withPaywall() on each tool
app.post('/mcp', mcpHandler)
app.listen(5001)
Create an Express router with OAuth 2.1 endpoints. Use this when you already have an Express app and want to add OAuth support.
Router configuration
Express Router
const router = payments.mcp.createRouter({
baseUrl: 'http://localhost:5001',
serverName: 'my-mcp-server',
tools: ['hello_world']
})
app.use(router)
Get the current configuration.
Current MCP configuration
Register a prompt with the simplified API. Must be called before start(). Matches the signature of MCP SDK registerPrompt.
Prompt name
Prompt configuration
Prompt handler function
Optional options: McpRegistrationOptionsRegistration options (credits, etc.)
Register a resource with the simplified API. Must be called before start().
Resource name
Resource URI (string) or template
Resource metadata configuration
Resource handler function
Optional options: McpRegistrationOptionsRegistration options (credits, etc.)
Register a tool with the simplified API. Must be called before start().
Tool name
Tool configuration
Tool handler function
Optional options: McpRegistrationOptionsRegistration options (credits, etc.)
payments.mcp.registerTool(
'hello_world',
{
description: 'Returns a hello world message',
inputSchema: { name: { type: 'string' } }
},
async (args: { name: string }, context?: ToolContext) => ({
content: [{ type: 'text', text: `Hello, ${args.name}!` }]
}),
{ credits: 1, onRedeemError: 'ignore' }
)
Start the MCP server with the simplified API. This creates and starts everything: McpServer, Express, OAuth endpoints, etc.
Server configuration
Server result with stop() method
// Register tools first
payments.mcp.registerTool('hello', { description: '...' }, handler)
// Then start the server
const { info, stop } = await payments.mcp.start({
port: 5001,
agentId: 'did:nv:...',
serverName: 'my-mcp-server'
})
console.log(`Server running at ${info.baseUrl}`)
// Later: stop gracefully
await stop()
Start a managed HTTP server with OAuth 2.1 support. This creates a complete Express server with all OAuth endpoints pre-configured.
Server configuration
Server result with control methods
const { baseUrl, stop } = await payments.mcp.startServer({
port: 5001,
serverName: 'my-mcp-server',
tools: ['hello_world', 'weather']
})
console.log(`Server running at ${baseUrl}`)
// Later: gracefully stop
await stop()
Stop the MCP server. This is a convenience method - you can also use the stop() from start()'s result.
Wrap a handler with paywall protection. The wrapped handler will validate authentication and burn credits.
Optional extra: anyOptional context: PaywallContextOptional extra: anyOptional extra: anyOptional context: PaywallContextOptional extra: anyOptional extra: anyOptional context: PaywallContextOptional extra: anyProtected accountProtected Optional appProtected environmentProtected environmentProtected heliconeProtected nvmProtected returnProtected Optional versionStatic a2aStatic A2A helpers and utilities. Example: Payments.a2a.buildPaymentAgentCard(...)
Builds an AgentCard with payment/pricing metadata in the capabilities.extensions field.
This function takes a base agent card and payment metadata, then creates a new agent card that includes the payment information in a standardized extension. The payment extension follows the A2A standard for extensibility and uses the URI 'urn:nevermined:payment' to identify payment-related capabilities.
The resulting agent card can be used with the PaymentsA2AServer to provide payment-enabled A2A agent functionality.
The base AgentCard (without payment info)
The payment/pricing metadata to include
The AgentCard with payment info in capabilities.extensions
const baseCard: AgentCard = {
name: 'My AI Assistant',
description: 'An AI assistant that helps with various tasks',
capabilities: {
tools: ['text-generation', 'image-analysis'],
extensions: []
}
}
const paymentMetadata: PaymentAgentCardMetadata = {
paymentType: 'fixed',
credits: 10,
agentId: 'agent-123',
planId: 'plan-456',
costDescription: '10 credits per request'
}
const paymentCard = buildPaymentAgentCard(baseCard, paymentMetadata)
// Use with PaymentsA2AServer
PaymentsA2AServer.start({
agentCard: paymentCard,
executor: new MyExecutor(),
paymentsService: payments,
port: 41242
})
Exposes A2A server and client registry methods. The client registry is initialized only if getClient is called.
Gets (or creates) a RegisteredPaymentsClient for the given alias. The registry is initialized only on first use.
ClientRegistryOptions.
Starts the A2A server with payment integration.
Server options.
Checks if a user is logged in.
True if the user is logged in.
payments.isLoggedIn
Returns the MCP integration API. The instance is memoized so that configuration
set via configure({ agentId, serverName }) persists across calls.
Attach paywall protection to an MCP server. Returns a registrar with protected register methods.
The MCP server instance
Protected registrar
Optional extra: anyOptional context: PaywallContextOptional options: Omit<PromptOptions, "kind" | "name">Optional extra: anyOptional context: PaywallContextOptional options: Omit<ResourceOptions, "kind" | "name">Optional extra: anyOptional context: PaywallContextOptional options: Omit<ToolOptions, "kind" | "name">Authenticate meta MCP operations (initialize, tools/list, etc.).
The extra parameter from MCP
Optional planThe MCP method being called
Authentication result
Configure the MCP integration. This sets up the agent ID, server name, and optional HTTP settings.
Configuration options
payments.mcp.configure({
agentId: 'agent_123',
serverName: 'my-mcp-server',
baseUrl: 'http://localhost:5001',
environment: 'staging_sandbox',
tools: ['hello_world', 'weather']
})
Create an Express app pre-configured with OAuth discovery endpoints. Use this when you want more control over the app before starting.
Note: Authentication is handled by withPaywall() on each tool, not by HTTP middleware.
App configuration
Configured Express app with OAuth endpoints
const app = payments.mcp.createApp({
baseUrl: 'http://localhost:5001',
serverName: 'my-mcp-server'
})
// Add your MCP handler - auth via withPaywall() on each tool
app.post('/mcp', mcpHandler)
app.listen(5001)
Create an Express router with OAuth 2.1 endpoints. Use this when you already have an Express app and want to add OAuth support.
Router configuration
Express Router
const router = payments.mcp.createRouter({
baseUrl: 'http://localhost:5001',
serverName: 'my-mcp-server',
tools: ['hello_world']
})
app.use(router)
Get the current configuration.
Current MCP configuration
Register a prompt with the simplified API. Must be called before start(). Matches the signature of MCP SDK registerPrompt.
Prompt name
Prompt configuration
Prompt handler function
Optional options: McpRegistrationOptionsRegistration options (credits, etc.)
Register a resource with the simplified API. Must be called before start().
Resource name
Resource URI (string) or template
Resource metadata configuration
Resource handler function
Optional options: McpRegistrationOptionsRegistration options (credits, etc.)
Register a tool with the simplified API. Must be called before start().
Tool name
Tool configuration
Tool handler function
Optional options: McpRegistrationOptionsRegistration options (credits, etc.)
payments.mcp.registerTool(
'hello_world',
{
description: 'Returns a hello world message',
inputSchema: { name: { type: 'string' } }
},
async (args: { name: string }, context?: ToolContext) => ({
content: [{ type: 'text', text: `Hello, ${args.name}!` }]
}),
{ credits: 1, onRedeemError: 'ignore' }
)
Start the MCP server with the simplified API. This creates and starts everything: McpServer, Express, OAuth endpoints, etc.
Server configuration
Server result with stop() method
// Register tools first
payments.mcp.registerTool('hello', { description: '...' }, handler)
// Then start the server
const { info, stop } = await payments.mcp.start({
port: 5001,
agentId: 'did:nv:...',
serverName: 'my-mcp-server'
})
console.log(`Server running at ${info.baseUrl}`)
// Later: stop gracefully
await stop()
Start a managed HTTP server with OAuth 2.1 support. This creates a complete Express server with all OAuth endpoints pre-configured.
Server configuration
Server result with control methods
const { baseUrl, stop } = await payments.mcp.startServer({
port: 5001,
serverName: 'my-mcp-server',
tools: ['hello_world', 'weather']
})
console.log(`Server running at ${baseUrl}`)
// Later: gracefully stop
await stop()
Stop the MCP server. This is a convenience method - you can also use the stop() from start()'s result.
Wrap a handler with paywall protection. The wrapped handler will validate authentication and burn credits.
Optional extra: anyOptional context: PaywallContextOptional extra: anyOptional extra: anyOptional context: PaywallContextOptional extra: anyOptional extra: anyOptional context: PaywallContextOptional extra: anyProtected getProtected getInternal Get HTTP options for public backend requests (no authorization header). Converts body keys from snake_case to camelCase for consistency.
HTTP method
Optional body: anyOptional request body (keys will be converted to camelCase)
HTTP options object
Optional body?: stringPrivate initializeInitializes the AI Query Protocol API.
Protected parseStatic getGet an instance of the Payments class for browser usage.
The options to initialize the payments class.
An instance of Payments
This is a browser-only function.
const payments = Payments.getBrowserInstance({
returnUrl: 'https://mysite.example',
environment: 'sandbox',
appId: 'my-app-id',
version: '1.0.0'
})
PaymentsError if returnUrl is missing.
Static getGet an instance of the Payments class for server-side usage.
The options to initialize the payments class.
An instance of Payments
const payments = Payments.getInstance({
nvmApiKey: 'your-nvm-api-key',
environment: 'sandbox'
})
PaymentsError if nvmApiKey is missing.
Main class that interacts with the Nevermined payments API. Use
Payments.getInstancefor server-side usage orPayments.getBrowserInstancefor browser usage.Remarks
This API requires a Nevermined API Key, which can be obtained by logging in to the Nevermined App.
The library provides methods to manage AI Agents, Plans & process AI Agent Requests.
Each of these functionalities is encapsulated in its own API class:
plans: Manages AI Plans, including registration and ordering and retrieving plan details.agents: Handles AI Agents, including registration of AI Agents and access token generation.requests: Manages requests received by AI Agents, including validation and tracking.observability: Provides observability and logging utilities for AI Agents with Helicone integration