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.
orders: Browser-fiat Orders — merchant-initiated, off-plan charges for an arbitrary amount.
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

Properties

`Protected`accountAddress

accountAddress: string

agents

agents: AgentsAPI

`Protected` `Optional`appId

appId?: string

contracts

contracts: ContractsAPI

`Protected`currentOrganizationId

currentOrganizationId: string | null

`Protected`environment

environment: EnvironmentInfo

`Protected`environmentName

environmentName: EnvironmentName

facilitator

facilitator: FacilitatorAPI

`Protected`heliconeApiKey

heliconeApiKey: string

isBrowserInstance

isBrowserInstance: boolean = true

`Experimental`mpp

mpp: MppAPI

MPP (Machine Payments Protocol) surface — challenge/credential framing over the same plans, delegations and credit burn as x402.

Shipped ahead of its epic's declared MVP scope, so that the Express middleware's own dependency on it is reachable rather than hidden behind an internal handle. The NAME is settled — payments.mpp beside payments.x402 is what a seller will guess, and renaming it after a tag costs a major. The SHAPE is not: this surface may change in a minor release until the epic adopts it.

`Protected`nvmApiKey

nvmApiKey: string

plans

plans: PlansAPI

query

query: AIQueryApi

requests

requests: AgentRequestsAPI

`Protected`returnUrl

returnUrl: string

`Protected`scheme

scheme: "nvm"

`Protected` `Optional`version

version?: string

Backend API version (MAJOR.MINOR) pinned by this instance, set from options.version. When unset, every request defaults to LOCKED_API_VERSION.

x402

x402: X402TokenAPI

`Static`a2a

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

a2a

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.
- Defined in src/payments.ts:73

delegation

get delegation(): DelegationAPI
Returns the Delegation API for listing enrolled payment methods. The instance is lazily initialized on first access — the current organization pin (set via setOrganizationId or the constructor option) and the backend API version pin (options.version) are forwarded so the first call carries the right X-Current-Org-Id and Nevermined-Version headers.

Returns DelegationAPI
- Defined in src/payments.ts:116

isLoggedIn

get isLoggedIn(): boolean
Checks if a user is logged in.

Returns boolean
True if the user is logged in.
Example
```
payments.isLoggedIn
```
- Defined in src/payments.ts:302

mcp

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, "name" | "kind">,
        ): void;
        registerResource(
            name: string,
            template: any,
            config: any,
            handler: (
                uri: URL,
                variables: Record<string, string | string[]>,
                extra?: any,
                context?: PaywallContext,
            ) => any,
            options?: Omit<ResourceOptions, "name" | "kind">,
        ): void;
        registerTool<TArgs = any>(
            name: string,
            config: any,
            handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
            options?: Omit<ToolOptions, "name" | "kind">,
        ): 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, "name" | "kind">,
        ): void;
        registerResource(
            name: string,
            template: any,
            config: any,
            handler: (
                uri: URL,
                variables: Record<string, string | string[]>,
                extra?: any,
                context?: PaywallContext,
            ) => any,
            options?: Omit<ResourceOptions, "name" | "kind">,
        ): void;
        registerTool<TArgs = any>(
            name: string,
            config: any,
            handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
            options?: Omit<ToolOptions, "name" | "kind">,
        ): 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, "name" | "kind">,
      ): void;
      registerResource(
          name: string,
          template: any,
          config: any,
          handler: (
              uri: URL,
              variables: Record<string, string | string[]>,
              extra?: any,
              context?: PaywallContext,
          ) => any,
          options?: Omit<ResourceOptions, "name" | "kind">,
      ): void;
      registerTool<TArgs = any>(
          name: string,
          config: any,
          handler: (args: TArgs, extra?: any, context?: PaywallContext) => any,
          options?: Omit<ToolOptions, "name" | "kind">,
      ): 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>;
  }
- Defined in src/payments.ts:101

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()
```
- Defined in src/payments.ts:235

getAccountAddress

getAccountAddress(): string | undefined
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
Inherited from BasePaymentsAPI.getAccountAddress
- Defined in src/api/base-payments.ts:177

`Protected`getBackendHTTPOptions

getBackendHTTPOptions(
    method: string,
    body?: any,
    extraHeaders?: Record<string, string>,
): any
Internal
Returns the HTTP options required to query the backend.
Parameters
- method: string
  HTTP method.
- Optionalbody: any
  Optional request body.
- OptionalextraHeaders: Record<string, string>
  Optional per-call header overrides. Use { 'X-Current-Org-Id': orgId } to target a specific workspace for one call without mutating the instance-level pin.
Returns any
HTTP options object.
Inherited from BasePaymentsAPI.getBackendHTTPOptions
- Defined in src/api/base-payments.ts:214

getEnvironmentName

getEnvironmentName(): EnvironmentName
Returns the environment name used to initialize the Payments instance.

Returns EnvironmentName
The environment name (e.g. 'sandbox', 'live')
Inherited from BasePaymentsAPI.getEnvironmentName
- Defined in src/api/base-payments.ts:169

getOrganizationId

getOrganizationId(): string | null
Returns the current organization context applied to every authenticated backend request via the X-Current-Org-Id header.

null means "no pinned workspace" — the backend falls back to the caller's API-key tag or most-recent active membership.

Returns string | null
Inherited from BasePaymentsAPI.getOrganizationId
- Defined in src/api/base-payments.ts:188

`Protected`getPublicHTTPOptions

getPublicHTTPOptions(
method: string,
body?: any,
): { body?: string; headers: Record<string, string>; method: string }
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: Record<string, string>; method: string }
HTTP options object
Inherited from BasePaymentsAPI.getPublicHTTPOptions
- Defined in src/api/base-payments.ts:254

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()
```
- Defined in src/payments.ts:251

`Protected`parseNvmApiKey

parseNvmApiKey(): { accountAddress: string; heliconeApiKey: string }
Parses the NVM API Key to extract the account address.

Returns { accountAddress: string; heliconeApiKey: string }
Throws
PaymentsError if the API key is invalid.
Inherited from BasePaymentsAPI.parseNvmApiKey
- Defined in src/api/base-payments.ts:151

setOrganizationId

setOrganizationId(organizationId: string | null): void
Pins (or clears) the active organization workspace used by every subsequent authenticated request. The SDK forwards the choice as the X-Current-Org-Id header so the backend scopes publications and other org-aware queries to the requested organization.

Pass null to clear the pin and let the backend fall back to the API key's org tag or the caller's most-recent active membership.

For one-off targeting (e.g. publish a single agent into Org B without leaving Org B as the active workspace) prefer the per-call { organizationId } option on agents.registerAgent / plans.registerPlan / similar.
Parameters
- organizationId: string | null
  Org ID to pin (e.g. org-…) or null to clear.
Returns void
Example
```
payments.setOrganizationId('org-abc123')
await payments.agents.registerAgent(metadata, api, [planId]) // lands in org-abc123
```
Overrides BasePaymentsAPI.setOrganizationId
- Defined in src/payments.ts:276

`Static`getBrowserInstance

getBrowserInstance(options: PaymentOptions): Payments
Get an instance of the Payments class for browser usage.
Parameters
- options: PaymentOptions
  The options to initialize the payments class.
Returns Payments
An instance of Payments
Remarks
This is a browser-only function.
Example
```
const payments = Payments.getBrowserInstance({
  returnUrl: 'https://mysite.example',
  environment: 'sandbox',
  appId: 'my-app-id',
  version: '1.1'
})
```
Throws
PaymentsError if returnUrl is missing.
- Defined in src/payments.ts:174

`Static`getInstance

getInstance(options: PaymentOptions): Payments
Get an instance of the Payments class for server-side usage.
Parameters
- options: PaymentOptions
  The options to initialize the payments class.
Returns Payments
An instance of Payments
Example
```
const payments = Payments.getInstance({
  nvmApiKey: 'your-nvm-api-key',
  environment: 'sandbox'
})
```
Throws
PaymentsError if nvmApiKey is missing.
- Defined in src/payments.ts:148

Class Payments

Remarks

Hierarchy

Index

Properties

Accessors

Methods

Properties

ProtectedaccountAddress

agents

Protected OptionalappId

contracts

ProtectedcurrentOrganizationId

Protectedenvironment

ProtectedenvironmentName

facilitator

ProtectedheliconeApiKey

isBrowserInstance

Experimentalmpp

ProtectednvmApiKey

observability

orders

organizations

plans

query

requests

ProtectedreturnUrl

Protectedscheme

Protected Optionalversion

x402

Statica2a

Type Declaration

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

Accessors

a2a

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

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

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

delegation

Returns DelegationAPI

isLoggedIn

Returns boolean

Example

mcp

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>

Methods

connect

Returns void

Remarks

Example

getAccountAddress

Returns string | undefined

ProtectedgetBackendHTTPOptions

Parameters

Returns any

getEnvironmentName

Returns EnvironmentName

getOrganizationId

Returns string | null

ProtectedgetPublicHTTPOptions

Parameters

Returns { body?: string; headers: Record<string, string>; method: string }

logout

Returns void

Remarks

Example

ProtectedparseNvmApiKey

Returns { accountAddress: string; heliconeApiKey: string }

Throws

setOrganizationId

`Protected`accountAddress

`Protected` `Optional`appId

`Protected`currentOrganizationId

`Protected`environment

`Protected`environmentName

`Protected`heliconeApiKey

`Experimental`mpp

`Protected`nvmApiKey

`Protected`returnUrl

`Protected`scheme

`Protected` `Optional`version

`Static`a2a

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

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

authenticateMeta: (
extra: any,
options?: { planId?: string },
method: string,
) => Promise<AuthResult>

createApp: (
options: Omit<CreateRouterOptions, "agentId"> & { agentId?: string },
) => Application

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

`Protected`getBackendHTTPOptions

`Protected`getPublicHTTPOptions

`Protected`parseNvmApiKey

`Static`getBrowserInstance

`Static`getInstance