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.
const { items } = await api.labels()
for (const label of items) console.log(label.label, label.feeBps, label.receipts)
curl https://api.privium.io/v1/labels
The capture keeps the first of its 3 labels.
{
"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:psiis not a base58 address of 32 bytes.NOT_FOUND: no leader has made this label followable.
const { label, receipts } = await api.label('7SQg6KjAyTU7e5DeSc3hRT2B6YvPSB7ZmZJE2o4VYcxt')
curl https://api.privium.io/v1/labels/7SQg6KjAyTU7e5DeSc3hRT2B6YvPSB7ZmZJE2o4VYcxt
{
"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 60POSTrequests to/v1in 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 60POSTrequests to/v1in 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. |