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

> Creates a transfer of cash from one venue of this key’s trading account to the account’s own balance on the other venue. Transfers are simulated against test cash for test keys; live keys are refused with LIVE_TRANSFERS_UNAVAILABLE. Nothing moves until the transfer is executed with the owner’s signatures over `authorization.payloads` or the account’s delegated signer. The amount must be at least the route minimum, fit what the sending venue holds and fit the per order and rolling 24 hour limits of the key and the account. Sending the same client_transfer_id again returns the transfer already created.



## OpenAPI

````yaml api-reference/openapi.json POST /transfers
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:
  /transfers:
    post:
      tags:
        - Transfers
      summary: Create a transfer
      description: >-
        Creates a transfer of cash from one venue of this key’s trading account
        to the account’s own balance on the other venue. Transfers are simulated
        against test cash for test keys; live keys are refused with
        LIVE_TRANSFERS_UNAVAILABLE. Nothing moves until the transfer is executed
        with the owner’s signatures over `authorization.payloads` or the
        account’s delegated signer. The amount must be at least the route
        minimum, fit what the sending venue holds and fit the per order and
        rolling 24 hour limits of the key and the account. Sending the same
        client_transfer_id again returns the transfer already created.
      operationId: createTransfer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from_venue:
                  type: string
                  enum:
                    - polymarket
                    - hyperliquid
                  description: The venue the cash leaves.
                to_venue:
                  type: string
                  enum:
                    - polymarket
                    - hyperliquid
                  description: >-
                    The venue the cash arrives on, credited to this trading
                    account’s own balance there.
                amount_usd:
                  type: string
                  description: >-
                    How much leaves from_venue, in dollars, with at most 6
                    decimal places.
                client_transfer_id:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{1,64}$
                  description: >-
                    Your id for this transfer, unique per key. Sending the same
                    request again returns the transfer already created instead
                    of creating another.
              required:
                - from_venue
                - to_venue
                - amount_usd
                - client_transfer_id
              additionalProperties: false
            example:
              from_venue: polymarket
              to_venue: hyperliquid
              amount_usd: '25'
              client_transfer_id: rebalance-0001
      responses:
        '200':
          description: The transfer
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      success:
                        type: boolean
                        enum:
                          - true
                      data:
                        type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                          client_transfer_id:
                            type: string
                            minLength: 1
                          from_venue:
                            type: string
                            enum:
                              - polymarket
                              - hyperliquid
                          to_venue:
                            type: string
                            enum:
                              - polymarket
                              - hyperliquid
                          amount_usd:
                            type: string
                            minLength: 1
                          fee_usd:
                            type: string
                            minLength: 1
                          receive_usd:
                            type: string
                            minLength: 1
                          status:
                            type: string
                            enum:
                              - awaiting_authorization
                              - pending
                              - completed
                              - failed
                              - expired
                          failure_reason:
                            type: string
                            nullable: true
                          authorization:
                            type: object
                            nullable: true
                            properties:
                              signer_address:
                                type: string
                                pattern: ^0x[a-fA-F0-9]{40}$
                              expires_at:
                                type: string
                                format: date-time
                              payloads:
                                type: array
                                items:
                                  oneOf:
                                    - type: object
                                      properties:
                                        scheme:
                                          type: string
                                          enum:
                                            - lean_test_transfer
                                        typed_data:
                                          type: object
                                          properties:
                                            domain:
                                              type: object
                                              properties:
                                                name:
                                                  type: string
                                                  enum:
                                                    - Lean API test transfer
                                                version:
                                                  type: string
                                                  enum:
                                                    - '1'
                                              required:
                                                - name
                                                - version
                                            types:
                                              type: object
                                              additionalProperties:
                                                type: array
                                                items:
                                                  type: object
                                                  properties:
                                                    name:
                                                      type: string
                                                    type:
                                                      type: string
                                                  required:
                                                    - name
                                                    - type
                                            primaryType:
                                              type: string
                                              enum:
                                                - Transfer
                                            message:
                                              type: object
                                              properties:
                                                transferId:
                                                  type: string
                                                  format: uuid
                                                nonce:
                                                  type: string
                                                  pattern: ^0x[a-fA-F0-9]{64}$
                                                fromVenue:
                                                  type: string
                                                  enum:
                                                    - polymarket
                                                    - hyperliquid
                                                toVenue:
                                                  type: string
                                                  enum:
                                                    - polymarket
                                                    - hyperliquid
                                                amountMicros:
                                                  type: string
                                                  pattern: ^\d+$
                                                expiresAt:
                                                  type: string
                                                  pattern: ^\d+$
                                              required:
                                                - transferId
                                                - nonce
                                                - fromVenue
                                                - toVenue
                                                - amountMicros
                                                - expiresAt
                                          required:
                                            - domain
                                            - types
                                            - primaryType
                                            - message
                                      required:
                                        - scheme
                                        - typed_data
                                minItems: 1
                            required:
                              - signer_address
                              - expires_at
                              - payloads
                          created_at:
                            type: string
                            format: date-time
                          updated_at:
                            type: string
                            format: date-time
                          livemode:
                            type: boolean
                        required:
                          - id
                          - client_transfer_id
                          - from_venue
                          - to_venue
                          - amount_usd
                          - fee_usd
                          - receive_usd
                          - status
                          - failure_reason
                          - authorization
                          - 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: 4b1d2c3e-5f60-4718-8a9b-0c1d2e3f4a5b
                  client_transfer_id: rebalance-0001
                  from_venue: polymarket
                  to_venue: hyperliquid
                  amount_usd: '25'
                  fee_usd: '0.1'
                  receive_usd: '24.9'
                  status: awaiting_authorization
                  failure_reason: null
                  authorization:
                    signer_address: '0x00000000000000000000000000000000000000a1'
                    expires_at: '2026-11-11T15:02:00.000Z'
                    payloads:
                      - scheme: lean_test_transfer
                        typed_data:
                          domain:
                            name: Lean API test transfer
                            version: '1'
                          types:
                            Transfer:
                              - name: transferId
                                type: string
                              - name: nonce
                                type: bytes32
                              - name: fromVenue
                                type: string
                              - name: toVenue
                                type: string
                              - name: amountMicros
                                type: uint256
                              - name: expiresAt
                                type: uint256
                          primaryType: Transfer
                          message:
                            transferId: 4b1d2c3e-5f60-4718-8a9b-0c1d2e3f4a5b
                            nonce: >-
                              0x1111111111111111111111111111111111111111111111111111111111111111
                            fromVenue: polymarket
                            toVenue: hyperliquid
                            amountMicros: '25000000'
                            expiresAt: '1794409320'
                  created_at: '2026-11-11T15:00:00.000Z'
                  updated_at: '2026-11-11T15:00:00.000Z'
                  livemode: false
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '400':
          description: >-
            Same venue twice, an unknown venue, an unknown field or an invalid
            amount
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: VALIDATION_ERROR
                  message: >-
                    Same venue twice, an unknown venue, an unknown field or an
                    invalid amount
                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 trade or route scope
          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_transfer_id was already used with a different request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                success: false
                error:
                  code: CONFLICT
                  message: client_transfer_id was already used with a different request
                meta:
                  timestampMs: 1792771200000
                  requestId: 7d2c9f4e-1b3a-4e8d-9c6f-2a5b8e0d4f17
        '422':
          description: >-
            details.reason is BELOW_VENUE_MINIMUM, INSUFFICIENT_FUNDS,
            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: >-
            details.reason is LIVE_TRANSFERS_UNAVAILABLE for a live key, or
            TRADING_PAUSED
          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.