Skip to content
Darwin Evolution

Tracium overview

Tracium is the traceability layer. It standardizes events from Captia or any ingestion source, validates them against the tenant’s process map, anchors critical events on-chain, and auto-generates regulatory bundles per framework.

What you can do via API

Section titled “What you can do via API”
CapabilitySurface
Submit events (prepared transaction flow)POST /api/v1/events/prepare plus client-side sign and submit to chain
Validate payload without spending gasPOST /api/v1/events/validate
Query events by lot, actor, or periodGET /api/v1/events, GET /api/v1/events/:id, GET /api/v1/events/nft/:tokenId
Query NFT inventory and lineageGET /api/v1/nfts, GET /api/v1/nfts/:tokenId, GET /api/v1/nfts/tlc/:tlc, /ancestry, /descendants, /relations
Carbon and environmental footprint (aggregated by tree)GET /api/v1/nfts/:tokenId/footprint
Recall impact analysisGET /api/v1/nfts/:tokenId/recall-impact
On-chain recall (TENANT_ADMIN)POST /api/v1/nfts/recall/prepare + sign
Custody transfer (prepare + sign)POST /api/v1/custody/prepare, GET /api/v1/custody/nft/:tokenId, GET /api/v1/custody/org/:orgId
Track submitted txPOST /api/v1/tx/track, POST /api/v1/tx/track/status, GET /api/v1/tx/track/mine
Operational reports (alerts, documents, supplier perf, yields, inventory)GET /api/v1/reports/*
FSMA 204 regulatory bundlededicated reporting service, exposed via POST /api/v1/reports/fsma204
Webhooks for downstreamPOST /api/v1/webhooks (CRUD, TENANT_ADMIN)
EUDR, USMCA, IATF, ESPR DPP bundlesavailable on demand

The full reference is auto-generated from the live OpenAPI spec. See the Reference.

The “prepared transaction” pattern

Section titled “The “prepared transaction” pattern”

Many write operations use a 3-step flow:

  1. POST /api/v1/<resource>/prepare: server validates the request, writes canonical metadata to content-addressed storage, constructs the unsigned tx, returns { preparedTx: { to, data, gasEstimate, chainId }, eventId, ipfsCid }.
  2. Client signs and submits the tx to the chain RPC directly, using the actor’s wallet (ethers.js, viem, MetaMask, hardware wallet).
  3. (Optional) POST /api/v1/tx/track: register the resulting txHash with Tracium so it monitors confirmation and emits event.recorded webhooks once the block is mined.

Why this flow:

  • The actor’s private key never touches the platform.
  • Server validates business rules before the client spends gas.
  • The content-addressed write is idempotent: same CID if you re-call /prepare with the same payload.

For high-volume server-to-server integrations, an API-key-scoped managed-wallet flow is available. Contact the team if you need this for a production deployment.

Reading the chain

Section titled “Reading the chain”

For read-only queries (the common case for retailers, auditors, AI analysis), no signing required. Bearer token or API key.

Ventana de terminal
# Set BASE_URL to the API base URL provided in your provisioning email.
export BASE_URL="<API_BASE_URL>"


# Get all events for a lot
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/api/v1/events?tlc=LOT-2026-A1"


# Walk the ancestry tree
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/api/v1/nfts/$TOKEN_ID/ancestry"

Replace <API_BASE_URL> with your sandbox or production base URL. See Sandbox.

What’s NOT on Tracium’s API

Section titled “What’s NOT on Tracium’s API”
  • Field capture: that’s Captia (mobile PWA plus ingestion connectors). Operators don’t hit Tracium directly.
  • Digital Product Passport viewer: that’s Fidenta. Consumer-facing QR experience.
  • Tenant provisioning and admin: not exposed publicly. Contact the team for provisioning.
Section titled “Cross-links”