> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signalium.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> REST API for the web app and judge worker. Bun + Hono. Source of truth for market reads, X-post evaluation, positions, and the cached 0G/USD price.

Base URL — production: `https://api.signalium.site` · local: `http://localhost:3001`

All responses are JSON. CORS is permissive (`*`) so the deployed web app can hit the same origin you're testing against.

<Card title="Interactive API reference" icon="play" href="https://api.signalium.site/docs">
  Try every endpoint live with request/response examples, schemas, and a
  copy-paste curl builder. Powered by [Scalar](https://scalar.com) over the
  [OpenAPI 3.1 spec](https://api.signalium.site/openapi.json) the API
  serves at `/openapi.json`.
</Card>

## Endpoint groups

| Group                                | Purpose                                                                           |
| ------------------------------------ | --------------------------------------------------------------------------------- |
| [`/markets`](/api-reference/markets) | List, paginate, fetch detail, holders, trades                                     |
| [`/posts`](/api-reference/posts)     | Evaluate an X URL — runs gatekeeper + writer in 0G Compute TEE                    |
| [`/users`](/api-reference/users)     | A wallet's positions and trade history                                            |
| [`/price`](/api-reference/price)     | Cached 0G/USD price + the live Gimo APY derived from a rolling rate sample window |
| [`/health`](/api-reference/health)   | Liveness + subgraph indexer lag                                                   |

## Caching strategy

The API keeps a small SQLite (`apps/api/data/signalium.db`) for three hot paths:

* **X post metadata** — fetched once via RapidAPI's `twitter241`, then served from disk.
* **AI proposals** — written when `/posts/evaluate` returns an eligible draft, keyed by the `judgeStorageRoot` merkle root that ends up on-chain.
* **0G/USD price** — refreshed at most every 6 hours; serves stale on upstream failure.

The same SQLite is what lets `/markets/:address` return the rich `description`, `resolutionCriteria`, and `proposalDetails` block that the on-chain market doesn't carry.