API Reference

HTTP endpoints for Loaf Backend. Base URL: https://api.loafmarkets.com. Authenticated routes use Authorization: Bearer <API_KEY> from the Loaf web app API settings.

Headlines are a separate public service. REST seed is https://news.loafmarkets.com/v1/headlines (no API key). See News.

For a Python SDK and bot template, see loaf-python-api-bot-template .

Money & units

Prices and cash amounts are plain dollars; quantities are plain tokens:

• Prices: up to 2 decimal places (cents).
• Quantities: up to 1 decimal place.
• Fields ending in Bps are raw basis points (30 = 0.30%).
• Fields ending in Percent / Percentage are already percentages (5.2 = 5.2%).

Rate limits

The backend allows about 100 requests per 15 minutes per IP by default and returns standard RateLimit-* headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset). Sensitive endpoints (orders, offering subscriptions, competition queue/payout) are additionally rate limited per account, so rotating IPs does not raise that ceiling.

Retry guidance:

• Idempotent reads (GET, and nonce-free reads): safe to retry with backoff that respects RateLimit-Reset / Retry-After.
• Order placement and other non-idempotent writes: do not blindly retry. A rate-limited or ambiguous POST /api/orders/ should be re-issued only after you confirm the prior attempt did not leave an open order / frozen balance, and only with a fresh nonce.

The Python SDK  auto-retries transient failures on read requests and raises on rate-limited order calls so you can refresh the nonce.

Caching

Some public GET routes emit Cache-Control: public, max-age=0, s-maxage=N for shared edge caches (for example competition overview and leaderboard). Authenticated share-card routes (queue, leaderboard, PnL cards) force Cache-Control: private, no-store, including on auth-failure responses.

Ask once vs listen

There are two ways to get data. Use the right one for each feed:

• Ask once (REST) — like taking a photo. You get the full picture as it is right now. Good for the starting point and for history.
• Listen (WebSocket) — like a live news feed. It only tells you what just changed (or, for some channels, a continuous full picture).

Some live feeds only send changes, not the starting picture. If you only listen, you sit with nothing until something moves. For those feeds, call REST once to load current state, then subscribe to WebSocket for updates. Channels that already push a full picture (order book, recent trades, leaderboard) do not need that seed — switch to WebSocket and do not poll REST in a loop.

See WebSocket for which channels are full-picture vs deltas. For tradeable markets, start with Trade. For headlines, start with News.