> ## 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. # Initiate an atomic swap > Create a maker-side atomic swap from a fresh RFQ. The response contains the `swapstring` and `payment_hash` the taker must whitelist before execution. Treat this as non-idempotent: creating a second swap requires a new request. ## OpenAPI ````yaml /openapi.json post /api/v1/swaps/init 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/swaps/init: post: tags: - swaps summary: Initiate an atomic swap description: >- Create a maker-side atomic swap from a fresh RFQ. The response contains the `swapstring` and `payment_hash` the taker must whitelist before execution. Treat this as non-idempotent: creating a second swap requires a new request. operationId: initiateAtomicSwap parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SwapRequest' examples: btc_to_rgb: summary: BTC to RGB atomic swap value: rfq_id: 8e6635fb-ab37-4aed-89f4-bc9c98fb8b49 from_asset: BTC from_amount: 1500000 to_asset: rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB to_amount: 875000 responses: '200': description: Swap initialized successfully. content: application/json: schema: $ref: '#/components/schemas/SwapResponse' example: swapstring: >- 1500000/BTC/875000/rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB/1715896416/9d342c6ba006e24abee84a2e034a22d5e30c1f2599fb9c3574d46d3cde3d65a2 payment_hash: >- 9d342c6ba006e24abee84a2e034a22d5e30c1f2599fb9c3574d46d3cde3d65a2 '400': description: The RFQ or swap parameters are invalid. content: application/json: example: error_code: VALIDATION_ERROR message: 'Invalid swap request: missing payment_hash or swapstring' details: {} 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' '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 trading service is still starting or temporarily unavailable. content: application/json: example: error_code: SERVICE_UNAVAILABLE message: >- Trading service is starting up. Please try again in a few moments. details: {} request_id: req_01HV8Q9X7G0Q7Y3Z schema: $ref: '#/components/schemas/KaleidoErrorResponse' security: - KaleidoApiKey: [] components: schemas: SwapRequest: properties: rfq_id: type: string title: Rfq Id examples: - '1234567890' from_asset: type: string title: From Asset examples: - BTC from_amount: type: integer format: int64 title: From Amount examples: - 1000000 to_asset: type: string title: To Asset examples: - rgb:2dkSTbr-jFhznbPmo-TQafzswCN-av4gTsJjX-ttx6CNou5-M98k8Zd to_amount: type: integer format: int64 title: To Amount examples: - 1000000 type: object required: - rfq_id - from_asset - from_amount - to_asset - to_amount title: SwapRequest example: from_amount: 1500000 from_asset: BTC rfq_id: 8e6635fb-ab37-4aed-89f4-bc9c98fb8b49 to_amount: 875000 to_asset: rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB SwapResponse: properties: swapstring: type: string title: Swapstring examples: - >- 30/rgb:2dkSTbr-jFhznbPmo-TQafzswCN-av4gTsJjX-ttx6CNou5-M98k8Zd/10/rgb:2eVw8uw-8G88LQ2tQ-kexM12SoD-nCX8DmQrw-yLMu6JDfK-xx1SCfc/1715896416/9d342c6ba006e24abee84a2e034a22d5e30c1f2599fb9c3574d46d3cde3d65a2 payment_hash: type: string title: Payment Hash examples: - 9d342c6ba006e24abee84a2e034a22d5e30c1f2599fb9c3574d46d3cde3d65a2 access_token: anyOf: - type: string - type: 'null' title: Access Token description: >- Per-swap token required to poll /swaps/atomic/status. Returned only once here at initiation — store it alongside the payment hash. type: object required: - swapstring - payment_hash title: SwapResponse example: payment_hash: 9d342c6ba006e24abee84a2e034a22d5e30c1f2599fb9c3574d46d3cde3d65a2 swapstring: >- 1500000/BTC/875000/rgb:2NZGjyz-pJePUgegh-RLHbpx1Hy-iZMagWiZZ-qY4AxGymW-yCEYwwB/1715896416/9d342c6ba006e24abee84a2e034a22d5e30c1f2599fb9c3574d46d3cde3d65a2 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 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 securitySchemes: KaleidoApiKey: type: http scheme: bearer bearerFormat: Kaleido API key description: Pass a Kaleido API key such as `kld_live_c_...`. ````