Your ledger, programmable.

In the app, open Settings → API & MCP and make a token. A read token can look at everything; a write token (editors and owners only) can also change things. The token is shown once, and it belongs to one ledger.

export LUMALEDGER_TOKEN="ll_…"
curl "https://api.lumaledger.app/v1/accounts" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

curl -X POST "https://api.lumaledger.app/v1/transactions" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-09-01",
    "description": "Farmers market",
    "lines": [
      {"account_id": 5010, "direction": "debit",  "amount": "24.00"},
      {"account_id": 1090, "direction": "credit", "amount": "24.00"}
    ]
  }'

Money is never a float. Every amount is {"amount": "1234.50", "currency": "USD"}, a decimal string with its currency, and amounts you send are decimal strings too. The schema has no JSON numbers at all.

Lists are pages. Every list answers {"data": [...], "has_more": true, "next_cursor": "…"}. Pass cursor to get the next page and limit (1–200) to size it.

Errors have a stable code. Every error is {"error": {"type", "code", "message", "param", "request_id"}}. Branch on code; message follows your Accept-Language and is for people. Quote request_id (also the X-Request-Id header) when you contact us.

Writes happen once. Send an Idempotency-Key with every create: a retry with the same key gets the first answer back (with Idempotent-Replayed: true) instead of a second entry. Keys last 24 hours.

Rate limits. 120 requests a minute per token. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; over the limit is a 429 with Retry-After.

Versioning. The version is the URL. /v1 only ever grows: new fields, operations and error codes, never a renamed or removed one, so ignore fields you do not know.

Instead of polling every list, follow the ledger's changes: transaction.created, transaction.updated, transaction.deleted, account.balance_updated, budget.exceeded, import.completed and job.completed. A change carries ids, not records (fetch the transaction for its current state), and it is written in the same transaction as what it describes, so it exists exactly when that happened.

Poll the feed. GET /v1/changes lists the last 30 days, oldest first. Keep the next_cursor it answers with, even on the last page, and pass it as cursor next time: you get exactly what happened since, in order, never twice.

curl "https://api.lumaledger.app/v1/changes?cursor=$CURSOR" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

Or have them pushed. Register an https endpoint with the change types it wants (* for all). The answer carries its signing secret, whsec_…, shown once.

curl -X POST "https://api.lumaledger.app/v1/webhook-endpoints" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/lumaledger",
       "change_types": ["transaction.created", "import.completed"]}'

Each change is POSTed to it as JSON, the same object the feed serves, with a signature. Answer with any 2xx within 10 seconds. Redirects are not followed. The URL must reach the public internet: hosts that resolve to private, loopback or link-local addresses are refused, when you save the endpoint and again before every delivery.

POST /hooks/lumaledger HTTP/1.1
Content-Type: application/json
LumaLedger-Signature: t=1790000000,v1=5f2b9c…
LumaLedger-Change-Id: 4812
LumaLedger-Change-Type: transaction.created

{"id":4812,"type":"transaction.created","created_at":"2026-09-24T12:00:03+00:00",
 "data":{"transaction_id":90211}}

Verify every delivery. v1 is the hex HMAC-SHA256 of <t>.<raw body> under your secret. Compare it in constant time, and refuse a t more than five minutes from your clock, so a captured delivery cannot be replayed. For a day after webhook_endpoints.rotate_secret the header carries two v1 values, one per secret; accept either.

import hashlib, hmac, time

def verify(raw: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    """raw: the request body exactly as received, before parsing it."""
    fields = [part.split("=", 1) for part in header.split(",")]
    t = next((v for k, v in fields if k == "t"), "")
    signatures = [v for k, v in fields if k == "v1"]
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False  # too old: a replay
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, s) for s in signatures)

import crypto from "node:crypto";

// raw: the request body exactly as received (a Buffer), before parsing it.
export function verify(raw, header, secret, toleranceSeconds = 300) {
  const fields = header.split(",").map((part) => part.split("="));
  const t = Number(fields.find(([k]) => k === "t")?.[1]);
  const signatures = fields.filter(([k]) => k === "v1").map(([, v]) => v);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.`).update(raw).digest("hex");
  return signatures.some((s) => s.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
}

Retries. A delivery that is not accepted is tried again after a minute, then three times longer each time, up to 12 hours apart: twelve tries over about three days. Delivery is at least once, so dedupe on the change id (also in LumaLedger-Change-Id). An endpoint that accepts nothing for three days is disabled and the ledger's owners get an email; turn it back on with webhook_endpoints.update, and catch up on what it missed from the feed.

@lumaledger/sdk is generated from the same schema as this reference, so every operation is a typed method named after it: transactions.list is client.transactions.list(). It has no dependencies beyond fetch, and runs on Node 20+ and in browsers.

import { LumaLedger, Money } from "@lumaledger/sdk";

const client = new LumaLedger({ token: process.env.LUMALEDGER_TOKEN });

// Every transaction since September, page after page
for await (const txn of client.transactions.listAll({ since: "2026-09-01" })) {
  console.log(txn.date, txn.description, Money.format(txn.amount, "en-US"));
}

// Safe to retry: creates carry an Idempotency-Key automatically
await client.transactions.create({
  date: "2026-09-01",
  description: "Farmers market",
  lines: [
    { account_id: 5010, direction: "debit", amount: "24.00" },
    { account_id: 1090, direction: "credit", amount: "24.00" },
  ],
});

It retries rate limits (honoring Retry-After) and server errors wherever a retry cannot do the work twice, throws typed errors carrying code, param and request_id, and does money math on exact decimals with Money, never floats. It is not on npm yet; until it is, call the API directly as in the quickstart.

LumaLedger is an MCP server. Every operation in the reference below is also a tool (transactions.list is transactions_list), next to the assistant's own read tools. A read token shows an agent the read tools only, and a write token adds the writes, each marked read-only, idempotent or destructive so your client can ask before it acts.

claude mcp add --transport http lumaledger https://api.lumaledger.app/api/mcp \
  --header "Authorization: Bearer $LUMALEDGER_TOKEN"

In Claude Desktop and other clients, add a custom connector with the URL https://api.lumaledger.app/api/mcp and the header Authorization: Bearer ll_….

Coming soon: sign in instead of pasting a token. The server speaks the MCP authorization spec (OAuth 2.1 with PKCE), so a client that supports it will only need the URL: it opens a sign-in window, you pick the ledger it may read, and it never sees a token you could leak. Apps connected this way read one ledger and cannot change anything, and you can disconnect them in Settings. It is switched on once our authorization server leaves beta; until then, use a token.

Generated from the API's own schema, so it is never out of date. The same schema is at openapi.json for SDK generators, and the whole reference as plain text is at llms.txt for language models.