> ## Documentation Index > Fetch the complete documentation index at: https://docs.4casters.io/llms.txt > Use this file to discover all available pages before exploring further. # Get graded bets since a cursor > Your settled (graded) bets in **settlement order**, paged by an opaque cursor — the way to keep a local copy of your bet history in sync without guessing date windows. **First call:** send `since` (ISO 8601). You get the bets settled strictly after that instant, oldest first, plus a `cursor`. **Every call after that — the recommended loop:** poll **once per second** with your latest `cursor`. If a response has `hasMore: true`, there is more to fetch — call again immediately with the new cursor until `hasMore` is false, then go back to polling once per second. Never construct or modify a cursor; a cursor you did not receive from this endpoint is rejected with `400`. An empty page returns your cursor unchanged, so a poller never loses its place. ```js let cursor = firstResponse.data.cursor; // from your one-time ?since= call while (true) { let hasMore = true; while (hasMore) { const res = await get('/user/v2/getGradedSince', { cursor }); if (res.status === 429) { await sleep(res.headers['retry-after'] * 1000); continue; } // same cursor for (const row of res.data.graded) upsert(row.txID, row); cursor = res.data.cursor; hasMore = res.data.hasMore; } await sleep(1000); } ``` Rows are exactly `getGraded`'s rows (per fill, your side, game embedded). A bet can appear again later if its settlement changes — a refund, or a regrade after a score correction — with a newer position in the walk; treat `txID` as the row's identity and let the latest version win. Pages are a fixed **100 rows**, and the endpoint is rate limited to **10 requests per 5 seconds per user**. That leaves room to drain a burst while polling once per second; live settlement never fills a page (a few rows per second at most), so `hasMore` effectively only fires when you are catching up after downtime — a day of a busy account's settlements drains in about 12 seconds. If you do get a `429`, wait `Retry-After` seconds and resend the **same** cursor. One second is the recommended and, in practice, the maximum polling rate. **`settledThrough` — the human-readable position.** Every response also carries `settledThrough`, an ISO timestamp meaning *you now hold every bet settled at or before this instant*. Several bets can settle in the same millisecond, and a page can end inside such a group; `settledThrough` then steps back to the last instant that is complete, so it is always safe. If you would rather not store an opaque token, resume with `since=settledThrough`: you can never miss a bet that way, you may just see the rows of that last group again (dedupe by `txID`). The `cursor` remains the exact position Also accepts `POST` with the same parameters sent as a JSON body. ## OpenAPI ````yaml /sources/core-api.openapi.json get /user/v2/getGradedSince openapi: 3.0.3 info: title: 4casters API version: 1.0.0 description: >- Programmatic access to the 4casters peer-to-peer betting exchange. Generated from the service itself — every documented endpoint is described by the same schema that validates its requests. x-audience: public servers: - url: https://api.4casters.io security: [] paths: /user/v2/getGradedSince: get: tags: - Graded bets summary: Get graded bets since a cursor description: >- Your settled (graded) bets in **settlement order**, paged by an opaque cursor — the way to keep a local copy of your bet history in sync without guessing date windows. **First call:** send `since` (ISO 8601). You get the bets settled strictly after that instant, oldest first, plus a `cursor`. **Every call after that — the recommended loop:** poll **once per second** with your latest `cursor`. If a response has `hasMore: true`, there is more to fetch — call again immediately with the new cursor until `hasMore` is false, then go back to polling once per second. Never construct or modify a cursor; a cursor you did not receive from this endpoint is rejected with `400`. An empty page returns your cursor unchanged, so a poller never loses its place. ```js let cursor = firstResponse.data.cursor; // from your one-time ?since= call while (true) { let hasMore = true; while (hasMore) { const res = await get('/user/v2/getGradedSince', { cursor }); if (res.status === 429) { await sleep(res.headers['retry-after'] * 1000); continue; } // same cursor for (const row of res.data.graded) upsert(row.txID, row); cursor = res.data.cursor; hasMore = res.data.hasMore; } await sleep(1000); } ``` Rows are exactly `getGraded`'s rows (per fill, your side, game embedded). A bet can appear again later if its settlement changes — a refund, or a regrade after a score correction — with a newer position in the walk; treat `txID` as the row's identity and let the latest version win. Pages are a fixed **100 rows**, and the endpoint is rate limited to **10 requests per 5 seconds per user**. That leaves room to drain a burst while polling once per second; live settlement never fills a page (a few rows per second at most), so `hasMore` effectively only fires when you are catching up after downtime — a day of a busy account's settlements drains in about 12 seconds. If you do get a `429`, wait `Retry-After` seconds and resend the **same** cursor. One second is the recommended and, in practice, the maximum polling rate. **`settledThrough` — the human-readable position.** Every response also carries `settledThrough`, an ISO timestamp meaning *you now hold every bet settled at or before this instant*. Several bets can settle in the same millisecond, and a page can end inside such a group; `settledThrough` then steps back to the last instant that is complete, so it is always safe. If you would rather not store an opaque token, resume with `since=settledThrough`: you can never miss a bet that way, you may just see the rows of that last group again (dedupe by `txID`). The `cursor` remains the exact position Also accepts `POST` with the same parameters sent as a JSON body. parameters: - name: since in: query required: false description: >- First call: return bets settled strictly after this instant. Mutually exclusive with `cursor`. schema: type: string example: '2026-08-01T00:00:00.000Z' - name: cursor in: query required: false description: >- Subsequent calls: the `cursor` from the previous response, verbatim. Mutually exclusive with `since`. schema: type: string responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: graded: type: array items: anyOf: - type: object properties: game: anyOf: - type: object properties: isSpecials: type: boolean eventName: type: string tournamentName: nullable: true type: string periodName: type: string id: type: string pattern: ^[0-9a-fA-F]{24}$ ended: type: boolean league: type: string live: type: boolean parentGameID: nullable: true type: string pattern: ^[0-9a-fA-F]{24}$ start: type: string description: ISO 8601 timestamp example: '2026-08-01T00:00:00.000Z' sport: type: string participants: type: array items: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-fA-F]{24}$ longName: type: string shortName: type: string mainPitcher: type: string homeAway: type: string enum: - home - away score: type: number rotationNumber: type: string futuresSide: type: string required: - id - longName - shortName - homeAway - futuresSide additionalProperties: false - type: object properties: id: type: string pattern: ^[0-9a-fA-F]{24}$ longName: type: string shortName: type: string mainPitcher: type: string homeAway: type: string enum: - home - away score: type: number rotationNumber: type: string futuresSide: type: string required: - id - longName - shortName - homeAway - futuresSide additionalProperties: false minItems: 2 maxItems: 2 description: Away participant first, then home. required: - isSpecials - tournamentName - periodName - id - league - live - sport - participants additionalProperties: false - type: object properties: _id: type: string error: type: string required: - _id - error additionalProperties: false description: >- The entity could not be loaded; `_id` identifies it. outcome: type: string enum: - winner - loser - half-win - half-loss - refunded id: type: string pattern: ^[0-9a-fA-F]{24}$ description: The order (session) id. graded: type: boolean type: type: string enum: - moneyline - spread - total - moneyline1x2 bet: type: number description: Your stake on this fill. txID: type: string pattern: ^[0-9a-fA-F]{24}$ description: The fill (take transaction) id. closed: type: boolean enum: - false createdAt: type: string description: ISO 8601 timestamp example: '2026-08-01T00:00:00.000Z' adminRefund: type: boolean wagerRequestID: nullable: true type: string pattern: ^[0-9a-fA-F]{24}$ userReference: nullable: true type: string isPostArb: type: boolean enum: - true ticketNumber: type: string odds: type: number description: American odds from your perspective. matchedTime: type: string description: ISO 8601 timestamp example: '2026-08-01T00:00:00.000Z' settledAt: type: string description: ISO 8601 timestamp example: '2026-08-01T00:00:00.000Z' fee: type: string description: Commission actually charged on this fill. platform: type: string risk: type: string description: Stake plus commission. win: type: string description: Gross winnings minus commission. result: description: >- Signed settled P&L; absent when the outcome is unknown. type: string origin: type: string enum: - wager description: You took this order. cancelled: type: boolean enum: - false participantID: nullable: true type: string pattern: ^[0-9a-fA-F]{24}$ spread: type: number total: type: number OU: type: string enum: - over - under side: type: string enum: - 'yes' - 'no' market: type: string required: - game - id - type - bet - txID - closed - ticketNumber - odds - fee - risk - win - origin - cancelled additionalProperties: false - type: object properties: game: anyOf: - type: object properties: isSpecials: type: boolean eventName: type: string tournamentName: nullable: true type: string periodName: type: string id: type: string pattern: ^[0-9a-fA-F]{24}$ ended: type: boolean league: type: string live: type: boolean parentGameID: nullable: true type: string pattern: ^[0-9a-fA-F]{24}$ start: type: string description: ISO 8601 timestamp example: '2026-08-01T00:00:00.000Z' sport: type: string participants: type: array items: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-fA-F]{24}$ longName: type: string shortName: type: string mainPitcher: type: string homeAway: type: string enum: - home - away score: type: number rotationNumber: type: string futuresSide: type: string required: - id - longName - shortName - homeAway - futuresSide additionalProperties: false - type: object properties: id: type: string pattern: ^[0-9a-fA-F]{24}$ longName: type: string shortName: type: string mainPitcher: type: string homeAway: type: string enum: - home - away score: type: number rotationNumber: type: string futuresSide: type: string required: - id - longName - shortName - homeAway - futuresSide additionalProperties: false minItems: 2 maxItems: 2 description: Away participant first, then home. required: - isSpecials - tournamentName - periodName - id - league - live - sport - participants additionalProperties: false - type: object properties: _id: type: string error: type: string required: - _id - error additionalProperties: false description: >- The entity could not be loaded; `_id` identifies it. outcome: type: string enum: - winner - loser - half-win - half-loss - refunded id: type: string pattern: ^[0-9a-fA-F]{24}$ description: The order (session) id. graded: type: boolean type: type: string enum: - moneyline - spread - total - moneyline1x2 bet: type: number description: Your stake on this fill. txID: type: string pattern: ^[0-9a-fA-F]{24}$ description: The fill (take transaction) id. closed: type: boolean enum: - false createdAt: type: string description: ISO 8601 timestamp example: '2026-08-01T00:00:00.000Z' adminRefund: type: boolean wagerRequestID: nullable: true type: string pattern: ^[0-9a-fA-F]{24}$ userReference: nullable: true type: string isPostArb: type: boolean enum: - true ticketNumber: type: string odds: type: number description: American odds from your perspective. matchedTime: type: string description: ISO 8601 timestamp example: '2026-08-01T00:00:00.000Z' settledAt: type: string description: ISO 8601 timestamp example: '2026-08-01T00:00:00.000Z' fee: type: string description: Commission actually charged on this fill. platform: type: string risk: type: string description: Stake plus commission. win: type: string description: Gross winnings minus commission. result: description: >- Signed settled P&L; absent when the outcome is unknown. type: string origin: type: string enum: - offer description: You posted the order that was taken. takenRatio: type: number description: >- How much of the order's full volume has been filled, 0–1. cancelled: type: boolean expiry: nullable: true type: string description: ISO 8601 timestamp example: '2026-08-01T00:00:00.000Z' spread: nullable: true type: number total: nullable: true type: number participantID: nullable: true type: string pattern: ^[0-9a-fA-F]{24}$ OU: type: string enum: - over - under side: type: string enum: - 'yes' - 'no' market: type: string required: - game - id - type - bet - txID - closed - ticketNumber - odds - fee - risk - win - origin - takenRatio - spread - total additionalProperties: false - type: object properties: txID: type: string pattern: ^[0-9a-fA-F]{24}$ ticketNumber: type: string id: type: object properties: _id: type: string error: type: string required: - _id - error additionalProperties: false description: >- The entity could not be loaded; `_id` identifies it. game: anyOf: - type: object properties: isSpecials: type: boolean eventName: type: string tournamentName: nullable: true type: string periodName: type: string id: type: string pattern: ^[0-9a-fA-F]{24}$ ended: type: boolean league: type: string live: type: boolean parentGameID: nullable: true type: string pattern: ^[0-9a-fA-F]{24}$ start: type: string description: ISO 8601 timestamp example: '2026-08-01T00:00:00.000Z' sport: type: string participants: type: array items: anyOf: - type: object properties: id: type: string pattern: ^[0-9a-fA-F]{24}$ longName: type: string shortName: type: string mainPitcher: type: string homeAway: type: string enum: - home - away score: type: number rotationNumber: type: string futuresSide: type: string required: - id - longName - shortName - homeAway - futuresSide additionalProperties: false - type: object properties: id: type: string pattern: ^[0-9a-fA-F]{24}$ longName: type: string shortName: type: string mainPitcher: type: string homeAway: type: string enum: - home - away score: type: number rotationNumber: type: string futuresSide: type: string required: - id - longName - shortName - homeAway - futuresSide additionalProperties: false minItems: 2 maxItems: 2 description: Away participant first, then home. required: - isSpecials - tournamentName - periodName - id - league - live - sport - participants additionalProperties: false - type: object properties: _id: type: string error: type: string required: - _id - error additionalProperties: false description: >- The entity could not be loaded; `_id` identifies it. settledAt: type: string description: ISO 8601 timestamp example: '2026-08-01T00:00:00.000Z' matchedTime: type: string description: ISO 8601 timestamp example: '2026-08-01T00:00:00.000Z' required: - txID - ticketNumber - id - game additionalProperties: false hasMore: type: boolean description: Whether another page follows. cursor: type: string description: >- Opaque walk position. Send it back as `cursor` to get the next page; on an empty page it is your request cursor, unchanged. settledThrough: type: string description: >- You now hold every bet settled at or before this instant. A human-readable resume point: `since=settledThrough` never misses a bet and may only repeat the last millisecond group (dedupe by `txID`). example: '2026-08-01T00:00:00.000Z' required: - graded - hasMore - cursor - settledThrough additionalProperties: false required: - data additionalProperties: false '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid auth token content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The account may not perform this action content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited — see Retry-After content: application/json: schema: $ref: '#/components/schemas/Error' security: - authToken: [] components: schemas: Error: type: object properties: error: type: string required: - error additionalProperties: false securitySchemes: authToken: type: apiKey in: header name: Authorization description: >- The auth token returned by `POST /user/login` (`data.user.auth`), sent as the raw header value — no `Bearer` prefix. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.