Payment Kit

About Nuwa Payment Kit

Overview

@nuwa-ai/payment-kit implements Nuwa’s unidirectional payment channels (NIP-4) for HTTP and MCP. It manages channel lifecycle, SubRAV receipts, streaming, and settlement.

Install

pnpm add @nuwa-ai/payment-kit @nuwa-ai/identity-kit @roochnetwork/rooch-sdk

HTTP Client

createHttpClient

Factory that builds a PaymentChannelHttpClient from an IdentityEnv.

Inputs

Creation options

options · object · required

Show options

baseUrl · string · required

Target service base URL

env · IdentityEnv · required

Identity environment

maxAmount · bigint?

Per-request budget (asset base unit)

debug · boolean?

Enable internal logging

fetchImpl · function?

Custom fetch replacement

mappingStore · HostChannelMappingStore?

Persist client state by host

channelRepo · ChannelRepository?

Channel meta storage

timeoutMs · number?

Non-streaming resolve timeout

timeoutMsStream · number?

Per-frame idle timeout for streams

Returns

client · PaymentChannelHttpClient

Configured HTTP payer client

PaymentChannelHttpClient.requestWithPayment

Create a payable request and return both response and payment promises.

Inputs

method · "GET"|"POST"|"PUT"|"DELETE"|"PATCH" · required

HTTP method

path · string · required

Relative URL or path

init · RequestInit?

Headers, body, and signal

Returns

clientTxRef · string

Correlation id

response · Promise

Raw fetch response promise

payment · Promise

Resolved payment info (PaymentInfo or undefined)

done · Promise

Resolves to object with data and payment

abort · function

Cancel the request

PaymentChannelHttpClient.request

Convenience wrapper returning only the HTTP response.

Inputs

method · "GET"|"POST"|"PUT"|"DELETE"|"PATCH" · required

HTTP method

path · string · required

Relative URL or path

init · RequestInit?

Request options

Returns

response · Promise

Raw fetch response promise

PaymentChannelHttpClient.requestAndWaitForPayment

Wait for both HTTP response and payment resolution.

Inputs

method · "GET"|"POST"|"PUT"|"DELETE"|"PATCH" · required

HTTP method

path · string · required

Relative URL or path

init · RequestInit?

Request options

Returns

data · Response

Raw fetch response

payment · PaymentInfo | undefined

Payment result (if billed)

PaymentChannelHttpClient.get/post/put/patch/delete

JSON helpers that parse the response and return { data, payment }.

Inputs

path · string · required

Relative URL or path

body · any?

JSON body for POST/PUT/PATCH

init · RequestInit?

Request options

Returns

data · any

Parsed JSON payload

payment · PaymentInfo | undefined

Payment result (if billed)

PaymentChannelHttpClient.getPendingSubRAV

Return the latest unsigned proposal (if any).

Inputs

(none) · void

No input parameters

Returns

subRav · SubRAV | null

Current pending SubRAV

PaymentChannelHttpClient.getPayerClient

Access the low-level payer client.

Inputs

(none) · void

No input parameters

Returns

payerClient · PaymentChannelPayerClient

Low-level client

PaymentChannelHttpClient.healthCheck

Check service health (free).

Inputs

(none) · void

No input parameters

Returns

health · HealthResponse

Server health payload

PaymentChannelHttpClient.recoverFromService

Recover latest SubRAV from service after failures.

Inputs

(none) · void

No input parameters

Returns

recovery · RecoveryResponse

Recovery payload

PaymentChannelHttpClient.logoutCleanup

Abort pending requests, reset state, and optionally clear persisted mapping.

Inputs

clearMapping · boolean? · default: "true"

Delete persisted mapping store

reason · string?

Optional note for logs

Returns

result · void

No return value

MCP Client

PaymentChannelMcpClient (constructor)

Create an MCP client with payment channels.

options · object · required

Show options

baseUrl · string · required

MCP server endpoint

signer · SignerInterface · required

keyId · string · required

chainConfig · ChainConfig · required

maxAmount · bigint · required

Per-call budget

storageOptions · object?

channelRepo?, namespace?

mappingStore · HostChannelMappingStore?

Persist client state

transactionStore · TransactionStore?

Tx logging

transactionLog · object?

Fields: enabled?, persist?, maxRecords?, sanitizeRequest?

returns · PaymentChannelMcpClient

PaymentChannelMcpClient.callTool

Call an MCP tool; payment handled internally.

name · string · required

args · any?

Tool params

returns · object

Object containing content: any[]

PaymentChannelMcpClient.callToolWithPayment

Call a tool and return both business content and payment info.

name · string · required

args · any?

Tool params

clientTxRef · string?

Correlation id

returns · object

Object with content and optional payment

PaymentChannelMcpClient.listTools

List server tools with internal reserved params removed.

options · object?

Optional flags (e.g., includeBuiltinTools)

returns · record

Map of tool name to definition

PaymentChannelMcpClient.tools

Return AI SDK compatible ToolSet.

returns · ToolSet

PaymentChannelMcpClient.listPrompts / loadPrompt

Prompt discovery helpers.

name · string?

For loadPrompt

args · any?

Prompt args

returns · any | string

PaymentChannelMcpClient.listResources / listResourceTemplates / readResource

Resource discovery helpers.

params · string | object?

For readResource (string or uri object)

returns · any[] | any

PaymentChannelMcpClient.getPendingSubRAV / commitSubRAV

Inspect or commit pending SubRAV.

signed · SignedSubRAV

For commitSubRAV

returns · SubRAV | object | null

Signed subRAV or success marker or null

PaymentChannelMcpClient.healthCheck / recoverFromService

Free endpoints for health and recovery.

returns · HealthResponse | RecoveryResponse

PaymentChannelMcpClient.close / clearPersistedState / getPayerClient / getTransactionStore

Lifecycle and accessors.

returns · void | PaymentChannelPayerClient | TransactionStore

Streaming

SSE/NDJSON responses include a payment frame that the client extracts and removes transparently. Use the same code paths for streaming and non-streaming.