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

# Withdraw cash

> Withdraws cash from one venue of this key’s trading account to the address the request names. The request names the source venue and the asset it holds, the destination chain, asset and address, and the amount of the source asset. Each venue pays out one asset as usdc, on any chain that destination.chain lists: pusd on Polymarket and usdc on Hyperliquid. Any other pair of assets is refused with a 400. The key needs the withdraw scope, and each withdrawal must fit the key’s optional per withdrawal limit, its optional limit across the last 24 hours and the venue’s available cash. The venue’s fee comes out of the amount: the response gives the fee and the net amount the destination is quoted to receive. A live withdrawal needs trading enabled for the account in the Lean app and is submitted once: it starts pending and becomes completed or failed as the venue settles it, with failure_reason saying why a failed one paid nothing. A Polymarket withdrawal is completed once the funds leave the account for Polymarket’s bridge, which then pays the USDC on the destination chain; a Hyperliquid withdrawal is completed once the USDC arrives on the destination chain. A test withdrawal moves nothing, charges no fee, completes at once and lowers the simulated cash on that venue until test mode is reset. Sending the same client_withdrawal_id again returns the withdrawal already made.



## OpenAPI

````yaml api-reference/openapi.json POST /withdrawals
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:
  /withdrawals:
    post:
      tags:
        - Withdrawals
      summary: Withdraw cash
      description: >-
        Withdraws cash from one venue of this key’s trading account to the
        address the request names. The request names the source venue and the
        asset it holds, the destination chain, asset and address, and the amount
        of the source asset. Each venue pays out one asset as usdc, on any chain
        that destination.chain lists: pusd on Polymarket and usdc on
        Hyperliquid. Any other pair of assets is refused with a 400. The key
        needs the withdraw scope, and each withdrawal must fit the key’s
        optional per withdrawal limit, its optional limit across the last 24
        hours and the venue’s available cash. The venue’s fee comes out of the
        amount: the response gives the fee and the net amount the destination is
        quoted to receive. A live withdrawal needs trading enabled for the
        account in the Lean app and is submitted once: it starts pending and
        becomes completed or failed as the venue settles it, with failure_reason
        saying why a failed one paid nothing. A Polymarket withdrawal is
        completed once the funds leave the account for Polymarket’s bridge,
        which then pays the USDC on the destination chain; a Hyperliquid
        withdrawal is completed once the USDC arrives on the destination chain.
        A test withdrawal moves nothing, charges no fee, completes at once and
        lowers the simulated cash on that venue until test mode is reset.
        Sending the same client_withdrawal_id again returns the withdrawal
        already made.
      operationId: createWithdrawal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source:
                  type: object
                  properties:
                    venue:
                      type: string
                      enum:
                        - polymarket
                        - hyperliquid
                      description: The venue whose cash is withdrawn.
                    asset:
                      type: string
                      enum:
                        - pusd
                        - usdc
                      description: >-
                        The asset the venue holds the cash in: pusd on
                        Polymarket, usdc on Hyperliquid.
                  required:
                    - venue
                    - asset
                  additionalProperties: false
                destination:
                  type: object
                  properties:
                    chain:
                      type: string
                      enum:
                        - polygon
                        - arbitrum
                        - base
                        - optimism
                        - ethereum
                        - bsc
                        - solana
                      description: >-
                        The chain the cash is paid out on. Every venue pays out
                        on each of these chains.
                    asset:
                      type: string
                      enum:
                        - pusd
                        - usdc
                      description: The asset the destination receives.
                    address:
                      type: string
                      maxLength: 44
                      description: >-
                        The address that receives the cash: a Solana address on
                        solana, a 0x address on any other chain.
                  required:
                    - chain
                    - asset
                    - address
                  additionalProperties: false
                amount:
                  type: string
                  description: >-
                    How much of the source asset to withdraw, with at most 6
                    decimal places. The fee comes out of this amount.
                client_withdrawal_id:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{1,64}$
                  description: >-
                    Your id for this withdrawal, unique per key. Sending the
                    same request again returns the withdrawal already made
                    instead of making another.
              required:
                - source
                - destination
                - amount
                - client_withdrawal_id
              additionalProperties: false
            example:
              source:
                venue: polymarket
                asset: pusd
              destination:
                chain: polygon
                asset: usdc
                address: '0x00000000000000000000000000000000000000a1'
              amount: '25'
              client_withdrawal_id: payout-0001
      responses:
        '200':
          description: The withdrawal
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        enum:
                          - true
                      data:
                        type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                          source:
                            type: object
                            properties:
                              venue:
                                type: string
                                enum:
                                  - polymarket
                                  - hyperliquid
                                description: The venue whose cash is withdrawn.
                              asset:
                                type: string
                                enum:
                                  - pusd
                                  - usdc
                                description: >-
                                  The asset the venue holds the cash in: pusd on
                                  Polymarket, usdc on Hyperliquid.
                            required:
                              - venue
                              - asset
                            additionalProperties: false
                          destination:
                            type: object
                            properties:
                              chain:
                                type: string
                                enum:
                                  - polygon
                                  - arbitrum
                                  - base
                                  - optimism
                                  - ethereum
                                  - bsc
                                  - solana
                                description: >-
                                  The chain the cash is paid out on. Every venue
                                  pays out on each of these chains.
                              asset:
                                type: string
                                enum:
                                  - pusd
                                  - usdc
                                description: The asset the destination receives.
                              address:
                                type: string
                                maxLength: 44
                                description: >-
                                  The address that receives the cash: a Solana
                                  address on solana, a 0x address on any other
                                  chain.
                            required:
                              - chain
                              - asset
                              - address
                            additionalProperties: false
                          amount:
                            type: string
                            minLength: 1
                            description: How much of the source asset was withdrawn.
                          fee:
                            type: string
                            minLength: 1
                            description: >-
                              What the venue's payout quote took from the amount
                              when the withdrawal was made. Zero for a test
                              withdrawal.
                          net_amount:
                            type: string
                            minLength: 1
                            description: >-
                              What the destination was quoted to receive: the
                              amount less the fee, in the destination asset.
                          status:
                            type: string
                            enum:
                              - pending
                              - completed
                              - failed
                            description: >-
                              pending until the venue settles the payment, then
                              completed, or failed when nothing was paid out. A
                              test withdrawal is completed at once.
                          failure_reason:
                            type: string
                            nullable: true
                            description: >-
                              Why a failed withdrawal did not pay out. Null
                              unless status is failed.
                          client_withdrawal_id:
                            type: string
                            minLength: 1
                          created_at:
                            type: string
                            format: date-time
                          livemode:
                            type: boolean
                        required:
                          - id
                          - source
                          - destination
                          - amount
                          - fee
                          - net_amount
                          - status
                          - failure_reason
                          - client_withdrawal_id
                          - created_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: 8f14e45f-ceea-4672-a5b0-6f1c9d2b7a31
                  source:
                    venue: polymarket
                    asset: pusd
                  destination:
                    chain: polygon
                    asset: usdc
                    address: '0x00000000000000000000000000000000000000a1'
                  amount: '25'
                  fee: '0.12'
                  net_amount: '24.88'
                  status: completed
                  failure_reason: null
                  client_withdrawal_id: payout-0001
                  created_at: '2026-11-10T15:00:00.000Z'
                  livemode: true
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '400':
          description: >-
            The request is invalid, names an unsupported source and destination
            pair, or the venue cannot pay this withdrawal out
          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 withdraw scope, or details.reason is
            ACCOUNT_NOT_DELEGATED
          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
        '409':
          description: >-
            client_withdrawal_id was already used with a different request, the
            venue wallet is not set up, or details.reason is
            WITHDRAWAL_IN_PROGRESS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: CONFLICT
                  message: The request conflicts with the current state
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '422':
          description: >-
            details.reason is WITHDRAWAL_LIMIT_EXCEEDED,
            DAILY_WITHDRAWAL_LIMIT_EXCEEDED or INSUFFICIENT_BALANCE
          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, or the venue
            is unavailable and nothing was paid
          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.