API Overview

Vision prediction market REST API reference

Vision API

The API is public. No authentication. No rate limiting. We trust you. This may be a mistake.

Use it to list batches, submit bitmaps, query balances, backtest strategies, and read tick history. Everything the prediction market knows, it will tell you.

Architecture

Vision API routes are split across two proxy targets depending on the type of data:

                            +------------------------------+
                            |   Next.js API Routes         |
                            |   /api/vision/*              |
     +----------+           |                              |
     |          |  HTTPS    |  /batches ----+              |
     | Browser  +---------->+  /leaderboard |              |
     |          |           |  /bitmap -----+-- fan-out    |
     +----------+           |               |              |
                            |               v              |
                            |     +---------+---------+    |
                            |     | Oracle API        |    |
                            |     | (port 10001)      |    |
                            |     | Batch state,      |    |
                            |     | player balances,   |    |
                            |     | bitmap processing  |    |
                            |     +-------------------+    |
                            |                              |
                            |  /snapshot -------+          |
                            |  /snapshot/meta --+          |
                            |                   |          |
                            |                   v          |
                            |     +-------------+-----+    |
                            |     | Data Node         |    |
                            |     | (port 8200)       |    |
                            |     | Market prices,    |    |
                            |     | source health,    |    |
                            |     | asset counts      |    |
                            |     +-------------------+    |
                            +------------------------------+

Bitmap fan-out pattern:

  Browser POSTs bitmap to /api/vision/bitmap (same-origin, no CORS)

                   +-- POST --> Oracle 1 (10001) --> accepted
                   |
  /api/vision/ ----+-- POST --> Oracle 2 (10002) --> accepted
  bitmap           |
                   +-- POST --> Oracle 3 (10003) --> rejected (error)

  Response: { acceptedCount: 2, totalCount: 3, results: [...] }

Base URL

All Vision endpoints are served under:

https://generalmarket.io/api/vision

Requests are proxied to the oracle node running Vision on port 10001, or to the data-node on port 8200 for snapshot data.

Authentication

None. The Vision API is public. Player identity is determined by Ethereum addresses passed as parameters. No keys, no tokens, no gatekeepers. The data belongs to everyone — the losses, unfortunately, are personal.

Endpoints

Method	Path	Description
GET	/vision/batches	List all active batches
GET	/vision/markets	List supported markets
GET	/vision/batch/{id}/state	Full state for a single batch
POST	/vision/bitmap	Submit a prediction bitmap (fan-out to all oracles)
GET	/vision/balance/{batch_id}/{player}	Player balance with BLS proof
GET	/vision/batch/{id}/history	Tick result history for a batch
GET	/vision/reveal/{batch_id}/{tick_id}	Revealed bitmaps after tick closes
POST	/vision/backtest	Backtest a bitmap strategy
GET	/vision/leaderboard	Player rankings by PnL
GET	/vision/snapshot	Market price snapshot for all or one source
GET	/vision/snapshot/meta	Source health, asset counts, sync status

Common Patterns

Wei-Encoded Values

All token amounts (balances, TVL, stake) are returned as string-encoded wei values to avoid floating-point precision loss. For L3 USDC (18 decimals), divide by 1e18 to get the human-readable amount.

balance_wei = "5000000000000000000"
balance_usdc = int(balance_wei) / 1e18  # 5.0 USDC (L3 uses 18 decimals)

L3 USDC uses 18 decimals, not 6. This applies to all Vision balances, TVL, PnL, and batch pool values.

Error Responses

All endpoints return errors in a consistent format:

{
  "error": "Human-readable error message"
}

Common HTTP status codes:

Code	Meaning
200	Success
400	Bad request (invalid parameters, malformed bitmap, etc.)
403	Forbidden (e.g., reveal window not yet expired)
404	Resource not found (batch or player does not exist)
500	Internal server error (database failure)
502	Upstream service (oracle or data-node) unavailable

Addresses

Ethereum addresses in responses are formatted as checksummed hex strings with the 0x prefix (e.g., 0xAbC123...def).

Rate Limits

There are currently no rate limits. Generosity, or negligence — the distinction matters less than you think.

Quick Start

Fetch all active batches:

cURL

curl https://generalmarket.io/api/vision/batches

Python

import requests

response = requests.get("https://generalmarket.io/api/vision/batches")
batches = response.json()["batches"]
for batch in batches:
    print(f"Batch {batch['id']}: {batch['market_count']} markets, {batch['player_count']} players")

TypeScript

const res = await fetch("https://generalmarket.io/api/vision/batches");
const { batches } = await res.json();
batches.forEach((b: any) =>
  console.log(`Batch ${b.id}: ${b.market_count} markets, ${b.player_count} players`)
);