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

# Create a stop loss or take profit

> Watches the best bid for shares this key’s trading account holds on the request’s venue and sells them once it reaches the trigger price. A stop_loss sells when the bid falls to trigger_price or below; a take_profit sells when it rises to trigger_price or above. The sale fills no lower than trigger_price minus slippage_limit: it sells what it can at once, then rests the rest at that price until it fills, is canceled or expires. The stop losses on the same shares together sell at most what the account holds. The sale is booked as an order at trigger_price would be: it counts toward the rolling day and is held to the account’s venue allow list, but as a sale it only takes risk off, so no notional limit refuses it. On a test key the stop loss is recorded, listed and booked but never sells. Every venue runs stop losses and take profits.



## OpenAPI

````yaml api-reference/openapi.json POST /stop-losses
openapi: 3.0.0
info:
  title: Lean API
  version: 0.1.0
  description: >-
    Programmatic access to Lean: canonical sports markets, quotes, orders,
    positions and balances.
servers:
  - url: '{baseUrl}/v1'
    description: Lean API
    variables:
      baseUrl:
        default: https://api.lean.xyz
        description: >-
          The Lean API base URL, without /v1. Same value as LEAN_API_URL in the
          guides.
security:
  - apiKey: []
paths:
  /stop-losses:
    post:
      tags:
        - Stop losses
      summary: Create a stop loss or take profit
      description: >-
        Watches the best bid for shares this key’s trading account holds on the
        request’s venue and sells them once it reaches the trigger price. A
        stop_loss sells when the bid falls to trigger_price or below; a
        take_profit sells when it rises to trigger_price or above. The sale
        fills no lower than trigger_price minus slippage_limit: it sells what it
        can at once, then rests the rest at that price until it fills, is
        canceled or expires. The stop losses on the same shares together sell at
        most what the account holds. The sale is booked as an order at
        trigger_price would be: it counts toward the rolling day and is held to
        the account’s venue allow list, but as a sale it only takes risk off, so
        no notional limit refuses it. On a test key the stop loss is recorded,
        listed and booked but never sells. Every venue runs stop losses and take
        profits.
      operationId: createStopLoss
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                market_id:
                  type: string
                  minLength: 1
                  maxLength: 512
                  description: The market whose shares are sold.
                venue:
                  type: string
                  enum:
                    - kalshi
                    - polymarket
                    - polymarket_us
                    - hyperliquid
                  description: >-
                    The venue holding the shares to sell. Every venue runs stop
                    losses and take profits.
                type:
                  type: string
                  enum:
                    - stop_loss
                    - take_profit
                  description: >-
                    stop_loss sells once the best bid falls to trigger_price or
                    below; take_profit sells once it rises to trigger_price or
                    above.
                trigger_price:
                  type: string
                  description: >-
                    The best bid, in dollars per share between 0.0001 and
                    0.9999, that starts the sale. A stop_loss must be below the
                    current best bid and a take_profit above it, or the request
                    is refused, since the sale would start at once. A stop_loss
                    is also refused when the market has no bid.
                quantity:
                  type: string
                  pattern: ^\d+(?:\.\d+)?$
                  description: >-
                    Shares to sell. Together with the account’s other stop
                    losses on these shares, at most what the account holds.
                slippage_limit:
                  type: string
                  description: >-
                    How far below trigger_price the sale may fill, in dollars
                    above 0 and at most 0.2, on the market’s price tick and
                    below trigger_price. Defaults to 0.05.
                expires_at:
                  type: string
                  format: date-time
                  description: >-
                    When the stop loss lapses if it has not started selling.
                    Omit to keep it until canceled.
              required:
                - market_id
                - venue
                - type
                - trigger_price
                - quantity
              additionalProperties: false
            example:
              market_id: >-
                mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
              venue: polymarket
              type: stop_loss
              trigger_price: '0.4'
              quantity: '25'
              slippage_limit: '0.05'
      responses:
        '200':
          description: The stop loss, watching the market
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        enum:
                          - true
                      data:
                        type: object
                        properties:
                          id:
                            type: string
                            minLength: 1
                          market_id:
                            type: string
                            nullable: true
                            minLength: 1
                          venue:
                            type: string
                            enum:
                              - kalshi
                              - polymarket
                              - polymarket_us
                              - hyperliquid
                          ticker:
                            type: string
                            minLength: 1
                          side:
                            type: string
                            enum:
                              - 'yes'
                              - 'no'
                          type:
                            type: string
                            enum:
                              - stop_loss
                              - take_profit
                          trigger_price:
                            type: string
                          quantity:
                            type: string
                            pattern: ^\d+(?:\.\d+)?$
                          slippage_limit:
                            type: string
                          status:
                            type: string
                            enum:
                              - active
                              - triggered
                              - executing
                              - filled
                              - partial
                              - canceled
                              - expired
                              - failed
                          triggered_at:
                            type: string
                            nullable: true
                            format: date-time
                          triggered_price:
                            type: string
                            nullable: true
                          filled_quantity:
                            type: string
                            pattern: ^\d+(?:\.\d+)?$
                          avg_fill_price:
                            type: string
                            nullable: true
                          expires_at:
                            type: string
                            nullable: true
                            format: date-time
                          cancel_requested_at:
                            type: string
                            nullable: true
                            format: date-time
                            description: >-
                              When a cancel was asked for, or null. A live stop
                              loss keeps its status until Lean applies the
                              cancel a moment later, then reads canceled.
                          created_at:
                            type: string
                            format: date-time
                          updated_at:
                            type: string
                            format: date-time
                          livemode:
                            type: boolean
                        required:
                          - id
                          - market_id
                          - venue
                          - ticker
                          - side
                          - type
                          - trigger_price
                          - quantity
                          - slippage_limit
                          - status
                          - triggered_at
                          - triggered_price
                          - filled_quantity
                          - avg_fill_price
                          - expires_at
                          - cancel_requested_at
                          - created_at
                          - updated_at
                          - livemode
                      meta:
                        type: object
                        properties:
                          timestampMs:
                            type: integer
                            minimum: 0
                          requestId:
                            type: string
                            minLength: 1
                          traceId:
                            type: string
                            minLength: 1
                          cachedAtMs:
                            type: integer
                            minimum: 0
                          source:
                            type: string
                            enum:
                              - cache
                              - database
                              - clickhouse
                              - upstream
                              - fallback
                              - internal
                        required:
                          - timestampMs
                          - requestId
                    required:
                      - success
                      - data
                      - meta
                  - $ref: '#/components/schemas/ApiError'
              example:
                success: true
                data:
                  id: 3c9d2e71-5a4b-4f08-b6e2-91d7c0a4f5e3
                  market_id: >-
                    mkt_bmZsOjIwMjYtMTAtMTE6REVOLUxBQwpzcHJlYWQ6Z2FtZTpERU46LTMuNQpERU4
                  venue: polymarket
                  ticker: >-
                    pm:0x2222222222222222222222222222222222222222222222222222222222222222
                  side: 'yes'
                  type: stop_loss
                  trigger_price: '0.4'
                  quantity: '25'
                  slippage_limit: '0.05'
                  status: active
                  triggered_at: null
                  triggered_price: null
                  filled_quantity: '0'
                  avg_fill_price: null
                  expires_at: null
                  cancel_requested_at: null
                  created_at: '2026-11-10T15:00:00.000Z'
                  updated_at: '2026-11-10T15:00:00.000Z'
                  livemode: false
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '400':
          description: >-
            The prices, quantity or expiry are invalid for this market, the
            trigger price is one the best bid already meets (a stop_loss at or
            above it, or with no bid; a take_profit at or below it), or the
            quantity is more than the account holds beyond its other stop losses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: Invalid request
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '401':
          description: Missing, invalid, expired or revoked API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: UNAUTHORIZED
                  message: Invalid, expired or revoked API key
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '403':
          description: The key lacks the scope this route needs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: FORBIDDEN
                  message: This API key lacks the scope this route needs
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '404':
          description: API error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: NOT_FOUND
                  message: Not found
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '422':
          description: >-
            details.reason is NO_EXECUTABLE_VENUE, VENUE_NOT_ALLOWED,
            ORDER_NOTIONAL_LIMIT or DAILY_NOTIONAL_LIMIT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: Refused by a limit; nothing was changed
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '429':
          description: API error
          headers:
            Retry-After:
              description: Seconds remaining in the upstream read cooldown, when available
              schema:
                type: integer
                minimum: 0
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: RATE_LIMITED
                  message: Too many requests for this API key
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '500':
          description: API error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: INTERNAL_ERROR
                  message: An internal error occurred.
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '503':
          description: >-
            Trading is paused for this key or its trading account, Lean has
            paused stop losses on the venue, or the market’s book could not be
            read to check the trigger price
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: FEATURE_DISABLED
                  message: A required service is temporarily unavailable.
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
components:
  schemas:
    ApiError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - VALIDATION_ERROR
                - NOT_FOUND
                - UNAUTHORIZED
                - FORBIDDEN
                - CONFLICT
                - UPSTREAM_ERROR
                - RATE_LIMITED
                - INTERNAL_ERROR
                - FEATURE_DISABLED
                - CONDITIONAL_SELL_REJECTED
                - CONDITIONAL_SELL_ACTIVE
            message:
              type: string
              minLength: 1
            details:
              nullable: true
          required:
            - code
            - message
        meta:
          type: object
          properties:
            timestampMs:
              type: integer
              minimum: 0
            requestId:
              type: string
              minLength: 1
            traceId:
              type: string
              minLength: 1
            cachedAtMs:
              type: integer
              minimum: 0
            source:
              type: string
              enum:
                - cache
                - database
                - clickhouse
                - upstream
                - fallback
                - internal
          required:
            - timestampMs
            - requestId
      required:
        - success
        - error
        - meta
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        A Lean API key, sent as `Authorization: Bearer <key>`. A test key
        (`lean_sk_test_...`) simulates orders and fills with no money; a live
        key (`lean_sk_live_...`) trades for real within the key's limits. Every
        successful response says which mode answered in `data.livemode`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.