Getting started

github.com/Serendipity-AI/markdown2pdf-typescript Our TypeScript SDK makes it easy to use markdown2pdf.ai in your agentic workflows. Whilst using our REST APIs is straightforward, the SDK handles the fiddly parts for you: it fetches a Lightning invoice, passes it to your payment callback, re-submits your request once the callback returns, and polls until your PDF is ready. First, install the SDK:

npm install @serendipityai/markdown2pdf-typescript

The SDK ships as an ES module only, and the examples on this page use ES module syntax, so Node must load your code as an ES module. Add "type": "module" to your package.json (or give your file the .mts extension). This also removes the warning Module type of file is not specified and it doesn’t parse as CommonJS that Node prints when you run a TypeScript file directly (for example, via node test.ts).

With that done, you can try a sample code snippet:

import { convertMarkdownToPdf } from "@serendipityai/markdown2pdf-typescript";
import type { OfferDetails } from "@serendipityai/markdown2pdf-typescript";

async function pay(offer: OfferDetails) {
    console.log("⚡ Lightning payment required");
    console.log(`Amount: ${offer.amount} cents (${offer.currency})`);
    console.log(`Description: ${offer.description}`);
    console.log(`Invoice: ${offer.payment_request}`);
    console.log("Press ENTER after completing the payment to continue...");
    await new Promise< void >(resolve => { process.stdin.once("data", () => { resolve(); }); });
}

async function main() {
    const result = await convertMarkdownToPdf("# Hello from TypeScript", {
        title: "My document title",
        downloadPath: "output.pdf",
        onPaymentRequest: pay
    });
    console.log("Saved PDF to:", result);
}

main().catch(console.error);

This code converts your markdown into a PDF. If a Lightning payment is required, the SDK calls your onPaymentRequest callback (here our pay function) so that you can handle the payment (for example, by printing the invoice and waiting for manual confirmation). You can also integrate with services like fewsats.com or albyhub for automatic payments.

SDK Reference

Types

The SDK exports the following types (and classes) (from “@serendipityai/markdown2pdf-typescript”):

type

A TypeScript type that describes the payment offer details. This type is used in the onPaymentRequest callback.

type OfferDetails = {
    offer_id: string;        // Unique identifier for the offer
    amount: number;          // The payment amount in US cents (1 = $0.01)
    currency: string;        // The currency code (e.g., "USD")
    description: string;     // Description of what the payment is for
    payment_context_token: string;  // Token used for payment verification
    payment_request_url: string;    // URL where the payment request can be viewed
    payment_request?: string;       // Lightning payment request (BOLT11 invoice); the SDK sets it before calling onPaymentRequest
};

Example usage:

async function pay(offer: OfferDetails) {
    console.log(`Payment required: ${offer.amount} cents (${offer.currency})`);
    console.log(`Description: ${offer.description}`);
    if (offer.payment_request) {
        console.log(`Lightning invoice: ${offer.payment_request}`);
    }
    // ... handle payment ...
}

type

A TypeScript type that describes the configuration options for the convertMarkdownToPdf function.

type ConvertOptions = {
    onPaymentRequest?: (offer: OfferDetails) => Promise<void>;  // Callback for handling Lightning payments (required: the SDK throws without it)
    date?: string;          // Date to display on the cover page
    title?: string;         // Title to display on the cover page
    downloadPath?: string;  // Path where the PDF should be saved
    returnBytes?: boolean;  // Whether to return the PDF as a Buffer instead of saving to file
    apiUrl?: string;        // Optional override for the API URL (for development/testing)
};

Example usage:

const options: ConvertOptions = {
    title: "My Document",
    date: "2024-03-20",
    downloadPath: "output.pdf",
    onPaymentRequest: async (offer) => {
        console.log(`Payment required: ${offer.amount} cents (${offer.currency})`);
        // ... handle payment ...
    }
};

const result = await convertMarkdownToPdf("# Hello World", options);

Markdown2PdfError – A class (extending Error) for conversion errors. The errors the SDK throws are not instances of the exported class, so instanceof Markdown2PdfError returns false; check error.name === "Markdown2PdfError" instead:

try {
    await convertMarkdownToPdf("# Hello from TypeScript", { onPaymentRequest: pay });
} catch (error) {
    if (error instanceof Error && error.name === "Markdown2PdfError") {
        console.error("Conversion failed:", error.message);
    } else {
        throw error;
    }
}

PaymentRequiredError – A class (extending Markdown2PdfError). The SDK exports it but never throws it.

Function: convertMarkdownToPdf

Signature:

async function convertMarkdownToPdf(
    markdown: string,
    options?: ConvertOptions
): Promise<string | Buffer>

Description: Converts the provided markdown (a string) into a PDF. The function takes two parameters:

markdown: The markdown content to convert
options: An object containing configuration parameters for the conversion process, including the required onPaymentRequest callback

If you omit onPaymentRequest, the SDK throws a Markdown2PdfError (“Payment required but no handler provided.”) before it sends any request. When the API asks for payment, the SDK fetches a Lightning invoice and calls your callback with it. The SDK waits up to 300 seconds for your callback to resolve, then re-submits the conversion request. If the invoice is still unpaid, the SDK fetches a new invoice and calls your callback again. Once the API accepts the request, the SDK checks the job status every 3 seconds, for up to 300 seconds.
The SDK retrieves the final PDF; either saving it to downloadPath or returning it as a Buffer if returnBytes is true. Parameters:

string

required

A string containing the markdown content you want to convert to PDF.

A note on markdown hashingmarkdown2pdf.ai uses a hashing mechanism to ensure that you won’t get charged twice for creating the same PDF. Subsequent requests to convert the same markdown content will return the previously generated PDF without requiring a new payment.

For example:

const result = await convertMarkdownToPdf("# Hello from TypeScript", {
    title: "My document title",
    downloadPath: "output.pdf",
    onPaymentRequest: pay
});

function

required

A callback function that is called when a Lightning payment is required. The function receives an offer object containing payment details. This parameter is required because the service uses the L402 protocol, which requires a payment to be made before generating the PDF.

async function pay(offer: OfferDetails) {
    console.log("⚡ Lightning payment required");
    console.log(`Amount: ${offer.amount} cents (${offer.currency})`);
    console.log(`Description: ${offer.description}`);
    console.log(`Invoice: ${offer.payment_request}`);
    await new Promise<void>(resolve => { process.stdin.once("data", () => { resolve(); }); });
}

const result = await convertMarkdownToPdf("# Hello from TypeScript", {
    onPaymentRequest: pay,
    downloadPath: "output.pdf"
});

const offer: OfferDetails = {
    offer_id: "abc",
    amount: 1,           // US cents, so $0.01; the Lightning invoice states the equivalent in sats
    currency: "USD",
    description: "test payment",
    payment_context_token: "def",
    payment_request_url: "http://path.to/payment/request",
    payment_request: "lnbc..." // Optional
};

string

A string containing the date to use on the front cover. If not provided, the current date will be used.For example:

const result = await convertMarkdownToPdf("# Hello from TypeScript", {
    date: "5th June 2025",
    downloadPath: "output.pdf",
    onPaymentRequest: pay
});

string

A string containing the title to use on the front cover. If not provided, a default will be used.For example:

const result = await convertMarkdownToPdf("# Hello from TypeScript", {
    title: "My document title",
    downloadPath: "output.pdf",
    onPaymentRequest: pay
});

string

A string containing the path to use for saving the PDF file. If not provided and returnBytes is false, the PDF URL will be returned instead.For example:

const path = await convertMarkdownToPdf("# Save this one", {
    downloadPath: "output.pdf",
    onPaymentRequest: pay
});
console.log("Saved PDF to:", path);

boolean

Whether or not to return the PDF as bytes instead of saving it to a file. If set to true, the method will return the PDF content as a Buffer. If set to false, it will save the PDF to the specified downloadPath or return the URL if no path is provided.For example:

const pdfBytes = await convertMarkdownToPdf("# Memory use case", {
    returnBytes: true,
    onPaymentRequest: pay
});
console.log(`PDF size in memory: ${pdfBytes.length} bytes`);

string

This parameter enables you to override the default API URL. This is typically used in development or testing environments, but for normal usage you won’t need to touch it and it can be set to undefined or omitted.

Returns

Condition	Resolves to	Type
`downloadPath` is provided and `returnBytes` is `false`	The value of `downloadPath`	string
`returnBytes` is `true`	The PDF as a Buffer	Buffer
Neither `downloadPath` nor `returnBytes` is provided/true	The final download URL	string
An error occurs (no `onPaymentRequest` callback, network, or timeout)	Rejects with error	`Error` with `name` `"Markdown2PdfError"`
Your `onPaymentRequest` callback throws	Rejects with your error	Whatever your callback throws

The function always returns a Promise that resolves or rejects as described above.

Automating payments

If you want to automate Lightning payments (so that your “onPaymentRequest” callback pays the invoice automatically), you can integrate with a service (or Lightning wallet) such as fewsats.com or albyhub. For X402 (USDC on Solana) use any Solana wallet that holds USDC — see the X402 tab below.

Alby
lnbits
Fewsats
Coinbase X402

import { convertMarkdownToPdf } from "@serendipityai/markdown2pdf-typescript";
import axios from 'axios';
import type { OfferDetails } from '@serendipityai/markdown2pdf-typescript';

// Configure Alby client
const ALBY_API_URL = 'https://api.getalby.com';
const client = axios.create({
  baseURL: ALBY_API_URL,
  headers: {
    'Authorization': `Bearer ${process.env.ALBY_ACCESS_TOKEN}`,
    'Content-Type': 'application/json'
  }
});

async function pay(offer: OfferDetails) {
  console.log("Paying using Alby:");
  try {
    // Pay the invoice using Alby's API
    const response = await client.post('/payments/bolt11', {
      invoice: offer.payment_request
    });

    if (response.status === 200)
      console.log('Payment successful:', response.data);
    else
      console.log('Payment status:', response.status);
  } catch (error) {
    if (axios.isAxiosError(error))
      console.error('Payment failed:', error.response?.data || error.message);
    else
      console.error('Payment failed:', error);
  }
  await new Promise(resolve => { process.stdin.once("data", () => resolve(undefined)); });
}

async function main() {
  const path = await convertMarkdownToPdf("# Save this one using Alby", { 
    downloadPath: "output.pdf", 
    onPaymentRequest: pay 
  });
  console.log("Saved PDF to:", path);
}

main().catch(console.error); 

import { convertMarkdownToPdf } from "@serendipityai/markdown2pdf-typescript";
import axios from "axios";
import type { OfferDetails } from '@serendipityai/markdown2pdf-typescript';

// Constants
const LN_BITS_URL = "https://demo.lnbits.com/api/v1/payments";
const ADMIN_KEY = process.env.LNBITS_ADMIN_KEY as string; // Set in your env

async function pay(offer: OfferDetails) {
console.log("Paying using lnbits:");

try {
  const response = await axios.post(
    LN_BITS_URL,
    {
      out: true,
      bolt11: offer.payment_request
    },
    {
      headers: {
        "X-Api-Key": ADMIN_KEY,
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Payment successful:", response.data);
} catch (error) {
  if (axios.isAxiosError(error)) {
    console.error("Payment failed:", error.response?.data || error.message);
  } else {
    console.error("Unexpected error:", error);
  }
}
}

async function main() {
const path = await convertMarkdownToPdf("# Save this one using LNbits", {
  downloadPath: "output.pdf",
  onPaymentRequest: pay
});
console.log("Saved PDF to:", path);
}

main().catch(console.error);

import { convertMarkdownToPdf } from "@serendipityai/markdown2pdf-typescript";
import type { OfferDetails } from '@serendipityai/markdown2pdf-typescript';
import { Fewsats } from 'fewsats';
// Configure the SDK
const client = new Fewsats({ apiKey: process.env.FEWSATS_API_KEY });

async function pay(offer: OfferDetails) {
 console.log("Paying using Fewsats:");
 console.log(offer);
 
 try {
   // Use the SDK to pay the offer
   if (!offer.payment_request) throw new Error("Offer has no Lightning invoice");
   const response = await client.payLightning(offer.payment_request, offer.amount, offer.currency, offer.description);

   if (response.success) {
     console.log('Payment successful:', response);
   } else {
     console.log('Payment failed:', response.error);
   }
 } catch (error) {
   console.error('Payment failed:', (error as Error).message);
 }

 await new Promise(resolve => { process.stdin.once("data", () => resolve(undefined)); });
}

async function main() {
 const path = await convertMarkdownToPdf("# Save this one using Fewsats", { 
   downloadPath: "output.pdf", 
   onPaymentRequest: pay 
 });
 console.log("Saved PDF to:", path);
}

main().catch(console.error);

npm install @x402/fetch @x402/svm @solana/kit

import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from "@x402/fetch";
import { ExactSvmScheme } from "@x402/svm";
import { createKeyPairSignerFromBytes, getBase58Encoder } from "@solana/kit";

const NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"; // Solana mainnet

async function main() {
  // Any Solana wallet that holds USDC (base58-encoded 64-byte secret key)
  const secretKey = getBase58Encoder().encode(process.env.SOLANA_SIGNER_KEY as string);
  const signer = await createKeyPairSignerFromBytes(secretKey);

  const client = new x402Client()
    .register(NETWORK, new ExactSvmScheme(signer))
    .registerPolicy((_version, reqs) => reqs.filter(r => r.network === NETWORK))
    .setSpendControls({ maxAmountPerPayment: "$1" }); // a conversion is $0.40 in USDC

  const fetchWithPayment = wrapFetchWithPayment(fetch, client);

  const resp = await fetchWithPayment("https://api.markdown2pdf.ai/markdown", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      data: { text_body: "# Save this one using X402" },
      options: { document_name: "output.pdf" },
    }),
  });
  if (!resp.ok) throw new Error(`Request failed: ${resp.status}`);

  const proof = resp.headers.get("PAYMENT-RESPONSE");
  if (proof) console.log("Paid tx proof:", decodePaymentResponseHeader(proof).transaction);
  const { path } = (await resp.json()) as { path: string };
  console.log("Poll:", path);
}

main().catch(console.error);

wrapFetchWithPayment catches the 402 response, signs a USDC transfer with your Solana key, and retries the request with a PAYMENT-SIGNATURE header. The spend cap stops the client signing any single payment above $1. A future SDK release will expose a first-class onX402PaymentRequired option on convertMarkdownToPdf; until then, poll the returned path yourself as described on the X402 page.

Welcome, agents!

SDKs

REST API

TypeScript SDK

Getting started

SDK Reference

Types

Function: convertMarkdownToPdf

Automating payments

​Getting started

​SDK Reference

​Types

​Function: convertMarkdownToPdf

​Automating payments

Getting started

SDK Reference

Types

Function: convertMarkdownToPdf

Automating payments