Class MppAPI

Machine Payments Protocol (MPP) module.

Hierarchy

BasePaymentsAPI
- MppAPI

Constructors

constructor

new MppAPI(options: PaymentOptions): MppAPI
Parameters
- options: PaymentOptions
Returns MppAPI
Inherited from BasePaymentsAPI.constructor
- Defined in src/api/base-payments.ts:84

Properties

`Protected`accountAddress

accountAddress: string

`Protected` `Optional`appId

appId?: string

`Protected`currentOrganizationId

currentOrganizationId: string | null

`Protected`environment

environment: EnvironmentInfo

`Protected`environmentName

environmentName: EnvironmentName

`Protected`heliconeApiKey

heliconeApiKey: string

isBrowserInstance

isBrowserInstance: boolean = true

`Protected`nvmApiKey

nvmApiKey: string

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

Methods

fetch

fetch(
    input: string | URL,
    init: RequestInit | undefined,
    options: MppFetchOptions,
): Promise<MppFetchResult>
Performs an HTTP request, paying an MPP challenge if the endpoint returns one.

The buyer needs no new plan, delegation or credential: the delegation that works for x402 works here unchanged.

init.body, if set, must be replayable if the endpoint may challenge the request: a ReadableStream throws a typed PaymentsError once a 402 challenge actually requires a retry, since the stream cannot be resent. A request that is never challenged sends a stream body exactly once, exactly like plain fetch — the paid: false / untouched-response guarantee still holds. A string, Buffer/ArrayBuffer/typed array, URLSearchParams, FormData or Blob body all work unchanged either way.

options.delegationConfig must carry a delegationId — this call refuses the deprecated inline create-on-the-fly shape (no delegationId) that X402TokenAPI.getX402AccessToken otherwise tolerates with a warning: the retry loop here can mint an access token twice per call, so that shape could silently create two delegations as a side effect of paying.
Parameters
- input: string | URL
- init: RequestInit | undefined
- options: MppFetchOptions
Returns Promise<MppFetchResult>
Example
```
const { response, receipt } = await payments.mpp.fetch(
  'https://agent.example/ask',
  { method: 'POST', body: JSON.stringify({ q: 'hello' }) },
  { delegationConfig: { delegationId }, planId },
)
```
- Defined in src/mpp/mpp-api.ts:258

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

getMppAccessToken

getMppAccessToken(
    planId: string,
    agentId?: string,
    tokenOptions?: MppTokenOptions,
): Promise<{ accessToken: string }>
Mints an access token signed under the Nevermined-MPP EIP-712 domain.

Same inputs and same settlement rail as X402TokenAPI.getX402AccessToken minus tokenVersion; the token verifies only on the MPP routes, which is what keeps the two protocols isolated.

MPP carries no token version (nvm-monorepo#3266): its single-use unit is the challenge, not the token, so one MPP token is presented across many challenges by design. The parameter type says so, and a JavaScript caller that sends one anyway is refused before the request — the backend answers BCK.MPP.0007 for any value, 2 included.
Parameters
- planId: string
- OptionalagentId: string
- OptionaltokenOptions: MppTokenOptions
Returns Promise<{ accessToken: string }>
- Defined in src/mpp/mpp-api.ts:212

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

issueChallenge

issueChallenge(
params: IssueMppChallengeParams,
): Promise<{ challenge: string; id: string }>
Mints the challenge a plan-protected endpoint returns with its 402.

Each call returns a distinct challenge even for identical inputs — the id doubles as the burn idempotency key, so two requests sharing one would settle as a single burn.
Parameters
- params: IssueMppChallengeParams
Returns Promise<{ challenge: string; id: string }>
- Defined in src/mpp/mpp-api.ts:168

`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
Sets the organization context applied to every subsequent authenticated backend request via the X-Current-Org-Id header.

Pass null to clear the pin and fall back to the backend default.
Parameters
- organizationId: string | null
  Org ID (e.g. org-…) or null to clear.
Returns void
Inherited from BasePaymentsAPI.setOrganizationId
- Defined in src/api/base-payments.ts:200

settleCredential

settleCredential(params: RedeemMppParams): Promise<MppSettleResult>
Verifies and burns through the same chokepoint an x402 settlement uses, so the credits charged are identical on both protocols. Settling the same credential twice burns once.
Parameters
- params: RedeemMppParams
Returns Promise<MppSettleResult>
- Defined in src/mpp/mpp-api.ts:193

verifyCredential

verifyCredential(params: RedeemMppParams): Promise<VerifyPermissionsResult>
Runs the full credential and plan checks without burning anything.
Parameters
- params: RedeemMppParams
Returns Promise<VerifyPermissionsResult>
- Defined in src/mpp/mpp-api.ts:184

`Static`getInstance

getInstance(options: PaymentOptions): MppAPI
Parameters
- options: PaymentOptions
Returns MppAPI
- Defined in src/mpp/mpp-api.ts:157

Class MppAPI

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns MppAPI

Properties

ProtectedaccountAddress

Protected OptionalappId

ProtectedcurrentOrganizationId

Protectedenvironment

ProtectedenvironmentName

ProtectedheliconeApiKey

isBrowserInstance

ProtectednvmApiKey

ProtectedreturnUrl

Protectedscheme

Protected Optionalversion

Methods

fetch

Parameters

Returns Promise<MppFetchResult>

Example

getAccountAddress

Returns string | undefined

ProtectedgetBackendHTTPOptions

Parameters

Returns any

getEnvironmentName

Returns EnvironmentName

getMppAccessToken

Parameters

Returns Promise<{ accessToken: string }>

getOrganizationId

Returns string | null

ProtectedgetPublicHTTPOptions

Parameters

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

issueChallenge

Parameters

Returns Promise<{ challenge: string; id: string }>

ProtectedparseNvmApiKey

Returns { accountAddress: string; heliconeApiKey: string }

Throws

setOrganizationId

Parameters

Returns void

settleCredential

Parameters

Returns Promise<MppSettleResult>

verifyCredential

Parameters

Returns Promise<VerifyPermissionsResult>

StaticgetInstance

Parameters

Returns MppAPI

Settings

On This Page

`Protected`accountAddress

`Protected` `Optional`appId

`Protected`currentOrganizationId

`Protected`environment

`Protected`environmentName

`Protected`heliconeApiKey

`Protected`nvmApiKey

`Protected`returnUrl

`Protected`scheme

`Protected` `Optional`version

`Protected`getBackendHTTPOptions

`Protected`getPublicHTTPOptions

`Protected`parseNvmApiKey

`Static`getInstance