API reference

Everything the console does, it does through these routes, and so can you. No key, no account. Reads are public chain data; what is served can be checked against the chain rather than believed. This page is drawn from the contract the server exports (version 0.6.0).

base: https://api.cachetzec.com
errors: application/problem+json, never cached
limit: 30 requests a second per client, bursts of 60, then 429
contract: openapi.json · try requests in Swagger

Registry

What the chain says, read for you: assets, issuers, public history, and what is kept of assets a reset took.

GET/api/v1/assets

List every asset observed on the chain, newest first.

Without parameters: the whole registry, as before. limit and offset cut a page out of it; q, issuer, supply and resolved narrow it first, and order=named_first brings attested names to the front. All of them are the caller's view, never moderation: everything stays reachable without them.

Three headers carry what a pager needs: X-Registry-Count (assets listed at all), X-Total-Count (assets matching the filters, before the page is cut) and X-Unresolved-Count (those among them without a resolved description). The response carries an ETag; send it back in If-None-Match and an unchanged listing answers 304 with no body.

Parameters

limitinteger · query: Keep only the newest N assets. Omitted: the whole registry (what a client doing its own search or mirroring wants).
offsetinteger · query: Skip this many assets before the first one returned. With limit, a page. The totals a pager needs come back as headers.
resolvedboolean · query: true: keep only assets whose description is known, so their name is attested rather than an id. Omitted: everything, which stays the default - this is a caller's view preference, never moderation.
qstring · query: Keep assets whose name or description contains this text (case ignored), or whose asset id or issuer key starts with it.
issuerstring · query: Keep only assets minted under this issuance key (hex).
supply"sealed" | "open" · query: sealed: finalized assets only. open: the others.
order"named_first" | "active" · query: named_first: sealed names, then free-text labels, then unnamed, chain order kept inside each group. active: latest public event (issuance, burn or seal) first. Omitted: newest first.

Answers

200AssetSummaryResponse[]

ETag Validator for If-None-Match

X-Registry-Count Assets listed, before any filter

X-Total-Count Assets matching the filters, before offset and limit

X-Unresolved-Count Matching assets without a resolved description

304

The listing the caller holds is still current

400ProblemDetails

A problem document (RFC 9457): type, title, status, detail.

503ProblemDetails

A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/assets"

GET/api/v1/assets/{asset_id}

Read the on-chain state of an asset, with its registry enrichment (journaled description, display name, image) when known.

Parameters

asset_idstring · path · required: Asset id, hex-encoded 32 bytes

Answers

200AssetSummaryResponse
400ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/assets/{asset_id}"

POST/api/v1/assets/{asset_id}/description

Teach the registry the plaintext description of an on-chain asset.

Verified, permissionless, and deliberately open on read-only deployments: the chain stores only the description hash (ZIP 227), so a submission either matches the on-chain commitment or is rejected — the registry cannot be lied to. This is how assets issued elsewhere gain names here.

Parameters

asset_idstring · path · required: Asset id, hex-encoded 32 bytes

Body · ResolveDescriptionRequest

descriptionstring · required: The plaintext asset description (1–512 bytes).

Answers

200AssetSummaryResponse: Resolved; the enriched record
400ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
422ProblemDetails: The description does not hash to the on-chain commitment
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl -X POST "https://api.cachetzec.com/api/v1/assets/{asset_id}/description" \
  -H "content-type: application/json" \
  -d '{"description":"Testnet Sample"}'

GET/api/v1/assets/{asset_id}/events

Public events of an asset's life, oldest first. Transfers are shielded and never listed.

Parameters

asset_idstring · path · required: Asset id, hex-encoded 32 bytes

Answers

200AssetEventResponse[]
400ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/assets/{asset_id}/events"

GET/api/v1/collections

Chain-level collections: every asset minted under one issuance key, grouped — the only provenance statement the chain itself makes.

Answers

200CollectionResponse[]: ETag Validator for If-None-Match
304: The listing the caller holds is still current
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/collections"

GET/api/v1/kept

Sealed content kept for assets the chain no longer carries.

A test network can be reset, and a reset takes every asset with it. The registry's journal of descriptions and its bundles are keyed by asset id and survive: this lists the ones whose asset is no longer on the chain the registry follows, sealed names first. X-Total-Count carries the total. Descriptions the operator withholds are left out.

Parameters

limitinteger · query: Rows per page (1-100, default 25).
offsetinteger · query: Rows to skip.

Answers

200KeptAssetResponse[]

ETag Validator for If-None-Match

X-Total-Count Kept assets, before offset and limit

304

The listing the caller holds is still current

503ProblemDetails

A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/kept"

GET/api/v1/kept/{asset_id}

The sealed content kept for one asset the chain no longer carries.

404 when the asset is on chain (ask /api/v1/assets/{asset_id}), was never known here, or its description is withheld by the operator.

Parameters

asset_idstring · path · required: Asset id, hex-encoded 32 bytes

Answers

200KeptAssetResponse
400ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/kept/{asset_id}"

GET/api/v1/transactions/{txid}

What one transaction publishes about ZSAs: its issuance bundle (issuer key, assets, units, seals, reference notes) and its burns, read from the transaction's own bytes. Transfers stay encrypted; only their action count shows. Issue-note recipients are public on chain but left out. A transaction issuing under a key this registry withholds answers 410.

Parameters

txidstring · path · required: Transaction id, hex, display byte order

Answers

200DecodedTransactionResponse
400ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
410ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/transactions/{txid}"

Sealed metadata

Content-addressed bundles. The hash is in the asset id, so check what you are served against it.

POST/api/v1/metadata

Body · MetadataUploadRequest

descriptionstring or null: Long-form description (≤ 4096 bytes), stored in the bundle only.
external_urlstring or null: Optional issuer link.
image_data_uristring or null: Embedded image as a base64 data URI (png/jpeg/webp/gif, ≤ ~400 KB).
namestring · required: Display name (1–120 bytes); becomes part of the immutable on-chain description.

Answers

201MetadataUploadResponse
400ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
410ProblemDetails: These exact bytes were withheld or purged by this registry's operator
429ProblemDetails: This client's upload budget for the minute is spent, or the pending-upload pool is at capacity
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl -X POST "https://api.cachetzec.com/api/v1/metadata" \
  -H "content-type: application/json" \
  -d '{"name":"Zcon Ticket 2027"}'

GET/api/v1/metadata/{sha256}

Fetch a metadata bundle by its content hash. Verifiable: re-hash the body and compare with the path.

Parameters

sha256string · path · required: Bundle hash, hex-encoded 32 bytes

Answers

200: The bundle JSON, byte-exact as stored
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/metadata/{sha256}"

GET/api/v1/metadata/{sha256}/image

Serve the image embedded in a metadata bundle (same-origin, so the console never fetches third-party assets — PRIVACY.md P5).

Parameters

sha256string · path · required: Bundle hash, hex-encoded 32 bytes

Answers

200: The embedded image bytes
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/metadata/{sha256}/image"

Chain and relay

The tip, raw blocks for scanning on your own machine, and the relay for transactions signed elsewhere.

GET/api/v1/chain

Identify the connected network and chain tip.

Answers

200ChainInfoResponse
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/chain"

GET/api/v1/chain/orchard-tree

The Orchard note commitment tree after the current tip.

A browser wallet created now has no note in any earlier block, so it starts from this tree instead of reading the chain from its first block. Every caller asking at the same tip gets the same answer.

Answers

200OrchardTreeResponse
404ProblemDetails: This backend keeps no Orchard tree
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/chain/orchard-tree"

GET/api/v1/chain/transactions

Raw transactions of a block range, for client-side note scanning.

Public chain data, identical for every caller — a browser wallet downloads these pages and trial-decrypts locally, so this instance never learns which notes belong to whom (PRIVACY.md). Open on read-only deployments for the same reason as description resolution: serving public data is not signing.

Parameters

start_heightinteger · query · required: First block height of the page (min 1).
limitinteger or null · query: Blocks per page (1-100, default 25).

Answers

200RawBlocksResponse
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/chain/transactions"

POST/api/v1/relay

Relay a fully signed, browser-built ZSA transaction (issuance, transfer or burn).

Deliberately open on read-only deployments: read-only means "this instance signs nothing", and a relayed transaction was signed by the sender's own browser-held key. The relay can refuse; it cannot alter.

Body · RelayRequest

tx_hexstring · required: Complete signed v6 transaction, hex-encoded.

Answers

202TxResponse: Accepted by the chain
400ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
422ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
429ProblemDetails: This client already has the maximum number of relays in flight (retry shortly), or has spent its relay budget for the minute (wait a minute)
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl -X POST "https://api.cachetzec.com/api/v1/relay" \
  -H "content-type: application/json" \
  -d '{ ... }'

Swaps

The swap board: offers to trade one asset for another in one shielded transaction, and the messages that complete it. The registry carries them and holds no key.

GET/api/v1/swaps

Offers open to takers, newest first.

Answers

200SwapOfferResponse[]

curl "https://api.cachetzec.com/api/v1/swaps"

POST/api/v1/swaps

Post an offer to the swap board. The offer is checked the way a taker would check it before it is listed.

Body · PostOfferRequest

hoursinteger or null: Hours it stays up: 1 to 72, 24 by default.
offerstring · required: The offer message, as the mint engine wrote it (JSON text).

Answers

201PostOfferResponse
400ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
429ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl -X POST "https://api.cachetzec.com/api/v1/swaps" \
  -H "content-type: application/json" \
  -d '{ ... }'

GET/api/v1/swaps/{id}

One offer, with the offer message itself.

Parameters

idstring · path · required: Offer id

Answers

200SwapOfferResponse
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/swaps/{id}"

DELETE/api/v1/swaps/{id}

Close an offer: the maker withdrawing it (maker token), or the taker reporting it complete once countersigned (taker token).

Parameters

idstring · path · required: Offer id

Answers

204: Closed
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl -X DELETE "https://api.cachetzec.com/api/v1/swaps/{id}"

GET/api/v1/swaps/{id}/countersignature

The countersignature, once the maker posted it (taker token).

Parameters

idstring · path · required: Offer id

Answers

200CountersignatureEnvelope
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/swaps/{id}/countersignature"

POST/api/v1/swaps/{id}/countersignature

Post the maker's countersignature (maker token).

Parameters

idstring · path · required: Offer id

Body · CountersignRequest

countersignaturestring · required
taken_atinteger · required: The taken_at of the take it signs.

Answers

204: Stored for the taker
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
409ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl -X POST "https://api.cachetzec.com/api/v1/swaps/{id}/countersignature" \
  -H "content-type: application/json" \
  -d '{ ... }'

GET/api/v1/swaps/{id}/take

The take waiting for the maker (maker token).

Parameters

idstring · path · required: Offer id

Answers

200TakeEnvelope
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/swaps/{id}/take"

POST/api/v1/swaps/{id}/take

Take an offer: hold it for the maker's countersignature.

Parameters

idstring · path · required: Offer id

Body · TakeRequest

takestring · required: The taker's message (JSON text): the transaction awaiting the maker.

Answers

201TakeResponse
409ProblemDetails: Not open: taken, closed or expired

curl -X POST "https://api.cachetzec.com/api/v1/swaps/{id}/take" \
  -H "content-type: application/json" \
  -d '{ ... }'

DELETE/api/v1/swaps/{id}/take

Release the take holding an offer (maker token): the maker's page refused it, and the offer is open again at once rather than after the hold.

Parameters

idstring · path · required: Offer id

Answers

204: Released
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl -X DELETE "https://api.cachetzec.com/api/v1/swaps/{id}/take"

Signed snapshot

The whole registry as one deterministic, signed document, for mirrors.

GET/api/v1/snapshot

Signed registry snapshot: a deterministic export of every asset the registry knows, sealed under the operator's Ed25519 key so mirrors can serve it offline and clients can verify it (see the registry spec for the verification procedure). 503 until the operator configures CACHET_SNAPSHOT_KEY.

Answers

200SnapshotResponse
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/snapshot"

Server wallet

Minting, transfers and burns signed by the instance itself. A read-only instance, like the public one, answers 403: mint from your browser instead.

POST/api/v1/assets

Issue units of an asset (creates the asset on first issuance).

Body · IssueAssetRequest

amountinteger · required: Units to issue; must be greater than zero.
descriptionstring · required: Asset description (1–512 bytes). Immutable once first issued: together with the issuer key it determines the on-chain asset id.
finalizeboolean: Permanently disable further issuance after this transaction.

Answers

202IssueAssetResponse: Accepted into the mempool
400ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
409ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
422ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl -X POST "https://api.cachetzec.com/api/v1/assets" \
  -H "content-type: application/json" \
  -d '{"amount":1000,"description":"Cachet Demo Ticket"}'

POST/api/v1/assets/batch

Mint several assets in ONE transaction (a single ZIP 227 issuance bundle, one action per item, all-or-nothing).

Body · BatchIssueRequest

itemsIssueAssetRequest[] · required: 1–16 items, no duplicate descriptions. The whole batch lands in one issuance bundle: one transaction, one txid, all-or-nothing.

Answers

202BatchIssueResponse: Accepted into the mempool
400ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
409ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
422ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl -X POST "https://api.cachetzec.com/api/v1/assets/batch" \
  -H "content-type: application/json" \
  -d '{ ... }'

POST/api/v1/assets/{asset_id}/burns

Permanently destroy units of an asset held by the wallet.

Parameters

asset_idstring · path · required: Asset id, hex-encoded 32 bytes

Body · BurnAssetRequest

amountinteger · required: Units to permanently destroy; must be greater than zero.

Answers

202TxResponse: Accepted by the chain
400ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
422ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl -X POST "https://api.cachetzec.com/api/v1/assets/{asset_id}/burns" \
  -H "content-type: application/json" \
  -d '{"amount":10}'

POST/api/v1/assets/{asset_id}/transfers

Transfer units of an asset from the wallet to a recipient.

Parameters

asset_idstring · path · required: Asset id, hex-encoded 32 bytes

Body · TransferAssetRequest

amountinteger · required: Units to move; must be greater than zero.
recipientstring · required: Destination: a unified address with an Orchard receiver, or account:N for one of the wallet's own accounts (demo convenience).

Answers

202TxResponse: Accepted by the chain
400ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
404ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
422ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl -X POST "https://api.cachetzec.com/api/v1/assets/{asset_id}/transfers" \
  -H "content-type: application/json" \
  -d '{"amount":25,"recipient":"account:1"}'

GET/api/v1/wallet

Spendable balances of the wallet's tracked accounts.

Disabled on read-only deployments: the operator's shielded balances are exactly the kind of information this project exists to keep private, and a public instance must not broadcast them.

Answers

200AccountBalancesResponse[]
403ProblemDetails: A problem document (RFC 9457): type, title, status, detail.
503ProblemDetails: A problem document (RFC 9457): type, title, status, detail.

curl "https://api.cachetzec.com/api/v1/wallet"

Operator

Liveness, and a token-gated surface that answers 404 unless the operator configured it.

GET/api/v1/admin/moderation

Every moderation entry, for the operator's audit view.

Answers

200ModerationEntryResponse[]
404: Admin surface disabled or bad token

curl "https://api.cachetzec.com/api/v1/admin/moderation"

POST/api/v1/admin/moderation

Hide a bundle, description or issuer from this registry's distribution.

Body · ModerationRequest

keystring · required: Hex-encoded key: bundle sha256, asset id, or issuance validating key.
kindstring · required: bundle, description or issuer.
purgeboolean: Bundles only: also delete the bytes from this registry's store. The moderation entry stays, so the same bytes are refused if re-uploaded; the chain commitment and the name are untouched.
reasonstring or null: Optional operator note, stored with the entry (audit trail).

Answers

204: Hidden
404: Admin surface disabled or bad token

curl -X POST "https://api.cachetzec.com/api/v1/admin/moderation" \
  -H "content-type: application/json" \
  -d '{ ... }'

DELETE/api/v1/admin/moderation

Lift a moderation entry.

Body · ModerationRequest

keystring · required: Hex-encoded key: bundle sha256, asset id, or issuance validating key.
kindstring · required: bundle, description or issuer.
purgeboolean: Bundles only: also delete the bytes from this registry's store. The moderation entry stays, so the same bytes are refused if re-uploaded; the chain commitment and the name are untouched.
reasonstring or null: Optional operator note, stored with the entry (audit trail).

Answers

204: Unhidden (or was not hidden)
404: Admin surface disabled or bad token

curl -X DELETE "https://api.cachetzec.com/api/v1/admin/moderation" \
  -H "content-type: application/json" \
  -d '{ ... }'

GET/api/v1/admin/pause

The current pause decision.

Answers

200PauseResponse
404: Admin surface disabled or bad token

curl "https://api.cachetzec.com/api/v1/admin/pause"

PUT/api/v1/admin/pause

Pause or resume minting through this instance. Effective on the next request; persisted so a restart keeps it. The chain is not involved: a paused instance simply stops relaying and storing.

Body · PauseRequest

pausedboolean · required: true pauses the relay and metadata uploads on this instance; false resumes them.
reasonstring or null: Optional operator note, shown on the admin page and kept with the decision.

Answers

200PauseResponse
404: Admin surface disabled or bad token

curl -X PUT "https://api.cachetzec.com/api/v1/admin/pause" \
  -H "content-type: application/json" \
  -d '{ ... }'

GET/healthz

Liveness probe. Does not touch the chain: a wedged node must not make the process look dead.

Answers

200: Process is alive

curl "https://api.cachetzec.com/healthz"

Shapes

The documents the routes above take and answer with.

AccountBalancesResponse

Spendable balances of one wallet account.

accountinteger · required
holdingsHoldingResponse[] · required

AssetEventResponse

One public event of an asset's life. Transfers are shielded and never listed.

amountinteger · required: Units issued or burned; zero for finalization.
heightinteger · required
kindstring · required: issuance, burn, or finalization.
txidstring · required

AssetSummaryResponse

The public record of one asset: a registry listing row, and also the full response of the single-asset endpoint.

asset_idstring · required: Asset id (hex-encoded 32 bytes).
descriptionstring or null: Raw asset description, when known. The chain only stores the description hash, so this is present only for assets issued through this instance (local journal).
display_namestring or null: Safest human-readable name derived from the description: the sealed envelope name or the raw free text. Render it according to name_source.
finalizedboolean · required
image_pathstring or null: Server-relative path to the asset's image (serve from the API origin), when a stored metadata bundle embeds one.
issuerstring or null: The issuance validating key that minted this asset (ZIP 227 canonical encoding, lowercase hex). The chain's only provenance statement: assets sharing this key share an issuer.
last_heightinteger or null: Height of the latest public event (issuance, burn or seal), when known. Shielded transfers never count.
name_sourcestring or null: Where display_name comes from — envelope (sealed into the asset id) or free_text (issuer-chosen, unverified label). Anti-phishing: clients must not present a name without its provenance.
total_supplyinteger · required

BatchIssueRequest

Request body for minting several assets in one transaction.

itemsIssueAssetRequest[] · required: 1–16 items, no duplicate descriptions. The whole batch lands in one issuance bundle: one transaction, one txid, all-or-nothing.

BatchIssueResponse

Result of an accepted batch issuance.

asset_idsstring[] · required: Minted asset ids, in request order.
txidstring · required: The single transaction that minted every asset in the batch.

BurnAssetRequest

Request body for burning units of an asset from the wallet.

amountinteger · required: Units to permanently destroy; must be greater than zero.

ChainInfoResponse

Connected network, chain tip, and deployment mode.

mints_pausedboolean · required: When true, the operator has paused minting through this instance: the relay and metadata uploads answer 503 until it is lifted. The chain itself is unaffected.
networkstring · required: Network name, e.g. regtest, zsa-testnet, in-memory.
read_onlyboolean · required: When true, the wallet-signing endpoints (mint, batch mint, transfer, burn, wallet) answer 403 — a public read-only deployment. Relay, description resolution and metadata upload stay open: they need no key from this instance.
snapshot_public_keystring or null: Ed25519 public key (hex) that signs this instance's registry snapshots; absent when snapshots are not enabled. Compare it to the operator's out-of-band publications (working paper, posts) before trusting a mirror.
tip_heightinteger · required: Chain tip height as seen by the node.

CollectionResponse

A chain-level collection: every asset minted under one issuance key.

asset_countinteger · required
finalized_countinteger · required: How many of the issuer's assets are finalized.
issuerstring · required: Issuance validating key, ZIP 227 canonical encoding, lowercase hex.
total_supplyinteger · required: Sum of the circulating supplies of the issuer's assets.

CountersignatureEnvelope

The countersignature, for the taker.

countersignaturestring or null

CountersignRequest

The maker's answer.

countersignaturestring · required
taken_atinteger · required: The taken_at of the take it signs.

DecodedBurnResponse

Units of one asset burned in the open.

amountinteger · required
asset_idstring · required

DecodedIssuanceResponse

The issuance bundle of a decoded transaction.

actionsDecodedIssueActionResponse[] · required
issuerstring · required: Issuance validating key, ZIP 227 canonical encoding, hex.

DecodedIssueActionResponse

One issue action of a decoded transaction.

amountinteger · required: Units issued by this action (the reference note carries zero).
asset_desc_hashstring or null: ZIP 227 description hash, hex; absent when the backend cannot see it.
asset_idstring · required
finalizeboolean · required: Whether this action seals the asset's supply.
notesinteger · required: Issue notes in the action, the reference note included.
reference_noteboolean · required: Whether the action carries the reference note of a first issuance.

DecodedTransactionResponse

What a transaction publishes about ZSAs. Transfers stay encrypted: only their action count is visible.

burnsDecodedBurnResponse[] · required
heightinteger or null: Height of the block holding it; null while it waits in the mempool.
issuancenull or DecodedIssuanceResponse
orchard_actionsinteger · required
sapling_outputsinteger · required
sapling_spendsinteger · required
swapnull or SwapFillResponse
transparent_inputsinteger · required
transparent_outputsinteger · required
txidstring · required
versioninteger · required: Transaction format version (6 for OrchardZSA).

HoldingResponse

One asset held by a wallet account.

amountinteger · required
asset_idstring · required

IssueAssetRequest

Request body for issuing units of an asset.

amountinteger · required: Units to issue; must be greater than zero.
descriptionstring · required: Asset description (1–512 bytes). Immutable once first issued: together with the issuer key it determines the on-chain asset id.
finalizeboolean: Permanently disable further issuance after this transaction.

IssueAssetResponse

Result of an accepted issuance.

asset_idstring · required: Id of the minted asset — use it with GET /api/v1/assets/{asset_id}.
txidstring · required: Transaction id (hex, display order). Acceptance, not finality.

KeptAssetResponse

Sealed content this registry still holds for an asset the chain it follows no longer carries (a reset test network takes its assets with it). No supply, no issuer: those were chain facts and went with the chain. What is left is what the asset id commits to, so minting it again under the same key gives the same asset id.

asset_idstring · required: Asset id (hex-encoded 32 bytes) the description was journaled under.
descriptionstring · required: The asset description as it was: for a Cachet asset, the v1 envelope naming the sealed bundle.
display_namestring · required
image_pathstring or null: Server-relative path to the sealed image, when the bundle is still held and embeds one.
name_sourcestring · required: envelope or free_text, as on a listed asset.

MetadataUploadRequest

Request body for registering a metadata bundle before issuance.

descriptionstring or null: Long-form description (≤ 4096 bytes), stored in the bundle only.
external_urlstring or null: Optional issuer link.
image_data_uristring or null: Embedded image as a base64 data URI (png/jpeg/webp/gif, ≤ ~400 KB).
namestring · required: Display name (1–120 bytes); becomes part of the immutable on-chain description.

MetadataUploadResponse

Result of a metadata upload: the bundle hash and the exact description string to use at issuance (which binds the bundle to the asset forever).

chain_descriptionstring · required: Ready-to-use asset description ({"v":1,"name":…,"sha256":…}).
sha256string · required: SHA-256 of the stored bundle bytes, hex-encoded.

ModerationEntryResponse

bytes_presentboolean or null: Bundles only: whether this registry still holds the bytes (false after a purge). null for other kinds.
hidden_atstring · required
keystring · required
kindstring · required
reasonstring or null

ModerationRequest

keystring · required: Hex-encoded key: bundle sha256, asset id, or issuance validating key.
kindstring · required: bundle, description or issuer.
purgeboolean: Bundles only: also delete the bytes from this registry's store. The moderation entry stays, so the same bytes are refused if re-uploaded; the chain commitment and the name are untouched.
reasonstring or null: Optional operator note, stored with the entry (audit trail).

OrchardTreeResponse

The Orchard note commitment tree after a block: where a wallet created at that block starts reading the chain.

final_rootstring or null: The tree's root, hex, when the node reports it.
final_statestring · required: The tree's frontier, hex, in zcashd's CommitmentTree encoding (as z_gettreestate reports it).
heightinteger · required: The block the tree stands after (the current tip when asked).

PauseRequest

Set the mint pause.

pausedboolean · required: true pauses the relay and metadata uploads on this instance; false resumes them.
reasonstring or null: Optional operator note, shown on the admin page and kept with the decision.

PauseResponse

The current pause decision.

pausedboolean · required
reasonstring or null
sinceinteger or null: Unix time (seconds) of the last change, when known.
untilinteger or null: Unix time (seconds) at which an automatic pause reopens by itself; absent for an operator pause, which holds until resumed.

PostOfferRequest

Post an offer.

hoursinteger or null: Hours it stays up: 1 to 72, 24 by default.
offerstring · required: The offer message, as the mint engine wrote it (JSON text).

PostOfferResponse

A posted offer, and the token that manages it.

expires_atinteger · required
idstring · required
maker_tokenstring · required: Shown once. Reads the take, posts the countersignature, withdraws.

ProblemDetails

RFC 9457 problem document. Every non-2xx response uses this shape.

detailstring · required: Human-readable explanation specific to this occurrence.
statusinteger · required: HTTP status code, duplicated for clients that drop it.
titlestring · required: Short human-readable summary.
typestring · required: Stable, documentation-friendly error identifier.

RawBlockResponse

One block's raw transactions, hex-encoded, consensus order.

heightinteger · required
txsstring[] · required: Every transaction of the block (coinbase included), raw hex. Order matters: client-side note scanning must append commitments in exactly this order.

RawBlocksResponse

A page of raw blocks for client-side note scanning. Public chain data, identical for every caller: browsers scan for their own notes locally and never tell the server which notes are theirs.

blocksRawBlockResponse[] · required
tip_heightinteger · required: Chain tip at the time of the call: fetch until height == tip_height.

RelayRequest

Request body for relaying a browser-built, fully signed transaction.

The instance signs nothing: the transaction was built, proven and signed in the sender's browser (see the mint engine). The relay can refuse, never alter. Available on read-only deployments — the whole point is that the server holds no keys.

tx_hexstring · required: Complete signed v6 transaction, hex-encoded.

ResolveDescriptionRequest

Request body for resolving an asset's description.

Permissionless by design: the chain stores only the description hash (ZIP 227), so a preimage either matches the commitment or is rejected — the registry cannot be lied to. This is how assets issued by *other* parties gain names here.

descriptionstring · required: The plaintext asset description (1–512 bytes).

SnapshotResponse

The wire envelope: payload bytes plus a detached signature. Mirrors store and serve this JSON as-is.

asset_countinteger · required
payloadstring · required: Base64 of the canonical payload JSON (see SnapshotPayload).
public_keystring · required: Hex Ed25519 public key of the signing operator.
sha256string · required: Hex SHA-256 of the decoded payload bytes.
signaturestring · required: Hex Ed25519 signature over ("cachet-snapshot-v1" || sha256 bytes).
tip_heightinteger · required: Convenience mirrors of payload facts (unsigned; trust the payload).

SwapFillResponse

A board offer a transaction filled.

give_amountinteger · required
give_assetstring · required
offer_idstring · required
want_amountinteger · required
want_assetstring · required

SwapOfferResponse

An offer on the board.

created_atinteger · required
expires_atinteger · required
give_amountinteger · required
give_assetstring · required
idstring · required
offerstring or null: The offer message itself; only on the single-offer route.
statusstring · required: open, taken (held for the maker's signature), countersigned, closed, expired, or stale (its anchor is too old for takers' wallets: off the board until the maker posts it again).
want_amountinteger · required
want_assetstring · required

TakeEnvelope

The take, for the maker.

takestring or null
taken_atinteger or null: Identifies the take a countersignature answers.

TakeRequest

Take an offer.

takestring · required: The taker's message (JSON text): the transaction awaiting the maker.

TakeResponse

hold_secsinteger · required: The take holds the offer this long for the maker, in seconds.
taker_tokenstring · required: Shown once. Reads the countersignature, reports the swap done.

TransferAssetRequest

Request body for transferring units of an asset from the wallet.

amountinteger · required: Units to move; must be greater than zero.
recipientstring · required: Destination: a unified address with an Orchard receiver, or account:N for one of the wallet's own accounts (demo convenience).

TxResponse

A transaction accepted by the chain.

txidstring · required: Transaction id (hex, display order). Acceptance, not finality.