Skip to main content
GET
cURL
List pre-game Polymarket sports markets where graded (S, A, B) sharp money is piled on one side. Use this endpoint to rank games before kickoff. It needs the Pro plan.

Read the signals

  • rank is 1-based within the min_grade-filtered result. The order is directional_rank_score, highest first, then conviction_score, smart_score, and condition_id.
  • directional_rank_score is conviction_score * (1 + 0.25 * directional_confidence). conviction_score is (5*s + 4*a + 3*b) * sharp_pct.
  • piled_side is the provider display label for the piled outcome. piled_outcome_index selects the provider column: 0 for YES, 1 for NO. token_id is the CLOB token for that outcome. Do not read piled_side alone as a team identity.
  • sharp_pct is the piled-side dollar share in (0.5, 1]. backed_sharp_usd is the raw piled-side USD.
  • s_count, a_count, b_count, graded_holders, and top_grade describe the piled-side holders.
  • signal_created_at is the snapshot compute time. Every row from one snapshot shares it. It is not request time.
  • game_start_time was in the future at snapshot time. The snapshot is cached up to about 180 seconds, so a served kickoff can already be in the past.
  • one_way_holder_count, hedged_holder_count, one_way_graded_usd, and directional_confidence are null when the directional read was not computed.
  • category_skill is shadow-only evidence. It never changes membership, order, rank, or cursor.
  • meta.ranking_source is live or db_only. meta.directional_source is live or degraded. A degraded snapshot is cached about 30 seconds instead of about 180.

Filter the list

  • category accepts a canonical sport bucket such as Basketball, Tennis, or Soccer. A raw provider value such as NBA resolves to its bucket. A non-sport category returns an empty list.
  • horizon_hours is 1 to 48 with a default of 12. The floor is now, so only games before kickoff appear.
  • min_grade accepts S, A, or B (default). A requires an S or A holder on the piled side. C, D, and F return 400.
  • limit is 1 to 100 with a default of 20.

Handle the expired cursor

  1. Read error.reason on a 400. cursor_expired with error.param="cursor" means the ranking snapshot behind the cursor refreshed.
  2. Request the first page again and walk forward. Do not wait; there is no Retry-After.
  3. A 400 without error.reason is an invalid parameter. Read error.param.

Cache the signals

The 200 response carries an ETag. Send If-None-Match to get 304 Not Modified with an empty body when nothing changed. Get Sports Edge Observations measures the observation-only cohorts outside this funded list.

Authorizations

Authorization
string
header
required

API key authentication. Send your key in the Authorization header as Bearer oxi_sk_live_.... Live keys require an active Pro subscription and return live data.

Headers

If-None-Match
string

Conditional GET validator from a previous ETag. Matching values return 304 Not Modified with an empty body.

Query Parameters

category
string

Optional canonical sport bucket filter (e.g. Basketball, Tennis, Soccer). A raw provider value (NBA) resolves to its canonical bucket. A non-sport category returns an empty list.

limit
integer
default:20

Page size.

Required range: 1 <= x <= 100
cursor
string

Opaque cursor from a previous response's next_cursor. Encodes the snapshot anchor plus the last row's directional_rank_score, conviction_score, smart_score and condition_id. A cursor from an expired snapshot returns 400.

horizon_hours
integer
default:12

Kickoff ceiling in hours from now; the floor is now (only games not yet started). Clamped to 1..48.

Required range: 1 <= x <= 48
min_grade
enum<string>
default:B

Minimum trader grade required on the piled side. Only S, A, B are accepted (the piled-side grade distribution is S/A/B only; C, D, F return 400). Default B means at least one S/A/B holder is piled; S requires an S holder, A requires an S or A holder.

Available options:
S,
A,
B

Response

Ranked pre-game sports-edge signals

object
string
required
Allowed value: "list"
data
object[]
required
has_more
boolean
required
meta
object
required
next_cursor
string | null
total
integer | null