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

# Cooperative claim (reverse)

> Claim through the cheaper key path. Send your preimage, your MuSig2 public nonce, and the claim transaction (or its sighash); the maker returns its nonce and partial signature, which you aggregate and broadcast. Revealing the preimage lets the maker settle your payment.



## OpenAPI

````yaml /openapi.json post /v2/swap/reverse/{id}/claim
openapi: 3.1.0
info:
  title: KaleidoSwap Maker API
  version: v2
  description: >-
    Public HTTP API of the KaleidoSwap maker. Wire-compatible with the Boltz
    `/v2` protocol for submarine, reverse, and chain swaps, with KaleidoSwap
    additions (RGB, atomic swaps, pay-through, LSPS1, swap credentials).
    Integrate through the Swap SDK where possible: it verifies every swap the
    maker proposes.
  contact:
    name: KaleidoSwap
    url: https://kaleidoswap.com
servers:
  - url: https://maker.signet.kaleidoswap.com
    description: Signet (Mutinynet)
security: []
tags:
  - name: Service
    description: Maker identity, version, and capabilities.
  - name: Pairs and quotes
    description: Routes the maker trades, their limits and fees, and quotes.
  - name: Submarine swaps
    description: On-chain → Lightning. You lock on chain; the maker pays your invoice.
  - name: Reverse swaps
    description: >-
      Lightning → on-chain. You pay a hold invoice; the maker locks on chain;
      you claim.
  - name: Chain swaps
    description: On-chain → on-chain. Both sides lock; you claim the maker's lockup.
  - name: Swap status
    description: Swap status over HTTP and WebSocket.
  - name: Recovery
    description: Restore swaps from an xpub and recover swap credentials.
  - name: Atomic RGB swaps
    description: BTC ↔ RGB asset swaps in a single transaction.
  - name: Pay-through
    description: Lightning payment → on-chain payout to any address.
  - name: Lightning channels (LSPS1)
    description: Buy inbound Lightning channels (LSPS1).
  - name: Chain data
    description: The maker's view of chain tips and fees.
paths:
  /v2/swap/reverse/{id}/claim:
    post:
      tags:
        - Reverse swaps
      summary: Cooperative claim (reverse)
      description: >-
        Claim through the cheaper key path. Send your preimage, your MuSig2
        public nonce, and the claim transaction (or its sighash); the maker
        returns its nonce and partial signature, which you aggregate and
        broadcast. Revealing the preimage lets the maker settle your payment.
      operationId: cooperative_claim_reverse
      parameters:
        - name: id
          in: path
          description: Swap id (ULID).
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReverseClaimRequest'
        required: true
      responses:
        '200':
          description: Maker's pub nonce + partial signature.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CooperativeSignatureResponse'
        '400':
          description: Bad preimage, sighash, or transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unknown swap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Swap not in a claimable state, or partial-sign failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Database, node, or signing key unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ReverseClaimRequest:
      type: object
      description: >-
        Body of `POST /v2/swap/reverse/{id}/claim` — Boltz-shaped, camelCase.
        Sighash sourcing: callers may either send the **raw unsigned tx**

        (Boltz convention) — `transaction` (hex) + `index` — and the server

        computes the BIP-341 key-path sighash, **or** send `signatureHash`

        precomputed locally. The server prefers `transaction` when both are

        present. Missing both is `400 missing_sighash`.
      required:
        - preimage
        - pubNonce
      properties:
        index:
          type:
            - integer
            - 'null'
          format: int32
          description: |-
            Input index in the claim transaction. Defaults to 0 — most
            cooperative claim txs only spend the single lockup input.
          minimum: 0
        preimage:
          type: string
          description: |-
            The 32-byte preimage that satisfies the swap's `preimageHash`. The
            maker uses this to settle the LN hold invoice.
        pubNonce:
          type: string
          description: The taker's MuSig2 pub nonce, 66 bytes hex.
        signatureHash:
          type:
            - string
            - 'null'
          description: >-
            32-byte BIP-341 sighash the taker wants the maker to partial-sign.
            Optional when `transaction` is provided; required otherwise.
        transaction:
          type:
            - string
            - 'null'
          description: |-
            Hex-encoded unsigned claim transaction. If present, the server
            computes the sighash from this + `index` against the swap's
            persisted lockup output, and any `signatureHash` is ignored.
    CooperativeSignatureResponse:
      type: object
      description: |-
        Maker's partial-signature response on the cooperative claim/refund
        endpoints (submarine refund, reverse claim, reverse refund, chain
        claim, chain refund).
      required:
        - pubNonce
        - partialSignature
      properties:
        partialSignature:
          type: string
          description: Maker's 32-byte partial signature, hex.
        pubNonce:
          type: string
          description: Maker's 66-byte MuSig2 pub nonce, hex.
    ErrorResponse:
      type: object
      description: Boltz-shaped error envelope.
      required:
        - error
      properties:
        details:
          type:
            - string
            - 'null'
          description: Optional human-readable detail. Present on 4xx; absent on 5xx.
        error:
          type: string
          description: Stable machine-readable error code, e.g. `pair_hash_mismatch`.

````

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