{
  "openapi": "3.1.0",
  "info": {
    "title": "kticket API",
    "version": "1.0.0",
    "description": "On-chain event ticketing on Kaspa. The HTTP API is the product: the browser app, a script, and an agent all use it the same way. Identity is wallet ownership — sign a server-issued challenge, then send the bearer token. Chain facts are kticket's own KCC20-fork covenant state; the covenant is not an implementation of KCC-20 Final.",
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://kticket.danieliyahu.com",
      "description": "kticket on testnet10"
    }
  ],
  "tags": [
    {
      "name": "config",
      "description": "The deployment's runtime network identity."
    },
    {
      "name": "auth",
      "description": "Challenge → signature → session token."
    },
    {
      "name": "feedback",
      "description": "Anonymous feedback, no wallet and no account."
    },
    {
      "name": "events",
      "description": "Verified events, deploys, and primary ticket purchases."
    },
    {
      "name": "tickets",
      "description": "The caller's tickets and the door (check-in) flow."
    },
    {
      "name": "resale",
      "description": "List, delist, browse, and trustlessly purchase tickets."
    }
  ],
  "paths": {
    "/v1/config": {
      "get": {
        "operationId": "getServerConfig",
        "tags": [
          "config"
        ],
        "summary": "Read the server's runtime network identity",
        "description": "The chain this deployment broadcasts on: canonical network, wRPC network id, the wallet's network name, and the address prefix. Public, no chain calls, short cache. The browser loads it at boot so one bundle works against whichever network the server serves.",
        "responses": {
          "200": {
            "description": "The runtime network identity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServerConfig"
                },
                "example": {
                  "network": "testnet10",
                  "network_id": "testnet-10",
                  "wallet_network": "kaspa_testnet_10",
                  "address_prefix": "kaspatest:"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/challenge": {
      "post": {
        "operationId": "authChallenge",
        "tags": [
          "auth"
        ],
        "summary": "Ask for a sign-in challenge",
        "description": "Returns a single-use nonce and the exact message to sign. The message names the server's network id — never choose a network yourself.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChallengeRequest"
              },
              "example": {
                "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The challenge to sign.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChallengeResponse"
                },
                "example": {
                  "nonce": "b7c9e1f4a2d84c6e9f0a1b2c3d4e5f60",
                  "message": "kticket\n\nkticket wants you to sign in with your Kaspa account:\nkaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun\n\nURI: https://kticket.danieliyahu.com\nVersion: 1\nChain ID: testnet-10\nNonce: b7c9e1f4a2d84c6e9f0a1b2c3d4e5f60\nIssued At: 2026-10-18T19:00:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/session": {
      "post": {
        "operationId": "authSession",
        "tags": [
          "auth"
        ],
        "summary": "Exchange a signed challenge for a session token",
        "description": "The nonce is consumed on first use. The response carries the bearer token required by user-specific reads.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionRequest"
              },
              "example": {
                "message": "kticket\n\nkticket wants you to sign in with your Kaspa account:\n...",
                "signature": "41abababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The session token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionResponse"
                },
                "example": {
                  "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ...",
                  "expires_in_seconds": 900
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required, or the session token is missing/expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/feedback": {
      "post": {
        "operationId": "submitFeedback",
        "tags": [
          "feedback"
        ],
        "summary": "Send anonymous feedback",
        "description": "Accepts a short note from any visitor - no wallet and no account. The server stores it durably before trying to deliver it, so a delivery outage or restart never loses it. The response's `delivered` flag says whether it reached the maintainers: `false` means it is queued for retry, not sent. Messages are capped at 1500 characters and rate-limited per client.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeedbackRequest"
              },
              "example": {
                "message": "The check-in page worked, but I could not find where to download my ticket."
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Feedback accepted and queued or delivered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FeedbackResponse"
                },
                "example": {
                  "accepted": true,
                  "delivered": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests; retry after `retryAfter` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events": {
      "get": {
        "operationId": "listEvents",
        "tags": [
          "events"
        ],
        "summary": "List verified events",
        "description": "Every registry entry is re-verified from the chain on read; entries that fail verification are hidden. Without `organizer_address` the call is public. With it, the call requires a bearer token and the address must match the signed-in wallet.",
        "security": [
          {
            "bearerAuth": []
          },
          {}
        ],
        "parameters": [
          {
            "name": "organizer_address",
            "in": "query",
            "required": false,
            "description": "Filter to one organizer. Requires `Authorization: Bearer <token>` for that same address.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The verified events.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/EventSummary"
                  }
                },
                "example": [
                  {
                    "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba",
                    "deploy_txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                    "name": "Testnet Rave",
                    "date": "2026-12-31",
                    "time": "20:00",
                    "ticker": "",
                    "decimals": 0,
                    "image": "",
                    "image_hash": "",
                    "price": 100000000,
                    "capacity": 2,
                    "organizer_address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun",
                    "verified": true
                  }
                ]
              }
            }
          },
          "401": {
            "description": "Authentication required, or the session token is missing/expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "registerEvent",
        "tags": [
          "events"
        ],
        "summary": "Register a deployed event for discovery",
        "description": "Looks the deploy transaction up on chain, verifies it, and adds its identifiers to the discovery registry. Deploying already registers the event; this exists for recovery and third-party clients.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterEventRequest"
              },
              "example": {
                "deploy_txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The registered event's covenant id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterEventResponse"
                },
                "example": {
                  "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{covenant_id}": {
      "get": {
        "operationId": "getEvent",
        "tags": [
          "events"
        ],
        "summary": "Read one verified event",
        "description": "Re-verifies the event from its deploy transaction and returns both the friendly facts and the raw chain facts they were derived from.",
        "parameters": [
          {
            "name": "covenant_id",
            "in": "path",
            "required": true,
            "description": "The event's covenant id (64 lowercase hex), as returned by `GET /v1/events`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The event and its raw chain facts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventDetail"
                },
                "example": {
                  "event": {
                    "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba",
                    "deploy_txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                    "name": "Testnet Rave",
                    "date": "2026-12-31",
                    "time": "20:00",
                    "ticker": "",
                    "decimals": 0,
                    "image": "",
                    "image_hash": "",
                    "price": 100000000,
                    "capacity": 2,
                    "organizer_address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun",
                    "verified": true
                  },
                  "raw_chain": {
                    "deploy_txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                    "authorizing_txid": "abababababababababababababababababababababababababababababababab",
                    "metadata_txid": "abababababababababababababababababababababababababababababababab",
                    "maker_address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun",
                    "decoded_constants": {
                      "price": 100000000,
                      "org_spk": "200102020202020202020202020202020202020202020202020202020202020202ac",
                      "burn_template_hash": "abababababababababababababababababababababababababababababababab"
                    },
                    "decoded_state": {
                      "owner": "0102020202020202020202020202020202020202020202020202020202020202",
                      "capacity": 2
                    },
                    "payload": "007b226e616d65223a22546573746e65742052617665222c2264617465223a22323032362d31322d3331222c2274696d65223a2232303a3030222c2270726963654b4153223a312c226f726753706b223a223230303130323032303230323032303230323032303230323032303230323032303230323032303230323032303230323032303230323032303230323032303230326163227d"
                  }
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/deploy/prepare": {
      "post": {
        "operationId": "prepareDeploy",
        "tags": [
          "events"
        ],
        "summary": "Prepare the KCC-23 preparation transaction",
        "description": "The backend fetches the organizer's UTXOs and builds the unsigned preparation template: it spends them into one organizer output and carries a `0x00 || UTF-8 JSON` metadata declaration in its payload. Sign `preparation.signing_template`, then send it to `deploy/genesis`. Nothing is broadcast until genesis.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeployPrepareRequest"
              },
              "example": {
                "capacity": 2,
                "price_kas": 1,
                "publicKey": "0202020202020202020202020202020202020202020202020202020202020202",
                "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun",
                "name": "Testnet Rave",
                "date": "2026-12-31",
                "time": "20:00"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The unsigned preparation template.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeployPrepareResult"
                },
                "example": {
                  "deploy_id": "f2b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
                  "preparation": {
                    "template": {
                      "version": 1,
                      "inputs": [
                        {
                          "previous_outpoint": {
                            "transaction_id": "abababababababababababababababababababababababababababababababab",
                            "index": 0
                          },
                          "signature_script": "",
                          "sequence": 0,
                          "sig_op_count": 50
                        }
                      ],
                      "outputs": [
                        {
                          "value": 99000000,
                          "script_public_key": {
                            "version": 0,
                            "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                          },
                          "covenant": null
                        }
                      ],
                      "lock_time": 0,
                      "payload": "007b226e616d65223a22546573746e65742052617665222c2264617465223a22323032362d31322d3331222c2274696d65223a2232303a3030222c2270726963654b4153223a312c226f726753706b223a223230303130323032303230323032303230323032303230323032303230323032303230323032303230323032303230323032303230323032303230323032303230326163227d"
                    },
                    "signing_template": "{\"version\":1,\"inputs\":[{\"previous_outpoint\":{\"transaction_id\":\"abababababababababababababababababababababababababababababababab\",\"index\":0},\"signature_script\":\"\",\"sequence\":0,\"sig_op_count\":50}],\"outputs\":[{\"value\":99000000,\"script_public_key\":{\"version\":0,\"script\":\"200102020202020202020202020202020202020202020202020202020202020202ac\"},\"covenant\":null}],\"lock_time\":0,\"payload\":\"007b226e616d65223a22546573746e65742052617665222c2264617465223a22323032362d31322d3331222c2274696d65223a2232303a3030222c2270726963654b4153223a312c226f726753706b223a223230303130323032303230323032303230323032303230323032303230323032303230323032303230323032303230323032303230323032303230323032303230326163227d\"}"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Rejected by a policy (sold out, not the owner, no spendable funds).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/deploy/genesis": {
      "post": {
        "operationId": "genesisDeploy",
        "tags": [
          "events"
        ],
        "summary": "Publish the preparation transaction and build the genesis transaction",
        "description": "Merges the preparation signatures, broadcasts the preparation transaction, waits until it is accepted, then returns the genesis template that spends its output 0. The covenant id commits to that outpoint, so it binds the metadata payload. Sign `genesis.signing_template` to continue.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeployGenesisRequest"
              },
              "example": {
                "capacity": 2,
                "price_kas": 1,
                "publicKey": "0202020202020202020202020202020202020202020202020202020202020202",
                "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun",
                "name": "Testnet Rave",
                "date": "2026-12-31",
                "time": "20:00",
                "deploy_id": "f2b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
                "preparation": {
                  "template": {
                    "version": 1,
                    "inputs": [
                      {
                        "previous_outpoint": {
                          "transaction_id": "abababababababababababababababababababababababababababababababab",
                          "index": 0
                        },
                        "signature_script": "",
                        "sequence": 0,
                        "sig_op_count": 50
                      }
                    ],
                    "outputs": [
                      {
                        "value": 99000000,
                        "script_public_key": {
                          "version": 0,
                          "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                        },
                        "covenant": null
                      }
                    ],
                    "lock_time": 0,
                    "payload": "007b226e616d65223a22546573746e65742052617665222c2264617465223a22323032362d31322d3331222c2274696d65223a2232303a3030222c2270726963654b4153223a312c226f726753706b223a223230303130323032303230323032303230323032303230323032303230323032303230323032303230323032303230323032303230323032303230323032303230326163227d"
                  },
                  "signed": {
                    "inputs": [
                      {
                        "transactionId": "abababababababababababababababababababababababababababababababab",
                        "index": 0,
                        "signatureScript": "41abababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The unsigned genesis template.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeployGenesisResult"
                },
                "example": {
                  "preparation_txid": "abababababababababababababababababababababababababababababababab",
                  "event_covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba",
                  "genesis": {
                    "template": {
                      "version": 0,
                      "inputs": [
                        {
                          "previous_outpoint": {
                            "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                            "index": 0
                          },
                          "signature_script": "",
                          "sequence": 0,
                          "sig_op_count": 1
                        }
                      ],
                      "outputs": [
                        {
                          "value": 50000000,
                          "script_public_key": {
                            "version": 0,
                            "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                          },
                          "covenant": {
                            "authorizing_input": 0,
                            "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                          }
                        }
                      ],
                      "lock_time": 0
                    },
                    "signing_template": "{\"version\":0,\"inputs\":[{\"previous_outpoint\":{\"transaction_id\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"index\":0},\"signature_script\":\"\",\"sequence\":0,\"sig_op_count\":1}],\"outputs\":[{\"value\":50000000,\"script_public_key\":{\"version\":0,\"script\":\"200102020202020202020202020202020202020202020202020202020202020202ac\"},\"covenant\":{\"authorizing_input\":0,\"covenant_id\":\"234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba\"}}],\"lock_time\":0}"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Rejected by a policy (sold out, not the owner, no spendable funds).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "502": {
            "description": "The network refused the signed transaction.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/deploy/finalize": {
      "post": {
        "operationId": "finalizeDeploy",
        "tags": [
          "events"
        ],
        "summary": "Finalize an event deploy",
        "description": "Merges the wallet's signatures into the exact genesis template it signed, validates it is a deploy, broadcasts it, waits for on-chain verification, and registers the event. Success is returned only after registration.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeployFinalizeRequest"
              },
              "example": {
                "deploy_id": "f2b1c2d3-e4f5-4a6b-8c7d-9e0f1a2b3c4d",
                "template": {
                  "version": 0,
                  "inputs": [
                    {
                      "previous_outpoint": {
                        "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                        "index": 0
                      },
                      "signature_script": "",
                      "sequence": 0,
                      "sig_op_count": 1
                    }
                  ],
                  "outputs": [
                    {
                      "value": 50000000,
                      "script_public_key": {
                        "version": 0,
                        "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                      },
                      "covenant": {
                        "authorizing_input": 0,
                        "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                      }
                    }
                  ],
                  "lock_time": 0
                },
                "signed": {
                  "inputs": [
                    {
                      "transactionId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                      "index": 0,
                      "signatureScript": "41abababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The deployed, registered event.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeployFinalizeResult"
                },
                "example": {
                  "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba",
                  "deploy_txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "502": {
            "description": "The network refused the signed transaction.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{covenant_id}/buy/prepare": {
      "post": {
        "operationId": "prepareBuy",
        "tags": [
          "events"
        ],
        "summary": "Prepare a primary ticket purchase",
        "description": "Verifies the event from the chain, computes remaining capacity, fetches the buyer's UTXOs, and returns the unsigned buy template. The server has already prepared the covenant spend at input 0; sign the indices in `sign_inputs`.",
        "parameters": [
          {
            "name": "covenant_id",
            "in": "path",
            "required": true,
            "description": "The event's covenant id (64 lowercase hex), as returned by `GET /v1/events`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BuyPrepareRequest"
              },
              "example": {
                "publicKey": "0202020202020202020202020202020202020202020202020202020202020202",
                "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The unsigned buy template.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuyPrepareResult"
                },
                "example": {
                  "buy_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
                  "signing_template": "{\"version\":0,\"inputs\":[{\"previous_outpoint\":{\"transaction_id\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"index\":0},\"signature_script\":\"\",\"sequence\":0,\"sig_op_count\":1}],\"outputs\":[{\"value\":50000000,\"script_public_key\":{\"version\":0,\"script\":\"200102020202020202020202020202020202020202020202020202020202020202ac\"},\"covenant\":{\"authorizing_input\":0,\"covenant_id\":\"234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba\"}}],\"lock_time\":0}",
                  "template": {
                    "version": 0,
                    "inputs": [
                      {
                        "previous_outpoint": {
                          "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                          "index": 0
                        },
                        "signature_script": "",
                        "sequence": 0,
                        "sig_op_count": 1
                      }
                    ],
                    "outputs": [
                      {
                        "value": 50000000,
                        "script_public_key": {
                          "version": 0,
                          "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                        },
                        "covenant": {
                          "authorizing_input": 0,
                          "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                        }
                      }
                    ],
                    "lock_time": 0
                  },
                  "sign_inputs": [
                    {
                      "index": 1
                    }
                  ],
                  "price": 100000000,
                  "ticket_value": 50000000,
                  "network_fee": 1000000,
                  "organizer_proceeds": 49000000
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Rejected by a policy (sold out, not the owner, no spendable funds).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{covenant_id}/buy/finalize": {
      "post": {
        "operationId": "finalizeBuy",
        "tags": [
          "events"
        ],
        "summary": "Finalize a primary ticket purchase",
        "description": "Merges signatures, validates the template is a buy (it must carry the ticket covenant output), broadcasts, and waits for the ledger to accept the mint. `status: \"settled\"` means the ticket exists; `\"pending\"` means the purchase was relayed but acceptance is not established yet — keep the txid and read `GET /v1/tickets` rather than re-broadcasting.",
        "parameters": [
          {
            "name": "covenant_id",
            "in": "path",
            "required": true,
            "description": "The event's covenant id (64 lowercase hex), as returned by `GET /v1/events`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BuyFinalizeRequest"
              },
              "example": {
                "buy_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
                "template": {
                  "version": 0,
                  "inputs": [
                    {
                      "previous_outpoint": {
                        "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                        "index": 0
                      },
                      "signature_script": "",
                      "sequence": 0,
                      "sig_op_count": 1
                    }
                  ],
                  "outputs": [
                    {
                      "value": 50000000,
                      "script_public_key": {
                        "version": 0,
                        "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                      },
                      "covenant": {
                        "authorizing_input": 0,
                        "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                      }
                    }
                  ],
                  "lock_time": 0
                },
                "signed": {
                  "inputs": [
                    {
                      "transactionId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                      "index": 1,
                      "signatureScript": "41cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd"
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The mint transaction and whether it settled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuyFinalizeResult"
                },
                "example": {
                  "txid": "1234123412341234123412341234123412341234123412341234123412341234",
                  "status": "settled"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "502": {
            "description": "The network refused the signed transaction.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/listings": {
      "get": {
        "operationId": "listAllListings",
        "tags": [
          "resale"
        ],
        "summary": "List every resale listing",
        "description": "The workspace-wide resale directory. Each entry is proven on chain exactly as in the per-event listing.",
        "responses": {
          "200": {
            "description": "Every live resale listing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ListingSummary"
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{covenant_id}/listings": {
      "get": {
        "operationId": "listEventListings",
        "tags": [
          "resale"
        ],
        "summary": "List an event's resale listings",
        "description": "Each entry is proven on chain: the ticket UTXO must still sit on the listed-state address for its recorded seller and price. Stale index rows are omitted.",
        "parameters": [
          {
            "name": "covenant_id",
            "in": "path",
            "required": true,
            "description": "The event's covenant id (64 lowercase hex), as returned by `GET /v1/events`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Live resale listings for the event.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ListingSummary"
                  }
                },
                "example": [
                  {
                    "ticket_id": "bb00000000000000000000000000000000000000000000000000000000000000:0",
                    "price": 200000000,
                    "seller_pkh": "0203030303030303030303030303030303030303030303030303030303030303",
                    "event_name": "Testnet Rave",
                    "event_date": "2026-12-31",
                    "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba",
                    "verified": true
                  }
                ]
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tickets": {
      "get": {
        "operationId": "listMyTickets",
        "tags": [
          "tickets"
        ],
        "summary": "List the signed-in wallet's tickets",
        "description": "Returns the tickets held by the bearer token's wallet, including listed ones with their asking price. Any `owner_pkh` query is ignored — the wallet proof is authoritative.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The caller's tickets.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/TicketSummary"
                  }
                },
                "example": [
                  {
                    "ticket_id": "bb00000000000000000000000000000000000000000000000000000000000000:0",
                    "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba",
                    "event_name": "Testnet Rave",
                    "event_date": "2026-12-31",
                    "event_time": "20:00"
                  }
                ]
              }
            }
          },
          "401": {
            "description": "Authentication required, or the session token is missing/expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tickets/{ticket_id}/use/prepare": {
      "post": {
        "operationId": "prepareUse",
        "tags": [
          "tickets"
        ],
        "summary": "Prepare a check-in (door flow)",
        "description": "The owner pre-signs a mark-used template. The returned `use_id` and template travel in the QR payload; the gate co-signs input 0 later.",
        "parameters": [
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "`<64-hex transaction id>:<output index>` — the shape served by `GET /v1/tickets`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}:[0-9]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UsePrepareRequest"
              },
              "example": {
                "publicKey": "0202020202020202020202020202020202020202020202020202020202020202",
                "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The check-in template the owner signs.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsePrepareResult"
                },
                "example": {
                  "use_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
                  "signing_template": "{\"version\":0,\"inputs\":[{\"previous_outpoint\":{\"transaction_id\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"index\":0},\"signature_script\":\"\",\"sequence\":0,\"sig_op_count\":1}],\"outputs\":[{\"value\":50000000,\"script_public_key\":{\"version\":0,\"script\":\"200102020202020202020202020202020202020202020202020202020202020202ac\"},\"covenant\":{\"authorizing_input\":0,\"covenant_id\":\"234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba\"}}],\"lock_time\":0}",
                  "template": {
                    "version": 0,
                    "inputs": [
                      {
                        "previous_outpoint": {
                          "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                          "index": 0
                        },
                        "signature_script": "",
                        "sequence": 0,
                        "sig_op_count": 1
                      }
                    ],
                    "outputs": [
                      {
                        "value": 50000000,
                        "script_public_key": {
                          "version": 0,
                          "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                        },
                        "covenant": {
                          "authorizing_input": 0,
                          "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                        }
                      }
                    ],
                    "lock_time": 0
                  },
                  "sign_inputs_owner": [
                    {
                      "index": 0
                    },
                    {
                      "index": 1
                    }
                  ],
                  "event": {
                    "name": "Testnet Rave",
                    "date": "2026-12-31"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Rejected by a policy (sold out, not the owner, no spendable funds).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tickets/{ticket_id}/use/sign-template": {
      "post": {
        "operationId": "signUseTemplate",
        "tags": [
          "tickets"
        ],
        "summary": "Rebuild a check-in signing template at the gate",
        "description": "Statelessly re-derives the safe JSON from the template's prev-output chain facts, so the gate's co-signature is over exactly the bytes the owner signed.",
        "parameters": [
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "`<64-hex transaction id>:<output index>` — the shape served by `GET /v1/tickets`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}:[0-9]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UseSignTemplateRequest"
              },
              "example": {
                "template": {
                  "version": 0,
                  "inputs": [
                    {
                      "previous_outpoint": {
                        "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                        "index": 0
                      },
                      "signature_script": "",
                      "sequence": 0,
                      "sig_op_count": 1
                    }
                  ],
                  "outputs": [
                    {
                      "value": 50000000,
                      "script_public_key": {
                        "version": 0,
                        "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                      },
                      "covenant": {
                        "authorizing_input": 0,
                        "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                      }
                    }
                  ],
                  "lock_time": 0
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The rebuilt safe JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UseSignTemplateResult"
                },
                "example": {
                  "signing_template": "{\"version\":0,\"inputs\":[{\"previous_outpoint\":{\"transaction_id\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"index\":0},\"signature_script\":\"\",\"sequence\":0,\"sig_op_count\":1}],\"outputs\":[{\"value\":50000000,\"script_public_key\":{\"version\":0,\"script\":\"200102020202020202020202020202020202020202020202020202020202020202ac\"},\"covenant\":{\"authorizing_input\":0,\"covenant_id\":\"234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba\"}}],\"lock_time\":0}"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tickets/{ticket_id}/use/finalize": {
      "post": {
        "operationId": "finalizeUse",
        "tags": [
          "tickets"
        ],
        "summary": "Finalize a check-in",
        "description": "Assembles the owner's and the gate's signatures over input 0, broadcasts, and waits for the ledger to accept the check-in. The door opens only on `status: \"settled\"`; `\"pending\"` means the mark_used was relayed but is not accepted yet.",
        "parameters": [
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "`<64-hex transaction id>:<output index>` — the shape served by `GET /v1/tickets`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}:[0-9]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UseFinalizeRequest"
              },
              "example": {
                "use_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
                "template": {
                  "version": 0,
                  "inputs": [
                    {
                      "previous_outpoint": {
                        "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                        "index": 0
                      },
                      "signature_script": "",
                      "sequence": 0,
                      "sig_op_count": 1
                    }
                  ],
                  "outputs": [
                    {
                      "value": 50000000,
                      "script_public_key": {
                        "version": 0,
                        "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                      },
                      "covenant": {
                        "authorizing_input": 0,
                        "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                      }
                    }
                  ],
                  "lock_time": 0
                },
                "owner_signed": {
                  "inputs": [
                    {
                      "transactionId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                      "index": 0,
                      "signatureScript": "41aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
                    }
                  ]
                },
                "gate_signed": {
                  "inputs": [
                    {
                      "transactionId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                      "index": 0,
                      "signatureScript": "41bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The check-in transaction and whether it settled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FinalizeResult"
                },
                "example": {
                  "txid": "5678567856785678567856785678567856785678567856785678567856785678",
                  "status": "settled"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Rejected by a policy (sold out, not the owner, no spendable funds).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "502": {
            "description": "The network refused the signed transaction.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tickets/{ticket_id}/list/prepare": {
      "post": {
        "operationId": "prepareList",
        "tags": [
          "resale"
        ],
        "summary": "Prepare a resale listing",
        "description": "The holder commits an asking price in sompi into the ticket covenant state. The asking price must be at least 1 KAS (no free tickets). Ownership, unused status, and listing status are all proven on chain before the template is built.",
        "parameters": [
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "`<64-hex transaction id>:<output index>` — the shape served by `GET /v1/tickets`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}:[0-9]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListPrepareRequest"
              },
              "example": {
                "publicKey": "0202020202020202020202020202020202020202020202020202020202020202",
                "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun",
                "price": 200000000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The unsigned listing template.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListPrepareResult"
                },
                "example": {
                  "list_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
                  "signing_template": "{\"version\":0,\"inputs\":[{\"previous_outpoint\":{\"transaction_id\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"index\":0},\"signature_script\":\"\",\"sequence\":0,\"sig_op_count\":1}],\"outputs\":[{\"value\":50000000,\"script_public_key\":{\"version\":0,\"script\":\"200102020202020202020202020202020202020202020202020202020202020202ac\"},\"covenant\":{\"authorizing_input\":0,\"covenant_id\":\"234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba\"}}],\"lock_time\":0}",
                  "template": {
                    "version": 0,
                    "inputs": [
                      {
                        "previous_outpoint": {
                          "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                          "index": 0
                        },
                        "signature_script": "",
                        "sequence": 0,
                        "sig_op_count": 1
                      }
                    ],
                    "outputs": [
                      {
                        "value": 50000000,
                        "script_public_key": {
                          "version": 0,
                          "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                        },
                        "covenant": {
                          "authorizing_input": 0,
                          "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                        }
                      }
                    ],
                    "lock_time": 0
                  },
                  "sign_inputs": [
                    {
                      "index": 0
                    },
                    {
                      "index": 1
                    }
                  ],
                  "price": 200000000,
                  "event": {
                    "name": "Testnet Rave",
                    "date": "2026-12-31"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Rejected by a policy (sold out, not the owner, no spendable funds).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tickets/{ticket_id}/list/finalize": {
      "post": {
        "operationId": "finalizeList",
        "tags": [
          "resale"
        ],
        "summary": "Finalize a resale listing",
        "description": "Merges signatures, broadcasts the listed-state spend, and indexes the listing. The price must match the one sent to prepare. The index row is a hint proven against the chain on every read, so a `pending` broadcast is safe to report as-is.",
        "parameters": [
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "`<64-hex transaction id>:<output index>` — the shape served by `GET /v1/tickets`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}:[0-9]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListFinalizeRequest"
              },
              "example": {
                "template": {
                  "version": 0,
                  "inputs": [
                    {
                      "previous_outpoint": {
                        "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                        "index": 0
                      },
                      "signature_script": "",
                      "sequence": 0,
                      "sig_op_count": 1
                    }
                  ],
                  "outputs": [
                    {
                      "value": 50000000,
                      "script_public_key": {
                        "version": 0,
                        "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                      },
                      "covenant": {
                        "authorizing_input": 0,
                        "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                      }
                    }
                  ],
                  "lock_time": 0
                },
                "signed": {
                  "inputs": [
                    {
                      "transactionId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                      "index": 0,
                      "signatureScript": "41acacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacacac"
                    }
                  ]
                },
                "price": 200000000
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The listing transaction and whether it settled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FinalizeResult"
                },
                "example": {
                  "txid": "9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc",
                  "status": "settled"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "502": {
            "description": "The network refused the signed transaction.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tickets/{ticket_id}/delist/prepare": {
      "post": {
        "operationId": "prepareDelist",
        "tags": [
          "resale"
        ],
        "summary": "Prepare a delisting",
        "description": "Clears a live listing. The recorded price comes from the index and is proven against the chain before the template is built.",
        "parameters": [
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "`<64-hex transaction id>:<output index>` — the shape served by `GET /v1/tickets`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}:[0-9]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DelistPrepareRequest"
              },
              "example": {
                "publicKey": "0202020202020202020202020202020202020202020202020202020202020202",
                "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The unsigned delisting template.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DelistPrepareResult"
                },
                "example": {
                  "delist_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7081",
                  "signing_template": "{\"version\":0,\"inputs\":[{\"previous_outpoint\":{\"transaction_id\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"index\":0},\"signature_script\":\"\",\"sequence\":0,\"sig_op_count\":1}],\"outputs\":[{\"value\":50000000,\"script_public_key\":{\"version\":0,\"script\":\"200102020202020202020202020202020202020202020202020202020202020202ac\"},\"covenant\":{\"authorizing_input\":0,\"covenant_id\":\"234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba\"}}],\"lock_time\":0}",
                  "template": {
                    "version": 0,
                    "inputs": [
                      {
                        "previous_outpoint": {
                          "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                          "index": 0
                        },
                        "signature_script": "",
                        "sequence": 0,
                        "sig_op_count": 1
                      }
                    ],
                    "outputs": [
                      {
                        "value": 50000000,
                        "script_public_key": {
                          "version": 0,
                          "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                        },
                        "covenant": {
                          "authorizing_input": 0,
                          "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                        }
                      }
                    ],
                    "lock_time": 0
                  },
                  "sign_inputs": [
                    {
                      "index": 0
                    },
                    {
                      "index": 1
                    }
                  ],
                  "event": {
                    "name": "Testnet Rave",
                    "date": "2026-12-31"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Rejected by a policy (sold out, not the owner, no spendable funds).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tickets/{ticket_id}/delist/finalize": {
      "post": {
        "operationId": "finalizeDelist",
        "tags": [
          "resale"
        ],
        "summary": "Finalize a delisting",
        "description": "Merges signatures, broadcasts the unlisted-state spend, and drops the index row.",
        "parameters": [
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "`<64-hex transaction id>:<output index>` — the shape served by `GET /v1/tickets`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}:[0-9]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DelistFinalizeRequest"
              },
              "example": {
                "template": {
                  "version": 0,
                  "inputs": [
                    {
                      "previous_outpoint": {
                        "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                        "index": 0
                      },
                      "signature_script": "",
                      "sequence": 0,
                      "sig_op_count": 1
                    }
                  ],
                  "outputs": [
                    {
                      "value": 50000000,
                      "script_public_key": {
                        "version": 0,
                        "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                      },
                      "covenant": {
                        "authorizing_input": 0,
                        "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                      }
                    }
                  ],
                  "lock_time": 0
                },
                "signed": {
                  "inputs": [
                    {
                      "transactionId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                      "index": 0,
                      "signatureScript": "41adadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadadad"
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The delisting transaction and whether it settled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FinalizeResult"
                },
                "example": {
                  "txid": "bcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcde",
                  "status": "settled"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "502": {
            "description": "The network refused the signed transaction.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tickets/{ticket_id}/purchase/prepare": {
      "post": {
        "operationId": "preparePurchase",
        "tags": [
          "resale"
        ],
        "summary": "Prepare a trustless resale purchase",
        "description": "The buyer does not need the seller online. The listing is proven on chain (live ticket UTXO on the listed-state address); input 0 is signatureless and only the buyer's fee inputs need signatures.",
        "parameters": [
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "`<64-hex transaction id>:<output index>` — the shape served by `GET /v1/tickets`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}:[0-9]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PurchasePrepareRequest"
              },
              "example": {
                "publicKey": "0405050505050505050505050505050505050505050505050505050505050505",
                "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The unsigned purchase template.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PurchasePrepareResult"
                },
                "example": {
                  "purchase_id": "f6a7b8c9-d0e1-4f2a-9b3c-4d5e6f708192",
                  "signing_template": "{\"version\":0,\"inputs\":[{\"previous_outpoint\":{\"transaction_id\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"index\":0},\"signature_script\":\"\",\"sequence\":0,\"sig_op_count\":1}],\"outputs\":[{\"value\":50000000,\"script_public_key\":{\"version\":0,\"script\":\"200102020202020202020202020202020202020202020202020202020202020202ac\"},\"covenant\":{\"authorizing_input\":0,\"covenant_id\":\"234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba\"}}],\"lock_time\":0}",
                  "template": {
                    "version": 0,
                    "inputs": [
                      {
                        "previous_outpoint": {
                          "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                          "index": 0
                        },
                        "signature_script": "",
                        "sequence": 0,
                        "sig_op_count": 1
                      }
                    ],
                    "outputs": [
                      {
                        "value": 50000000,
                        "script_public_key": {
                          "version": 0,
                          "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                        },
                        "covenant": {
                          "authorizing_input": 0,
                          "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                        }
                      }
                    ],
                    "lock_time": 0
                  },
                  "sign_inputs": [
                    {
                      "index": 1
                    }
                  ],
                  "price": 200000000,
                  "ticket_value": 50000000,
                  "seller_proceeds": 199000000,
                  "network_fee": 1000000,
                  "seller_pkh": "0203030303030303030303030303030303030303030303030303030303030303",
                  "event": {
                    "name": "Testnet Rave",
                    "date": "2026-12-31"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "Rejected by a policy (sold out, not the owner, no spendable funds).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tickets/{ticket_id}/purchase/finalize": {
      "post": {
        "operationId": "finalizePurchase",
        "tags": [
          "resale"
        ],
        "summary": "Finalize a trustless resale purchase",
        "description": "Validates the escrow, broadcasts, and drops the index row. The seller is paid and the ticket changes hands atomically once the ledger accepts it, so `status` says whether that happened yet.",
        "parameters": [
          {
            "name": "ticket_id",
            "in": "path",
            "required": true,
            "description": "`<64-hex transaction id>:<output index>` — the shape served by `GET /v1/tickets`.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-f]{64}:[0-9]+$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PurchaseFinalizeRequest"
              },
              "example": {
                "template": {
                  "version": 0,
                  "inputs": [
                    {
                      "previous_outpoint": {
                        "transaction_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                        "index": 0
                      },
                      "signature_script": "",
                      "sequence": 0,
                      "sig_op_count": 1
                    }
                  ],
                  "outputs": [
                    {
                      "value": 50000000,
                      "script_public_key": {
                        "version": 0,
                        "script": "200102020202020202020202020202020202020202020202020202020202020202ac"
                      },
                      "covenant": {
                        "authorizing_input": 0,
                        "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
                      }
                    }
                  ],
                  "lock_time": 0
                },
                "signed": {
                  "inputs": [
                    {
                      "transactionId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
                      "index": 1,
                      "signatureScript": "41cececececececececececececececececececececececececececececececececececececececececececececececececececececececececececececececece"
                    }
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The purchase transaction and whether it settled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FinalizeResult"
                },
                "example": {
                  "txid": "def0def0def0def0def0def0def0def0def0def0def0def0def0def0def0def0",
                  "status": "settled"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request — a field is missing, malformed, or out of range.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "The named resource is not known (or not on chain).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "502": {
            "description": "The network refused the signed transaction.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "503": {
            "description": "The chain upstream is unavailable; retry after `retryAfter`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Session token from `POST /v1/auth/session`. The same token is a JWT whose subject is the wallet address."
      }
    },
    "responses": {
      "Error": {
        "description": "The shared error envelope.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorEnvelope": {
        "type": "object",
        "description": "Every failure uses this envelope. `type` is stable and machine-readable; `retryable` says whether the same request may succeed on retry.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "type",
              "message",
              "retryable"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "One of `invalid`, `conflict`, `policy`, `network`, `upstream`, `unauthorized`, or `unknown-*`."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation."
              },
              "retryable": {
                "type": "boolean",
                "description": "True when the same request may succeed later without changes."
              },
              "retryAfter": {
                "type": "integer",
                "minimum": 0,
                "description": "Seconds to wait before retrying, when the server knows."
              },
              "detail": {
                "description": "Optional machine-readable context."
              }
            }
          }
        }
      },
      "SigningOutput": {
        "description": "The wallet's signing output. A kaspa-wasm `signPskt` result (object) or a safe-JSON string; the server only merges signatures over the template it issued.",
        "anyOf": [
          {
            "type": "object"
          },
          {
            "type": "string"
          }
        ]
      },
      "InputIndex": {
        "type": "object",
        "required": [
          "index"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "EventRef": {
        "type": "object",
        "required": [
          "name",
          "date"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "date": {
            "type": "string"
          }
        }
      },
      "FinalizeResult": {
        "type": "object",
        "required": [
          "txid",
          "status"
        ],
        "properties": {
          "txid": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "status": {
            "type": "string",
            "enum": [
              "settled",
              "pending"
            ],
            "description": "`settled` — the ledger accepted the transaction, so every output it declares exists (the ticket exists, the payment settled). `pending` — the transaction was relayed and is not accepted yet; it may still settle. A pending response is not a failure: do not re-broadcast, and read the chain to learn the outcome."
          }
        }
      },
      "ServerConfig": {
        "type": "object",
        "description": "The deployment's runtime network identity. Read it at boot; never derive the chain from a build-time value.",
        "required": [
          "network",
          "network_id",
          "wallet_network",
          "address_prefix"
        ],
        "properties": {
          "network": {
            "type": "string",
            "description": "Canonical network id, e.g. `testnet10`."
          },
          "network_id": {
            "type": "string",
            "description": "The wRPC network id, e.g. `testnet-10`."
          },
          "wallet_network": {
            "type": "string",
            "description": "The wallet's network name, e.g. `kaspa_testnet_10`."
          },
          "address_prefix": {
            "type": "string",
            "description": "The bech32 address prefix, including the trailing colon."
          }
        }
      },
      "ChallengeRequest": {
        "type": "object",
        "required": [
          "address"
        ],
        "properties": {
          "address": {
            "type": "string",
            "description": "The wallet's bech32 address; the backend fetches its UTXOs itself."
          }
        }
      },
      "ChallengeResponse": {
        "type": "object",
        "required": [
          "nonce",
          "message"
        ],
        "properties": {
          "nonce": {
            "type": "string",
            "description": "Single-use nonce, consumed by session exchange."
          },
          "message": {
            "type": "string",
            "description": "Sign this verbatim with the wallet's private key."
          }
        }
      },
      "SessionRequest": {
        "type": "object",
        "required": [
          "message",
          "signature"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "The `message` from the challenge response."
          },
          "signature": {
            "type": "string",
            "description": "Kaspa Schnorr message signature over `message`, hex or base64."
          }
        }
      },
      "SessionResponse": {
        "type": "object",
        "required": [
          "token",
          "expires_in_seconds"
        ],
        "properties": {
          "token": {
            "type": "string",
            "description": "Bearer token for authenticated routes."
          },
          "expires_in_seconds": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "FeedbackRequest": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1500,
            "description": "The visitor's note. Whitespace-only messages are rejected; the server trims before storing."
          }
        }
      },
      "FeedbackResponse": {
        "type": "object",
        "required": [
          "accepted",
          "delivered"
        ],
        "properties": {
          "accepted": {
            "type": "boolean",
            "const": true,
            "description": "The note is durably stored."
          },
          "delivered": {
            "type": "boolean",
            "description": "`true` only when the note reached the maintainers. `false` means it is queued for retry and has not been sent yet."
          }
        }
      },
      "WireScriptPublicKey": {
        "type": "object",
        "description": "A Kaspa script public key: version plus hex-encoded script.",
        "required": [
          "version",
          "script"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "minimum": 0
          },
          "script": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]*$",
            "description": "Hex-encoded script."
          }
        }
      },
      "WireOutpoint": {
        "type": "object",
        "required": [
          "transaction_id",
          "index"
        ],
        "properties": {
          "transaction_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "index": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "WireCovenant": {
        "type": "object",
        "required": [
          "authorizing_input",
          "covenant_id"
        ],
        "properties": {
          "authorizing_input": {
            "type": "integer",
            "minimum": 0
          },
          "covenant_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          }
        }
      },
      "WireInput": {
        "type": "object",
        "required": [
          "previous_outpoint",
          "signature_script",
          "sequence",
          "sig_op_count"
        ],
        "properties": {
          "previous_outpoint": {
            "$ref": "#/components/schemas/WireOutpoint"
          },
          "signature_script": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]*$"
          },
          "sequence": {
            "type": "integer",
            "minimum": 0
          },
          "sig_op_count": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "WireOutput": {
        "type": "object",
        "required": [
          "value",
          "script_public_key",
          "covenant"
        ],
        "properties": {
          "value": {
            "type": "integer",
            "minimum": 0,
            "description": "Amount in sompi."
          },
          "script_public_key": {
            "$ref": "#/components/schemas/WireScriptPublicKey"
          },
          "covenant": {
            "description": "The covenant binding, or null for an ordinary output.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/WireCovenant"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "WireTransaction": {
        "type": "object",
        "description": "The unsigned transaction template. It is also carried inside `signing_template` as kaspa-wasm safe JSON.",
        "required": [
          "version",
          "inputs",
          "outputs",
          "lock_time"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "minimum": 0
          },
          "inputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WireInput"
            }
          },
          "outputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WireOutput"
            }
          },
          "lock_time": {
            "type": "integer",
            "minimum": 0
          },
          "payload": {
            "type": "string",
            "pattern": "^[0-9a-fA-F]*$",
            "description": "Hex-encoded transaction payload. On a KCC-23 preparation tx it is the metadata declaration: `0x00` (JSON codec) followed by the UTF-8 JSON object, e.g. `007b7d` for `{}`."
          }
        }
      },
      "EventSummary": {
        "type": "object",
        "description": "Chain-verified event facts. Every field is re-derived from the deploy transaction on each read.",
        "required": [
          "covenant_id",
          "deploy_txid",
          "name",
          "date",
          "time",
          "ticker",
          "decimals",
          "image",
          "image_hash",
          "price",
          "capacity",
          "organizer_address",
          "verified"
        ],
        "properties": {
          "covenant_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "deploy_txid": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "name": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD; empty when absent."
          },
          "time": {
            "type": "string",
            "description": "Local wall-clock HH:MM; empty when absent."
          },
          "ticker": {
            "type": "string"
          },
          "decimals": {
            "type": "integer",
            "minimum": 0
          },
          "image": {
            "type": "string",
            "description": "https:// or ipfs:// URI; empty when absent."
          },
          "image_hash": {
            "type": "string",
            "description": "Lowercase hex; empty when absent."
          },
          "price": {
            "type": "integer",
            "minimum": 100000000,
            "description": "Ticket price in sompi (minimum 1 KAS)."
          },
          "capacity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "organizer_address": {
            "type": "string",
            "description": "The event's trust anchor."
          },
          "verified": {
            "type": "boolean",
            "const": true
          }
        }
      },
      "EventDetail": {
        "type": "object",
        "required": [
          "event",
          "raw_chain"
        ],
        "properties": {
          "event": {
            "$ref": "#/components/schemas/EventSummary"
          },
          "raw_chain": {
            "$ref": "#/components/schemas/RawChainFacts"
          }
        }
      },
      "RawChainFacts": {
        "type": "object",
        "description": "Raw on-chain facts behind an event, so any displayed value can be re-checked.",
        "required": [
          "deploy_txid",
          "authorizing_txid",
          "metadata_txid",
          "maker_address",
          "decoded_constants",
          "decoded_state",
          "payload"
        ],
        "properties": {
          "deploy_txid": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "authorizing_txid": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "metadata_txid": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^[0-9a-f]{64}$",
            "description": "Transaction whose payload carried the KCC-23 metadata declaration (the preparation tx); legacy deploys carry it on the genesis tx. Null when the event declares no metadata."
          },
          "maker_address": {
            "type": "string"
          },
          "decoded_constants": {
            "type": "object",
            "required": [
              "price",
              "org_spk",
              "burn_template_hash"
            ],
            "properties": {
              "price": {
                "type": "integer",
                "minimum": 100000000
              },
              "org_spk": {
                "type": "string",
                "pattern": "^[0-9a-fA-F]*$"
              },
              "burn_template_hash": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              }
            }
          },
          "decoded_state": {
            "type": "object",
            "required": [
              "owner",
              "capacity"
            ],
            "properties": {
              "owner": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$"
              },
              "capacity": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          },
          "payload": {
            "type": [
              "string",
              "null"
            ],
            "description": "The hex-encoded metadata payload, read from `metadata_txid`. Null when the event declares no metadata."
          }
        }
      },
      "RegisterEventRequest": {
        "type": "object",
        "description": "Discovery-only registration: the deploy txid is the retrieval key.",
        "anyOf": [
          {
            "required": [
              "deploy_txid"
            ]
          },
          {
            "required": [
              "genesis_txid"
            ]
          }
        ],
        "properties": {
          "deploy_txid": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "genesis_txid": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "deprecated": true,
            "description": "Legacy alias for `deploy_txid`."
          }
        }
      },
      "RegisterEventResponse": {
        "type": "object",
        "required": [
          "covenant_id"
        ],
        "properties": {
          "covenant_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          }
        }
      },
      "DeployPrepareRequest": {
        "type": "object",
        "description": "The event to deploy. The backend derives the organizer payout and preparation output scripts from `publicKey`; it never trusts a caller-supplied owner or script.",
        "required": [
          "capacity",
          "price_kas",
          "publicKey",
          "address"
        ],
        "properties": {
          "capacity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Number of tickets the event can mint."
          },
          "price_kas": {
            "type": "number",
            "minimum": 1,
            "description": "Ticket price in KAS (not sompi). Minimum 1 KAS; free events are not supported."
          },
          "publicKey": {
            "type": "string",
            "pattern": "^(?:[0-9a-fA-F]{64}|[0-9a-fA-F]{66})$",
            "description": "Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key."
          },
          "address": {
            "type": "string",
            "description": "The wallet's bech32 address; the backend fetches its UTXOs itself."
          },
          "name": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD; required with `name`."
          },
          "time": {
            "type": "string",
            "description": "HH:MM; requires `date`."
          },
          "ticker": {
            "type": "string",
            "description": "Ecosystem token ticker, declared in the KCC-23 metadata."
          },
          "decimals": {
            "type": "integer",
            "minimum": 0,
            "maximum": 255
          },
          "image": {
            "type": "string",
            "description": "https:// or ipfs:// poster URI."
          },
          "image_hash": {
            "type": "string",
            "description": "sha256 of the poster, 64 hex."
          }
        }
      },
      "DeployPrepareResult": {
        "type": "object",
        "description": "The KCC-23 preparation round: sign `preparation.signing_template`, then post it back with this request to `deploy/genesis`.",
        "required": [
          "deploy_id",
          "preparation"
        ],
        "properties": {
          "deploy_id": {
            "type": "string",
            "description": "Correlation id echoed on genesis and finalize."
          },
          "preparation": {
            "type": "object",
            "required": [
              "template",
              "signing_template"
            ],
            "properties": {
              "template": {
                "$ref": "#/components/schemas/WireTransaction"
              },
              "signing_template": {
                "type": "string",
                "description": "kaspa-wasm safe JSON the wallet signs."
              }
            }
          }
        }
      },
      "DeployGenesisRequest": {
        "type": "object",
        "description": "The prepare request again, plus the deploy id and the signed preparation transaction. The backend relays it and returns the genesis template to sign.",
        "required": [
          "deploy_id",
          "preparation",
          "capacity",
          "price_kas",
          "publicKey",
          "address"
        ],
        "properties": {
          "capacity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Number of tickets the event can mint."
          },
          "price_kas": {
            "type": "number",
            "minimum": 1,
            "description": "Ticket price in KAS (not sompi). Minimum 1 KAS; free events are not supported."
          },
          "publicKey": {
            "type": "string",
            "pattern": "^(?:[0-9a-fA-F]{64}|[0-9a-fA-F]{66})$",
            "description": "Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key."
          },
          "address": {
            "type": "string",
            "description": "The wallet's bech32 address; the backend fetches its UTXOs itself."
          },
          "name": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "description": "YYYY-MM-DD; required with `name`."
          },
          "time": {
            "type": "string",
            "description": "HH:MM; requires `date`."
          },
          "ticker": {
            "type": "string",
            "description": "Ecosystem token ticker, declared in the KCC-23 metadata."
          },
          "decimals": {
            "type": "integer",
            "minimum": 0,
            "maximum": 255
          },
          "image": {
            "type": "string",
            "description": "https:// or ipfs:// poster URI."
          },
          "image_hash": {
            "type": "string",
            "description": "sha256 of the poster, 64 hex."
          },
          "deploy_id": {
            "type": "string"
          },
          "preparation": {
            "type": "object",
            "required": [
              "template",
              "signed"
            ],
            "properties": {
              "template": {
                "$ref": "#/components/schemas/WireTransaction"
              },
              "signed": {
                "$ref": "#/components/schemas/SigningOutput"
              }
            }
          }
        }
      },
      "DeployGenesisResult": {
        "type": "object",
        "description": "The genesis round: `preparation_txid` is the transaction whose payload commits the metadata; sign `genesis.signing_template` and post it to `deploy/finalize`.",
        "required": [
          "preparation_txid",
          "event_covenant_id",
          "genesis"
        ],
        "properties": {
          "preparation_txid": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "event_covenant_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "genesis": {
            "type": "object",
            "required": [
              "template",
              "signing_template"
            ],
            "properties": {
              "template": {
                "$ref": "#/components/schemas/WireTransaction"
              },
              "signing_template": {
                "type": "string",
                "description": "kaspa-wasm safe JSON the wallet signs."
              }
            }
          }
        }
      },
      "DeployFinalizeRequest": {
        "type": "object",
        "required": [
          "deploy_id",
          "template",
          "signed"
        ],
        "properties": {
          "deploy_id": {
            "type": "string"
          },
          "template": {
            "$ref": "#/components/schemas/WireTransaction"
          },
          "signed": {
            "$ref": "#/components/schemas/SigningOutput"
          }
        }
      },
      "DeployFinalizeResult": {
        "type": "object",
        "required": [
          "covenant_id",
          "deploy_txid"
        ],
        "properties": {
          "covenant_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "deploy_txid": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$",
            "description": "The genesis transaction id."
          }
        }
      },
      "BuyPrepareRequest": {
        "type": "object",
        "required": [
          "publicKey",
          "address"
        ],
        "properties": {
          "publicKey": {
            "type": "string",
            "pattern": "^(?:[0-9a-fA-F]{64}|[0-9a-fA-F]{66})$",
            "description": "Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key."
          },
          "address": {
            "type": "string",
            "description": "The wallet's bech32 address; the backend fetches its UTXOs itself."
          }
        }
      },
      "BuyPrepareResult": {
        "type": "object",
        "required": [
          "buy_id",
          "signing_template",
          "template",
          "sign_inputs",
          "price",
          "ticket_value",
          "network_fee",
          "organizer_proceeds"
        ],
        "properties": {
          "buy_id": {
            "type": "string",
            "description": "Correlation id echoed on finalize."
          },
          "signing_template": {
            "type": "string"
          },
          "template": {
            "$ref": "#/components/schemas/WireTransaction"
          },
          "sign_inputs": {
            "type": "array",
            "description": "Inputs the wallet must sign — all but the covenant spend at index 0.",
            "items": {
              "$ref": "#/components/schemas/InputIndex"
            }
          },
          "price": {
            "type": "integer",
            "minimum": 100000000,
            "description": "Ticket price in sompi (minimum 1 KAS). This is exactly what the buyer pays."
          },
          "ticket_value": {
            "type": "integer",
            "minimum": 0,
            "description": "Value carried inside the newly minted ticket, in sompi. Part of `price`, not an extra charge."
          },
          "network_fee": {
            "type": "integer",
            "minimum": 0,
            "description": "Network fee taken out of `price`, in sompi."
          },
          "organizer_proceeds": {
            "type": "integer",
            "minimum": 0,
            "description": "What the organizer receives: `price - ticket_value - network_fee`."
          }
        }
      },
      "BuyFinalizeRequest": {
        "type": "object",
        "required": [
          "buy_id",
          "template",
          "signed"
        ],
        "properties": {
          "buy_id": {
            "type": "string"
          },
          "template": {
            "$ref": "#/components/schemas/WireTransaction"
          },
          "signed": {
            "$ref": "#/components/schemas/SigningOutput"
          }
        }
      },
      "BuyFinalizeResult": {
        "type": "object",
        "required": [
          "txid",
          "status"
        ],
        "properties": {
          "txid": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "status": {
            "type": "string",
            "enum": [
              "settled",
              "pending"
            ],
            "description": "`settled` — the ledger accepted the transaction, so every output it declares exists (the ticket exists, the payment settled). `pending` — the transaction was relayed and is not accepted yet; it may still settle. A pending response is not a failure: do not re-broadcast, and read the chain to learn the outcome."
          }
        }
      },
      "TicketSummary": {
        "type": "object",
        "required": [
          "ticket_id",
          "covenant_id",
          "event_name",
          "event_date",
          "event_time"
        ],
        "properties": {
          "ticket_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}:[0-9]+$"
          },
          "covenant_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "event_name": {
            "type": "string"
          },
          "event_date": {
            "type": "string"
          },
          "event_time": {
            "type": "string"
          },
          "listed": {
            "type": "boolean",
            "description": "Present and true for a listed ticket."
          },
          "price": {
            "type": "integer",
            "minimum": 0,
            "description": "Asking price in sompi; present only for a listed ticket."
          }
        }
      },
      "UsePrepareRequest": {
        "type": "object",
        "required": [
          "publicKey",
          "address"
        ],
        "properties": {
          "publicKey": {
            "type": "string",
            "pattern": "^(?:[0-9a-fA-F]{64}|[0-9a-fA-F]{66})$",
            "description": "Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key."
          },
          "address": {
            "type": "string",
            "description": "The wallet's bech32 address; the backend fetches its UTXOs itself."
          }
        }
      },
      "UsePrepareResult": {
        "type": "object",
        "required": [
          "use_id",
          "signing_template",
          "template",
          "sign_inputs_owner",
          "event"
        ],
        "properties": {
          "use_id": {
            "type": "string",
            "description": "Correlation id carried in the QR payload."
          },
          "signing_template": {
            "type": "string"
          },
          "template": {
            "$ref": "#/components/schemas/WireTransaction"
          },
          "sign_inputs_owner": {
            "type": "array",
            "description": "The ticket input (index 0) plus the owner's fee inputs.",
            "items": {
              "$ref": "#/components/schemas/InputIndex"
            }
          },
          "event": {
            "$ref": "#/components/schemas/EventRef"
          }
        }
      },
      "UseSignTemplateRequest": {
        "type": "object",
        "required": [
          "template"
        ],
        "properties": {
          "template": {
            "$ref": "#/components/schemas/WireTransaction"
          }
        }
      },
      "UseSignTemplateResult": {
        "type": "object",
        "required": [
          "signing_template"
        ],
        "properties": {
          "signing_template": {
            "type": "string"
          }
        }
      },
      "UseFinalizeRequest": {
        "type": "object",
        "required": [
          "use_id",
          "template",
          "owner_signed",
          "gate_signed"
        ],
        "properties": {
          "use_id": {
            "type": "string"
          },
          "template": {
            "$ref": "#/components/schemas/WireTransaction"
          },
          "owner_signed": {
            "$ref": "#/components/schemas/SigningOutput"
          },
          "gate_signed": {
            "$ref": "#/components/schemas/SigningOutput"
          }
        }
      },
      "ListingSummary": {
        "type": "object",
        "required": [
          "ticket_id",
          "price",
          "seller_pkh",
          "event_name",
          "event_date",
          "covenant_id",
          "verified"
        ],
        "properties": {
          "ticket_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}:[0-9]+$"
          },
          "price": {
            "type": "integer",
            "minimum": 100000000,
            "description": "Asking price in sompi (minimum 1 KAS)."
          },
          "seller_pkh": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "event_name": {
            "type": "string"
          },
          "event_date": {
            "type": "string"
          },
          "covenant_id": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "verified": {
            "type": "boolean",
            "const": true
          }
        }
      },
      "ListPrepareRequest": {
        "type": "object",
        "required": [
          "publicKey",
          "address",
          "price"
        ],
        "properties": {
          "publicKey": {
            "type": "string",
            "pattern": "^(?:[0-9a-fA-F]{64}|[0-9a-fA-F]{66})$",
            "description": "Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key."
          },
          "address": {
            "type": "string",
            "description": "The wallet's bech32 address; the backend fetches its UTXOs itself."
          },
          "price": {
            "type": "integer",
            "minimum": 100000000,
            "description": "Asking price in sompi (minimum 1 KAS)."
          }
        }
      },
      "ListPrepareResult": {
        "type": "object",
        "required": [
          "list_id",
          "signing_template",
          "template",
          "sign_inputs",
          "price",
          "event"
        ],
        "properties": {
          "list_id": {
            "type": "string"
          },
          "signing_template": {
            "type": "string"
          },
          "template": {
            "$ref": "#/components/schemas/WireTransaction"
          },
          "sign_inputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InputIndex"
            }
          },
          "price": {
            "type": "integer",
            "minimum": 100000000
          },
          "event": {
            "$ref": "#/components/schemas/EventRef"
          }
        }
      },
      "ListFinalizeRequest": {
        "type": "object",
        "required": [
          "template",
          "signed",
          "price"
        ],
        "properties": {
          "template": {
            "$ref": "#/components/schemas/WireTransaction"
          },
          "signed": {
            "$ref": "#/components/schemas/SigningOutput"
          },
          "price": {
            "type": "integer",
            "minimum": 100000000,
            "description": "The same price sent to prepare (minimum 1 KAS)."
          }
        }
      },
      "DelistPrepareRequest": {
        "type": "object",
        "required": [
          "publicKey",
          "address"
        ],
        "properties": {
          "publicKey": {
            "type": "string",
            "pattern": "^(?:[0-9a-fA-F]{64}|[0-9a-fA-F]{66})$",
            "description": "Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key."
          },
          "address": {
            "type": "string",
            "description": "The wallet's bech32 address; the backend fetches its UTXOs itself."
          }
        }
      },
      "DelistPrepareResult": {
        "type": "object",
        "required": [
          "delist_id",
          "signing_template",
          "template",
          "sign_inputs",
          "event"
        ],
        "properties": {
          "delist_id": {
            "type": "string"
          },
          "signing_template": {
            "type": "string"
          },
          "template": {
            "$ref": "#/components/schemas/WireTransaction"
          },
          "sign_inputs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InputIndex"
            }
          },
          "event": {
            "$ref": "#/components/schemas/EventRef"
          }
        }
      },
      "DelistFinalizeRequest": {
        "type": "object",
        "required": [
          "template",
          "signed"
        ],
        "properties": {
          "template": {
            "$ref": "#/components/schemas/WireTransaction"
          },
          "signed": {
            "$ref": "#/components/schemas/SigningOutput"
          }
        }
      },
      "PurchasePrepareRequest": {
        "type": "object",
        "required": [
          "publicKey",
          "address"
        ],
        "properties": {
          "publicKey": {
            "type": "string",
            "pattern": "^(?:[0-9a-fA-F]{64}|[0-9a-fA-F]{66})$",
            "description": "Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key."
          },
          "address": {
            "type": "string",
            "description": "The wallet's bech32 address; the backend fetches its UTXOs itself."
          }
        }
      },
      "PurchasePrepareResult": {
        "type": "object",
        "required": [
          "purchase_id",
          "signing_template",
          "template",
          "sign_inputs",
          "price",
          "ticket_value",
          "seller_proceeds",
          "network_fee",
          "seller_pkh",
          "event"
        ],
        "properties": {
          "purchase_id": {
            "type": "string"
          },
          "signing_template": {
            "type": "string"
          },
          "template": {
            "$ref": "#/components/schemas/WireTransaction"
          },
          "sign_inputs": {
            "type": "array",
            "description": "Only the buyer's fee inputs; input 0 is signatureless.",
            "items": {
              "$ref": "#/components/schemas/InputIndex"
            }
          },
          "price": {
            "type": "integer",
            "minimum": 100000000,
            "description": "Asking price in sompi (minimum 1 KAS). This is exactly what the buyer pays."
          },
          "ticket_value": {
            "type": "integer",
            "minimum": 0,
            "description": "Value carried inside the ticket, in sompi. Included in `price`."
          },
          "seller_proceeds": {
            "type": "integer",
            "minimum": 0,
            "description": "What the seller receives: `price - network_fee`."
          },
          "network_fee": {
            "type": "integer",
            "minimum": 0,
            "description": "Network fee taken out of `price`, in sompi."
          },
          "seller_pkh": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          },
          "event": {
            "$ref": "#/components/schemas/EventRef"
          }
        }
      },
      "PurchaseFinalizeRequest": {
        "type": "object",
        "required": [
          "template",
          "signed"
        ],
        "properties": {
          "template": {
            "$ref": "#/components/schemas/WireTransaction"
          },
          "signed": {
            "$ref": "#/components/schemas/SigningOutput"
          }
        }
      }
    }
  },
  "x-network": {
    "network": "testnet10",
    "networkId": "testnet-10"
  }
}
