API Documentation

Use the A House Divided API to build tools that read game data or automate fund transfers and forex trades. Generate keys in Settings → API Keys.

Usage & Anti-Abuse Guidelines

Rate limits are enforced. Exceeding them returns a 429 response with a Retry-After header. Back off and retry.
Cache responses when possible. Game state turns over every few minutes; polling faster than once per minute is unnecessary and may hit rate limits.
Do not create multiple keys to circumvent limits. All requests under your account count toward the same quota regardless of which key you use.
Private keys are secrets. Never commit them to source control, embed them in client-side code, or share them publicly. If a key is compromised, revoke it immediately in Settings.
Automated fund transfers must respect in-game rules. Cooldowns, minimums, same-country restrictions, and admin pauses apply identically to API requests. Attempting to bypass them will result in revocation of API access.
Abuse results in revocation. Repeated rate-limit violations, key sharing, or attempts to circumvent in-game restrictions will result in key revocation and possibly account-level API restrictions.

Authentication

All API requests require authentication. Include your key in the appropriate header:

Personal API Keys

Pass in the X-API-Key header. Tied to your user account.

Public— Read-only access to all public endpoints. Cannot send funds or trade forex.
Private— All public endpoints + send campaign funds and trade forex. Treat like a password.

# Public key (read-only) curl -H "X-API-Key: ahd_pub_..." \ https://ahousedividedgame.com/api/public/v1/game # Private key (read + send) curl -X POST -H "X-API-Key: ahd_priv_..." \ -H "Content-Type: application/json" \ -d '{"targetCharacterId":"...","amount":5000}' \ https://ahousedividedgame.com/api/v1/transfer

Key Prefixes

API keys have identifying prefixes so you can tell the type at a glance:

Param	Type	Description
ahd_pub_	string	Personal read-only key
ahd_priv_	string	Personal read + send funds/forex key

You can have up to 3 active keys per scope type. Token values are shown only once at creation.

Rate Limits

Param	Type	Description
Public read	60 req/min	Per key
Fund transfers	20 req/min	Per key
Forex trades	30 req/min	Per key
Key management	10 req/min	Create/revoke

Rate-limited responses include a Retry-After header (in seconds).

Public Read Endpoints

Accessible with any personal API key via the X-API-Key header.

GET /api/public/v1/game

Current game state and turn timing.

Field	Type	Description
ok	boolean	Always true on success
found	boolean	Whether game data was found
currentTurn	number	Current turn number
gameDate	string	In-game date (YYYY-MM-DD)
nextTurnAt	string\|null	ISO 8601 timestamp of next turn
turnDurationMs	number	Turn duration in milliseconds

GET /api/public/v1/character

Search characters. Requires name or discordId query param.

Param	Type	Description
name	string	Character name (partial match)
discordId	string	Discord user ID

Response shape:

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether matches were found
characters	array	List of matching characters
characters[].id	string	Character ObjectId
characters[].name	string	Display name
characters[].bio	string\|null	Character biography
characters[].countryId	string\|null	Home country code
characters[].party	string	Party name
characters[].partyId	string\|null	Party ObjectId
characters[].partyColor	string	Hex color
characters[].state	string	Home state name
characters[].stateCode	string	Home state code
characters[].position	string	Current office/position
characters[].politicalInfluence	number	PI score
characters[].nationalInfluence	number	NPI score
characters[].favorability	number	Favorability rating
characters[].campaignFunds	number	Campaign treasury
characters[].netWorth	number	Total net worth
characters[].isCeo	boolean	Whether CEO of a corporation
characters[].profileUrl	string	Relative profile URL
characters[].activeElection	object\|null	Current election info if running

GET /api/public/v1/character/[id]

Full character details by ObjectId.

Same field shape as the characters array entry above, with additional detail fields.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether the character exists
character	object	Full character object (same shape as characters[] above)

GET /api/public/v1/character/[id]/career

Character career history.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether the character exists
characterId	string	Character ObjectId
characterName	string	Character display name
career	array	Career entries
career[].type	string	Entry type (election, appointment, etc.)
career[].office	string\|null	Office held
career[].party	string\|null	Party at time
career[].fromState	string\|null	Start turn/term
career[].toState	string\|null	End turn/term

GET /api/public/v1/character/[id]/achievements

Achievements earned by a character.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether the character exists
characterId	string	Character ObjectId
characterName	string	Display name
achievements	array	Achievement list
achievements[].id	string	Achievement ID
achievements[].name	string\|null	Display name
achievements[].description	string\|null	Description text
achievements[].icon	string\|null	Emoji/icon
achievements[].category	string\|null	Category
achievements[].isHidden	boolean	Whether hidden from others
achievements[].earnedAt	string\|null	ISO 8601 timestamp

GET /api/public/v1/party?id=ID&country=CODE

Party details. Both id and country params required.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether the party exists
party.id	string	Party ObjectId
party.name	string	Party name
party.abbreviation	string\|null	Short name
party.color	string	Hex color
party.economicPosition	number	Economic axis position
party.socialPosition	number	Social axis position
party.memberCount	number	Active member count
party.seatCount	number	Legislative seats held
party.treasury	number	Party treasury balance
party.chairName	string\|null	Party chair name
party.topMembers	array	Top 5 members by influence

GET /api/public/v1/country

List all countries.

Field	Type	Description
ok	boolean	Always true
countries	array	Array of { id, name, governmentType }

GET /api/public/v1/country/[code]

Country details by code (e.g. US, GB).

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether the country exists
countryId	string	Country code
name	string	Country name
governmentType	string	Regime type (e.g. presidential, parliamentary)
population	number\|null	Population count
currentLeader	object\|null	{ name, party, profileUrl } or null
legislatureComposition	array	Seat breakdown by party
legislatureComposition[].partyName	string	Party name
legislatureComposition[].seats	number	Seats held
legislatureComposition[].seatPct	number	Percentage of total
lastElectionCycle	number\|null	Last election cycle number

GET /api/public/v1/country/[code]/legislature

Legislature details for a country.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether found
countryId	string	Country code
chamber	string	Chamber name
totalSeats	number	Total legislative seats
composition	array	Party seat breakdown
pendingBills	array	Bills awaiting vote
pendingBills[].id	string	Bill ObjectId
pendingBills[].title	string	Bill title
pendingBills[].status	string	Bill status
recentlyPassed	array	Recently passed bills
recentlyPassed[].vote	object	{ yes, no } vote tally

GET /api/public/v1/country/[code]/economy

Economic indicators for a country.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether found
countryId	string	Country code
primeRate	number\|null	Current central bank rate
inflation	number\|null	Current inflation rate
gdpGrowth	number\|null	GDP growth rate
chair	object\|null	{ name, profileUrl } central bank chair
rateHistory	array	[{ turn, rate }] historical rates
stockMarket	object	Stock market summary
stockMarket.totalMarketCap	number	Total market cap
stockMarket.change24h	number	24h change percentage

GET /api/public/v1/government?country=CODE

Government overview. Requires country query param.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether found
country	string	Country code
officials	array	Government officials
officials[].role	string	Position title
officials[].characterName	string\|null	Office holder name
officials[].party	string\|null	Party affiliation
officials[].section	string	"executive" or "leadership"
cabinet	array	Cabinet members
governmentFormation	object	Varies by regime type

GET /api/public/v1/elections?country=CODE

Active elections. Requires country param; optional state.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether elections found
elections	array	List of elections
elections[].id	string	Election ObjectId
elections[].electionType	string	Type (primary, general, etc.)
elections[].state	string	State code
elections[].status	string	Status (open, closed, etc.)
elections[].candidates	array	Candidate list
elections[].candidates[].characterName	string	Candidate name
elections[].candidates[].party	string	Party name
elections[].candidates[].isNPP	boolean	Non-party member

GET /api/public/v1/elections/[id]

Detailed election info including candidates, votes, and phases.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether found
election	object	Full election data
election.id	string	Election ObjectId
election.electionType	string	Type
election.status	string	Current status
election.totalSeats	number	Seats contested
phase	object	{ inPrimary, inGeneral, isUpcoming, isEnded }
incumbent	object\|null	{ name, party } or null
candidates	array	Full candidate list with details
votes	object\|null	Vote tallies and snapshots

GET /api/public/v1/news?limit=N&category=CAT

News feed. Optional limit and category params.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether posts found
posts	array	News posts
posts[].id	string	Post ObjectId
posts[].title	string\|null	Headline
posts[].content	string\|null	Body text
posts[].authorName	string\|null	Author
posts[].isSystem	boolean	System-generated post
posts[].category	string\|null	Category tag
posts[].countryId	string\|null	Related country
posts[].createdAt	string\|null	ISO 8601 timestamp

GET /api/public/v1/legislation?country=CODE&status=pending|passed|failed&limit=N

Bills and votes. Optional filters.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether bills found
bills	array	Legislation list
bills[].id	string	Bill ObjectId
bills[].title	string	Bill title
bills[].sponsor	string\|null	Sponsor name
bills[].status	string	pending, passed, or failed
bills[].vote	object	{ yes, no, abstain }
bills[].effects	array	[{ metric, direction }]

GET /api/public/v1/market?type=SECTOR&country=CODE&page=N

Stock market data. type param required. Pass view=share for shares, view=unowned for unowned sectors.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether data found
mode	string	"share" or "unowned"
sectorType	string	Requested sector type
page	number	Current page
totalPages	number	Total pages
companies\|sectors	array	Results (depends on mode)

GET /api/public/v1/bonds?corp=NAME&page=N

Bond market data. Optional corp and page params.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether bonds found
bonds	array	Bond list
bonds[].id	string	Bond ObjectId
bonds[].couponRate	number	Coupon rate (e.g. 0.05 = 5%)
bonds[].maturityLabel	string\|null	Maturity description
bonds[].totalIssued	number	Total bonds issued
bonds[].marketPrice	number	Current market price
bonds[].yieldToMaturity	number\|null	YTM
bonds[].defaulted	boolean	Whether bond is in default
pagination	object	{ page, perPage, totalCount, totalPages }

GET /api/public/v1/corporations

List all corporations.

Field	Type	Description
ok	boolean	Always true
corporations	array	List of { id, name, sequentialId, type, countryId }

GET /api/public/v1/corporation?name=X&id=N

Corporation details. Requires name or id. Note: id is the corporation's sequentialId (e.g. 112), not the Mongo ObjectId.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether found
id	string	Corporation ObjectId
name	string	Corporation name
type	string	Corporation type
typeLabel	string	Human-readable type
ceo	object\|null	{ name, profileUrl }
financials	object	Revenue, income, costs, dividends
balanceSheet	object	{ cashOnHand, marketCapitalization, totalDebt }
shareStructure	object	Shares, price, float, shareholders
creditRating	object	Rating, score, components
bonds	array	Corporate bonds
sectors	array	Operational sectors

GET /api/public/v1/leaderboard?country=CODE&metric=METRIC&limit=N

Player rankings. Metrics: npi, pi, favorability, funds, actions.

Field	Type	Description
ok	boolean	Always true
found	boolean	Whether found
metric	string	Requested metric
characters	array	Ranked characters
characters[].rank	number	Position
characters[].name	string	Character name
characters[].party	string	Party name
characters[].funds	number	Campaign funds
characters[].politicalInfluence	number	PI score
characters[].profileUrl	string	Profile link

Private Endpoints (Send Funds & Forex)

Require a private personal API key. All in-game restrictions apply identically to API requests.

POST /api/v1/transfer

Send campaign funds to another character.

Request body:

Param	Type	Description
targetCharacterId	string	Recipient character ObjectId
amount	number	Amount in your character's home currency (e.g. ¥, £) — the same unit as your in-game balance (min 1000, integer)

Response:

Field	Type	Description
success	boolean	true
amount	number	Amount transferred (home currency)
currency	string	Sender home currency code (e.g. "CNY")
senderRemainingFunds	number	Sender campaign balance after transfer (home currency)
targetName	string	Recipient character name

Restrictions:

Minimum transfer: 1,000 (home currency)
Sender and target must be in the same country
Cannot transfer to yourself
Must have sufficient campaign funds
Transfers may be paused by admins (returns 403)

POST /api/v1/forex/exchange

Execute a forex market order.

Request body:

Param	Type	Description
fromCurrency	string	Source currency code (e.g. "USD")
toCurrency	string	Target currency code (e.g. "GBP")
amount	number	Amount in source currency (must be > 0)

Response:

Field	Type	Description
success	boolean	true
trade.fromCurrency	string	Source currency
trade.toCurrency	string	Target currency
trade.fromAmount	number	Amount deducted
trade.toAmount	number	Amount received
trade.effectiveRate	number	Effective exchange rate
trade.spreadCharged	number	0.275% spread (50% destroyed, 50% to central bank)

Restrictions:

Cannot trade a currency for itself
Forex must be enabled on the server
Must have sufficient funds in source currency
Character must exist and be in an active country

Error Responses

Status	Code	Meaning
401	missing / invalid	No API key, or key not found/revoked
403	insufficient scope	Public key used on a private endpoint
403	Transfers are paused	Admin has temporarily paused fund transfers
403	Currency exchange is not yet enabled	Forex is disabled on this server
429	rate_limited	Too many requests — check Retry-After header

Quick-Start: Scripting & Automation

Generate keys in Settings → API Keys, or use the API directly:

# Create a public key (read-only) curl -X POST https://ahousedividedgame.com/api/settings/user-api-keys \ -H "Content-Type: application/json" \ -b "your-session-cookie" \ -d '{"name":"My Dashboard","scope":"public"}' # Create a private key (read + send) curl -X POST https://ahousedividedgame.com/api/settings/user-api-keys \ -H "Content-Type: application/json" \ -b "your-session-cookie" \ -d '{"name":"Auto Transfer","scope":"private"}' # List your keys curl https://ahousedividedgame.com/api/settings/user-api-keys \ -b "your-session-cookie" # Revoke a key curl -X DELETE https://ahousedividedgame.com/api/settings/user-api-keys \ -H "Content-Type: application/json" \ -b "your-session-cookie" \ -d '{"keyId":"683f..."}'

The full token is only shown once at creation. Store it securely.

Python

import os, requests BASE = "https://ahousedividedgame.com" headers = {"X-API-Key": os.environ["AHD_API_KEY"]} # Read public data (any key) game = requests.get(f"{BASE}/api/public/v1/game", headers=headers).json() print(f"Turn {game['currentTurn']}") # Send funds (requires private key) if "priv" in os.environ["AHD_API_KEY"]: res = requests.post( f"{BASE}/api/v1/transfer", headers={**headers, "Content-Type": "application/json"}, json={"targetCharacterId": "507f1f77bcf86cd799439011", "amount": 5000}, ).json() print(res.get("success") and f"Sent {res['amount']} to {res['targetName']}" or res.get("error"))

Bash (cron-friendly)

export AHD_API_KEY="ahd_pub_your_key_here" # Fetch game state curl -s -H "X-API-Key: $AHD_API_KEY" \ https://ahousedividedgame.com/api/public/v1/game | jq . # Check character count curl -s -H "X-API-Key: $AHD_API_KEY" \ "https://ahousedividedgame.com/api/public/v1/character?name=Smith" | jq '.characters | length'

Quick-Start: Discord Bot

To build a personal automation bot that sends funds or trades forex, use a personal API key with the X-API-Key header:

Go to Settings → API Keys and create a private key (e.g. "Discord Bot")
Copy the key — it's only shown once
In your bot code, use the key in the X-API-Key header
Call the transfer or forex endpoint as shown in the scripting examples above

Node.js / Discord.js

← Back to Settings