]> Tempo Labs

jake@tempo.xyz

Tempo Labs

brendan@tempo.xyz

This document defines how the Payment HTTP Authentication Scheme operates over JSON-RPC 2.0 transports. It specifies the mapping of payment challenges to JSON-RPC error responses using implementation-defined error codes, credential transmission via metadata fields, receipt delivery in successful responses, and error handling conventions. This specification applies to any transport carrying JSON-RPC 2.0 messages, including WebSocket, HTTP, stdio, and protocol frameworks such as the Model Context Protocol (MCP).

Introduction JSON-RPC 2.0 is a stateless, lightweight remote procedure call protocol using JSON . Many modern protocols layer JSON-RPC over various transports including HTTP, WebSocket , and stdio. Protocol frameworks such as the Model Context Protocol (MCP) also use JSON-RPC 2.0 as their message format. This document defines how the Payment HTTP Authentication Scheme operates within JSON-RPC 2.0 messages, independent of the underlying transport. This specification defines: Error codes for payment signaling Challenge structure in JSON-RPC error responses Credential transmission via _meta metadata fields Receipt delivery via _meta metadata fields Error handling conventions Notification behavior Capability advertisement

Applicability This specification applies to any system that exchanges JSON-RPC 2.0 messages, including but not limited to: WebSocket: JSON-RPC over persistent wss:// connections for real-time APIs, streaming services, and subscriptions. HTTP: JSON-RPC 2.0 over standard HTTP request-response exchanges. stdio: JSON-RPC 2.0 over standard input/output streams for local process communication. This specification also defines MCP-specific conventions for the Model Context Protocol , which uses JSON-RPC 2.0 for tool invocations (tools/call), resource access (resources/read), and prompt retrieval (prompts/get). Transport-specific security requirements (e.g., TLS for WebSocket, process isolation for stdio) are addressed in .

Design Goals Native JSON: Use JSON objects directly rather than base64url encoding, leveraging JSON-RPC's native capabilities. Transport Independent: Define payment semantics at the JSON-RPC layer, applicable to any transport carrying JSON-RPC messages. Minimal Overhead: Add payment data only when needed via the _meta extension mechanism. Multiple Options: Support servers offering multiple payment methods in a single challenge.

Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Terminology This document uses terminology from :

Challenge

Payment requirements communicated by the server.

Credential

Payment authorization data sent by the client.

Receipt

Server acknowledgment of successful payment.

Protocol Overview The payment flow follows three phases within JSON-RPC message exchanges:

│ │ │ │ (2) JSON-RPC Error │ │ {code: -32042, data: {challenges: [...]}} │ │<─────────────────────────────────────────────────────┤ │ │ │ (3) Client fulfills challenge │ │ │ │ (4) JSON-RPC Request │ │ {method: "...", │ │ _meta: {credential: {...}}} │ ├─────────────────────────────────────────────────────>│ │ │ │ (5) JSON-RPC Result │ │ {result: {...}, _meta: {receipt: {...}}} │ │<─────────────────────────────────────────────────────┤ ]]>

Capability Advertisement Servers and clients SHOULD advertise supported payment methods and intents before payment flows begin. The capability object SHOULD contain: methods (REQUIRED): Object mapping payment method identifiers (as registered in the IANA HTTP Payment Methods registry) to their configuration. Each method object MUST contain an intents array listing the supported payment intent types (as registered in the IANA HTTP Payment Intents registry) for that method. Example capability object:

The mechanism for advertising capabilities depends on the transport: WebSocket: Servers MAY send a payment.capabilities JSON-RPC notification after connection establishment. MCP: See . Clients MAY use capability information to determine compatibility before invoking paid methods. Clients MUST NOT rely solely on capability advertisement to determine payment support; malicious servers could claim capabilities they don't properly implement. Clients SHOULD validate challenge structure before fulfilling payment.

MCP Capability Advertisement For MCP specifically, servers SHOULD advertise payment support in the InitializeResult:

Clients SHOULD advertise in the InitializeRequest:

Servers MAY use client capabilities to filter which payment options to offer in challenges.

Payment Challenge

Signaling Payment Required When a JSON-RPC method requires payment, the server MUST respond with a JSON-RPC error using code -32042 (Payment Required). This code is within the JSON-RPC implementation-defined server error range (-32000 to -32099) per :

The error.data.httpStatus field SHOULD be included with value 402 to indicate the corresponding HTTP status code for transports that bridge to HTTP (e.g., MCP Streamable HTTP).

Challenge Structure The error.data object MUST contain: challenges (REQUIRED): Array of one or more challenge objects. problem (OPTIONAL): An RFC 9457 Problem Details object providing additional error context. When present, contains type, title, status, detail, and optionally challengeId. Each challenge object MUST contain: id (REQUIRED): Unique challenge identifier. Servers MUST cryptographically bind this value to at minimum the following parameters: realm, method, intent, request (canonical hash), and expires. Clients MUST include this value unchanged in the credential. realm (REQUIRED): Protection space identifier defining the scope of the payment requirement. method (REQUIRED): Payment method identifier as registered in the IANA HTTP Payment Methods registry. intent (REQUIRED): Payment intent type as registered in the IANA HTTP Payment Intents registry. request (REQUIRED): Method-specific payment request data as a native JSON object. Servers MUST NOT base64url-encode the request when using JSON-RPC transport. For challenge binding and challenge ID verification, both parties MUST canonicalize request using JSON Canonicalization Scheme (JCS) and hash the canonicalized bytes. The schema is defined by the payment method specification. Each challenge object MAY contain: expires (OPTIONAL): Timestamp in format after which the challenge is no longer valid. Clients SHOULD NOT attempt to fulfill challenges past their expiry. If absent, servers define the validity period. description (OPTIONAL): Human-readable description of what the payment is for.

Multiple Payment Options When multiple challenges are present, they represent alternative payment options. Clients MUST select exactly one challenge to fulfill. Servers MUST NOT require multiple simultaneous payments via this mechanism. Servers MAY offer multiple payment options by including multiple challenge objects in the challenges array:

Clients SHOULD select one challenge based on their capabilities and user preferences. Clients MUST send only one credential corresponding to a single selected challenge.

Payment Credential

Metadata Placement This specification defines two placement strategies for the _meta field, depending on the protocol: Root-level _meta (Generic JSON-RPC): The _meta field is placed at the root of the JSON-RPC message object. This approach works with any JSON-RPC method regardless of whether params is an object or an array:

Nested _meta (MCP): The _meta field is placed inside params (for requests) or result (for responses), per MCP conventions where params is always an object:

Servers MUST check both locations for _meta and MUST NOT require clients to use a specific placement. Servers MUST ignore org.paymentauth/credential on methods that do not require payment.

Transmitting Payment Data Clients send payment credentials using the _meta field with key org.paymentauth/credential. The key uses reverse-DNS naming to avoid collisions with other extensions:

Credential Structure The org.paymentauth/credential object MUST contain: challenge (REQUIRED): The complete challenge object from the server's -32042 error response. Clients MUST echo the challenge unchanged. payload (REQUIRED): Method-specific payment proof as a JSON object. The schema is defined by the payment method specification. The credential object MAY contain: source (OPTIONAL): Identifier of the payment source (e.g., a DID or address).

Payment Receipt

Successful Payment Response After successful payment verification and settlement, servers MUST include a receipt using _meta with key org.paymentauth/receipt. The _meta field placement follows the same rules as : root-level for generic JSON-RPC, nested in result for MCP.

Servers MUST return org.paymentauth/receipt on every successful response to a paid request. Servers MUST NOT return receipts for unpaid requests.

Receipt Structure The org.paymentauth/receipt object MUST contain: status (REQUIRED): Settlement status. MUST be "success" for successful payments. method (REQUIRED): Payment method that was used. timestamp (REQUIRED): timestamp of settlement. challengeId (REQUIRED): The id from the fulfilled challenge. The receipt object MAY contain: reference (OPTIONAL): Method-specific settlement reference (e.g., transaction hash, invoice ID).

MCP Covered Operations The following MCP operations support payment flows.

Tool Calls Tool invocations via tools/call MAY require payment: Challenge:

Response:

Resource Access Resource reads via resources/read MAY require payment: Challenge:

Response:

Prompt Retrieval Prompt retrieval via prompts/get MAY require payment: Response:

Error Handling

Error Code Mapping Servers MUST map payment errors to JSON-RPC error codes within the server error range (-32000 to -32099) per : Condition Code Description Payment required -32042 Payment challenge in error.data Payment verification failed -32043 Fresh challenge + failure reason Malformed credential -32602 Invalid params (bad JSON structure) Internal payment error -32603 Payment processor failure Note: -32700 (Parse error) applies only when the entire JSON-RPC message is unparseable, not for malformed _meta subfields. Use -32602 for credential structure errors.

Payment Verification Failure When payment verification fails, servers MUST return code -32043 with a fresh challenge and failure details:

On verification failure, servers MAY return the same challenge if it remains valid, or issue a fresh challenge. Clients SHOULD treat any -32043 response as requiring a new payment attempt. The failure object MAY contain: reason (OPTIONAL): Machine-readable failure code. detail (OPTIONAL): Human-readable failure description.

Protocol Errors Technical errors use standard JSON-RPC error codes: Invalid Params (-32602): Used for malformed credentials or missing required fields:

Notifications JSON-RPC notifications are requests without an id field that expect no response. Since payment challenges require a response, notifications cannot support payment flows.

Server Behavior Servers MUST NOT process payment-gated operations invoked as notifications. Servers SHOULD silently drop such notifications per JSON-RPC 2.0 semantics. Servers MAY log dropped payment-required notifications for debugging purposes. Servers MAY send JSON-RPC notifications to deliver data after a client has fulfilled a prior payment challenge (e.g., streaming subscription updates over WebSocket).

Client Guidance Clients SHOULD NOT invoke payment-gated operations as notifications. Operations that may require payment SHOULD always include a request id to receive payment challenges and results.

Security Considerations

Challenge Binding Servers MUST cryptographically bind challenge IDs to their parameters (at minimum: realm, method, intent, request hash, expires). The request hash MUST be computed over the JCS-canonicalized representation of request per . This prevents clients from reusing a challenge ID with modified payment terms. Servers SHOULD also bind challenges to the specific operation being requested (e.g., tool name, resource URI) to prevent a challenge issued for one operation being used for another.

Replay Protection Servers MUST reject credentials for: Unknown challenge IDs Expired challenges (past expires timestamp) Previously-used challenge IDs Servers SHOULD maintain a record of used challenge IDs for at least the challenge validity period. For high-throughput scenarios, servers MAY use stateless challenge tokens (e.g., MAC over canonical parameters) and maintain only a post-use replay set. When two concurrent requests race using the same challenge, servers MUST ensure only one succeeds via atomic check-and-mark operations.

Transport Security When using network transports (HTTP, WebSocket), all communication MUST occur over TLS 1.2 or later (TLS 1.3 RECOMMENDED). For stdio transport, security depends on the process isolation provided by the operating system. For persistent transports (e.g., WebSocket), servers SHOULD additionally rate limit connection establishment and close connections that exceed challenge request thresholds.

Credential Confidentiality Payment credentials MAY contain sensitive data (signatures, tokens). Clients MUST NOT log or persist credentials beyond immediate use. Servers MUST NOT log full credential payloads. This includes crash dumps, distributed tracing, and analytics telemetry.

Metadata Stripping On-path attackers or malicious intermediaries could strip org.paymentauth/credential from requests (causing repeated payment challenges) or org.paymentauth/receipt from responses (affecting auditability). For network transports, TLS provides integrity. For stdio transport, rely on process isolation.

Confused Deputy Clients may be tricked into paying for unintended operations if method names or realms are misleading. Client implementations SHOULD: Display realm, amount, currency, and recipient to users before fulfilling payment challenges Allow users to configure payment policies per realm Validate that challenge parameters match the requested operation

Denial of Service Attackers may trigger many payment challenges to exhaust server resources or payment processor rate limits. Servers SHOULD: Rate limit challenge issuance per client Use stateless challenge encoding where possible Implement exponential backoff for repeated failures

IANA Considerations This document has no IANA actions. Payment methods and intents are registered per . Servers MUST use the following JSON-RPC error codes: Code Name Description -32042 Payment Required Server requires payment to proceed -32043 Payment Verification Failed Payment credential invalid These codes are within the JSON-RPC server error range (-32000 to -32099). Implementations MUST use these exact codes for interoperability.

&RFC2119; &RFC3339; &RFC5246; &RFC6455; &RFC8174; &RFC8259; &RFC8446; &RFC8785;

Example: Ethereum JSON-RPC over WebSocket An eth_getBlockByNumber call over WebSocket with payment required for RPC access: Connection:

Step 1: Initial Request

Step 2: Payment Challenge

Step 3: Request with Credential

Step 4: Success with Receipt

Example: MCP Tool Call A complete MCP tool call with payment, using nested _meta per MCP conventions: Step 1: Initial Request

Step 2: Payment Challenge

Step 3: Request with Payment

Step 4: Success with Receipt

References to MCP Specification MCP Base Protocol: https://modelcontextprotocol.io/specification/2025-11-25/basic MCP Transports: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports MCP Tools: https://modelcontextprotocol.io/specification/2025-11-25/server/tools MCP Resources: https://modelcontextprotocol.io/specification/2025-11-25/server/resources MCP _meta Field: https://modelcontextprotocol.io/specification/2025-11-25/basic