Documentation

Integration overview.

How a participant writes handover records and runs checks. Trace is designed for existing order flows: the code ID travels in a reference field you already have, and each party posts a signed record at a moment it already handles.

Preview. Trace is in its reporting stage; this page describes the record format and the checks as designed.

Who writes what, and when

The buyer gives its seller its pseudonym, like a receiving address. The seller writes the record. The buyer's next record is its receipt.

Party	Writes a record	Carries the code ID in
Brand processor	At issuance, allocation and redemption	Its own reference on the stored value call
Distribution network	When stock ships or an activation is approved	Network transaction id, delivery note, store and lane
Aggregator	When an order completes	Client request id or idempotency key
Reseller	When the code lands, and when it is sold	Its own order id
Retailer	From the activation record it already keeps	Terminal id, batch reference

A record

One record per handover, daisy-chained: signed by the writer, linked to the record before it. Sample values.

record-3.json

// Record 3: aggregator A-1 fulfils an order to reseller R-7
{
  "code_id": "8812",                 // random, assigned at issuance
  "from":    "A-1",                  // pseudonym, per brand programme
  "to":      "R-7",
  "state":   "fulfilled",
  "sector":  "crypto-off-ramp",
  "time":    "2026-11-05T14:02:00Z",
  "prev":    "sha256:7c21…e04b",     // fingerprint of record 2
  "sig":     "ecdsa-p256:…"          // A-1's key, held by A-1 alone
}
// never on a record: the code, the price, the customer, a name

Checks

Two questions the registry is designed to answer in the advisory stage, planned next. Neither returns a name, a price or a code.

Pre-sale check

Planned

A seller asks: may I sell this code ID to this buyer?

ok: Valid, not redeemed, chain intact, buyer allowed.
redeemed: Already redeemed. Do not sell it.
voided: Voided by the brand. Do not sell it.
not_holder: The registry does not have you as the current holder. The check is recorded.
flagged: In an open case. Do not sell it until it is resolved.
no_relationship: No registered relationship with this buyer.
buyer_blacklisted: Blacklisted by the brand for this programme. The brand does not know the name. You do.

Public check

Planned

Anyone with a code ID, before accepting a code: an exchange, a marketplace, a customer.

Chain intact, not yet redeemed, with the hop count
Already redeemed, or voided by the brand
Chain intact, but the last handover was never confirmed
Chain intact, but in an open case
Chain broken: a record was altered after it was written
Unknown code ID

Checks are counted and rate-limited. Thousands of checks on unknown IDs from one source are themselves a signal.

What a participant needs

A verified identity in the vault, and a pseudonym for each brand programme it takes part in.
A signing key it holds alone.
A reference field, in a call it already makes, to carry the code ID.
A signed record posted to the registry at each handover it writes, and a receipt, confirm or dispute, for each handover it receives.

Getting the integration guide

Endpoints, key registration and the reporting interface are shared with pilot participants. Ask for the guide and say which role you play in the chain.

See it on sample data

A walk-through of the Trace reporting view takes half an hour and needs nothing of yours.

Request a demo