Node.js

Install

pnpm add @tael/sdk

createTael(defaults)

Binds service-wide settlement details once and returns a paid() function for defining individual routes. This is the recommended entry point.

const paid = createTael({
  payTo,     // StellarAddress that receives settlement
  issuer,    // StellarAddress of the USDC issuer
  network,   // "stellar-testnet" | "stellar-mainnet"
  verifier,  // PaymentVerifier
});

// paid(route) -> (Request) => Promise<Response>
export const POST = paid({ price: "0.02", handler });

tael(options)

The one-shot form. Takes the full option set and returns a payment-gated Fetch handler (Request) => Promise<Response>. Use it when a route doesn't share defaults with others.

const handler = tael({
  price: "0.02",
  payTo,
  issuer,
  network: "stellar-testnet",
  verifier: createMockVerifier(),
  handler: ({ request, receipt }) => Response.json({ ok: true }),
});

TaelOptions

• price: string — price per call, a decimal USDC string (e.g. "0.02").
• payTo: string — Stellar address that receives settlement.
• issuer: string — the USDC issuer on the target network.
• network: "stellar-testnet" | "stellar-mainnet"
• verifier: PaymentVerifier — verifies + settles the payment.
• description?: string — human text shown in the 402 challenge.
• handler: (ctx) => Response | Promise<Response> — runs after payment. Receives { request, receipt }.

With createTael, payTo/issuer/network/verifier come from the defaults and each route supplies only price, handler, and an optional description.

Verifiers

The PaymentVerifier is the chain-specific port. It's injected so the SDK stays chain-agnostic and your handlers stay portable.

• createMockVerifier() — re-exported from the SDK; accepts any well-formed proof for dev and tests.
• The Stellar verifier from @tael/stellar — real on-chain settlement for production.

Exports

• createTael, tael
• Types: TaelOptions, TaelDefaults, TaelRoute, TaelContext, TaelHandler, FetchHandler
• Re-exported from @tael/payments: createMockVerifier, PaymentVerifier, PaymentNetwork, SettlementReceipt

Prefer raw HTTP? See the cURL guide.