API automation guide

What this covers

A House Divided exposes a read API (world state, markets, elections, politicians) and a narrow set of write endpoints for money movement, so players can build Discord bots, trading dashboards, and portfolio trackers on top of the live simulation. This page covers what scoped keys are allowed to do and how to handle them safely. For the full endpoint reference (routes, parameters, response shapes, and example requests), see the complete API documentation.

What you can read

Public-scope keys can read the live game clock, countries and regions, national metrics and budgets, governments, elections, legislation, referendums, international organizations, trade restrictions and flows, sovereign risk, historical economic and fiscal series, conflicts, corporations, stocks, bonds, commodities, funds, and forex.

Start with /api/public/v1/meta for the machine-readable route catalog. The catalog is tested against the route tree, so it cannot silently omit an implemented v1 endpoint. OpenAPI clients can load the complete contract from /api/public/v1/openapi.json.

What API keys can do

View endpoints accept any personal API key (public or private scope) sent in the X-API-Key header. Write endpoints require a private scope key. To check which scope a key has and what it is allowed to do, call GET /api/v1/key with the key: it reports the key's scope, allowed operations, and usage metadata, and never returns the secret itself.

Rate limits

Read endpoints are limited per key, per endpoint, in a one-minute window. The base allowance is 60 requests per minute. Supporter+ keys get 1.5x that (90/min) and Supporter++ keys 3x (180/min), applied automatically to every key the account owns for as long as the pledge is active. Write endpoints keep their own limits: 20/min for transfers and 30/min for forex.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, so read your live allowance from the headers rather than hardcoding it. Over the limit you get HTTP 429 with a Retry-After header. /api/public/v1/meta lists the current allowance for each tier.

Security checklist

• Store keys in environment variables, never in public repos.
• Use one key per app or bot for easier revocation.
• Revoke keys immediately if leaked or shared accidentally.
• Treat full-access keys like your account password.

Getting started

1. Create a key from Settings → API Keys.
2. Copy it once and save it in your bot/app secret store.
3. For all API endpoints, send your key in the X-API-Key header.

Return to Settings.