> ## 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 refund (chain)

> Ask the maker to co-sign a refund of your lockup before the payout is committed. Requires `X-Swap-Auth`.



## OpenAPI

````yaml /openapi.json post /v2/swap/chain/{id}/refund
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/chain/{id}/refund:
    post:
      tags:
        - Chain swaps
      summary: Cooperative refund (chain)
      description: >-
        Ask the maker to co-sign a refund of your lockup before the payout is
        committed. Requires `X-Swap-Auth`.
      operationId: cooperative_refund_chain
      parameters:
        - name: id
          in: path
          description: Swap id (ULID).
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmarineRefundRequest'
        required: true
      responses:
        '200':
          description: >-
            Maker's pub nonce + partial signature; refund authorization
            persisted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CooperativeSignatureResponse'
        '400':
          description: Bad pubNonce, sighash, or transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or wrong `X-Swap-Auth` credential for this swap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unknown swap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Swap no longer cooperatively refundable (payout already committed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Database, signing key, or Bitcoin chain backend unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - SwapAuth: []
components:
  schemas:
    SubmarineRefundRequest:
      type: object
      description: >-
        Body of `POST /v2/swap/submarine/{id}/refund` — Boltz-shaped. The taker
        submits their `pubNonce` and the complete unsigned Bitcoin

        refund transaction, or the versioned RGB PSBT request. Refunds do not

        reveal a preimage. Bitcoin hash-only requests are no longer accepted.
      required:
        - pubNonce
      properties:
        index:
          type:
            - integer
            - 'null'
          format: int32
          description: Refund tx input index (defaults to 0).
          minimum: 0
        protocol:
          type:
            - string
            - 'null'
        psbt:
          type:
            - string
            - 'null'
        pubNonce:
          type: string
          description: The taker's MuSig2 pub nonce, 66 bytes hex.
        sessionId:
          type:
            - string
            - 'null'
        signatureHash:
          type:
            - string
            - 'null'
          description: >-
            Deprecated for refunds. Hash-only requests return
            transaction_required;

            ignored when a full transaction is provided.
        transaction:
          type:
            - string
            - 'null'
          description: >-
            Hex-encoded unsigned refund transaction, required for Bitcoin
            refunds. The server computes the sighash from actual funding outputs
            via the Bitcoin

            chain backend, validating that every input spends this swap's
            lockup.
    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`.
  securitySchemes:
    SwapAuth:
      type: apiKey
      in: header
      name: X-Swap-Auth
      description: >-
        Per-swap credential returned as `swapAuth` when the swap is created.
        Required on the routes that decide a live swap's outcome (re-quotes,
        cooperative refunds), so knowing the swap ID is not enough.

````

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