Skip to main content

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