API

Endpoints

Response envelope

{ "ok": true, "data": <payload>, "meta": { "generated_at": "..." } }

Errors use the same envelope with { "ok": false, "error": { "code", "message" } }.

Event schema

One normalized shape, independent of both Polymarket’s wire format and any notification provider. It is what the webhook body will carry unchanged, and it is the row you see on the feed: the same side, size and rank, drawn here the way the tape draws them.

{
  "event_id": "9f2c1ab4e7d0435c8a61f0d3c72b19ee",
  "event_type": "new_trade",
  "timestamp": "2026-08-22T06:32:13.000Z",

  "trader": {
    "username": "BOOMBOYS.Kiritych",
    "wallet": "0xcd30f4698c6f5f3829893e68e183a8e5ea18f316",
    "rank": 1,
    "monthly_profit": 1525246.07,
    "profile_url": "https://polymarket.com/profile/0xcd30…f316",
    "profile_image": null
  },

  "market": {
    "id": "0x72f93cc5347291e42699dc9db76a38e184a00a088b368fe0a71148148d0260b4",
    "title": "Dota 2: Nigma Galaxy vs BoomBoys - Game 2 Winner",
    "slug": "dota2-ngx-boombo-2026-08-22-game2",
    "event_slug": "dota2-ngx-boombo-2026-08-22",
    "category": "esports",
    "game": "dota2",
    "game_label": "Dota 2",
    "game_short": "DOTA 2",
    "game_source": "title",
    "url": "https://polymarket.com/event/dota2-ngx-boombo-2026-08-22/dota2-ngx-boombo-2026-08-22-game2",
    "icon": null
  },

  "trade": {
    "side": "BUY",
    "outcome": "BoomBoys",
    "outcome_index": 1,
    "price": 0.4767867447,
    "size_usd": 1131.08548,
    "shares": 2311.83,
    "transaction_hash": "0x93010113387bdefb7b7c162b0c2eae2f05013b267db149af3acd95019ae83816",
    "asset": "42974820668140481674546125062447708867633239207219559804172577672111834920324"
  },

  "timing": {
    "source_timestamp": "2026-08-22T06:32:13.000Z",
    "detected_timestamp": "2026-08-22T06:32:14.180Z",
    "detection_latency_ms": 1180,
    "ingest_source": "stream"
  }
}

Field notes

outcome

The real outcome label. Esports markets use team names, not YES/NO; do not assume a binary vocabulary.

price

Always the canonical probability in [0,1], whatever odds format the site is displaying. The format selector is a display preference only; it never changes a stored event or an API payload. Convert client-side: decimal is 1 / price, American is -100·p/(1-p) for p ≥ 0.5 and 100·(1-p)/p below it, fractional is (1-p)/p. Those conversions are exact: a Polymarket share settles at $1, so the price is the implied probability, unlike a sportsbook price, which carries margin.

size_usd

From Polymarket’s usdcSize when available; otherwise shares × price.

category

esports only when the market was found in the esports index; otherwise unknown. Never guessed.

game

Derived, not supplied by Polymarket: its per-game tags are not attached to match markets, so the game is parsed from the title and slug. game_source says how. title and slug mean Polymarket named the game outright; league means it was inferred from a tournament name (“IEM Cologne” is Counter-Strike); none means unclassified, in which case game is "other". Never treat league as authoritative. A market with game: "other" that is in the esports tag index carries game_label: "Esports": confirmed esports, unidentified title.

detection_latency_ms

null when it cannot be measured reliably, rather than estimated.

event_id

Derived from trade content, so the same trade seen via the stream and via a poll produces the same id. Safe to use as an idempotency key.

The public feed excludes markets that are not identifiably esports: a market qualifies if the classifier names a game or its condition ID is under Polymarket’s esports tag. /trades/history is unfiltered and still returns them.

Examples

curl -s https://alpha.box/api/v1/trades/latest?limit=10 | jq

const res = await fetch('https://alpha.box/api/v1/trades/latest?limit=25');
const { data } = await res.json();

for (const event of data) {
  console.log(
    event.trader.username,
    event.trade.side,
    event.trade.outcome,
    `$${event.trade.size_usd.toFixed(0)}`,
    event.market.title,
  );
}

import requests

r = requests.get("https://alpha.box/api/v1/trades/latest", params={"limit": 25})
for event in r.json()["data"]:
    print(
        event["trader"]["username"],
        event["trade"]["side"],
        event["trade"]["outcome"],
        f'${event["trade"]["size_usd"]:.0f}',
        event["market"]["title"],
    )

Rate limits

None enforced on this deployment yet. Upstream, Polymarket’s data API allows 1,000 requests per 10 seconds; this service polls far below that. Please be reasonable until keys and quotas land.

What this API does not claim

Executed trades only

Unfilled orders are visible only to the trader who placed them; no public API exposes them.

BUY is not “opened a position”

Distinguishing open from close needs position-state tracking, which is not implemented, so events are labelled by side rather than intent.

Win rate counts positions, not dollars

It is counted from settled position records, not estimated, but a trader can win well under half their positions and still be far ahead if the winners are larger, which is common here. It is served beside P&L, never instead of it.

The game is parsed, not published

Markets whose game cannot be identified are other, never assigned to the most likely title.