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

# Abandon a reverse swap

> Cancel the hold invoice so your Lightning payment is released, and move the swap to `refunding`. Requires `X-Swap-Auth`. Returns the swap's status.



## OpenAPI

````yaml /openapi.json post /v2/swap/reverse/{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/reverse/{id}/refund:
    post:
      tags:
        - Reverse swaps
      summary: Abandon a reverse swap
      description: >-
        Cancel the hold invoice so your Lightning payment is released, and move
        the swap to `refunding`. Requires `X-Swap-Auth`. Returns the swap's
        status.
      operationId: cooperative_refund_reverse
      parameters:
        - name: id
          in: path
          description: Swap id (ULID).
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            Hold invoice cancelled after confirmed maker recovery, or an
            unfunded swap expires.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapStatus'
        '400':
          description: Not a Reverse swap.
          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 cannot be refunded from its current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Database, node, or signing key unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - SwapAuth: []
components:
  schemas:
    SwapStatus:
      type: object
      description: '`GET /v2/swap/{id}` response.'
      required:
        - id
        - type
        - status
        - paymentStatus
        - events
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/SwapEventEntry'
        failureDetails:
          type:
            - string
            - 'null'
        failureReason:
          type:
            - string
            - 'null'
        id:
          type: string
        paymentStatus:
          type: string
          description: Customer-funding status, independent from the swap lifecycle.
        payout:
          oneOf:
            - $ref: '#/components/schemas/PayoutStatus'
              description: Present on pay-through swaps only.
            - type: 'null'
        status:
          type: string
        type:
          type: string
          description: 'Swap kind: `submarine` / `reverse` / `chain`.'
    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`.
    SwapEventEntry:
      type: object
      description: >-
        One row of a swap's append-only event log. The log always opens with
        `created`: the creation event is written in the

        same transaction as the order, so a swap cannot exist without it.
      required:
        - ts
        - kind
      properties:
        data:
          description: |-
            Payment attempt number, rejection reason and certainty, or final
            failure reason. Present only for submarine payment audit events.
        kind:
          type: string
          description: |-
            The first entry of
            every swap is `created`.
        ts:
          type: integer
          format: int64
          description: Unix-seconds timestamp.
    PayoutStatus:
      type: object
      description: The maker's leg of a pay-through swap, on `GET /v2/swap/{id}`.
      required:
        - mode
        - destination
      properties:
        destination:
          type: string
        layer:
          type:
            - string
            - 'null'
          description: Destination layer, as in `destinationLayer`.
        mode:
          type: string
          description: Always `direct` today.
        reference:
          type:
            - string
            - 'null'
          description: >-
            Destination-layer txid of the payout once broadcast, in display
            order.
  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.