Python SDK

The official Python SDK gives you typed resources, synchronous and asynchronous clients, automatic retries and webhook helpers. The current release is 4.1.0.

Requirements and installation

The SDK supports Python 3.9 and newer.

pip install ledgerline
# or
uv add ledgerline

The package ships type hints and a py.typed marker, so mypy and pyright work without extra stubs.

Create a client

import os
import ledgerline

client = ledgerline.Client(
    api_key=os.environ["LEDGERLINE_API_KEY"],
    api_version="2026-09-01",
    max_retries=2,
    timeout=30,
)

When api_key is omitted, the client reads LEDGERLINE_API_KEY. A ll_test_ key uses the sandbox and a ll_live_ key uses production.

Make requests

Resources use snake_case, the same as the REST API. Amounts are integers in minor units.

payout = client.payouts.create(
    source_account_id="acc_01J9QK5M2A",
    counterparty_bank_account_id="cba_01JA6C8W4N",
    amount=1_250_000,
    currency="USD",
    rail="ach",
    idempotency_key=f"payout:{invoice.id}",
)
print(payout.status)  # "scheduled"

Async client

import asyncio
import ledgerline

async def main() -> None:
    async with ledgerline.AsyncClient() as client:
        balances = await client.accounts.balances("acc_01J9QK5N7C")
        print(balances.available)

asyncio.run(main())

The async client uses httpx.AsyncClient, exposes the same methods and honors the same retry and timeout settings.

Idempotency

Every method that creates or changes something accepts idempotency_key. If you leave it out, the SDK generates one and reuses it across its own retries. Provide your own when your code may retry the whole operation. See Idempotency keys.

Pagination

List calls return a page object. auto_paging_iter() walks every page, requesting 100 items at a time.

for payout in client.payouts.list(status="paid").auto_paging_iter():
    print(payout.id, payout.amount)

page = client.payouts.list(limit=25)
if page.has_more:
    next_page = client.payouts.list(limit=25, cursor=page.next_cursor)

Errors

All errors inherit from ledgerline.LedgerlineError and expose code, message, param and request_id. Branch on the code. The list is in Error format and codes.

from ledgerline import LedgerlineError, RateLimitError

try:
    client.transactions.create(**params)
except RateLimitError as error:
    time.sleep(error.retry_after_seconds)
except LedgerlineError as error:
    logger.error("ledgerline failed", extra={"code": error.code, "request_id": error.request_id})
    raise

Verify webhooks

from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/hooks/ledgerline")
def hook():
    try:
        event = client.webhooks.construct_event(
            request.get_data(),
            request.headers.get("Ledgerline-Signature", ""),
            os.environ["LEDGERLINE_WEBHOOK_SECRET"],
        )
    except ledgerline.SignatureVerificationError:
        abort(400)
    queue.enqueue(event)
    return "", 200

request.get_data() returns the raw body, which is what the signature covers. See Verifying webhook signatures.

Rate limits

After each call, client.last_response.rate_limit holds limit, remaining and reset_at. The default limit is 600 requests per minute per key. See Rate limits.

Logging

Set LEDGERLINE_LOG=debug to log request lines, status codes and request ids. Authorization headers and request bodies are never logged.

Versioning

The SDK follows semantic versioning, and a new API version changes nothing until you set api_version. The Node equivalent is the Node.js SDK. Release notes are in the changelog.