River Markets Positions API

openapi: 3.2.0
info:
  title: River Markets Positions 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: Positions
  description: View current portfolio positions across all connected exchanges.
paths:
  /v1/positions:
    get:
      tags:
      - Positions
      summary: Get Positions
      description: 'Fetch positions for user''s subaccounts.


        Positions are computed from cumulative fills, with avg buy/sell prices,

        fees, and fill count. Returns positions grouped by subaccount.

        By default, only positions in open markets are returned.'
      operationId: get_positions_v1_positions_get
      parameters:
      - name: subaccount_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Filter by specific subaccount
          title: Subaccount Id
        description: Filter by specific subaccount
      - name: river_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Filter by instrument
          title: River Id
        description: Filter by instrument
      - name: include_closed
        in: query
        required: false
        schema:
          type: boolean
          description: Include positions in closed markets
          default: false
          title: Include Closed
        description: Include positions in closed markets
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPositionListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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
    PositionResponse:
      properties:
        river_id:
          type: integer
          title: River Id
        position:
          type: number
          title: Position
        avg_buy_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Buy Price
        avg_sell_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Avg Sell Price
        total_fees:
          type: number
          title: Total Fees
        total_qty_bought:
          type: number
          title: Total Qty Bought
        total_qty_sold:
          type: number
          title: Total Qty Sold
        fill_count:
          type: integer
          title: Fill Count
        first_fill_at:
          type: string
          title: First Fill At
        last_fill_at:
          type: string
          title: Last Fill At
        exchange_name:
          type: string
          title: Exchange Name
        exchange_ticker:
          type: string
          title: Exchange Ticker
      type: object
      required:
      - river_id
      - position
      - total_fees
      - total_qty_bought
      - total_qty_sold
      - fill_count
      - first_fill_at
      - last_fill_at
      - exchange_name
      - exchange_ticker
      title: PositionResponse
      description: Schema for a position (computed from cumulative fills).
    UserPositionListResponse:
      properties:
        subaccount_to_positions:
          items:
            additionalProperties:
              anyOf:
              - type: string
              - items:
                  $ref: '#/components/schemas/PositionResponse'
                type: array
            type: object
          type: array
          title: Subaccount To Positions
      type: object
      required:
      - subaccount_to_positions
      title: UserPositionListResponse
      description: Positions grouped by subaccount.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  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.