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
200 | The 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
}
] |
401 | Authentication required, or the session token is missing/expired. ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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 stringgenesis_txid optional string — Legacy alias for deploy_txid.
{
"deploy_txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
Responses
200 | The registered event's covenant id. RegisterEventResponse |
| {
"covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba"
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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
200 | The 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"
}
} |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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 stringdate 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 integerimage 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
200 | The 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\"}"
}
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
422 | Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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 stringdate 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 integerimage optional string — https:// or ipfs:// poster URI.image_hash optional string — sha256 of the poster, 64 hex.deploy_id required stringpreparation 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
200 | The 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}"
}
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
422 | Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
502 | The network refused the signed transaction. ErrorEnvelope |
503 | The 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 stringtemplate required WireTransactionsigned 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
200 | The deployed, registered event. DeployFinalizeResult |
| {
"covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba",
"deploy_txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
502 | The network refused the signed transaction. ErrorEnvelope |
503 | The 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
200 | The 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
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
422 | Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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 stringtemplate required WireTransactionsigned 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
200 | The mint transaction and whether it settled. BuyFinalizeResult |
| {
"txid": "1234123412341234123412341234123412341234123412341234123412341234",
"status": "settled"
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
502 | The network refused the signed transaction. ErrorEnvelope |
503 | The 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
200 | The caller's tickets. TicketSummary[] |
| [
{
"ticket_id": "bb00000000000000000000000000000000000000000000000000000000000000:0",
"covenant_id": "234f446748ff76774c8ca9c99531a34111066f902daa95663a399f4a2893a3ba",
"event_name": "Testnet Rave",
"event_date": "2026-12-31",
"event_time": "20:00"
}
] |
401 | Authentication required, or the session token is missing/expired. ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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
200 | The 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"
}
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
422 | Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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
200 | The 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}"
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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 stringtemplate required WireTransactionowner_signed required SigningOutputgate_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
200 | The check-in transaction and whether it settled. FinalizeResult |
| {
"txid": "5678567856785678567856785678567856785678567856785678567856785678",
"status": "settled"
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
422 | Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
502 | The network refused the signed transaction. ErrorEnvelope |
503 | The 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
200 | Every live resale listing. ListingSummary[] |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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
200 | Live 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
}
] |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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
200 | The 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"
}
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
422 | Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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 WireTransactionsigned required SigningOutputprice 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
200 | The listing transaction and whether it settled. FinalizeResult |
| {
"txid": "9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc9abc",
"status": "settled"
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
502 | The network refused the signed transaction. ErrorEnvelope |
503 | The 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
200 | The 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"
}
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
422 | Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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 WireTransactionsigned 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
200 | The delisting transaction and whether it settled. FinalizeResult |
| {
"txid": "bcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcdebcde",
"status": "settled"
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
502 | The network refused the signed transaction. ErrorEnvelope |
503 | The 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
200 | The 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"
}
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
422 | Rejected by a policy (sold out, not the owner, no spendable funds). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
503 | The 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 WireTransactionsigned 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
200 | The purchase transaction and whether it settled. FinalizeResult |
| {
"txid": "def0def0def0def0def0def0def0def0def0def0def0def0def0def0def0def0",
"status": "settled"
} |
400 | Invalid request — a field is missing, malformed, or out of range. ErrorEnvelope |
404 | The named resource is not known (or not on chain). ErrorEnvelope |
500 | Unexpected server error. ErrorEnvelope |
502 | The network refused the signed transaction. ErrorEnvelope |
503 | The 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-*
| Status | Meaning |
400 | Invalid request — a field is missing, malformed, or out of range. |
401 | Authentication required, or the session token is missing/expired. |
404 | The named resource is not known (or not on chain). |
422 | Rejected by a policy (sold out, not the owner, no spendable funds). |
500 | Unexpected server error. |
502 | The network refused the signed transaction. |
503 | The chain upstream is unavailable; retry after retryAfter. |
429 | Too many requests; retry after retryAfter seconds. |