Class Payments

Main class that interacts with the Nevermined payments API. Use Payments.getInstance for server-side usage or Payments.getBrowserInstance for 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

Hierarchy

  • BasePaymentsAPI
    • Payments

Constructors

constructor

Properties

_a2aRegistry? _mcpIntegration? accountAddress? agents appId? environment heliconeApiKey? isBrowserInstance nvmApiKey observability plans query requests returnUrl version? a2a

Accessors

a2a isLoggedIn mcp

Methods

connect getAccountAddress getBackendHTTPOptions initializeApi logout parseNvmApiKey getBrowserInstance getInstance

Constructors

Private constructor

  • new Payments(options, isBrowserInstance?): Payments

  • Initializes the Payments class.

    Parameters

    • options: PaymentOptions

      The options to initialize the payments class.

    • isBrowserInstance: boolean = true

      Whether this instance is for browser usage.

    Returns Payments

Properties

Private Optional _a2aRegistry

_a2aRegistry?: ClientRegistry

Private Optional _mcpIntegration

_mcpIntegration?: {
    attach: ((server) => {
        registerPrompt<TArgs>(name, config, handler, options?): void;
        registerResource(name, template, config, handler, options?): void;
        registerTool<TArgs>(name, config, handler, options?): void;
    });
    authenticateMeta: ((extra, method) => Promise<AuthResult>);
    configure: ((options) => void);
    withPaywall: {
        <TArgs>(handler, options): ((args, extra?) => Promise<any>);
        <TArgs>(handler): ((args, extra?) => Promise<any>);
        (handler, options): ((uri, variables, extra?) => Promise<any>);
    };
}

Cached 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.

Type declaration

  • attach: ((server) => {
        registerPrompt<TArgs>(name, config, handler, options?): void;
        registerResource(name, template, config, handler, options?): void;
        registerTool<TArgs>(name, config, handler, options?): void;
    })
      • (server): {
            registerPrompt<TArgs>(name, config, handler, options?): void;
            registerResource(name, template, config, handler, options?): void;
            registerTool<TArgs>(name, config, handler, options?): void;
        }

      • Parameters

        • server: {
              registerPrompt: ((name, config, handler) => void);
              registerResource: ((name, template, config, handler) => void);
              registerTool: ((name, config, handler) => void);
          }
          • registerPrompt: ((name, config, handler) => void)
              • (name, config, handler): void

              • Parameters

                • name: string
                • config: any
                • handler: any

                Returns void

          • registerResource: ((name, template, config, handler) => void)
              • (name, template, config, handler): void

              • Parameters

                • name: string
                • template: any
                • config: any
                • handler: any

                Returns void

          • registerTool: ((name, config, handler) => void)
              • (name, config, handler): void

              • Parameters

                • name: string
                • config: any
                • handler: any

                Returns void

        Returns {
            registerPrompt<TArgs>(name, config, handler, options?): void;
            registerResource(name, template, config, handler, options?): void;
            registerTool<TArgs>(name, config, handler, options?): void;
        }

        • registerPrompt:function
          • registerPrompt<TArgs>(name, config, handler, options?): void

          • Type Parameters

            • TArgs = any

            Parameters

            • name: string
            • config: any
            • handler: ((args, extra?) => any)
                • (args, extra?): any

                • Parameters

                  • args: TArgs
                  • Optional extra: any

                  Returns any

            • Optional options: Omit<PromptOptions, "kind" | "name">

            Returns void

        • registerResource:function
          • registerResource(name, template, config, handler, options?): void

          • Parameters

            • name: string
            • template: any
            • config: any
            • handler: ((uri, variables, extra?) => any)
                • (uri, variables, extra?): any

                • Parameters

                  • uri: URL
                  • variables: Record<string, string | string[]>
                  • Optional extra: any

                  Returns any

            • Optional options: Omit<ResourceOptions, "kind" | "name">

            Returns void

        • registerTool:function
          • registerTool<TArgs>(name, config, handler, options?): void

          • Type Parameters

            • TArgs = any

            Parameters

            • name: string
            • config: any
            • handler: ((args, extra?) => any)
                • (args, extra?): any

                • Parameters

                  • args: TArgs
                  • Optional extra: any

                  Returns any

            • Optional options: Omit<ToolOptions, "kind" | "name">

            Returns void

  • authenticateMeta: ((extra, method) => Promise<AuthResult>)
      • (extra, method): Promise<AuthResult>

      • Simple helper to authenticate meta MCP operations (e.g., initialize, tools/resources/prompts list). Usage on server routers: await mcp.authenticateMeta(extra, method)

        Parameters

        • extra: any
        • method: string

        Returns Promise<AuthResult>

  • configure: ((options) => void)
      • (options): void

      • Parameters

        • options: {
              agentId: string;
              serverName?: string;
          }
          • agentId: string
          • Optional serverName?: string

        Returns void

  • withPaywall: {
        <TArgs>(handler, options): ((args, extra?) => Promise<any>);
        <TArgs>(handler): ((args, extra?) => Promise<any>);
        (handler, options): ((uri, variables, extra?) => Promise<any>);
    }
      • <TArgs>(handler, options): ((args, extra?) => Promise<any>)

      • Type Parameters

        • TArgs = any

        Parameters

        • handler: ((args, extra?) => any)
            • (args, extra?): any

            • Parameters

              • args: TArgs
              • Optional extra: any

              Returns any

        • options: ToolOptions | PromptOptions

        Returns ((args, extra?) => Promise<any>)

          • (args, extra?): Promise<any>

          • Parameters

            • args: TArgs
            • Optional extra: any

            Returns Promise<any>

      • <TArgs>(handler): ((args, extra?) => Promise<any>)

      • Type Parameters

        • TArgs = any

        Parameters

        • handler: ((args, extra?) => any)
            • (args, extra?): any

            • Parameters

              • args: TArgs
              • Optional extra: any

              Returns any

        Returns ((args, extra?) => Promise<any>)

          • (args, extra?): Promise<any>

          • Parameters

            • args: TArgs
            • Optional extra: any

            Returns Promise<any>

      • (handler, options): ((uri, variables, extra?) => Promise<any>)

      • Parameters

        • handler: ((uri, variables, extra?) => any)
            • (uri, variables, extra?): any

            • Parameters

              • uri: URL
              • variables: Record<string, string | string[]>
              • Optional extra: any

              Returns any

        • options: ResourceOptions

        Returns ((uri, variables, extra?) => Promise<any>)

          • (uri, variables, extra?): Promise<any>

          • Parameters

            • uri: URL
            • variables: Record<string, string | string[]>
            • Optional extra: any

            Returns Promise<any>

Protected Optional accountAddress

accountAddress?: string

agents

agents: AgentsAPI

Protected Optional appId

appId?: string

Protected environment

environment: EnvironmentInfo

Protected Optional heliconeApiKey

heliconeApiKey?: string

isBrowserInstance

isBrowserInstance: boolean = true

Protected nvmApiKey

nvmApiKey: string

observability

observability: ObservabilityAPI

plans

plans: PlansAPI

query

query: AIQueryApi

requests

requests: AgentRequestsAPI

Protected returnUrl

returnUrl: string

Protected Optional version

version?: string

Static a2a

a2a: {
    buildPaymentAgentCard: ((baseCard, paymentMetadata) => AgentCard);
} = ...

Static A2A helpers and utilities. Example: Payments.a2a.buildPaymentAgentCard(...)

Type declaration

  • buildPaymentAgentCard: ((baseCard, paymentMetadata) => AgentCard)
      • (baseCard, paymentMetadata): AgentCard

      • 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.

        Parameters

        • baseCard: AgentCard

          The base AgentCard (without payment info)

        • paymentMetadata: PaymentAgentCardMetadata

          The payment/pricing metadata to include

        Returns AgentCard

        The AgentCard with payment info in capabilities.extensions

        Example

        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
        })

Accessors

a2a

  • get a2a(): {
        getClient: ((options) => PaymentsClient);
        start: ((options) => PaymentsA2AServerResult);
    }

  • Exposes A2A server and client registry methods. The client registry is initialized only if getClient is called.

    Returns {
        getClient: ((options) => PaymentsClient);
        start: ((options) => PaymentsA2AServerResult);
    }

    • getClient: ((options) => PaymentsClient)

      Gets (or creates) a RegisteredPaymentsClient for the given alias. The registry is initialized only on first use.

        • (options): PaymentsClient

        • Parameters

          • options: any

            ClientRegistryOptions.

          Returns PaymentsClient

    • start: ((options) => PaymentsA2AServerResult)

      Starts the A2A server with payment integration.

        • (options): PaymentsA2AServerResult

        • Parameters

          • options: Omit<PaymentsA2AServerOptions, "paymentsService">

            Server options.

          Returns PaymentsA2AServerResult

isLoggedIn

  • get isLoggedIn(): boolean

  • Checks if a user is logged in.

    Returns boolean

    True if the user is logged in.

    Example

    payments.isLoggedIn

mcp

  • get mcp(): {
        attach: ((server) => {
            registerPrompt<TArgs>(name, config, handler, options?): void;
            registerResource(name, template, config, handler, options?): void;
            registerTool<TArgs>(name, config, handler, options?): void;
        });
        authenticateMeta: ((extra, method) => Promise<AuthResult>);
        configure: ((options) => void);
        withPaywall: {
            <TArgs>(handler, options): ((args, extra?) => Promise<any>);
            <TArgs>(handler): ((args, extra?) => Promise<any>);
            (handler, options): ((uri, variables, extra?) => Promise<any>);
        };
    }

  • Returns the MCP integration API. The instance is memoized so that configuration set via configure({ agentId, serverName }) persists across calls.

    Returns {
        attach: ((server) => {
            registerPrompt<TArgs>(name, config, handler, options?): void;
            registerResource(name, template, config, handler, options?): void;
            registerTool<TArgs>(name, config, handler, options?): void;
        });
        authenticateMeta: ((extra, method) => Promise<AuthResult>);
        configure: ((options) => void);
        withPaywall: {
            <TArgs>(handler, options): ((args, extra?) => Promise<any>);
            <TArgs>(handler): ((args, extra?) => Promise<any>);
            (handler, options): ((uri, variables, extra?) => Promise<any>);
        };
    }

    • attach: ((server) => {
          registerPrompt<TArgs>(name, config, handler, options?): void;
          registerResource(name, template, config, handler, options?): void;
          registerTool<TArgs>(name, config, handler, options?): void;
      })
        • (server): {
              registerPrompt<TArgs>(name, config, handler, options?): void;
              registerResource(name, template, config, handler, options?): void;
              registerTool<TArgs>(name, config, handler, options?): void;
          }

        • Parameters

          • server: {
                registerPrompt: ((name, config, handler) => void);
                registerResource: ((name, template, config, handler) => void);
                registerTool: ((name, config, handler) => void);
            }
            • registerPrompt: ((name, config, handler) => void)
                • (name, config, handler): void

                • Parameters

                  • name: string
                  • config: any
                  • handler: any

                  Returns void

            • registerResource: ((name, template, config, handler) => void)
                • (name, template, config, handler): void

                • Parameters

                  • name: string
                  • template: any
                  • config: any
                  • handler: any

                  Returns void

            • registerTool: ((name, config, handler) => void)
                • (name, config, handler): void

                • Parameters

                  • name: string
                  • config: any
                  • handler: any

                  Returns void

          Returns {
              registerPrompt<TArgs>(name, config, handler, options?): void;
              registerResource(name, template, config, handler, options?): void;
              registerTool<TArgs>(name, config, handler, options?): void;
          }

          • registerPrompt:function
            • registerPrompt<TArgs>(name, config, handler, options?): void

            • Type Parameters

              • TArgs = any

              Parameters

              • name: string
              • config: any
              • handler: ((args, extra?) => any)
                  • (args, extra?): any

                  • Parameters

                    • args: TArgs
                    • Optional extra: any

                    Returns any

              • Optional options: Omit<PromptOptions, "kind" | "name">

              Returns void

          • registerResource:function
            • registerResource(name, template, config, handler, options?): void

            • Parameters

              • name: string
              • template: any
              • config: any
              • handler: ((uri, variables, extra?) => any)
                  • (uri, variables, extra?): any

                  • Parameters

                    • uri: URL
                    • variables: Record<string, string | string[]>
                    • Optional extra: any

                    Returns any

              • Optional options: Omit<ResourceOptions, "kind" | "name">

              Returns void

          • registerTool:function
            • registerTool<TArgs>(name, config, handler, options?): void

            • Type Parameters

              • TArgs = any

              Parameters

              • name: string
              • config: any
              • handler: ((args, extra?) => any)
                  • (args, extra?): any

                  • Parameters

                    • args: TArgs
                    • Optional extra: any

                    Returns any

              • Optional options: Omit<ToolOptions, "kind" | "name">

              Returns void

    • authenticateMeta: ((extra, method) => Promise<AuthResult>)
        • (extra, method): Promise<AuthResult>

        • Simple helper to authenticate meta MCP operations (e.g., initialize, tools/resources/prompts list). Usage on server routers: await mcp.authenticateMeta(extra, method)

          Parameters

          • extra: any
          • method: string

          Returns Promise<AuthResult>

    • configure: ((options) => void)
        • (options): void

        • Parameters

          • options: {
                agentId: string;
                serverName?: string;
            }
            • agentId: string
            • Optional serverName?: string

          Returns void

    • withPaywall: {
          <TArgs>(handler, options): ((args, extra?) => Promise<any>);
          <TArgs>(handler): ((args, extra?) => Promise<any>);
          (handler, options): ((uri, variables, extra?) => Promise<any>);
      }
        • <TArgs>(handler, options): ((args, extra?) => Promise<any>)

        • Type Parameters

          • TArgs = any

          Parameters

          • handler: ((args, extra?) => any)
              • (args, extra?): any

              • Parameters

                • args: TArgs
                • Optional extra: any

                Returns any

          • options: ToolOptions | PromptOptions

          Returns ((args, extra?) => Promise<any>)

            • (args, extra?): Promise<any>

            • Parameters

              • args: TArgs
              • Optional extra: any

              Returns Promise<any>

        • <TArgs>(handler): ((args, extra?) => Promise<any>)

        • Type Parameters

          • TArgs = any

          Parameters

          • handler: ((args, extra?) => any)
              • (args, extra?): any

              • Parameters

                • args: TArgs
                • Optional extra: any

                Returns any

          Returns ((args, extra?) => Promise<any>)

            • (args, extra?): Promise<any>

            • Parameters

              • args: TArgs
              • Optional extra: any

              Returns Promise<any>

        • (handler, options): ((uri, variables, extra?) => Promise<any>)

        • Parameters

          • handler: ((uri, variables, extra?) => any)
              • (uri, variables, extra?): any

              • Parameters

                • uri: URL
                • variables: Record<string, string | string[]>
                • Optional extra: any

                Returns any

          • options: ResourceOptions

          Returns ((uri, variables, extra?) => Promise<any>)

            • (uri, variables, extra?): Promise<any>

            • Parameters

              • uri: URL
              • variables: Record<string, string | string[]>
              • Optional extra: any

              Returns Promise<any>

Methods

connect

  • connect(): void

  • Initiates the connect flow. The user's browser will be redirected to the Nevermined App login page.

    Returns void

    Remarks

    This is a browser-only function.

    Example

    payments.connect()

getAccountAddress

  • getAccountAddress(): undefined | string

  • It returns the account address associated with the NVM API Key used to initialize the Payments Library instance.

    Returns undefined | string

    The account address extracted from the NVM API Key

Protected getBackendHTTPOptions

  • getBackendHTTPOptions(method, body?): any
  • Internal

    Returns the HTTP options required to query the backend.

    Parameters

    • method: string

      HTTP method.

    • Optional body: any

      Optional request body.

    Returns any

    HTTP options object.

Private initializeApi

logout

  • logout(): void

  • Logs out the user by removing the NVM API key.

    Returns void

    Remarks

    This is a browser-only function.

    Example

    payments.logout()

Protected parseNvmApiKey

  • parseNvmApiKey(): void

  • Parses the NVM API Key to extract the account address.

    Returns void

    Throws

    PaymentsError if the API key is invalid.

Static getBrowserInstance

  • getBrowserInstance(options): Payments

  • Get an instance of the Payments class for browser usage.

    Parameters

    Returns Payments

    An instance of Payments

    Remarks

    This is a browser-only function.

    Example

    const payments = Payments.getBrowserInstance({
      returnUrl: 'https://mysite.example',
      environment: 'testing',
      appId: 'my-app-id',
      version: '1.0.0'
    })

    Throws

    PaymentsError if returnUrl is missing.

Static getInstance

  • getInstance(options): Payments

  • Get an instance of the Payments class for server-side usage.

    Parameters

    Returns Payments

    An instance of Payments

    Example

    const payments = Payments.getInstance({1
      nvmApiKey: 'your-nvm-api-key',
      environment: 'testing'
    })

    Throws

    PaymentsError if nvmApiKey is missing.

Settings

Member Visibility

Theme

On This Page

constructor_a2aRegistry_mcpIntegrationaccountAddressagentsappIdenvironmentheliconeApiKeyisBrowserInstancenvmApiKeyobservabilityplansqueryrequestsreturnUrlversiona2aa2aisLoggedInmcpconnectgetAccountAddressgetBackendHTTPOptionsinitializeApilogoutparseNvmApiKeygetBrowserInstancegetInstance