RFC: Web Monetization Extensions API

[lukewarlow]

This issue is to open a discussion on what shape an extensions API for Web Monetization should take. There are a number of open questions but it's hoped that by opening this conversation we can answer those questions more easily.

[lukewarlow]

Draft Proposal: Web Monetization Extension API

Summary

An extension API that allows browser extensions to observe, control, and present Web Monetization sessions using a browser-provided core.

Document Metadata

Authors: @lukewarlow @asurkov

Sponsoring Browser: N/A

Contributors: @sidvishnoi

Created: 2025-12-16

Related Issues: <urls>

Motivation

Objective

This API enables extensions (and browser vendors) to build user-facing Web Monetization experiences on top of a browser-provided, headless monetization engine.

The browser implements all core functionality: processing monetization links, managing sessions, handling payment flows, and communicating with wallets. While extensions provide additional UI, indicators, preferences, and dashboards. This separation reduces upstream UI burden, enables faster iteration, and allows browsers to differentiate their user experience while sharing a common underlying engine.

Importantly, exposing this extension API does not imply that all internal capabilities are exposed to public extensions. Capabilities can be leveled such that safer subsets can be exposed more freely. Additionally, the payment credentials are never exposed.

Use Cases

• Displaying monetization indicators
• Providing richer onboarding and wallet connection flows.
• Presenting session summaries.
• Applying user preferences.
• Enforcing monetization rules.

Known Consumers

• Browser-provided Web Monetization UI implementations.
• Interledger Web Monetization Extension

Specification

Schema

namespace webMonetization {
    // Wallet (may be priviledge or restricted)
    connectWallet?(): Promise<WalletInfo>;
    disconnectWallet?(): Promise<void>;
    getWallet?(): Promise<WalletInfo | null>
    
    // Session Management
    startSession(): Promise<void>;
    stopSession(): Promise<void>;
    listSessions(): Promise<Array<SessionSummary>>;
    
    // History
    listSessionHistory(): Promise<Array<SessionSummary>>;
    getSessionDetails(sessionId: ?): Promise<SessionDetails>;
    getStreamSummary(): Promise<StreamSummary>;
    
    // Rules
    getRules(): Promise<Array<Rule>>;
    setRules(rules: Array<Rule>): Promise<void>;
    clearRules(): Promise<void>;
    
    // Events
    onsessionstart: ((this: WebMonetizationAPI, ev: Event) => any) | null;
    onsessionstop:  ((this: WebMonetizationAPI, ev: Event) => any) | null;
    onload:  ((this: WebMonetizationAPI, ev: Event) => any) | null;
    onpayment: ((this: WebMonetizationAPI, ev: MonetizationEvent));
}

Notes:

• Events may be rate-limited, especially onpayment.

Behavior

Wallet Connection

Wallet methods are intentionally marked optional, these might end up being browser internal.

How to handle multiple wallets?

Session Management

• startSession() begins a monetization session for the current page or monetization link. What should the parameters be?
• stopSession() ends an active session. There can be multiple so what should parameters be?
• listSessions() returns all currently active sessions.

History Access

• History APIs are read-only
• This access should be behind an additional permission

Should these be scoped per site, or should extensions be able to access this data at a high level?

Rules

If the engine supports rule-based logic, extensions may access it through the provided methods.

Using the session management APIs they could enforce custom rules without needing to set built-in ones.

New Permissions

Permission Added	Suggested Warning
webMonetization	"Access and control Web Monetization sessions on pages you visit."
webMonetizationHistory	"Access historical Web Monetization sessions."

Wallet-related capabilities, if exposed, may require an additional permission or be restricted to private extensions only.

Manifest File Changes

No new manifest fields are required beyond declaring additional permissions.

Security and Privacy

Exposed Sensitive Data

• Active monetization session metadata
• Historical session data, which is essentially a subset of user navigation history.

Raw payment credentials, private keys, or any other private data associated with Open Payments are never exposed.

Abuse Mitigations

Potential abuse includes:

• Misleading UI during wallet connection flow.
• Correlating monetization activity with browsing behaviour.
• Starting of sessions against the users wishes, especially with rule access.

Mitigations Include:

• Restricting wallet connection APIs.
• Requiring explicit permissions with gates for different levels of access.
• Potentially aggregagting historical data.
• Possibly session management is left to the browser, we just expose the events to enable the UI use cases.

Additional Security Considerations

In the case of a compromised process, the browser still has control as the actual Open Payments flow occurs within the priviledged host process, NOT in the renderer or extension process.

Alternatives

Existing Workarounds

• Extensions inject content scripts and infer monetization state from events exposed there.
• Complete re-implementation of the web monetization specification at the extension level.

Open Web API

This API augments another API that is exposed to the open-web, to allow for improved user experiences. Certain data such as session history would allow sites to access browsing history which is too sensitive.

Future Work

• Standardising rule formats.
• Clarifying which operations can be safely exposed to public extensions. Session Management and wallet connection are two aspects likely to be deferred.