Getting started

Getting started

This page shows the smallest end-to-end setup:

• a server that charges for a single tool
• a client that can pay via Lightning BOLT11 over NWC

If you haven’t set up Nostr transports yet, start with the transport docs first.

1) Server: mark capabilities as priced

Define what is paid using pricedCapabilities.

import type { PricedCapability } from "@contextvm/sdk/payments";

export const pricedCapabilities: PricedCapability[] = [
  {
    method: "tools/call",
    name: "my-tool",
    amount: 10,
    currencyUnit: "sats",
    description: "Example paid tool",
  },
];

2) Server: attach payments middleware

Create a processor, then wrap your server transport.

import {
  LnBolt11NwcPaymentProcessor,
  withServerPayments,
} from "@contextvm/sdk/payments";
import { NostrServerTransport } from "@contextvm/sdk/transport";

const baseTransport = new NostrServerTransport({
  signer,
  relayHandler,
});

const processor = new LnBolt11NwcPaymentProcessor({
  nwcConnectionString: process.env.NWC_SERVER_CONNECTION!,
});

const paidTransport = withServerPayments(baseTransport, {
  processors: [processor],
  pricedCapabilities,
});

Server behavior for priced requests:

1. emits notifications/payment_required (correlated to the request)
2. waits for settlement verification
3. emits notifications/payment_accepted
4. forwards the request to the underlying MCP server

3) Client: attach payments middleware

Create a handler and wrap your client transport.

import {
  LnBolt11NwcPaymentHandler,
  withClientPayments,
} from "@contextvm/sdk/payments";
import { NostrClientTransport } from "@contextvm/sdk/transport";

const baseTransport = new NostrClientTransport({
  signer,
  relayHandler,
  serverPubkey,
});

const handler = new LnBolt11NwcPaymentHandler({
  nwcConnectionString: process.env.NWC_CLIENT_CONNECTION!,
});

const paidTransport = withClientPayments(baseTransport, {
  handlers: [handler],
});

Now priced calls will automatically pay when required.

4) Try a paid call

Any request that matches pricedCapabilities will trigger the payment flow.

await client.callTool({
  name: "my-tool",
  arguments: { example: true },
});

What to read next

• Server payments
• Client payments
• Lightning over NWC