@nevermined-io/payments
    Preparing search index...

    Class Payments

    Main class that interacts with the Nevermined payments API. Use Payments.getInstance for server-side usage or Payments.getBrowserInstance for browser usage.

    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
    Index

    Properties

    accountAddress agents appId? contracts environment environmentName facilitator heliconeApiKey isBrowserInstance nvmApiKey observability organizations plans query requests returnUrl scheme version? x402 a2a

    Accessors

    a2a delegation isLoggedIn mcp

    Methods

    connect getAccountAddress getBackendHTTPOptions getEnvironmentName getPublicHTTPOptions logout parseNvmApiKey getBrowserInstance getInstance

    Properties

    accountAddress: string
    agents: AgentsAPI
    appId?: string
    contracts: ContractsAPI
    environment: EnvironmentInfo
    environmentName: EnvironmentName
    facilitator: FacilitatorAPI
    heliconeApiKey: string
    isBrowserInstance: boolean = true
    nvmApiKey: string
    observability: ObservabilityAPI
    organizations: OrganizationsAPI
    plans: PlansAPI
    query: AIQueryApi
    requests: AgentRequestsAPI
    returnUrl: string
    scheme: PaymentScheme
    version?: string
    x402: X402TokenAPI
    a2a: {
        buildPaymentAgentCard: (
            baseCard: AgentCard,
            paymentMetadata: PaymentAgentCardMetadata,
        ) => AgentCard;
    } = ...

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

    Type Declaration

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

    Accessors

    • get a2a(): {
          getClient: (options: any) => Promise<PaymentsClient>;
          start: (
              options: Omit<PaymentsA2AServerOptions, "paymentsService">,
          ) => PaymentsA2AServerResult;
      }

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

      Returns {
          getClient: (options: any) => Promise<PaymentsClient>;
          start: (
              options: Omit<PaymentsA2AServerOptions, "paymentsService">,
          ) => PaymentsA2AServerResult;
      }

      • getClient: (options: any) => Promise<PaymentsClient>

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

      • start: (
            options: Omit<PaymentsA2AServerOptions, "paymentsService">,
        ) => PaymentsA2AServerResult

        Starts the A2A server with payment integration.

    • get isLoggedIn(): boolean

      Checks if a user is logged in.

      Returns boolean

      True if the user is logged in.

      payments.isLoggedIn
    • get mcp(): {
          attach: (
              server: {
                  registerPrompt: (name: string, config: any, handler: any) => void;
                  registerResource: (
                      name: string,
                      template: any,
                      config: any,
                      handler: any,
                  ) => void;
                  registerTool: (name: string, config: any, handler: any) => void;
              },
          ) => {
              registerPrompt<TArgs = any>(
                  name: string,
                  config: any,
                  handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
                  options?: Omit<PromptOptions, "kind" | "name">,
              ): void;
              registerResource(
                  name: string,
                  template: any,
                  config: any,
                  handler: (
                      uri: URL,
                      variables: Record<string, string | string[]>,
                      extra?: any,
                      context?: PaywallContext,
                  ) => any,
                  options?: Omit<ResourceOptions, "kind" | "name">,
              ): void;
              registerTool<TArgs = any>(
                  name: string,
                  config: any,
                  handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
                  options?: Omit<ToolOptions, "kind" | "name">,
              ): void;
          };
          authenticateMeta: (
              extra: any,
              options?: { planId?: string },
              method: string,
          ) => Promise<AuthResult>;
          configure: (options: ExtendedMcpConfig) => void;
          createApp: (
              options: Omit<CreateRouterOptions, "agentId"> & { agentId?: string },
          ) => Application;
          createRouter: (options: CreateRouterOptions) => Router;
          getConfig: () => ExtendedMcpConfig;
          registerPrompt: <Args = any>(
              name: string,
              config: McpPromptConfig,
              handler: PromptHandler<Args>,
              options?: McpRegistrationOptions,
          ) => void;
          registerResource: (
              name: string,
              uriOrTemplate: string,
              config: McpResourceConfig,
              handler: ResourceHandler,
              options?: McpRegistrationOptions,
          ) => void;
          registerTool: <Args = any>(
              name: string,
              config: McpToolConfig,
              handler: ToolHandler<Args>,
              options?: McpRegistrationOptions,
          ) => void;
          start: (config: McpServerConfig) => Promise<McpServerResult>;
          startServer: (options: StartServerOptions) => Promise<HttpServerResult>;
          stop: () => Promise<void>;
          withPaywall: {
              <TArgs = any>(
                  handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
                  options: ToolOptions | PromptOptions,
              ): (args: TArgs, extra?: any) => Promise<any>;
              <TArgs = any>(
                  handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
              ): (args: TArgs, extra?: any) => Promise<any>;
              (
                  handler: (
                      uri: URL,
                      variables: Record<string, string | string[]>,
                      extra?: any,
                      context?: PaywallContext,
                  ) => any,
                  options: ResourceOptions,
              ): (
                  uri: URL,
                  variables: Record<string, string | string[]>,
                  extra?: any,
              ) => 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: (name: string, config: any, handler: any) => void;
                  registerResource: (
                      name: string,
                      template: any,
                      config: any,
                      handler: any,
                  ) => void;
                  registerTool: (name: string, config: any, handler: any) => void;
              },
          ) => {
              registerPrompt<TArgs = any>(
                  name: string,
                  config: any,
                  handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
                  options?: Omit<PromptOptions, "kind" | "name">,
              ): void;
              registerResource(
                  name: string,
                  template: any,
                  config: any,
                  handler: (
                      uri: URL,
                      variables: Record<string, string | string[]>,
                      extra?: any,
                      context?: PaywallContext,
                  ) => any,
                  options?: Omit<ResourceOptions, "kind" | "name">,
              ): void;
              registerTool<TArgs = any>(
                  name: string,
                  config: any,
                  handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
                  options?: Omit<ToolOptions, "kind" | "name">,
              ): void;
          };
          authenticateMeta: (
              extra: any,
              options?: { planId?: string },
              method: string,
          ) => Promise<AuthResult>;
          configure: (options: ExtendedMcpConfig) => void;
          createApp: (
              options: Omit<CreateRouterOptions, "agentId"> & { agentId?: string },
          ) => Application;
          createRouter: (options: CreateRouterOptions) => Router;
          getConfig: () => ExtendedMcpConfig;
          registerPrompt: <Args = any>(
              name: string,
              config: McpPromptConfig,
              handler: PromptHandler<Args>,
              options?: McpRegistrationOptions,
          ) => void;
          registerResource: (
              name: string,
              uriOrTemplate: string,
              config: McpResourceConfig,
              handler: ResourceHandler,
              options?: McpRegistrationOptions,
          ) => void;
          registerTool: <Args = any>(
              name: string,
              config: McpToolConfig,
              handler: ToolHandler<Args>,
              options?: McpRegistrationOptions,
          ) => void;
          start: (config: McpServerConfig) => Promise<McpServerResult>;
          startServer: (options: StartServerOptions) => Promise<HttpServerResult>;
          stop: () => Promise<void>;
          withPaywall: {
              <TArgs = any>(
                  handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
                  options: ToolOptions | PromptOptions,
              ): (args: TArgs, extra?: any) => Promise<any>;
              <TArgs = any>(
                  handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
              ): (args: TArgs, extra?: any) => Promise<any>;
              (
                  handler: (
                      uri: URL,
                      variables: Record<string, string | string[]>,
                      extra?: any,
                      context?: PaywallContext,
                  ) => any,
                  options: ResourceOptions,
              ): (
                  uri: URL,
                  variables: Record<string, string | string[]>,
                  extra?: any,
              ) => Promise<any>;
          };
      }

      • attach: (
            server: {
                registerPrompt: (name: string, config: any, handler: any) => void;
                registerResource: (
                    name: string,
                    template: any,
                    config: any,
                    handler: any,
                ) => void;
                registerTool: (name: string, config: any, handler: any) => void;
            },
        ) => {
            registerPrompt<TArgs = any>(
                name: string,
                config: any,
                handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
                options?: Omit<PromptOptions, "kind" | "name">,
            ): void;
            registerResource(
                name: string,
                template: any,
                config: any,
                handler: (
                    uri: URL,
                    variables: Record<string, string | string[]>,
                    extra?: any,
                    context?: PaywallContext,
                ) => any,
                options?: Omit<ResourceOptions, "kind" | "name">,
            ): void;
            registerTool<TArgs = any>(
                name: string,
                config: any,
                handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
                options?: Omit<ToolOptions, "kind" | "name">,
            ): void;
        }
      • authenticateMeta: (
            extra: any,
            options?: { planId?: string },
            method: string,
        ) => Promise<AuthResult>
      • configure: (options: ExtendedMcpConfig) => void
      • createApp: (
            options: Omit<CreateRouterOptions, "agentId"> & { agentId?: string },
        ) => Application
      • createRouter: (options: CreateRouterOptions) => Router
      • getConfig: () => ExtendedMcpConfig
      • registerPrompt: <Args = any>(
            name: string,
            config: McpPromptConfig,
            handler: PromptHandler<Args>,
            options?: McpRegistrationOptions,
        ) => void
      • registerResource: (
            name: string,
            uriOrTemplate: string,
            config: McpResourceConfig,
            handler: ResourceHandler,
            options?: McpRegistrationOptions,
        ) => void
      • registerTool: <Args = any>(
            name: string,
            config: McpToolConfig,
            handler: ToolHandler<Args>,
            options?: McpRegistrationOptions,
        ) => void
      • start: (config: McpServerConfig) => Promise<McpServerResult>
      • startServer: (options: StartServerOptions) => Promise<HttpServerResult>
      • stop: () => Promise<void>
      • withPaywall: {
            <TArgs = any>(
                handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
                options: ToolOptions | PromptOptions,
            ): (args: TArgs, extra?: any) => Promise<any>;
            <TArgs = any>(
                handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
            ): (args: TArgs, extra?: any) => Promise<any>;
            (
                handler: (
                    uri: URL,
                    variables: Record<string, string | string[]>,
                    extra?: any,
                    context?: PaywallContext,
                ) => any,
                options: ResourceOptions,
            ): (
                uri: URL,
                variables: Record<string, string | string[]>,
                extra?: any,
            ) => Promise<any>;
        }

    Methods

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

      Returns void

      This is a browser-only function.

      payments.connect()

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

      Returns string | undefined

      The account address extracted from the NVM API Key

    • Internal

      Returns the HTTP options required to query the backend.

      Parameters

      • method: string

        HTTP method.

      • Optionalbody: any

        Optional request body.

      Returns any

      HTTP options object.

    • Internal

      Get HTTP options for public backend requests (no authorization header). Converts body keys from snake_case to camelCase for consistency.

      Parameters

      • method: string

        HTTP method

      • Optionalbody: any

        Optional request body (keys will be converted to camelCase)

      Returns {
          body?: string;
          headers: { Accept: string; "Content-Type": string };
          method: string;
      }

      HTTP options object

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

      Returns void

      This is a browser-only function.

      payments.logout()

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

      Returns { accountAddress: string; heliconeApiKey: string }

      PaymentsError if the API key is invalid.

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

      Parameters

      Returns Payments

      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.

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

      Parameters

      Returns Payments

      An instance of Payments

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

      PaymentsError if nvmApiKey is missing.

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors
    Methods