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

# Create LSPS1 order

> Create an LSPS1 channel order. When the client is purchasing assets, a fresh `rfq_id` must be supplied and is extended to remain valid through the payment window. The response includes a per-order `access_token` for later polling or rate decisions. Treat this call as non-idempotent.



## OpenAPI

````yaml /openapi.json post /api/v1/lsps1/create_order
openapi: 3.1.0
info:
  title: Kaleidoswap RGB-LSP API
  summary: Public KaleidoSwap Maker API contract
  description: >-
    Public Maker API for KaleidoSwap market data, quotes, atomic swaps, and RGB
    LSPS1

    channel operations.


    Maker endpoints support Bearer API-key authentication. During rollout,

    deployments may accept anonymous requests while attribution is collected;
    once

    API-key enforcement is enabled, requests without a valid `kld_...` key
    return

    `401`.


    Use the per-order `access_token` returned by LSPS1 channel-order creation
    when

    polling protected order status endpoints or submitting a rate decision after
    the

    maker requests client confirmation.
  version: 0.2.0
  termsOfService: https://kaleidoswap.com/terms
  contact:
    name: Kaleidoswap Team
    email: info@kaleidoswap.com
    url: https://kaleidoswap.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  x-support:
    email: contact@kaleidoswap.com
    documentation: https://docs.kaleidoswap.com/api-reference/introduction
  x-build-info:
    version: archive/settlement-backends-pre-removal-7-gb8788aa2
    commit: b8788aa257ea4a01ac0dffc1826cf3bcf1caf09f
    buildDate: '2026-08-05T09:57:35.455127+00:00'
servers:
  - url: http://localhost:8000
    description: Local development
security: []
tags:
  - name: lsps1
    description: >-
      RGB LSPS1 liquidity endpoints for capability discovery, channel-order
      creation, fee estimation, order tracking, rate decisions, and asset
      delivery retries.
  - name: market
    description: >-
      Public market discovery APIs for assets, trading pairs, routes, and
      RFQ-based quote requests.
  - name: swaps
    description: >-
      Atomic swap APIs used by direct RLN integrations to initialize, execute,
      and track swaps.
paths:
  /api/v1/lsps1/create_order:
    post:
      tags:
        - lsps1
      summary: Create LSPS1 order
      description: >-
        Create an LSPS1 channel order. When the client is purchasing assets, a
        fresh `rfq_id` must be supplied and is extended to remain valid through
        the payment window. The response includes a per-order `access_token` for
        later polling or rate decisions. Treat this call as non-idempotent.
      operationId: createLspOrder
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            examples:
              asset_purchase:
                summary: Create LSPS1 order with asset purchase
                value:
                  client_pubkey: >-
                    03e7156ae33b0a208d0744199163177e909e80176e55d97a2f221ede0f934dd9ad
                  lsp_balance_sat: 150000
                  client_balance_sat: 50000
                  required_channel_confirmations: 3
                  funding_confirms_within_blocks: 144
                  channel_expiry_blocks: 4032
                  announce_channel: true
                  asset_id: rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB
                  client_asset_amount: 2500
                  rfq_id: 8e6635fb-ab37-4aed-89f4-bc9c98fb8b49
                  refund_onchain_address: tb1qexampleaddress0000000000000000000000000
                  email: ops@kaleidoswap.com
      responses:
        '200':
          description: LSPS1 order created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChannelOrderResponse'
              example:
                order_id: 550e8400-e29b-41d4-a716-446655440000
                client_pubkey: >-
                  03e7156ae33b0a208d0744199163177e909e80176e55d97a2f221ede0f934dd9ad
                lsp_balance_sat: 150000
                client_balance_sat: 50000
                required_channel_confirmations: 3
                funding_confirms_within_blocks: 144
                channel_expiry_blocks: 4032
                token: ''
                created_at: '2026-03-11T12:00:00Z'
                announce_channel: true
                order_state: CREATED
                payment:
                  bolt11:
                    state: EXPECT_PAYMENT
                    expires_at: '2026-03-11T12:15:00Z'
                    fee_total_sat: 500
                    order_total_sat: 50500
                    invoice: lnbc1example
                  onchain:
                    state: EXPECT_PAYMENT
                    expires_at: '2026-03-11T12:15:00Z'
                    fee_total_sat: 500
                    order_total_sat: 50500
                    address: tb1qmakerdeposit0000000000000000000000000
                    min_fee_for_0conf: 253
                    min_onchain_payment_confirmations: 0
                    refund_onchain_address: tb1qexampleaddress0000000000000000000000000
                asset_id: rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB
                client_asset_amount: 2500
                rfq_id: 8e6635fb-ab37-4aed-89f4-bc9c98fb8b49
                access_token: ord_live_3rCkP9dG7mN4
        '400':
          description: The LSPS1 parameters, quote, or access constraints are invalid.
          content:
            application/json:
              example:
                error_code: LSPS1_INVALID_PARAMS
                message: >-
                  RFQ ID is required when purchasing assets (client_asset_amount
                  > 0). Please request a quote first.
                details:
                  code: -32602
                  property: rfq_id
                  message: >-
                    RFQ ID is required when purchasing assets
                    (client_asset_amount > 0). Please request a quote first.
                request_id: req_01HV8Q9X7G0Q7Y3Z
              schema:
                $ref: '#/components/schemas/KaleidoErrorResponse'
        '401':
          description: Missing or invalid Bearer API key.
          content:
            application/json:
              example:
                error: missing_api_key
              schema:
                $ref: '#/components/schemas/ApiKeyAuthErrorResponse'
        '404':
          description: The referenced asset was not found.
          content:
            application/json:
              example:
                error_code: ASSET_NOT_FOUND
                message: 'Asset not found: rgb:unknown'
                details: {}
                request_id: req_01HV8Q9X7G0Q7Y3Z
              schema:
                $ref: '#/components/schemas/KaleidoErrorResponse'
        '422':
          description: Request validation failed before reaching application logic.
          content:
            application/json:
              example:
                detail:
                  - loc:
                      - body
                      - rfq_id
                    msg: Field required
                    type: missing
              schema:
                $ref: '#/components/schemas/FastAPIValidationErrorResponse'
        '429':
          description: Too many requests. Respect the rate-limit headers before retrying.
          content:
            application/json:
              example:
                error_code: RATE_LIMIT_EXCEEDED
                message: Too many requests
                details:
                  retry_after: 60
                request_id: req_01HV8Q9X7G0Q7Y3Z
              schema:
                $ref: '#/components/schemas/KaleidoErrorResponse'
        '500':
          description: Unhandled server error.
          content:
            application/json:
              example:
                error_code: INTERNAL_ERROR
                message: Internal Server Error
                details: {}
                request_id: req_01HV8Q9X7G0Q7Y3Z
              schema:
                $ref: '#/components/schemas/KaleidoErrorResponse'
        '503':
          description: The backing LSP node or required service is unavailable.
          content:
            application/json:
              example:
                error_code: LSPS1_NODE_UNREACHABLE
                message: LSP node unreachable
                details:
                  code: 102
                  message: LSP node is unreachable
                request_id: req_01HV8Q9X7G0Q7Y3Z
              schema:
                $ref: '#/components/schemas/KaleidoErrorResponse'
      security:
        - KaleidoApiKey: []
components:
  schemas:
    CreateOrderRequest:
      properties:
        client_pubkey:
          type: string
          title: Client Pubkey
        lsp_balance_sat:
          type: integer
          minimum: 0
          title: Lsp Balance Sat
        client_balance_sat:
          type: integer
          minimum: 0
          title: Client Balance Sat
        required_channel_confirmations:
          type: integer
          minimum: 0
          title: Required Channel Confirmations
        funding_confirms_within_blocks:
          type: integer
          minimum: 1
          title: Funding Confirms Within Blocks
        channel_expiry_blocks:
          type: integer
          minimum: 1
          title: Channel Expiry Blocks
        token:
          anyOf:
            - type: string
            - type: 'null'
          title: Token
        refund_onchain_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Refund Onchain Address
        announce_channel:
          type: boolean
          title: Announce Channel
          default: true
        asset_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Asset Id
        lsp_asset_amount:
          anyOf:
            - type: integer
            - type: 'null'
          title: Lsp Asset Amount
        client_asset_amount:
          anyOf:
            - type: integer
            - type: 'null'
          title: Client Asset Amount
        rfq_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Rfq Id
        email:
          anyOf:
            - type: string
              format: email
            - type: 'null'
          title: Email
          description: Optional email for notifications
      type: object
      required:
        - client_pubkey
        - lsp_balance_sat
        - client_balance_sat
        - required_channel_confirmations
        - funding_confirms_within_blocks
        - channel_expiry_blocks
      title: CreateOrderRequest
      example:
        announce_channel: true
        asset_id: rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB
        channel_expiry_blocks: 4032
        client_asset_amount: 2500
        client_balance_sat: 50000
        client_pubkey: 03e7156ae33b0a208d0744199163177e909e80176e55d97a2f221ede0f934dd9ad
        email: ops@kaleidoswap.com
        funding_confirms_within_blocks: 144
        lsp_balance_sat: 150000
        refund_onchain_address: tb1qexampleaddress0000000000000000000000000
        required_channel_confirmations: 3
        rfq_id: 8e6635fb-ab37-4aed-89f4-bc9c98fb8b49
    ChannelOrderResponse:
      properties:
        order_id:
          type: string
          title: Order Id
        client_pubkey:
          type: string
          title: Client Pubkey
        lsp_balance_sat:
          type: integer
          title: Lsp Balance Sat
        client_balance_sat:
          type: integer
          title: Client Balance Sat
        required_channel_confirmations:
          type: integer
          title: Required Channel Confirmations
        funding_confirms_within_blocks:
          type: integer
          title: Funding Confirms Within Blocks
        channel_expiry_blocks:
          type: integer
          title: Channel Expiry Blocks
        token:
          anyOf:
            - type: string
            - type: 'null'
          title: Token
          default: ''
        created_at:
          type: string
          format: date-time
          title: Created At
        announce_channel:
          type: boolean
          title: Announce Channel
        order_state:
          $ref: '#/components/schemas/OrderState'
        payment:
          $ref: '#/components/schemas/PaymentDetails'
        channel:
          anyOf:
            - $ref: '#/components/schemas/ChannelDetails'
            - type: 'null'
        asset_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Asset Id
        lsp_asset_amount:
          anyOf:
            - type: integer
            - type: 'null'
          title: Lsp Asset Amount
        client_asset_amount:
          anyOf:
            - type: integer
            - type: 'null'
          title: Client Asset Amount
        rfq_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Rfq Id
        asset_price_sat:
          anyOf:
            - type: integer
            - type: 'null'
          title: Asset Price Sat
        failure_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Failure Reason
        access_token:
          anyOf:
            - type: string
            - type: 'null'
          title: Access Token
      type: object
      required:
        - order_id
        - client_pubkey
        - lsp_balance_sat
        - client_balance_sat
        - required_channel_confirmations
        - funding_confirms_within_blocks
        - channel_expiry_blocks
        - announce_channel
        - order_state
        - payment
      title: ChannelOrderResponse
    KaleidoErrorResponse:
      properties:
        error_code:
          type: string
          title: Error Code
          description: Stable machine-readable application error code
          examples:
            - PAIR_NOT_FOUND
        message:
          type: string
          title: Message
          description: Human-readable error message
          examples:
            - 'Trading pair not found: BTC/USDT'
        details:
          additionalProperties: true
          type: object
          title: Details
          description: Optional structured error details
        request_id:
          type: string
          title: Request Id
          description: Request correlation identifier for support and debugging
          examples:
            - req_01HV8Q9X7G0Q7Y3Z
      type: object
      required:
        - error_code
        - message
        - request_id
      title: KaleidoErrorResponse
    ApiKeyAuthErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: API-key authentication error code
          examples:
            - missing_api_key
            - invalid_api_key
      type: object
      required:
        - error
      title: ApiKeyAuthErrorResponse
    FastAPIValidationErrorResponse:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationErrorDetail'
          type: array
          title: Detail
      type: object
      required:
        - detail
      title: FastAPIValidationErrorResponse
    OrderState:
      type: string
      enum:
        - CREATED
        - CHANNEL_OPENING
        - COMPLETED
        - FAILED
        - PENDING_RATE_DECISION
      title: OrderState
    PaymentDetails:
      properties:
        bolt11:
          $ref: '#/components/schemas/PaymentBolt11'
        onchain:
          $ref: '#/components/schemas/PaymentOnchain'
      type: object
      required:
        - bolt11
        - onchain
      title: PaymentDetails
    ChannelDetails:
      properties:
        channel_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Channel Id
        temporary_channel_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Temporary Channel Id
        funded_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Funded At
        funding_outpoint:
          anyOf:
            - type: string
            - type: 'null'
          title: Funding Outpoint
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Expires At
      type: object
      title: ChannelDetails
    ValidationErrorDetail:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Loc
          description: Location of the validation failure
          examples:
            - - body
              - rfq_id
        msg:
          type: string
          title: Msg
          description: Validation error message
          examples:
            - Field required
        type:
          type: string
          title: Type
          description: FastAPI/Pydantic validation error type
          examples:
            - missing
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationErrorDetail
    PaymentBolt11:
      properties:
        state:
          $ref: '#/components/schemas/PaymentState'
        expires_at:
          type: string
          format: date-time
          title: Expires At
        fee_total_sat:
          type: integer
          title: Fee Total Sat
        order_total_sat:
          type: integer
          title: Order Total Sat
        invoice:
          type: string
          title: Invoice
      type: object
      required:
        - state
        - expires_at
        - fee_total_sat
        - order_total_sat
        - invoice
      title: PaymentBolt11
    PaymentOnchain:
      properties:
        state:
          $ref: '#/components/schemas/PaymentState'
        expires_at:
          type: string
          format: date-time
          title: Expires At
        fee_total_sat:
          type: integer
          title: Fee Total Sat
        order_total_sat:
          type: integer
          title: Order Total Sat
        address:
          type: string
          title: Address
        min_fee_for_0conf:
          type: integer
          title: Min Fee For 0Conf
        min_onchain_payment_confirmations:
          type: integer
          title: Min Onchain Payment Confirmations
        refund_onchain_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Refund Onchain Address
        payment_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Payment Status
        payment_difference:
          anyOf:
            - type: integer
            - type: 'null'
          title: Payment Difference
          description: >-
            Payment difference in satoshis. Positive for overpayment, negative
            for underpayment, zero for exact payment
        last_payment_check:
          anyOf:
            - type: integer
            - type: 'null'
          title: Last Payment Check
      type: object
      required:
        - state
        - expires_at
        - fee_total_sat
        - order_total_sat
        - address
        - min_fee_for_0conf
        - min_onchain_payment_confirmations
      title: PaymentOnchain
    PaymentState:
      type: string
      enum:
        - EXPECT_PAYMENT
        - HOLD
        - PAID
        - REFUNDED
        - TO_REFUND
      title: PaymentState
  securitySchemes:
    KaleidoApiKey:
      type: http
      scheme: bearer
      bearerFormat: Kaleido API key
      description: Pass a Kaleido API key such as `kld_live_c_...`.

````