Markets API

The catalogue service (packages/markets-api) owns the markets table in PostgreSQL, serves it over REST, and hosts the create-market CLI.

Base URL: CLOB_MARKETS_API_URL, default http://localhost:8081.

Why it exists

The markets program has no on-chain token registry. Nothing on Solana maps a token id to a market and an outcome mint. This service is that map, and it is the single source of truth for:

The order manager (CLOB_MARKETS_BACKEND=api) — which books to create, and their tick sizes.
The on-chain risk adapter — resolving asset mints to check ATA balances and delegate allowances.
The executor — resolving (market_id, outcome_mint) for every settlement it builds.

If this service is wrong, settlements are built against the wrong mint. It is the most safety-critical piece of off-chain configuration in the system.

Routes

Method	Path	Auth
`GET`	`/markets`	none
`GET`	`/markets/{condition_id}`	none
`GET`	`/health`	none
`POST`	`/markets`	internal token
`PATCH`	`/markets/{condition_id}`	internal token

curl -s http://localhost:8081/markets | jq
curl -s http://localhost:8081/markets/0xdemo-condition | jq
curl -s http://localhost:8081/health

Reads are open — the catalogue is public information. Writes are gated by a shared internal token.

Market record

A catalogue entry ties together the three identifier spaces:

Concept	Field	Used by
On-chain market	`market_id` (`u64`)	The Market PDA seed
Catalogue key	`condition_id`	Order manager books, API paths
Tradable side	`token_id` per outcome	Orders, book queries
Outcome mint	Per token id	The executor, building settlements
Tick size	—	Price-grid validation
Status / readiness	—	Whether orders are accepted
Game start	—	The pre-start ejection listener

The order manager’s TokenRegistry adapter resolves token ids to mints through this service, TTL-cached with last-known-good on failure — a catalogue outage degrades to stale data rather than halting matching.

Creating a market

The create-market CLI is the same binary in a different mode. It does two things in one operation:

Sends markets::create_market on-chain — creating the Market PDA, both outcome mint PDAs and the collateral vault.
Inserts the corresponding catalogue row.

Doing both in one place is what keeps the on-chain state and the catalogue from diverging. Creating a market by sending the instruction directly leaves the catalogue blind to it, and no book will ever be created.

Migrations are applied at startup via sqlx.

Catalogue refresh

The order manager pulls the catalogue every CLOB_MARKET_UPDATES_INTERVAL_MS (default 10s) on its market-updates thread and reconciles:

Change	Effect
New market	A book is created
Updated market	Book metadata refreshed
Removed market	The book is deleted

So a market becomes tradable within one refresh interval of appearing here, and untradable within one of disappearing.

Relationship to the Platform API

Two different catalogues, for two different jobs:

	Markets API	Platform API
Owns	The `markets` table used by the CLOB	Product data: questions, images, categories, events
Consumers	Order manager, executor, risk adapter	The webapp
Keyed by	`condition_id`	`market_id`
Written by	`create-market` CLI	Admin endpoints + Helius indexing

The Platform API is where you get “what is this market about”; the Markets API is where you get “which mint do I settle against.”

# Product-shaped
curl -s https://prod-api.gomarket.io/api/markets/
curl -s https://prod-api.gomarket.io/api/markets/trending/
curl -s https://prod-api.gomarket.io/api/markets/events/
curl -s https://prod-api.gomarket.io/api/markets/{market_id}/price-history/
curl -s https://prod-api.gomarket.io/api/markets/search/?q=fed