kticket API

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.

Version 1.0.0

config

The deployment's runtime network identity.

GET /v1/config

Read the server's runtime network identity

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

200The runtime network identity. ServerConfig
{
  "network": "testnet10",
  "network_id": "testnet-10",
  "wallet_network": "kaspa_testnet_10",
  "address_prefix": "kaspatest:"
}
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

auth

Challenge → signature → session token.

POST /v1/auth/challenge

Ask for a sign-in challenge

Returns a single-use nonce and the exact message to sign. The message names the server's network id — never choose a network yourself.

Request body

ChallengeRequest

  • address required string — The wallet's bech32 address; the backend fetches its UTXOs itself.
{
  "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun"
}

Responses

200The challenge to sign. ChallengeResponse
{
  "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"
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/auth/session

Exchange a signed challenge for a session token

The nonce is consumed on first use. The response carries the bearer token required by user-specific reads.

Request body

SessionRequest

  • message required string — The message from the challenge response.
  • signature required string — Kaspa Schnorr message signature over message, hex or base64.
{
  "message": "kticket\n\nkticket wants you to sign in with your Kaspa account:\n...",
  "signature": "41abababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababababab"
}

Responses

200The session token. SessionResponse
{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ...",
  "expires_in_seconds": 900
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
401Authentication required, or the session token is missing/expired. ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

feedback

Anonymous feedback, no wallet and no account.

POST /v1/feedback

Send anonymous feedback

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.

Request body

FeedbackRequest

  • message required string — The visitor's note. Whitespace-only messages are rejected; the server trims before storing.
{
  "message": "The check-in page worked, but I could not find where to download my ticket."
}

Responses

202Feedback accepted and queued or delivered. FeedbackResponse
{
  "accepted": true,
  "delivered": true
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope
429Too many requests; retry after retryAfter seconds. ErrorEnvelope

events

Verified events, deploys, and primary ticket purchases.

GET /v1/events

List verified events

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.

Auth: bearer token.

Parameters

  • organizer_address query optional — Filter to one organizer. Requires Authorization: Bearer <token> for that same address.

Responses

200The verified events. EventSummary[]
[
  {
    "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
  }
]
401Authentication required, or the session token is missing/expired. ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/events

Register a deployed event for discovery

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.

Request body

RegisterEventRequest

  • deploy_txid optional string
  • genesis_txid optional string — Legacy alias for deploy_txid.
{
  "deploy_txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

Responses

200The registered event's covenant id. RegisterEventResponse
{
  "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
404The named resource is not known (or not on chain). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

GET /v1/events/{covenant_id}

Read one verified event

Re-verifies the event from its deploy transaction and returns both the friendly facts and the raw chain facts they were derived from.

Parameters

  • covenant_id path required — The event's covenant id (64 lowercase hex), as returned by GET /v1/events.

Responses

200The event and its raw chain facts. EventDetail
{
  "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"
  }
}
404The named resource is not known (or not on chain). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/events/deploy/prepare

Prepare the KCC-23 preparation transaction

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.

Request body

DeployPrepareRequest

  • capacity required integer — Number of tickets the event can mint.
  • price_kas required number — Ticket price in KAS (not sompi). Minimum 1 KAS; free events are not supported.
  • publicKey required string — Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key.
  • address required string — The wallet's bech32 address; the backend fetches its UTXOs itself.
  • name optional string
  • date optional string — YYYY-MM-DD; required with name.
  • time optional string — HH:MM; requires date.
  • ticker optional string — Ecosystem token ticker, declared in the KCC-23 metadata.
  • decimals optional integer
  • image optional string — https:// or ipfs:// poster URI.
  • image_hash optional string — sha256 of the poster, 64 hex.
{
  "capacity": 2,
  "price_kas": 1,
  "publicKey": "0202020202020202020202020202020202020202020202020202020202020202",
  "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun",
  "name": "Testnet Rave",
  "date": "2026-12-31",
  "time": "20:00"
}

Responses

200The unsigned preparation template. DeployPrepareResult
{
  "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\"}"
  }
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
422Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/events/deploy/genesis

Publish the preparation transaction and build the genesis transaction

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.

Request body

DeployGenesisRequest

  • capacity required integer — Number of tickets the event can mint.
  • price_kas required number — Ticket price in KAS (not sompi). Minimum 1 KAS; free events are not supported.
  • publicKey required string — Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key.
  • address required string — The wallet's bech32 address; the backend fetches its UTXOs itself.
  • name optional string
  • date optional string — YYYY-MM-DD; required with name.
  • time optional string — HH:MM; requires date.
  • ticker optional string — Ecosystem token ticker, declared in the KCC-23 metadata.
  • decimals optional integer
  • image optional string — https:// or ipfs:// poster URI.
  • image_hash optional string — sha256 of the poster, 64 hex.
  • deploy_id required string
  • preparation required object
{
  "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

200The unsigned genesis template. DeployGenesisResult
{
  "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}"
  }
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
422Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
502The network refused the signed transaction. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/events/deploy/finalize

Finalize an event deploy

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.

Request body

DeployFinalizeRequest

  • deploy_id required string
  • template required WireTransaction
  • signed required SigningOutput
{
  "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

200The deployed, registered event. DeployFinalizeResult
{
  "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba",
  "deploy_txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
404The named resource is not known (or not on chain). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
502The network refused the signed transaction. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/events/{covenant_id}/buy/prepare

Prepare a primary ticket purchase

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

  • covenant_id path required — The event's covenant id (64 lowercase hex), as returned by GET /v1/events.

Request body

BuyPrepareRequest

  • publicKey required string — Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key.
  • address required string — The wallet's bech32 address; the backend fetches its UTXOs itself.
{
  "publicKey": "0202020202020202020202020202020202020202020202020202020202020202",
  "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun"
}

Responses

200The unsigned buy template. BuyPrepareResult
{
  "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
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
404The named resource is not known (or not on chain). ErrorEnvelope
422Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/events/{covenant_id}/buy/finalize

Finalize a primary ticket purchase

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

  • covenant_id path required — The event's covenant id (64 lowercase hex), as returned by GET /v1/events.

Request body

BuyFinalizeRequest

  • buy_id required string
  • template required WireTransaction
  • signed required SigningOutput
{
  "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

200The mint transaction and whether it settled. BuyFinalizeResult
{
  "txid": "1234123412341234123412341234123412341234123412341234123412341234",
  "status": "settled"
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
500Unexpected server error. ErrorEnvelope
502The network refused the signed transaction. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

tickets

The caller's tickets and the door (check-in) flow.

GET /v1/tickets

List the signed-in wallet's tickets

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.

Auth: bearer token.

Responses

200The caller's tickets. TicketSummary[]
[
  {
    "ticket_id": "bb00000000000000000000000000000000000000000000000000000000000000:0",
    "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba",
    "event_name": "Testnet Rave",
    "event_date": "2026-12-31",
    "event_time": "20:00"
  }
]
401Authentication required, or the session token is missing/expired. ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/tickets/{ticket_id}/use/prepare

Prepare a check-in (door flow)

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

  • ticket_id path required — <64-hex transaction id>:<output index> — the shape served by GET /v1/tickets.

Request body

UsePrepareRequest

  • publicKey required string — Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key.
  • address required string — The wallet's bech32 address; the backend fetches its UTXOs itself.
{
  "publicKey": "0202020202020202020202020202020202020202020202020202020202020202",
  "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun"
}

Responses

200The check-in template the owner signs. UsePrepareResult
{
  "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"
  }
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
404The named resource is not known (or not on chain). ErrorEnvelope
422Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/tickets/{ticket_id}/use/sign-template

Rebuild a check-in signing template at the gate

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

  • ticket_id path required — <64-hex transaction id>:<output index> — the shape served by GET /v1/tickets.

Request body

UseSignTemplateRequest

  • template required WireTransaction
{
  "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

200The rebuilt safe JSON. UseSignTemplateResult
{
  "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}"
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
404The named resource is not known (or not on chain). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/tickets/{ticket_id}/use/finalize

Finalize a check-in

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

  • ticket_id path required — <64-hex transaction id>:<output index> — the shape served by GET /v1/tickets.

Request body

UseFinalizeRequest

  • use_id required string
  • template required WireTransaction
  • owner_signed required SigningOutput
  • gate_signed required SigningOutput
{
  "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

200The check-in transaction and whether it settled. FinalizeResult
{
  "txid": "5678567856785678567856785678567856785678567856785678567856785678",
  "status": "settled"
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
404The named resource is not known (or not on chain). ErrorEnvelope
422Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
502The network refused the signed transaction. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

resale

List, delist, browse, and trustlessly purchase tickets.

GET /v1/listings

List every resale listing

The workspace-wide resale directory. Each entry is proven on chain exactly as in the per-event listing.

Responses

200Every live resale listing. ListingSummary[]
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

GET /v1/events/{covenant_id}/listings

List an event's resale listings

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

  • covenant_id path required — The event's covenant id (64 lowercase hex), as returned by GET /v1/events.

Responses

200Live resale listings for the event. ListingSummary[]
[
  {
    "ticket_id": "bb00000000000000000000000000000000000000000000000000000000000000:0",
    "price": 200000000,
    "seller_pkh": "0203030303030303030303030303030303030303030303030303030303030303",
    "event_name": "Testnet Rave",
    "event_date": "2026-12-31",
    "covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba",
    "verified": true
  }
]
404The named resource is not known (or not on chain). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/tickets/{ticket_id}/list/prepare

Prepare a resale listing

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

  • ticket_id path required — <64-hex transaction id>:<output index> — the shape served by GET /v1/tickets.

Request body

ListPrepareRequest

  • publicKey required string — Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key.
  • address required string — The wallet's bech32 address; the backend fetches its UTXOs itself.
  • price required integer — Asking price in sompi (minimum 1 KAS).
{
  "publicKey": "0202020202020202020202020202020202020202020202020202020202020202",
  "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun",
  "price": 200000000
}

Responses

200The unsigned listing template. ListPrepareResult
{
  "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"
  }
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
404The named resource is not known (or not on chain). ErrorEnvelope
422Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/tickets/{ticket_id}/list/finalize

Finalize a resale listing

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

  • ticket_id path required — <64-hex transaction id>:<output index> — the shape served by GET /v1/tickets.

Request body

ListFinalizeRequest

  • template required WireTransaction
  • signed required SigningOutput
  • price required integer — The same price sent to prepare (minimum 1 KAS).
{
  "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

200The listing transaction and whether it settled. FinalizeResult
{
  "txid": "9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc",
  "status": "settled"
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
404The named resource is not known (or not on chain). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
502The network refused the signed transaction. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/tickets/{ticket_id}/delist/prepare

Prepare a delisting

Clears a live listing. The recorded price comes from the index and is proven against the chain before the template is built.

Parameters

  • ticket_id path required — <64-hex transaction id>:<output index> — the shape served by GET /v1/tickets.

Request body

DelistPrepareRequest

  • publicKey required string — Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key.
  • address required string — The wallet's bech32 address; the backend fetches its UTXOs itself.
{
  "publicKey": "0202020202020202020202020202020202020202020202020202020202020202",
  "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun"
}

Responses

200The unsigned delisting template. DelistPrepareResult
{
  "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"
  }
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
404The named resource is not known (or not on chain). ErrorEnvelope
422Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/tickets/{ticket_id}/delist/finalize

Finalize a delisting

Merges signatures, broadcasts the unlisted-state spend, and drops the index row.

Parameters

  • ticket_id path required — <64-hex transaction id>:<output index> — the shape served by GET /v1/tickets.

Request body

DelistFinalizeRequest

  • template required WireTransaction
  • signed required SigningOutput
{
  "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

200The delisting transaction and whether it settled. FinalizeResult
{
  "txid": "bcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcde",
  "status": "settled"
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
404The named resource is not known (or not on chain). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
502The network refused the signed transaction. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/tickets/{ticket_id}/purchase/prepare

Prepare a trustless resale purchase

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

  • ticket_id path required — <64-hex transaction id>:<output index> — the shape served by GET /v1/tickets.

Request body

PurchasePrepareRequest

  • publicKey required string — Compressed (66 hex) or bare x-coordinate (64 hex) Kaspa public key.
  • address required string — The wallet's bech32 address; the backend fetches its UTXOs itself.
{
  "publicKey": "0405050505050505050505050505050505050505050505050505050505050505",
  "address": "kaspatest:qqqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszapw00vun"
}

Responses

200The unsigned purchase template. PurchasePrepareResult
{
  "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"
  }
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
404The named resource is not known (or not on chain). ErrorEnvelope
422Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

POST /v1/tickets/{ticket_id}/purchase/finalize

Finalize a trustless resale purchase

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

  • ticket_id path required — <64-hex transaction id>:<output index> — the shape served by GET /v1/tickets.

Request body

PurchaseFinalizeRequest

  • template required WireTransaction
  • signed required SigningOutput
{
  "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

200The purchase transaction and whether it settled. FinalizeResult
{
  "txid": "def0def0def0def0def0def0def0def0def0def0def0def0def0def0def0def0",
  "status": "settled"
}
400Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope
404The named resource is not known (or not on chain). ErrorEnvelope
500Unexpected server error. ErrorEnvelope
502The network refused the signed transaction. ErrorEnvelope
503The chain upstream is unavailable; retry after retryAfter. ErrorEnvelope

Errors

Every failure uses one envelope. type is stable and machine-readable; retryable says whether the same request may succeed later.

{
  "error": {
    "type": "invalid",
    "message": "capacity must be 0..100",
    "retryable": false
  }
}

Types: invalid, conflict, policy, network, upstream, unauthorized, unknown-*

StatusMeaning
400Invalid request — a field is missing, malformed, or out of range.
401Authentication required, or the session token is missing/expired.
404The named resource is not known (or not on chain).
422Rejected by a policy (sold out, not the owner, no spendable funds).
500Unexpected server error.
502The network refused the signed transaction.
503The chain upstream is unavailable; retry after retryAfter.
429Too many requests; retry after retryAfter seconds.