• Reading the docs…
Start trading

API reference

The board

The labels their leaders made followable, each with its fee and the Receipts published under it. Followers read it to choose a label, and every Receipt on it verifies again in the reader’s browser, as at /r (Receipt). The board names a label by its pseudonym ψ, the pseudonym its Receipts carry, and names no account or wallet (Mirrors).

Routes#

GET /v1/labels#

Every label on the board, the 200 most recently updated, newest first, each with its count of published Receipts and the newest of them.

Returns Labels. It raises no error of its own.

TypeScript
const { items } = await api.labels()
for (const label of items) console.log(label.label, label.feeBps, label.receipts)

The capture keeps the first of its 3 labels.

Response
{
  "items": [
    {
      "psi": "7SQg6KjAyTU7e5DeSc3hRT2B6YvPSB7ZmZJE2o4VYcxt",
      "label": "alpha-mwl5v7mz",
      "feeBps": 50,
      "leadSlot": "470882183",
      "statement": "{\"feeBps\":50,\"label\":\"alpha-mwl5v7mz\",\"program\":\"BH2ggvL6MxJ96zQhiuCdJDym84kN4RPpkf4bVJgZAVYe\",\"psi\":\"7SQg6KjAyTU7e5DeSc3hRT2B6YvPSB7ZmZJE2o4VYcxt\",\"slot\":\"470882183\"}",
      "signature": "vBicaJxXxFZ05Wua8m9EXDyfrScPQgRQtPzwLsgLIFZCsCp0iWQOT1V9cSjFo+1lRGaVnInipY7TJfAWfkf+Dg==",
      "receipts": 1,
      "latestReceipt": "OQEAAAGYsBEOtdpdrxMCNvtVqnnQXQI3+52uq5kO810wBvtQI1+oaPmK7mr+PnvcjDabKbiYpwdDVjYcHlcm06cHIKMNAQAAAAAAAAAhAAAAAAAAAJ4VnecPtbZOYAXWSqp9N02q0Zlr5PWt80tgQhHFrJa6AwAAAAlWFAIAAAAAAAAAAAAAAAAACk7jnwEAAAAAAAAAAAAAAAADAQEAAAAAHJvgmINtRDhiOinTi5+5JSS3br5WoULUaARAgno6DK2BlVe1zQ0LqOqYe/ePd4u2RyTMbRW4Azz+dxoA2WFbwpwPAOaQBBkZRV0oLwvWQ/gSvFlysAhR+VH9muIDTJUlCBkRHAAAAAAOAAAAYWxwaGEtbXdsNXY3bXrG+nrzvtutOj1l82qryXQxsbvkwtL24OR8pgIDRS9dYQCJuE6GVC93SVhTUEQGZuiUQZ3bEn+DxGXeanMdRbNleuLijdlPcHzR7VitsEUNbsSFvq2zmplgvjuQa1v3T+wK"
    }
  ]
}

GET /v1/labels/{psi}#

One label and the Receipts its leader published under it, the 100 latest by their span’s last Crossing, newest first. receipts[].bytes is the signed Receipt, which decodeReceipt reads and receipts.verify checks.

Parameter Type In Meaning
psi Address path A label's pseudonym ψ, base58.

Returns LabelDetail.

Errors

  • VALIDATION_ERROR: psi is not a base58 address of 32 bytes.
  • NOT_FOUND: no leader has made this label followable.
TypeScript
const { label, receipts } = await api.label('7SQg6KjAyTU7e5DeSc3hRT2B6YvPSB7ZmZJE2o4VYcxt')
Response
{
  "label": {
    "psi": "7SQg6KjAyTU7e5DeSc3hRT2B6YvPSB7ZmZJE2o4VYcxt",
    "label": "alpha-mwl5v7mz",
    "feeBps": 50,
    "leadSlot": "470882183",
    "statement": "{\"feeBps\":50,\"label\":\"alpha-mwl5v7mz\",\"program\":\"BH2ggvL6MxJ96zQhiuCdJDym84kN4RPpkf4bVJgZAVYe\",\"psi\":\"7SQg6KjAyTU7e5DeSc3hRT2B6YvPSB7ZmZJE2o4VYcxt\",\"slot\":\"470882183\"}",
    "signature": "vBicaJxXxFZ05Wua8m9EXDyfrScPQgRQtPzwLsgLIFZCsCp0iWQOT1V9cSjFo+1lRGaVnInipY7TJfAWfkf+Dg==",
    "receipts": 1,
    "latestReceipt": "OQEAAAGYsBEOtdpdrxMCNvtVqnnQXQI3+52uq5kO810wBvtQI1+oaPmK7mr+PnvcjDabKbiYpwdDVjYcHlcm06cHIKMNAQAAAAAAAAAhAAAAAAAAAJ4VnecPtbZOYAXWSqp9N02q0Zlr5PWt80tgQhHFrJa6AwAAAAlWFAIAAAAAAAAAAAAAAAAACk7jnwEAAAAAAAAAAAAAAAADAQEAAAAAHJvgmINtRDhiOinTi5+5JSS3br5WoULUaARAgno6DK2BlVe1zQ0LqOqYe/ePd4u2RyTMbRW4Azz+dxoA2WFbwpwPAOaQBBkZRV0oLwvWQ/gSvFlysAhR+VH9muIDTJUlCBkRHAAAAAAOAAAAYWxwaGEtbXdsNXY3bXrG+nrzvtutOj1l82qryXQxsbvkwtL24OR8pgIDRS9dYQCJuE6GVC93SVhTUEQGZuiUQZ3bEn+DxGXeanMdRbNleuLijdlPcHzR7VitsEUNbsSFvq2zmplgvjuQa1v3T+wK"
  },
  "receipts": [
    {
      "bytes": "OQEAAAGYsBEOtdpdrxMCNvtVqnnQXQI3+52uq5kO810wBvtQI1+oaPmK7mr+PnvcjDabKbiYpwdDVjYcHlcm06cHIKMNAQAAAAAAAAAhAAAAAAAAAJ4VnecPtbZOYAXWSqp9N02q0Zlr5PWt80tgQhHFrJa6AwAAAAlWFAIAAAAAAAAAAAAAAAAACk7jnwEAAAAAAAAAAAAAAAADAQEAAAAAHJvgmINtRDhiOinTi5+5JSS3br5WoULUaARAgno6DK2BlVe1zQ0LqOqYe/ePd4u2RyTMbRW4Azz+dxoA2WFbwpwPAOaQBBkZRV0oLwvWQ/gSvFlysAhR+VH9muIDTJUlCBkRHAAAAAAOAAAAYWxwaGEtbXdsNXY3bXrG+nrzvtutOj1l82qryXQxsbvkwtL24OR8pgIDRS9dYQCJuE6GVC93SVhTUEQGZuiUQZ3bEn+DxGXeanMdRbNleuLijdlPcHzR7VitsEUNbsSFvq2zmplgvjuQa1v3T+wK",
      "from": "1",
      "to": "33",
      "signedSlot": "470882568",
      "publishedAt": "2026-11-17T20:46:30.401Z"
    }
  ]
}

POST /v1/labels/{psi}#

Puts a label on the board, or updates it, from the statement the enclave signed when the leader sent its lead Intent. lead sends the Intent and posts the reply here in one call. The statement is JSON, {"program", "psi", "label", "feeBps", "slot"}, and the signature is the enclave’s Ed25519 signature over privium/lead/v1 ‖ statement. The API checks that the statement names this Pool and this ψ and that an admitted enclave key signed it, and keeps the newest statement by its slot: an older one answers with the label as it stands.

Parameter Type In Meaning
psi Address path The pseudonym the statement names.

The body is PublishLeadRequest. Returns LabelSummary.

Errors

  • VALIDATION_ERROR: the statement is not JSON, or names another Pool or label.
  • SIGNATURE_INVALID: no admitted enclave key signed the statement.
  • RATE_LIMITED: more than 60 POST requests to /v1 in a minute from this client.

POST /v1/labels/{psi}/receipts#

Publishes a Receipt under its label. publishReceipt posts one, and the app’s Publish on Follow does the same. The API decodes the Receipt, checks that it belongs to this Pool, that its pseudonym is ψ and that an admitted enclave key signed it, and stores it once: the same bytes again answer with the stored record.

Parameter Type In Meaning
psi Address path The pseudonym the Receipt carries.

The body is PublishReceiptRequest. Returns PublishedReceipt, as receipts[] above lists it.

Errors

  • NOT_FOUND: the label is not on the board yet; put it there first.
  • MALFORMED_RECEIPT: the bytes are not a Privium Receipt.
  • VALIDATION_ERROR: the Receipt belongs to another Pool or label.
  • SIGNATURE_INVALID: no admitted enclave key signed the Receipt.
  • RATE_LIMITED: more than 60 POST requests to /v1 in a minute from this client.

Types#

Labels#

Field Type Meaning
items LabelSummary[] The labels on the board, the 200 most recently updated, newest first.

LabelSummary#

Field Type Meaning
psi Address The label's pseudonym ψ, which its Receipts carry.
label string The label.
feeBps integer The leader fee each mirror fill pays, in basis points.
leadSlot U64 The slot of the newest lead statement.
statement string That statement, as the enclave signed it.
signature Base64 The enclave's signature over privium/lead/v1 ‖ statement, base64.
receipts integer How many Receipts are published under the label.
latestReceipt Base64 or null The newest published Receipt's bytes, base64; null before the first.

LabelDetail#

Field Type Meaning
label LabelSummary The label, as the board lists it.
receipts PublishedReceipt[] Its published Receipts, the 100 latest by their span's last Crossing, newest first.

PublishedReceipt#

Field Type Meaning
bytes Base64 The signed Receipt, base64.
from U64 The first Crossing of its span.
to U64 The last Crossing of its span.
signedSlot U64 The slot the enclave signed it at.
publishedAt Timestamp When it was published on the board.

PublishLeadRequest#

Field Type Meaning
statement string The statement from the lead Intent's reply, 2 to 2,048 characters.
signature Base64 The enclave's signature from the same reply, base64.

PublishReceiptRequest#

Field Type Meaning
receipt Base64 The signed Receipt's bytes, base64.