> ## Documentation Index
> Fetch the complete documentation index at: https://docs.droyd.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List My Race Payouts

> Discover your payout items and whether each one can be claimed.

Use this route after a race closes to find winnings or cancelled-race refunds,
their claim deadlines, and any claim already in progress.

Auth: Droyd API key or signed-in user bearer token. Alias:
`GET /api/v1/competitions/{slug}/races/{race_id}/payouts`. Results are strictly
caller-owned and ordered by payout-item `created_at DESC, id DESC`.
Pagination uses integer `limit` and `offset`; `limit` defaults to `25`, must be
`1..100`, and `offset + limit` must not exceed `100000`. Follow
`page.has_more` and `page.next_offset`.

Each result includes `settlement_kind` (`payout` or `refund`), the immutable
amount and recipient wallet/token-account snapshot, item status, claim-window
timestamps, derived claimability, and the latest claim when one exists.
Refund items belong only to a race with `status=cancelled` and
`cancellation_kind=refund`; they are never competitive winnings. Claimability
states are `claimable`,
`claim_in_progress`, `claimed`, `forfeited`, `race_not_finalized`,
`manifest_not_finalized`, `payout_state_unavailable`, `claim_not_open`,
`claim_window_closed`, or `claim_window_unavailable`. Claimability requires a
finalized race for payouts, or a published funded-cancellation refund
settlement for refunds, plus a finalized or published referenced manifest. The
claim window is inclusive at both endpoints. This read supports either bearer auth or
an API key, but claim preparation and hosted signing remain signed-in-user-only
actions.

The response never contains Merkle leaves/proofs, private manifest or series
metadata, hosted-wallet provider IDs, encrypted fields, other users, or raw
dependency failure details. Use the payout status together with
`latest_claim.status`; do not treat a missing claim as claimable unless
`claimability.claimable` is true.

When `latest_claim` is non-successful it may include an allowlisted
`failure_code` and sanitized `failure_message`. These fields never contain raw
Privy, Solana RPC, wallet, transaction, credential, or database payloads, and
they are `null` after successful confirmation.


## OpenAPI

````yaml api-key.openapi.json GET /v1/competitions/{slug}/races/{race_id}/payouts
openapi: 3.1.0
info:
  title: Droyd API-key Automation API
  version: 1.0.0
  description: >-
    The production API contract for Droyd API-key automations. It contains only
    operations that accept a Droyd API key. `/v1` is canonical; `/api/v1` is a
    compatibility alias.
servers: []
security:
  - droydApiKeyBearer: []
  - droydApiKeyHeader: []
tags:
  - name: Identity
    description: Account-scoped automation identity and onboarding state.
  - name: Workflows
    description: Caller-owned workflows and research nodes.
  - name: Competitions
    description: Competition readiness, submissions, and race entries.
  - name: Experiments
    description: Experiments, artifacts, agent versions, and evaluations.
  - name: Usage
    description: Caller-owned evaluation usage.
  - name: Billing
    description: Caller-owned prepaid credit balances and funding.
paths:
  /v1/competitions/{slug}/races/{race_id}/payouts:
    get:
      tags:
        - Competitions
      summary: List finalized caller-owned payout and refund items.
      operationId: listRacePayouts
      parameters:
        - $ref: '#/components/parameters/Slug'
        - $ref: '#/components/parameters/RaceId'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  parameters:
    Slug:
      name: slug
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    RaceId:
      name: race_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  responses:
    Success:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessEnvelope'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: Account state or route policy prevents the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: The resource is missing or not owned by the API-key account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ServerError:
      description: >-
        The request could not be completed. Retry only when the operation's
        idempotency contract permits it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - ok
      properties:
        ok:
          const: true
      additionalProperties: true
    ErrorEnvelope:
      type: object
      required:
        - ok
        - error
      properties:
        ok:
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
  securitySchemes:
    droydApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: Droyd API key
      description: A Droyd API key in the Authorization Bearer slot.
    droydApiKeyHeader:
      type: apiKey
      in: header
      name: x-droyd-api-key
      description: A Droyd API key when Authorization is absent.

````