---
title: "Grade settleable player-prop and game-market legs"
method: POST
path: "/v1/grade/slip"
tags: ["grade"]
---

# Grade settleable player-prop and game-market legs

`POST /v1/grade/slip`

## Request

- Base URL: `https://lumify.ai`
- URL: `https://lumify.ai/v1/grade/slip`
- Auth: HTTP bearer

Grade settleable player-prop legs (over/under/push/in_progress/dnp/no_stat) on nfl/nba/ncaaf/ncaab/nhl/mlb/soccer, plus structured game markets (h2h/spreads/totals) on any sport GET /odds already settles. Structured event_id preferred; player_id is required on props and forbidden on game keys. Free-text player props are graded only when player and event resolve uniquely — ambiguous names stay unmapped with candidates. Call this endpoint or MCP grade_slip with an API key to grade from an app or agent. The public /grade sheet uses the same engine without a key (20 grades / IP / day). How-to: https://lumify.ai/docs/grade. Not live trading odds. Not wagering advice.

## Request body

- GradeSlipRequest
  - `legs` GradeSlipLegInput[]: Structured legs (preferred). Cap 8.
    - `event_id` integer, required: Lumify event id.
    - `player_id` integer, nullable: Lumify player id from resolve_player or GET /v1/players. Required on player-prop markets. Forbidden on h2h, spreads, totals, and team_total.
    - `team_id` integer, nullable: Lumify team id from resolve_team or GET /v1/teams. Required on team_total. Forbidden on player-prop, h2h, spreads, and totals (those use side=home|away, not a team id).
    - `market_key` string, required: Settleable player-prop slug (e.g. receiving_yards), game market h2h | spreads | totals, or team_total. Common aliases are accepted: player_reception_yds -> receiving_yards, moneyline/ml -> h2h, spread -> spreads, total/ou -> totals, team totals/tt -> team_total.
    - `line` number, nullable: Submitted ticket line to grade against the official score. Required on player-prop, spreads, totals, and team_total legs — signed to the side on the ticket (e.g. side=home with a home -3.5 favorite is line=-3.5, not 3.5). Omit on h2h.
    - `side` string, required: Player-prop, totals, and team_total: over | under (o | u also accepted). Spreads: home | away — matches the signed line above, not the favorite. Moneyline: home | away, or draw on soccer three-way.
  - `text` string, nullable: Free-text slip (e.g. "Chase over 74.5 receiving yards tonight"). Date words (today, tonight, yesterday, last night, last Wednesday, this Thursday, or an ISO date) narrow the event window. A roster-team mention (CIN, Niners) is resolved first — a unique team_id scopes the player; ambiguous/not_found stays on team_resolve. vs/at on a player prop is the opponent and narrows the event, not the player's team. Game phrases also include Yankees to win, Yankees over 4.5 runs (team_total), and Over 52.5 Syracuse vs Pittsburgh. A colliding nickname plus a date promotes only the unique in-window team; a football-sized line will not pick a baseball club, and vs plus that date keeps the unique matchup. A tennis moneyline with a full player name (Novak Djokovic ML) binds as a player, not a team; vs names the opponent player. Last-name-only tennis stays unmapped. A last-name-only player prop (Bergeron over 1.5 shots on goal last night) grades when a date is present and that surname is unique in scope — a named sport, team, or event narrows it (Johnson nhl last night); with no such clue, uniqueness is across every prop sport visible to the key. No date, or a surname shared by more than one player in that scope, still stays unmapped unless a date is present and exactly one of those candidates played in the window (optionally vs a named opponent). "anytime goal"/"anytime assist" implies soccer_goals/soccer_assists over 0.5 with no explicit number; "over a hit"/"over a homer" implies hits/home_runs over 1.0. Graded only when player and event resolve uniquely. Otherwise unmapped with candidates on resolve / team_resolve / event_resolve — free text never invents a grade.
  - `clues` object, nullable: Optional sport / league / event_id / team_id / team_text clues for free-text mode.
  - `options` GradeSlipOptions
    - `include_branding` boolean: Attribution block is always present in this version.
    - `max_legs` integer: v0 cap is 8 legs.
    - `auto_resolve` boolean: When free-text uniquely resolves a player and event, grade that leg. Ambiguous resolve never auto-picks a candidate.

## Response `200`

Per-leg settlement (props: over / under / push / in_progress / dnp / no_stat; spreads and moneyline: won / lost / push / void / in_progress; totals: over / under / push / void / in_progress) plus a slip summary. Attribution is always Graded by Lumify.

- GradeSlipResponse
  - `status` string, required: graded | partial | pending | unmapped
  - `legs` GradeSlipLeg[], required
    - `input` object, nullable: Parse echo of the leg (player, market_key, line, side, sport, team). Informational only — prefer market + resolve for the IDs and line that were actually graded.
    - `resolve` GradeSlipResolve
      - `status` string, nullable: resolved|ambiguous|not_found|error
      - `player_id` integer, nullable
      - `display_name` string, nullable
      - `candidates` object[]: Player candidates when status is ambiguous. Empty on a unique bind.
    - `team_resolve` GradeSlipTeamResolve
      - `status` string, nullable: resolved|ambiguous|not_found|error
      - `team_id` integer, nullable
      - `display_name` string, nullable
      - `sport` string, nullable
      - `league` string, nullable
      - `abbreviation` string, nullable
      - `confidence` number, nullable
      - `match_reasons` string[]
      - `sport_conflict` boolean
      - `candidates` object[]
      - `message` string, nullable
    - `event_resolve` GradeSlipEventResolve
      - `status` string, nullable: resolved|ambiguous|not_found|error
      - `event_id` integer, nullable
      - `candidates` object[]: Event candidates when status is ambiguous. Empty on a unique bind.
      - `message` string, nullable
    - `market` GradeSlipMarket
      - `event_id` integer, nullable
      - `market_key` string, nullable
      - `line` number, nullable
      - `side` string, nullable
      - `settleable` boolean, nullable
      - `home_team` string, nullable: Null when the event never resolved to a row.
      - `away_team` string, nullable: Null when the event never resolved to a row.
      - `starts_at` string, nullable: ISO-8601 UTC kickoff/first-pitch time. Null when the event never resolved to a row.
      - `home_score` number, nullable: Official home (or player_1) numeric score. Null on tennis set-strings and when the event never resolved.
      - `away_score` number, nullable: Official away (or player_2) numeric score. Null on tennis set-strings and when the event never resolved.
      - `team_id` integer, nullable: The team whose score was graded on a team_total leg. Null on other markets.
    - `current` number, nullable: Number compared to the line: prop box count, totals home+away, spreads home−away. Null on moneyline (read market.home_score / away_score) and when unmapped.
    - `result` string, nullable: Props: in_progress | over | under | push | dnp | no_stat. Spreads and moneyline: won | lost | push | void | in_progress. Totals: over | under | push | void | in_progress. Null when unmapped.
    - `message` string, nullable
  - `summary` GradeSlipSummary, required
    - `graded` integer
    - `pending` integer
    - `unmapped` integer
    - `hits` integer
    - `misses` integer
    - `pushes` integer
    - `voids` integer: Walkover, cancel, postpone, suspend, or retired legs. Not a miss and not unmapped.
  - `branding` GradeSlipBranding, required
    - `attribution` string, required: Always 'Graded by Lumify' on this surface.
    - `links` object
  - `honesty` GradeSlipHonesty, required
    - `notes` string[]
  - `slip_id` string, nullable: Null in this version; share URLs are not persisted.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api.md) · [All operations](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lumify/apis/lumify-sports-intelligence-api/revisions/f91ea41a2606?raw)