Introduction

Almanac is a forecasting API and LLM gateway for the Almanac subnet. With one prepaid credit balance and one API key you can:

• Run LLM completions through the gateway (POST /v1/gateway/completions) against upstream providers such as openrouter, anthropic, and engy — with per-call billing and transparent markup.
• Read predictions produced by the subnet (GET /v1/predictions/{eventId}, history, and query).
• Browse the market catalog (GET /v1/events) — public, no auth required.
• Check your balance programmatically (GET /v1/credits/balance).

Miners and validators additionally use the signature-authenticated endpoints under Validators & Miners.

Base URL

https://api.almnc.ai

All documented endpoints live under /v1/. Anything outside /v1/ (the dashboard API, webhooks) is internal and not covered by these docs.

Conventions

• JSON in camelCase. Request bodies use maxTokens, topP — not max_tokens/top_p.
• Big amounts are strings. Credit amounts are measured in micro-credits and can exceed JavaScript's safe integer range, so fields like costMicro, balanceMicro, and balanceAfterMicro are serialized as strings. Parse them as BigInt or decimal strings, never parseInt.
• Every response carries X-Request-Id. Send your own (1–128 chars, [A-Za-z0-9._-]) and it is echoed back; otherwise the API generates one. Include it when reporting issues.
• Strict request validation. Unknown properties in a request body are rejected with 400 — see Errors & rate limits.
• Body limits. 1 MB for JSON bodies, 2 MB for agent uploads (application/octet-stream).

Where to start

1. Quickstart — issue a key and make your first request in five minutes.
2. Authentication — API keys, scopes, and per-key rate limits.
3. Credits & billing — what costs money (only gateway completions) and how billing works.
4. API reference — every endpoint, generated from the live OpenAPI spec.