COLEX API

Overview

Base URL: https://colex-v2-api.demarkelabs.workers.dev

All money fields are decimal strings (USDC-style), never floats. Timestamps are Unix seconds. Pagination is limit (1–100, default 50) and offset.

Routes are vertical-prefixed. Pokémon is live; watches, sneakers, and bags can ship later as /v1/watches/… without changing auth.

Authentication

Send your key on every private request. Keys look like cx_live_… and are shown once in the developer portal.

X-Api-Key: cx_live_…

GET /v1/plans and GET /v1/openapi.json are public. Everything else under /v1 requires a key.

Errors

Errors are JSON: { "error": "code" }. Common codes:

Plans & limits

Limits live in config and can change without a code deploy. Defaults:

Add-on: $100 / month per 100 custom real-time cards. Pay USDC in the developers portal (Robinhood testnet MockUSDC today; Base USDC in production). Leftover prepaid credit auto-renews the next period; otherwise keys return 402.

Asset IDs

IDs are oracletcg form: pokemon_{set}_{name}_{number}_{lang}_{grade}

pokemon_sv151_mew_ex_205_en_raw

Grade suffix is raw, holo, reverse, psa10… psa7, cgc10, or bgs10. Raw cards and slabs are separate assets.

Real-time prices

The COLEX Index set (~550 raw + slab assets), refreshed on a high-frequency cadence. Your active custom tracks are included in the list once oracletcg activates them.

GET /v1/pokemon/realtime

Query: limit, offset, q (search name or id)

curl -sS "https://colex-v2-api.demarkelabs.workers.dev/v1/pokemon/realtime?limit=5" \
  -H "X-Api-Key: $COLEX_API_KEY"

{
  "items": [ /* spot objects */ ],
  "total": 548,
  "limit": 50,
  "offset": 0
}

GET /v1/pokemon/realtime/{asset_id}

curl -sS "https://colex-v2-api.demarkelabs.workers.dev/v1/pokemon/realtime/pokemon_sv151_mew_ex_205_en_raw" \
  -H "X-Api-Key: $COLEX_API_KEY"

{
  "asset_id": "pokemon_sv151_mew_ex_205_en_raw",
  "display_name": "Mew ex #205 · Raw",
  "set_name": "sv151",
  "grade": "raw",
  "image_url": null,
  "price_usd": "412.50",
  "asof": 1776278400,
  "freshness_seconds": 42,
  "volume_usd": "18420.00",
  "sales_7d": 18,
  "tier": "realtime",
  "includes_listings": false,
  "method": "colex_index"
}

History

Depth is gated by plan (history_days). Points come from our snapshot store, or oracletcg if it exposes a history feed. We do not invent candles.

GET /v1/pokemon/realtime/{asset_id}/history

Query: limit (1–5000, default 500)

curl -sS "https://colex-v2-api.demarkelabs.workers.dev/v1/pokemon/realtime/pokemon_sv151_mew_ex_205_en_raw/history?limit=100" \
  -H "X-Api-Key: $COLEX_API_KEY"

{
  "asset_id": "pokemon_sv151_mew_ex_205_en_raw",
  "history": [
    { "price_usd": "412.50", "asof": 1776278400 }
  ],
  "source": "snapshot"
}

Catalog

Broader Pokémon coverage at a softer cadence. Standard, Plus, and Enterprise. Returns 403 on Basic, 503 until catalog ingest has published.

GET /v1/pokemon/assets

GET /v1/pokemon/assets/{asset_id}

curl -sS "https://colex-v2-api.demarkelabs.workers.dev/v1/pokemon/assets?q=charizard&limit=20" \
  -H "X-Api-Key: $COLEX_API_KEY"

Same spot shape as real-time. tier is catalog or realtime when the card is also an Index asset. method is normalized_sales.

Custom tracking

Buy packs on the portal, then queue extra cards for the same high-frequency path as Index assets. Status starts pending until activation.

GET /v1/pokemon/tracking

POST /v1/pokemon/tracking

curl -sS -X POST "https://colex-v2-api.demarkelabs.workers.dev/v1/pokemon/tracking" \
  -H "X-Api-Key: $COLEX_API_KEY" \
  -H "content-type: application/json" \
  -d '{"asset_ids":["pokemon_sv151_mew_ex_205_en_raw"]}'

Account

GET /v1/me

curl -sS "https://colex-v2-api.demarkelabs.workers.dev/v1/me" \
  -H "X-Api-Key: $COLEX_API_KEY"

{
  "wallet": "0xabc…",
  "plan": { "id": 2, "name": "Standard", "price_usdc": "49000000" },
  "status": "active",
  "credit_usdc": "98000000",
  "period_end": 1778860800,
  "custom_packs": 0,
  "custom_slots": 0,
  "custom_used": 0,
  "key_prefix": "cx_live_a1b2c3",
  "entitlements": {
    "realtime": true,
    "catalog": true,
    "history_days": 90,
    "rpm": 60,
    "daily": 25000,
    "enterprise": false
  },
  "usage": { "minute": 3, "day": 140 }
}

credit_usdc and plan.price_usdc are integer micro-USD strings (6 decimals). period_end is when the current prepaid month ends.

Methodology

• COLEX price is an executable market value from completed / verified sales(eBay, Cardmarket, Goldin, and similar).
• PriceCharting and TCGplayer aggregates can inform a normalized average. They are not treated as prints.
• Active listings are not transactions. If a named rule ever requires them, the payload sets includes_listings: true.
• Real-time Index assets use method: "colex_index". Catalog uses method: "normalized_sales".