> ## 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.

# Trade

> Execute a trade via SDK.

Venues:
- venue="sim" (default): Execute on Simmer's LMSR market with $SIM
- venue="polymarket": Execute real trade on Polymarket via Dome API
  (requires wallet setup with allowances)
- venue="kalshi": Execute real trade on Kalshi via DFlow
  (requires Solana wallet setup with SOL + USDC)

Options:
- dry_run=True: Validate and calculate without executing. Returns the exact
  shares, projected price, and cost the live path would settle for.
  Supported on all venues: polymarket, kalshi, and sim (LMSR — closed-form
  cost-inversion guarantees dry_run.cost == live.cost within float
  precision). Useful for sizing budgets without committing the trade.

Deprecated: venue="sandbox"/"simmer" are deprecated, use venue="sim" instead.

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

<Note>Multi-outcome markets (e.g., "Who will win the election?") use a different contract type on Polymarket. This is auto-detected and handled server-side — no extra parameters needed.</Note>

<Warning>
  **Before selling, verify:**

  1. Market is active — resolved markets cannot be sold, use `/redeem` instead
  2. Shares >= 5 — Polymarket minimum per sell order
  3. Position exists on-chain — call `GET /positions` fresh before selling
  4. Use `shares` (not `amount`) for sells
</Warning>

<Note>The `source` tag groups trades for P\&L tracking and prevents accidental re-buys on markets you already hold. Use a consistent prefix like `sdk:strategy-name`.</Note>


## OpenAPI

````yaml /openapi.json post /api/sdk/trade
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/trade:
    post:
      tags:
        - sdk-trade
      summary: Trade
      description: >-
        Execute a trade via SDK.


        Venues:

        - venue="sim" (default): Execute on Simmer's LMSR market with $SIM

        - venue="polymarket": Execute real trade on Polymarket via Dome API
          (requires wallet setup with allowances)
        - venue="kalshi": Execute real trade on Kalshi via DFlow
          (requires Solana wallet setup with SOL + USDC)

        Options:

        - dry_run=True: Validate and calculate without executing. Returns the
        exact
          shares, projected price, and cost the live path would settle for.
          Supported on all venues: polymarket, kalshi, and sim (LMSR — closed-form
          cost-inversion guarantees dry_run.cost == live.cost within float
          precision). Useful for sizing budgets without committing the trade.

        Deprecated: venue="sandbox"/"simmer" are deprecated, use venue="sim"
        instead.


        Requires API key in Authorization header (rate limited: 120/minute).
      operationId: api_sdk_trade_api_sdk_trade_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SDKTradeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    SDKTradeRequest:
      properties:
        market_id:
          type: string
          title: Market Id
        side:
          type: string
          enum:
            - 'yes'
            - 'no'
          title: Side
        amount:
          type: number
          title: Amount
          default: 0
        shares:
          type: number
          title: Shares
          default: 0
        action:
          type: string
          enum:
            - buy
            - sell
          title: Action
          default: buy
        venue:
          type: string
          enum:
            - sim
            - simmer
            - sandbox
            - polymarket
            - kalshi
          title: Venue
          default: sim
        order_type:
          anyOf:
            - type: string
              enum:
                - GTC
                - GTD
                - FOK
                - FAK
            - type: 'null'
          title: Order Type
        execute:
          type: boolean
          title: Execute
          description: >-
            DEPRECATED. Legacy flag that returns Polymarket order params for
            client-side CLOB submission instead of executing the trade. YES side
            only — NO is not supported. Does not write to sim_trades and is
            incompatible with venue='sim'. Use venue='polymarket' for
            server-side execution (handles both managed and external wallets) or
            venue='sim' for sandbox trades.
          default: false
          deprecated: true
        reasoning:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
        skill_slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Skill Slug
        signal_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Signal Data
        dry_run:
          type: boolean
          title: Dry Run
          default: false
        price:
          anyOf:
            - type: number
            - type: 'null'
          title: Price
        synthetic:
          type: boolean
          title: Synthetic
          default: false
        signed_order:
          anyOf:
            - $ref: '#/components/schemas/SignedPolymarketOrder'
            - type: 'null'
        which_side_to_close:
          anyOf:
            - type: string
              enum:
                - 'yes'
                - 'no'
            - type: 'null'
          title: Which Side To Close
        wallet_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Wallet Address
      type: object
      required:
        - market_id
        - side
      title: SDKTradeRequest
      description: Request to execute a trade via SDK.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SignedPolymarketOrder:
      properties:
        salt:
          type: string
          title: Salt
        maker:
          type: string
          title: Maker
        signer:
          type: string
          title: Signer
        tokenId:
          type: string
          title: Tokenid
        makerAmount:
          type: string
          title: Makeramount
        takerAmount:
          type: string
          title: Takeramount
        side:
          type: string
          title: Side
        signatureType:
          type: integer
          title: Signaturetype
        signature:
          type: string
          title: Signature
        taker:
          anyOf:
            - type: string
            - type: 'null'
          title: Taker
        nonce:
          anyOf:
            - type: string
            - type: 'null'
          title: Nonce
        feeRateBps:
          anyOf:
            - type: string
            - type: 'null'
          title: Feeratebps
        timestamp:
          anyOf:
            - type: string
            - type: 'null'
          title: Timestamp
        metadata:
          anyOf:
            - type: string
            - type: 'null'
          title: Metadata
        builder:
          anyOf:
            - type: string
            - type: 'null'
          title: Builder
        expiration:
          anyOf:
            - type: string
            - type: 'null'
          title: Expiration
      type: object
      required:
        - salt
        - maker
        - signer
        - tokenId
        - makerAmount
        - takerAmount
        - side
        - signatureType
        - signature
      title: SignedPolymarketOrder
      description: |-
        Pre-signed Polymarket order from external wallet (client-side signing).

        Supports both V1 and V2 order shapes via optional fields. The frontend
        populates V1-or-V2 depending on its VITE_POLYMARKET_V2_ENABLED flag;
        the /polymarket/place-order-external handler routes based on
        exchange_version hint on the parent ExternalWalletOrderRequest (or
        infers from which fields are present).

        V1 uses: taker, expiration, nonce, feeRateBps (in signed hash)
        V2 uses: timestamp, metadata, builder (in signed hash); expiration
                 retained in HTTP body at "0" (out of signed hash)
    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

````