The ledgers' API

Your key

On the account site, Account > API keys, choose the character and Make a key. A key is made for a character who leads a faction (its master) or owns a business. It reads:

• while that character is the faction's master: its coffers ledger and their days, each member's contributions, the members' activity, the storage logs, its territory and Authority, its diplomacy, its members' trade packs and supply orders;
• for each business that character owns (and each business of the faction while they are its master): its ledger, its stock and its sales.

It never shows where anyone or anything is: no member's position or online status, no trade pack's place. The key is shown once: copy it then and keep it like a password - anyone holding it reads all of that. An account holds three keys at most. Revoke a key the moment you think it leaked: it stops at once. The rights are checked again at every call: a master who steps down or leaves, or a business sold, and the key reads nothing more of it.

Plans

A plan counts for 30 days from the payment; buying the same plan again adds 30 days after the days you have left (another plan starts at once, and the days left on the old one are not carried over). Renew automatically is off until you turn it on: then the KCD Points are taken again when the 30 days end, and if you are short of them the key goes back to the free 100 a day and the renewal turns off. The day's count starts again at 00:00 UTC. The free 100 calls are the account's: all its free keys share them (a paid key has its own). Whatever the plan, an account makes 60 calls a minute at most, one at a time (wait for an answer before the next call), and at most five keys a day.

Calling the API

Every call is a GET to https://account.kcdroleplay.com/api/ucp/v1/..., with the key in the header (never in the address - addresses end up in logs):

curl -H "Authorization: Bearer krp_your_key_here" https://account.kcdroleplay.com/api/ucp/v1/me

The answers are JSON. Times are UTC (ISO 8601), money is in groschen.

Pages of rows

The ledgers come 100 rows at a time at most (limit=1..100), by the row's id:

• Newest first (no cursor, or before=<id>): to read back through the history. When more is true, ask again with before= the next value.
• Only what is new (after=<id>): oldest first, from that row on. Keep the highest id you have and ask with it every few minutes - the cheapest way to stay up to date.

Filters: on /faction/ledger, dir=in|out and a period from=YYYY-MM-DD, to=YYYY-MM-DD (UTC days, both included); on /business/ledger, kind=stock|withdraw|price|sale. The same call made again within 30 seconds is answered from memory.

{
  "faction": { "id": 12, "name": "House of Ostrov" },
  "order": "newest first",
  "more": true,
  "next": 48210,
  "rows": [
    { "id": 48311, "at": "2026-10-25T09:14:02Z", "amount": -250, "note": "wages", "member": "Jan Novak" }
  ]
}

A small Python loop that keeps a copy up to date:

import os, time, requests
KEY = os.environ["KRP_API_KEY"]
URL = "https://account.kcdroleplay.com/api/ucp/v1/faction/ledger"
last = 0
while True:
    r = requests.get(URL, params={"after": last} if last else {"limit": 100},
                     headers={"Authorization": "Bearer " + KEY}, timeout=20)
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", 60))); continue
    r.raise_for_status()
    rows = r.json()["rows"]
    for row in rows: print(row)
    if rows: last = max(row["id"] for row in rows)
    time.sleep(300)   # every five minutes: 288 calls a day

The routes in detail

Every route below is a GET under https://account.kcdroleplay.com/api/ucp/v1. A period is from=YYYY-MM-DD and to=YYYY-MM-DD (UTC days, both included) or days=N (the last N days); 30 days when none is given, 366 at most. Pages means the limit, before and after above, and an answer with order, more, next and rows.

A business's ledger, stock and sales are its present owner's: a business bought from someone else starts a new ledger for its new owner. Item names are the game's own keys (beer, bandage_classic...).

Errors