River Markets Watchlists API

openapi: 3.2.0
info:
  title: River Markets Watchlists API
  description: '# Getting Started


    River Markets provides users with a unified prime brokerage interface for prediction markets, including

    - Liquidity aggregation

    - Order routing

    - Market and data search


    This API guide will help you get up and running quickly.'
  contact:
    name: River Markets
    url: https://rivermarkets.com/
  license:
    name: Proprietary
  version: 1.0.0
servers:
- url: https://api.rivermarkets.com
security:
- SignedRequestKeyId: []
  SignedRequestTimestamp: []
  SignedRequestSignature: []
- BearerAuth: []
tags:
- name: Watchlists
paths:
  /v1/watchlists:
    get:
      tags:
      - Watchlists
      summary: List Watchlists
      description: List the caller's watchlists (optionally scoped to one subaccount), newest first.
      operationId: list_watchlists_v1_watchlists_get
      parameters:
      - name: subaccount_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Restrict to a single owning subaccount
          title: Subaccount Id
        description: Restrict to a single owning subaccount
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Watchlists
      summary: Create Watchlist
      description: Create a new watchlist, optionally seeded with an ordered set of river_ids.
      operationId: create_watchlist_v1_watchlists_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/watchlists/{watchlist_id}:
    get:
      tags:
      - Watchlists
      summary: Get Watchlist
      description: Fetch a single watchlist with its ordered member markets.
      operationId: get_watchlist_v1_watchlists__watchlist_id__get
      parameters:
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Watchlist Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Watchlists
      summary: Update Watchlist
      description: Rename a watchlist or edit its description.
      operationId: update_watchlist_v1_watchlists__watchlist_id__patch
      parameters:
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Watchlist Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Watchlists
      summary: Delete Watchlist
      description: Delete a watchlist (cascades to its members).
      operationId: delete_watchlist_v1_watchlists__watchlist_id__delete
      parameters:
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Watchlist Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/watchlists/{watchlist_id}/members:
    post:
      tags:
      - Watchlists
      summary: Add Watchlist Members
      description: Append river_ids to the end of a watchlist.
      operationId: add_watchlist_members_v1_watchlists__watchlist_id__members_post
      parameters:
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Watchlist Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistMemberAdd'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Watchlists
      summary: Remove Watchlist Members
      description: Remove river_ids from a watchlist. Remaining members keep their relative order.
      operationId: remove_watchlist_members_v1_watchlists__watchlist_id__members_delete
      parameters:
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Watchlist Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistMemberAdd'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/watchlists/{watchlist_id}/members/order:
    put:
      tags:
      - Watchlists
      summary: Reorder Watchlist Members
      description: 'Reorder a watchlist. The body is the full ordered river_id list; the server

        rewrites each member''s position to match. Unknown river_ids are ignored;

        members omitted from the list are pushed to the end in their prior order.'
      operationId: reorder_watchlist_members_v1_watchlists__watchlist_id__members_order_put
      parameters:
      - name: watchlist_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Watchlist Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WatchlistMemberReorder'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WatchlistMemberReorder:
      properties:
        river_ids:
          items:
            type: integer
          type: array
          minItems: 1
          title: River Ids
      type: object
      required:
      - river_ids
      title: WatchlistMemberReorder
      description: 'Request schema for reordering a watchlist.


        The body is the full ordered list of ``river_id``s; the server rewrites

        ``position`` to match. Sending the whole array avoids partial-reorder races

        and keeps it to one round-trip.'
    WatchlistUpdate:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      type: object
      title: WatchlistUpdate
      description: Request schema for renaming / editing a watchlist.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    InstrumentStatus:
      type: string
      enum:
      - active
      - closed
      - inactive
      title: InstrumentStatus
      description: "Instrument status derived in instruments table from exchange-specific fields.\n\nKalshi: maps from kalshi_markets.status\n    - 'active' -> ACTIVE\n    - everything else (closed, determined, finalized, settled, amended, inactive, initialized) -> CLOSED\n\nPolymarket: maps from polymarket_markets.closed and polymarket_markets.active booleans\n    - closed=true -> CLOSED\n    - active=true (and not closed) -> ACTIVE\n    - else (active=false, closed=false) -> INACTIVE"
    WatchlistDetailResponse:
      properties:
        watchlist_id:
          type: string
          format: uuid
          title: Watchlist Id
        owner_subaccount_id:
          type: string
          format: uuid
          title: Owner Subaccount Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        river_ids:
          items:
            type: integer
          type: array
          title: River Ids
        members:
          items:
            $ref: '#/components/schemas/MarketSearchResult'
          type: array
          title: Members
        created_at:
          type: string
          title: Created At
          description: Creation timestamp (UTC)
      type: object
      required:
      - watchlist_id
      - owner_subaccount_id
      - name
      - river_ids
      - members
      - created_at
      title: WatchlistDetailResponse
      description: 'Response schema for a watchlist with its resolved members (detail view).


        ``members`` are ordered by ``position``; ``river_ids`` is the same ordering

        as a convenience for handing straight to the multibook handoff.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WatchlistCreate:
      properties:
        subaccount_id:
          type: string
          format: uuid
          title: Subaccount Id
        name:
          type: string
          maxLength: 255
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        river_ids:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: River Ids
      type: object
      required:
      - subaccount_id
      - name
      title: WatchlistCreate
      description: Request schema for creating a new watchlist.
    WatchlistListResponse:
      properties:
        watchlists:
          items:
            $ref: '#/components/schemas/WatchlistResponse'
          type: array
          title: Watchlists
      type: object
      required:
      - watchlists
      title: WatchlistListResponse
    WatchlistResponse:
      properties:
        watchlist_id:
          type: string
          title: Watchlist Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        owner_subaccount_id:
          type: string
          title: Owner Subaccount Id
        river_ids:
          items:
            type: integer
          type: array
          title: River Ids
        created_at:
          type: string
          title: Created At
      type: object
      required:
      - watchlist_id
      - name
      - owner_subaccount_id
      - river_ids
      - created_at
      title: WatchlistResponse
      description: 'A watchlist summary (list view): metadata + ordered member river_ids.'
    MarketSearchResult:
      properties:
        river_id:
          type: integer
          title: River Id
        exchange_value:
          type: integer
          title: Exchange Value
        exchange_name:
          type: string
          title: Exchange Name
        ticker:
          anyOf:
          - type: string
          - type: 'null'
          title: Ticker
        token_id_yes:
          anyOf:
          - type: string
          - type: 'null'
          title: Token Id Yes
        token_id_no:
          anyOf:
          - type: string
          - type: 'null'
          title: Token Id No
        slug:
          anyOf:
          - type: string
          - type: 'null'
          title: Slug
        tick_size_price:
          type: number
          title: Tick Size Price
        tick_size_qty:
          type: number
          title: Tick Size Qty
        tick_structure:
          type: string
          title: Tick Structure
          default: uniform
        minimum_order_size:
          type: number
          title: Minimum Order Size
        expiration_datetime:
          anyOf:
          - type: string
          - type: 'null'
          title: Expiration Datetime
          description: Market expiration datetime (UTC)
        start_datetime:
          anyOf:
          - type: string
          - type: 'null'
          title: Start Datetime
          description: Game/event start datetime (UTC). Populated for sports; null otherwise.
        neg_risk:
          type: boolean
          title: Neg Risk
        neg_risk_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Neg Risk Id
        condition_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Condition Id
        name:
          type: string
          title: Name
        subtitle:
          anyOf:
          - type: string
          - type: 'null'
          title: Subtitle
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        status:
          $ref: '#/components/schemas/InstrumentStatus'
        category:
          type: string
          title: Category
          default: Other
        subcategory:
          anyOf:
          - type: string
          - type: 'null'
          title: Subcategory
        rank:
          anyOf:
          - type: number
          - type: 'null'
          title: Rank
        event_ticker:
          anyOf:
          - type: string
          - type: 'null'
          title: Event Ticker
        event_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Event Title
        volume:
          anyOf:
          - type: integer
          - type: 'null'
          title: Volume
        volume_24h:
          anyOf:
          - type: integer
          - type: 'null'
          title: Volume 24H
        series_ticker:
          anyOf:
          - type: string
          - type: 'null'
          title: Series Ticker
        image:
          anyOf:
          - type: string
          - type: 'null'
          title: Image
        last_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Last Price
          description: Most recent YES price normalized to 0.0–1.0 (probability). Kalshi cents / 100; Polymarket already 0.0–1.0. NULL when no trade has been observed.
        primary_entity_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Primary Entity Name
          description: Resolved display name of the canonical structured-target entity (player, team, competitor, …) referenced by the market. NULL for markets without a structured target. Kalshi only — Polymarket has no equivalent concept.
      type: object
      required:
      - river_id
      - exchange_value
      - exchange_name
      - tick_size_price
      - tick_size_qty
      - minimum_order_size
      - neg_risk
      - name
      - status
      title: MarketSearchResult
      description: Schema for a single market search result.
    WatchlistMemberAdd:
      properties:
        river_ids:
          items:
            type: integer
          type: array
          minItems: 1
          title: River Ids
      type: object
      required:
      - river_ids
      title: WatchlistMemberAdd
      description: Request schema for adding members to a watchlist (appended at the end).
  securitySchemes:
    SignedRequestKeyId:
      type: apiKey
      in: header
      name: X-River-Key-Id
      description: UUID of your API key (from Settings → API Keys).
    SignedRequestTimestamp:
      type: apiKey
      in: header
      name: X-River-Timestamp
      description: Current unix seconds. Must be within 30s of server time.
    SignedRequestSignature:
      type: apiKey
      in: header
      name: X-River-Signature
      description: 'Base64 Ed25519 signature over the canonical request: METHOD\nPATH\nSORTED_QUERY\nTIMESTAMP\nSHA256(body) hex. See /api-reference/authentication for the full recipe.'
    BearerAuth:
      type: http
      scheme: bearer
      description: JWT bearer token for web client authentication.