Getting started

github.com/Serendipity-AI/markdown2pdf-python Our Python SDK makes it easy to use markdown2pdf.ai in your agentic workflows. Whilst using our REST APIs is straightforward, there are some complexities to handle around polling for payment completion and document generation that the SDK avoids you needing to worry about. First up, you’ll need to install the SDK:

pip install markdown2pdf-python

With that done, you can try some sample code:

from markdown2pdf import MarkdownPDF

def pay(offer):
    print("⚡ Lightning payment required")
    print(f"Amount: {offer['amount']} cents ({offer['currency']})")
    print(f"Description: {offer['description']}")
    print(f"Invoice: {offer['payment_request']}")
    input("Press Enter once paid...")

client = MarkdownPDF(on_payment_request=pay)
path = client.convert(markdown="# Insert your own markdown content here", title="My document title", download_path="output.pdf")
print("Saved PDF to:", path)

This code will convert the markdown content you provide into a PDF, prompting you to pay via Lightning Network if necessary. The on_payment_request function is called when payment is required, allowing you to handle the payment process in your application. There are several ways of handling payments automatically, such as fewsats.com or albyhub or using a Lightning wallet that supports automatic payments. In the example above, we simply print the payment details and wait for you to confirm payment manually. You can simply copy and paste the lightning invoice into your lightning wallet to pay.

SDK Reference

`class MarkdownPDF`

The main class for interacting with the markdown2pdf.ai service.

`constructor`

Used for initializing the MarkdownPDF client.

function

default:"None"

The SDK calls this function when the service asks for payment. It receives an offer dict containing details about the payment, such as amount, currency, description, and the Lightning invoice. You can implement your own logic to handle payments here, and the function can be a plain function or an async one. The service uses the L402 protocol, so a new document needs a payment before the service generates the PDF. If the service asks for payment and you haven’t supplied a handler, convert raises PaymentRequiredException("Payment required but no handler provided.").

def pay(offer):
    print("⚡ Lightning payment required")
    print(f"Amount: {offer['amount']} cents ({offer['currency']})")
    print(f"Description: {offer['description']}")
    print(f"Invoice: {offer['payment_request']}")
    input("Press Enter once paid...")

client = MarkdownPDF(on_payment_request=pay)

The offer dict looks like this. amount is in US cents, so 1 means one cent; the Lightning invoice in payment_request carries the equivalent in sats.

offer = {
    "offer_id": "abc",
    "amount": 1,
    "currency": "USD",
    "description": "test payment",
    "payment_context_token": "def",
    "payment_request_url": "http://path.to/payment/request",
    "payment_request": "lnbc...",
}

string

default:"https://api.markdown2pdf.ai"

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: omit it and the client uses https://api.markdown2pdf.ai. Don’t pass None, as the client would then build an invalid URL.

number

default:"3"

The number of seconds the client waits between polling requests, both after calling your payment handler and while the service generates the PDF. The client polls for the finished document up to 10 times (about 30 seconds at the default interval), then raises Markdown2PDFException.

`convert`

Converts the provided markdown content into a PDF document. This method handles the payment process automatically if required, and either saves the PDF to download_path, returns it as bytes, or returns its download URL.

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

Typically your markdown will come from the output of an LLM or AI agent. If you want to load some from a file, you can do it like this:

from markdown2pdf import MarkdownPDF
from pathlib import Path

def pay(offer):
    print("⚡ Lightning payment required")
    print(f"Amount: {offer['amount']} cents ({offer['currency']})")
    print(f"Description: {offer['description']}")
    print(f"Invoice: {offer['payment_request']}")
    input("Press Enter once paid...")

client = MarkdownPDF(on_payment_request=pay)
markdown = Path("my-document.md").read_text(encoding="utf-8")
url = client.convert(markdown=markdown, title="My document", date="5th June 2025")
print("PDF URL:", url)

string

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

string

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

string

A string containing the path to use for saving the PDF file. When you provide it, convert writes the PDF there and returns the path. If you provide neither download_path nor return_bytes=True, convert returns the PDF’s download URL as a string.For example:

path = client.convert(markdown="# Save this one", download_path="output.pdf") 
print("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 returns the PDF content as a byte string and doesn’t write a file. If set to False (the default), the method saves the PDF to download_path and returns that path, or returns the download URL if you didn’t provide a path.For example:

pdf_bytes = client.convert(markdown="# Memory use case", return_bytes=True) 
print(f"PDF size in memory: {len(pdf_bytes)} bytes")

`class AsyncMarkdownPDF`

An async version of MarkdownPDF with the same constructor and convert parameters. Use it when your code already runs in an event loop, and await the call:

from markdown2pdf import AsyncMarkdownPDF

client = AsyncMarkdownPDF(on_payment_request=pay)
path = await client.convert(markdown="# Hello from async", download_path="output.pdf")

Automating payments

If you want to automate payments, you can use a service like fewsats.com or Albyhub for Lightning, or any Solana wallet that holds USDC for X402. These services let you pay programmatically, completely headlessly.

Albyhub
lnbits
Fewsats
Coinbase X402

from markdown2pdf import MarkdownPDF
from dotenv import load_dotenv
from pyalby import Payment

load_dotenv()
# In your .env file, ensure you have set the following. You can learn more about alby at https://albyhub.com.
# BASE_URL = https://api.getalby.com
# ALBY_ACCESS_TOKEN = <your_alby_access_token>
# LOG_LEVEL = INF

def pay(offer):
    print("Paying using Alby:")
    payment = Payment()
    result = payment.bolt11_payment(offer["payment_request"])
    print(f"Payment made: {result}")

client = MarkdownPDF(on_payment_request=pay)
path = client.convert(markdown="# Save this one using Alby", download_path="output.pdf") # Replace with your own unique markdown content to ensure you trigger L402.
print("Saved PDF to:", path)

from markdown2pdf import MarkdownPDF
import requests

LN_BITS_URL = "https://demo.lnbits.com/api/v1/payments"
ADMIN_KEY = "<your_lnbits_admin_key>"  # Replace with your LNbits admin key, see https://lnbits.com

def pay(offer):
    print("Paying using lnbits:")
    headers = {"X-Api-Key": ADMIN_KEY, "Content-Type": "application/json"}
    data = {
        "out": True,
        "bolt11": offer["payment_request"],
    }

    res = requests.post(LN_BITS_URL, json=data, headers=headers)
    res.raise_for_status()
    print("Payment status:", res)

client = MarkdownPDF(on_payment_request=pay)
path = client.convert(markdown="# Save this one using lnbits", download_path="output.pdf") # Replace with your own unique markdown content to ensure you trigger L402.
print("Saved PDF to:", path)

from markdown2pdf import MarkdownPDF
from dotenv import load_dotenv
from fewsats.core import *
load_dotenv()
fs = Fewsats()
# In your .env file, ensure you have set the following. You can learn more about fewsats at https://fewsats.com.
# FEWSATS_API_KEY = <your_fewsats_api_key>

def pay(offer):
    print("Paying using Fewsats:")
    r = fs.pay_lightning(invoice=offer["payment_request"], amount=offer["amount"], currency=offer["currency"], description=offer["description"])
    print(f"Payment made: {r}")

client = MarkdownPDF(on_payment_request=pay)
path = client.convert(markdown="# Save this one using Fewsats", download_path="output.pdf") # Replace with your own unique markdown content to ensure you trigger L402.
print("Saved PDF to:", path)

X402 uses a different flow to L402 — instead of a callback that receives an invoice, the signer constructs a base64 X-PAYMENT header that is attached to the request automatically. The simplest integration is to bypass the L402 on_payment_request path entirely and talk to the REST API with an x402-aware HTTP client:

pip install "x402[httpx,svm]"

import os
import asyncio
from solders.keypair import Keypair
from x402 import x402Client, prefer_network
from x402.http.clients.httpx import x402HttpxClient
from x402.mechanisms.svm import KeypairSigner
from x402.mechanisms.svm.exact import ExactSvmScheme

async def main():
    # 1. Initialize signer from base58 private key
    keypair = Keypair.from_base58_string(os.environ["SOLANA_SIGNER_KEY"])
    signer = KeypairSigner(keypair)

    # 2. Configure x402 client for Solana Mainnet
    NETWORK = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
    x402 = x402Client()
    x402.register(NETWORK, ExactSvmScheme(signer=signer))
    x402.register_policy(prefer_network(NETWORK))

    # 3. The async client handles the 402 → sign → retry loop
    async with x402HttpxClient(x402, timeout=120.0) as client:
        resp = await client.post(
            "https://api.markdown2pdf.ai/markdown",
            json={
                "data": {"text_body": "# Save this one using X402"},
                "options": {"document_name": "output.pdf"},
            },
        )
        resp.raise_for_status()
        print("Paid tx proof:", resp.headers.get("payment-response"))
        print("Poll:", resp.json()["path"])

if __name__ == "__main__":
    asyncio.run(main())

A future release of the SDK will expose a first-class on_x402_payment_required callback so you can pick the rail from a single MarkdownPDF constructor. See the X402 page for details.

Using from your AI Agents

In our Python SDK we provide examples of how to use the markdown2pdf.ai service from your AI agents using the langchain framework.

Welcome, agents!

SDKs

REST API

Python SDK

Getting started

SDK Reference

`class MarkdownPDF`

`constructor`

`convert`

`class AsyncMarkdownPDF`

Automating payments

Using from your AI Agents

​Getting started

​SDK Reference

​class MarkdownPDF

​constructor

​convert

​class AsyncMarkdownPDF

​Automating payments

​Using from your AI Agents

Getting started

SDK Reference

`class MarkdownPDF`

`constructor`

`convert`

`class AsyncMarkdownPDF`

Automating payments

Using from your AI Agents