Data Guide · Acme Corp Costing Portal

Acme Corp is a small company that makes and sells widgets. Every time something money-related happens — a sale, a bill, a refund — a new record shows up in the API. Your job is to build an agent that reads this data and spots when something looks wrong. Everything is served by a small read-only REST API (try it at /docs); this page explains every endpoint and field in plain language, no finance background needed.

Big picture Simulation clock How money is recorded /transactions /skus /vendors /customers Entry types Glossary

The big picture

Four read endpoints matter. One is the live event stream; the other three are reference lists it points at. Each returns JSON.

Endpoint	What it returns	Grows over time?
`GET /transactions`	Every financial event — the heart of the data	Yes, constantly
`GET /skus`	The catalog of products Acme makes/sells	No, fixed list
`GET /vendors`	Companies Acme buys from (suppliers)	No, fixed list
`GET /customers`	Companies Acme sells to	No, fixed list

Each transaction can reference a product (sku_id → /skus), a supplier (vendor_id → /vendors), and/or a buyer (customer_id → /customers) by id — which ones are filled in depends on the kind of event. /transactions also takes query filters (time range, entry_type, sku, amount, …), and pre-computed rollups live under /aggregates/… (revenue, margin, cost-by-category, time series). The full, exact contract is at /docs.

The simulation clock — time is "game time"

This is the one thing to understand before anything else. Acme runs on its own simulation clock, not the real-world clock on your computer.

Every ts (timestamp) on a transaction is a moment in game time. The game starts at a fixed date (currently 2025-01-01) and the simulator pushes the clock forward as it runs. So "now", from the data's point of view, is whatever the simulation clock currently reads — shown live in the top-right of the dashboard. When you ask for "the last 30 days", that means the last 30 game days, ending at the current game time.

Two consequences worth building around:

The clock can run faster than real life. A speed control on the dashboard lets a single real second represent anything from one second up to a whole day of game time — so months of business can unfold in minutes, or it can run at real-time. Your agent shouldn't assume a fixed real-world pace.
The data is identical for everyone. Because the clock and the random generator both start from fixed values, every candidate sees the exact same history. Great for comparing solutions fairly.

Practical tip: don't compare transaction times to your computer's clock (you'll be a year or more off). Compare them to the current game time — read it from the dashboard, or from GET /health or GET /control (both report sim_clock).

How money is recorded

Two ideas unlock the whole dataset:

1. Money is a single signed number. The amount field is positive when money comes in (a sale, a customer paying a bill) and negative when money goes out (paying a supplier, a refund, rent, taxes). So you never need a separate "is this income or expense" flag — the sign tells you. The direction field just spells this out as inflow or outflow.

2. Product records should add up. For sales and cost-of-goods records, the money equals quantity × price: amount ≈ quantity × unit_price. When that equation is badly broken, or a number is suddenly thousands of times too big or small, something is wrong. That is exactly the kind of thing your agent should catch.

GET /transactions

One JSON object per financial event. This is where almost all your monitoring happens.

Field	Type	Meaning
`id`	integer	Unique id for the record. Higher = more recent.
`ts`	timestamp	When the event happened, in game time (see the simulation clock). Filter by this for "last 24h", "this month", etc. — relative to the current game time, not your real clock.
`entry_type`	string	What kind of event it is — `sale`, `cogs`, `payable`, and so on. Full list below.
`direction`	string	`inflow` (money in) or `outflow` (money out). Matches the sign of `amount`.
`amount`	number	The money, signed: + in, − out. In dollars.
`currency`	string	Always `USD` here.
`quantity`	integer / null	How many units, for product events (sales, cost-of-goods). Null otherwise.
`unit_price`	number / null	Price or cost per single unit. For a sale this is the selling price; for cost-of-goods it's the make cost. Null for non-product events.
`sku_id`	id / null	→ /skus. Which product this event is about, if any.
`vendor_id`	id / null	→ /vendors. Which supplier was paid, if any.
`customer_id`	id / null	→ /customers. Which buyer this involves, if any.
`counterparty`	string / null	The name of the other party as free text (e.g. a customer or vendor name, or "Payroll Run"). Handy for display.
`status`	string	Lifecycle: `posted` (recorded), `pending` (not finalized), `settled` (money actually moved).
`memo`	string / null	A short human description, e.g. "Sale of 60x ASM-200".
`created_at`	timestamp	Real wall-clock time the record was created. This is operational metadata — for the business timeline use `ts` (game time) instead.

GET /skus

The product catalog. "SKU" just means a single distinct product (Stock Keeping Unit). Each sale or cost-of-goods event points at one of these.

Field	Type	Meaning
`id`	integer	Unique product id (what a transaction's `sku_id` points to).
`sku_code`	string	Short product code, e.g. `WID-100`.
`name`	string	Human name, e.g. "Standard Widget".
`category`	string	Product family: Widgets, Gadgets, Components, Assemblies, Accessories.
`unit_cost`	number	What it costs Acme to make one unit.
`list_price`	number	What Acme sells one unit for. (Should be higher than `unit_cost`.)

Tip: list_price − unit_cost is the profit per unit. A sale whose unit_price is wildly different from the SKU's list_price is suspicious.

GET /vendors

Companies Acme buys from — raw materials, parts, utilities, software, rent.

Field	Type	Meaning
`id`	integer	Unique supplier id (what a transaction's `vendor_id` points to).
`name`	string	Supplier name.
`category`	string	What they supply: raw_materials, components, freight, utilities, software, packaging, facilities, rent.

GET /customers

Companies Acme sells to.

Field	Type	Meaning
`id`	integer	Unique buyer id (what a transaction's `customer_id` points to).
`name`	string	Customer name.
`segment`	string	Type of buyer: retail, wholesale, or enterprise.

The entry_type values

Every transaction is one of these. The colored label shows whether money flows in or out.

sale ▲ inflow

Acme sold products to a customer. Has a sku_id, quantity, and unit_price.

receivable_payment ▲ inflow

A customer paid an invoice they owed. Money actually arriving.

cogs ▼ outflow

"Cost of goods sold" — what it cost Acme to make the products it sold. Has a sku_id and quantity.

payable ▼ outflow

Paying a supplier (vendor) for materials or services.

operating_expense ▼ outflow

Day-to-day running costs: cloud hosting, utilities, marketing, supplies, insurance.

payroll ▼ outflow

Paying staff wages.

rent ▼ outflow

Monthly cost of the facility. Tends to be a steady, repeating amount.

tax ▼ outflow

Money paid to the government.

refund ▼ outflow

Money returned to a customer (e.g. they sent back a product).

chargeback ▼ outflow

A payment was disputed and clawed back by the customer's bank.

Mini glossary

Inflow / Outflow	Money coming in vs. going out.
Revenue	Total money from sales (the `sale` records).
COGS	Cost of Goods Sold — the direct cost of making what you sold.
Gross margin	Revenue minus COGS — roughly the profit before running costs. Usually a healthy positive percentage of revenue.
Operating expense (opex)	The cost of running the business beyond making the product.
Payable	Money Acme owes a supplier (an outgoing bill).
Receivable	Money a customer owes Acme; `receivable_payment` is when they actually pay.
Chargeback	A reversed payment forced by the customer's bank after a dispute.
Net cash	Everything added up — all inflows minus all outflows.

Where to go next. Browse the data live on the dashboard, then explore the read-only REST API — that's the surface your agent monitors. Decide what "normal" looks like, and build an agent that notices when it isn't.