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

# Context

> Get rich context for a market - gives skills "memory" between runs.

Composes data from:
- Market info (current price, price history, resolution time)
- Position data (shares, cost basis, P&L) — per venue, in `positions`
- Recent trades (last 5 trades with reasoning)
- Trading discipline (flip-flop detection, warnings)
- Slippage estimates (for different trade sizes)
- Edge analysis (time-adjusted threshold, recommendation)
- Warnings (time decay, low liquidity, etc.)

Optional query params:
- my_probability: Your probability estimate (0-1). If provided, returns edge
  calculation and TRADE/HOLD recommendation.
- venue: Which venue's positions to include. Default 'all'. The `positions`
  response field always contains per-venue breakdown. The flat `position`
  field mirrors the requested venue (or the first non-null one when
  venue='all'), for backwards compatibility.

An agent can hold positions on the same market across multiple venues
simultaneously (e.g., paper-trading on sim + real trading on Polymarket).
Use `positions.sim`, `positions.polymarket`, `positions.kalshi` to inspect
each independently.

Requires API key in Authorization header (rate limited: 300/minute).

<Tip>
  **Per-venue positions.** An agent can hold positions on the same market across multiple venues simultaneously (e.g., sim paper trade + real Polymarket position). The `positions` container has `sim`, `polymarket`, and `kalshi` fields — each is either `null` or a position object.

  Use `?venue=sim|polymarket|kalshi|all` to filter (default `all`). The flat `position` field is preserved for backwards compatibility and mirrors the first non-null venue.
</Tip>


## OpenAPI

````yaml /openapi.json get /api/sdk/context/{market_id}
openapi: 3.1.0
info:
  title: Simmer API
  description: Agent-native trading infrastructure for prediction markets.
  version: 1.0.0
servers:
  - url: https://api.simmer.markets
security: []
paths:
  /api/sdk/context/{market_id}:
    get:
      summary: Context
      description: >-
        Get rich context for a market - gives skills "memory" between runs.


        Composes data from:

        - Market info (current price, price history, resolution time)

        - Position data (shares, cost basis, P&L) — per venue, in `positions`

        - Recent trades (last 5 trades with reasoning)

        - Trading discipline (flip-flop detection, warnings)

        - Slippage estimates (for different trade sizes)

        - Edge analysis (time-adjusted threshold, recommendation)

        - Warnings (time decay, low liquidity, etc.)


        Optional query params:

        - my_probability: Your probability estimate (0-1). If provided, returns
        edge
          calculation and TRADE/HOLD recommendation.
        - venue: Which venue's positions to include. Default 'all'. The
        `positions`
          response field always contains per-venue breakdown. The flat `position`
          field mirrors the requested venue (or the first non-null one when
          venue='all'), for backwards compatibility.

        An agent can hold positions on the same market across multiple venues

        simultaneously (e.g., paper-trading on sim + real trading on
        Polymarket).

        Use `positions.sim`, `positions.polymarket`, `positions.kalshi` to
        inspect

        each independently.


        Requires API key in Authorization header (rate limited: 300/minute).
      operationId: api_sdk_context_api_sdk_context__market_id__get
      parameters:
        - name: market_id
          in: path
          required: true
          schema:
            type: string
            title: Market Id
        - name: my_probability
          in: query
          required: false
          schema:
            anyOf:
              - type: number
                maximum: 1
                minimum: 0
              - type: 'null'
            description: Your probability estimate (0-1) for edge calculation
            title: My Probability
          description: Your probability estimate (0-1) for edge calculation
        - name: venue
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Venue filter for position lookup: 'all' (default), 'sim',
              'polymarket', or 'kalshi'. Response always includes per-venue
              positions in the `positions` field.
            default: all
            title: Venue
          description: >-
            Venue filter for position lookup: 'all' (default), 'sim',
            'polymarket', or 'kalshi'. Response always includes per-venue
            positions in the `positions` field.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SDKContextResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SDKContextResponse:
      properties:
        market:
          $ref: '#/components/schemas/SDKContextMarket'
        position:
          $ref: '#/components/schemas/SDKContextPosition'
        positions:
          anyOf:
            - $ref: '#/components/schemas/SDKContextPositions'
            - type: 'null'
        recent_trades:
          items:
            $ref: '#/components/schemas/SDKContextTrade'
          type: array
          title: Recent Trades
          default: []
        discipline:
          $ref: '#/components/schemas/SDKContextDiscipline'
        slippage:
          anyOf:
            - $ref: '#/components/schemas/SDKContextSlippage'
            - type: 'null'
        edge:
          anyOf:
            - $ref: '#/components/schemas/SDKContextEdge'
            - type: 'null'
        warnings:
          items:
            type: string
          type: array
          title: Warnings
          default: []
      type: object
      required:
        - market
        - position
        - discipline
      title: SDKContextResponse
      description: Full SDK context response.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SDKContextMarket:
      properties:
        id:
          type: string
          title: Id
        question:
          type: string
          title: Question
        current_price:
          type: number
          title: Current Price
        current_probability:
          anyOf:
            - type: number
            - type: 'null'
          title: Current Probability
        price_1h_ago:
          anyOf:
            - type: number
            - type: 'null'
          title: Price 1H Ago
        price_24h_ago:
          anyOf:
            - type: number
            - type: 'null'
          title: Price 24H Ago
        volume_24h:
          anyOf:
            - type: number
            - type: 'null'
          title: Volume 24H
        resolves_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Resolves At
        time_to_resolution:
          anyOf:
            - type: string
            - type: 'null'
          title: Time To Resolution
        status:
          type: string
          title: Status
        resolution_criteria:
          anyOf:
            - type: string
            - type: 'null'
          title: Resolution Criteria
        ai_consensus:
          anyOf:
            - type: number
            - type: 'null'
          title: Ai Consensus
        external_price:
          anyOf:
            - type: number
            - type: 'null'
          title: External Price
        divergence:
          anyOf:
            - type: number
            - type: 'null'
          title: Divergence
        import_source:
          anyOf:
            - type: string
            - type: 'null'
          title: Import Source
        event_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Event Id
        event_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Event Name
        tags:
          items:
            type: string
          type: array
          title: Tags
          default: []
        is_paid:
          type: boolean
          title: Is Paid
          default: false
        fee_rate_bps:
          type: integer
          title: Fee Rate Bps
          default: 0
        fee_note:
          anyOf:
            - type: string
            - type: 'null'
          title: Fee Note
        spread:
          anyOf:
            - type: number
            - type: 'null'
          title: Spread
      type: object
      required:
        - id
        - question
        - current_price
        - status
      title: SDKContextMarket
      description: Market info for SDK context.
    SDKContextPosition:
      properties:
        has_position:
          type: boolean
          title: Has Position
        side:
          anyOf:
            - type: string
            - type: 'null'
          title: Side
        shares:
          type: number
          title: Shares
          default: 0
        avg_cost_basis:
          anyOf:
            - type: number
            - type: 'null'
          title: Avg Cost Basis
        current_value:
          type: number
          title: Current Value
          default: 0
        unrealized_pnl:
          type: number
          title: Unrealized Pnl
          default: 0
        pnl_pct:
          type: number
          title: Pnl Pct
          default: 0
        position_age_hours:
          anyOf:
            - type: number
            - type: 'null'
          title: Position Age Hours
      type: object
      required:
        - has_position
      title: SDKContextPosition
      description: Position info for SDK context.
    SDKContextPositions:
      properties:
        sim:
          anyOf:
            - $ref: '#/components/schemas/SDKContextPosition'
            - type: 'null'
        polymarket:
          anyOf:
            - $ref: '#/components/schemas/SDKContextPosition'
            - type: 'null'
        kalshi:
          anyOf:
            - $ref: '#/components/schemas/SDKContextPosition'
            - type: 'null'
      type: object
      title: SDKContextPositions
      description: |-
        Per-venue positions for a single market.

        An agent can hold positions on the same market across multiple venues
        simultaneously (sim paper-trading + real Polymarket/Kalshi). Each
        field is populated independently based on that venue's position storage:
        - sim: from agent_market_positions
        - polymarket: aggregated from real_trades (venue='polymarket')
        - kalshi: aggregated from real_trades (venue='kalshi')

        Fields are None when no position exists on that venue.
    SDKContextTrade:
      properties:
        action:
          type: string
          title: Action
        shares:
          type: number
          title: Shares
        price:
          type: number
          title: Price
        timestamp:
          type: string
          title: Timestamp
        reasoning:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning
      type: object
      required:
        - action
        - shares
        - price
        - timestamp
      title: SDKContextTrade
      description: Recent trade for SDK context.
    SDKContextDiscipline:
      properties:
        last_action:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Action
        last_action_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Action At
        direction_changes_24h:
          type: integer
          title: Direction Changes 24H
          default: 0
        flip_flop_warning:
          anyOf:
            - type: string
            - type: 'null'
          title: Flip Flop Warning
        warning_level:
          type: string
          title: Warning Level
          default: none
      type: object
      title: SDKContextDiscipline
      description: Trading discipline info for SDK context.
    SDKContextSlippage:
      properties:
        venue:
          type: string
          title: Venue
        spread_pct:
          type: number
          title: Spread Pct
          default: 0
        estimates:
          items:
            $ref: '#/components/schemas/SDKContextSlippageEstimate'
          type: array
          title: Estimates
          default: []
      type: object
      required:
        - venue
      title: SDKContextSlippage
      description: Slippage info for SDK context.
    SDKContextEdge:
      properties:
        suggested_threshold:
          type: number
          title: Suggested Threshold
        base_threshold:
          type: number
          title: Base Threshold
          default: 0.05
        time_factor:
          type: number
          title: Time Factor
          default: 1
        user_probability:
          anyOf:
            - type: number
            - type: 'null'
          title: User Probability
        user_edge:
          anyOf:
            - type: number
            - type: 'null'
          title: User Edge
        recommended_side:
          anyOf:
            - type: string
            - type: 'null'
          title: Recommended Side
        recommendation:
          anyOf:
            - type: string
            - type: 'null'
          title: Recommendation
      type: object
      required:
        - suggested_threshold
      title: SDKContextEdge
      description: >-
        Edge analysis for trading decisions.


        Helps skills determine if a trade is worth making based on:

        - suggested_threshold: Time-adjusted minimum edge (higher = more
        conservative)

        - user_edge: Calculated edge if user provided their probability estimate

        - recommendation: TRADE / HOLD / SKIP based on edge vs threshold
    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
    SDKContextSlippageEstimate:
      properties:
        amount_usd:
          type: number
          title: Amount Usd
        shares:
          type: number
          title: Shares
        avg_price:
          type: number
          title: Avg Price
        slippage_pct:
          type: number
          title: Slippage Pct
      type: object
      required:
        - amount_usd
        - shares
        - avg_price
        - slippage_pct
      title: SDKContextSlippageEstimate
      description: Slippage estimate for a trade size.

````