Public API Reference

FenixTrace exposes REST endpoints for external integrations. Public endpoints require no authentication. The v1 integration endpoints require an API key generated from your dashboard. FenixTrace handles IPFS, on-chain signing and notarization server-side — your integration only sends product data.

REST API

Public + Auth

CORS Enabled

JSON Response

Integration Kit

Base URL

https://fenixtrace.com

Companies

Products

Labels

Integrations (v1)

Companies

GET

/api/public/companies

List all companies registered on FenixTrace. Supports text search by company name, and filtering by DID identity status. Returns public profile data only — no internal blockchain addresses are exposed.

Parameters

Name	Type	Required	Description
search	string	optional	Filter by company name (case-insensitive)
hasIdentity	boolean	optional	Filter companies with/without an on-chain DID identity
limit	number	optional	Max results per page (default: 50, max: 200)
offset	number	optional	Pagination offset (default: 0)

Response

json

{
  "companies": [
    {
      "companyId": "cmp_8f2a4c",
      "companyName": "Rossi Alimentari S.r.l.",
      "identityDid": "did:iota:testnet:0x8f2a...c4d7e9",
      "identityStatus": "active",
      "profileImageCid": "QmX9vB3kR...",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "expiryDate": "2027-01-15T09:30:00.000Z"
    }
  ],
  "total": 48,
  "limit": 50,
  "offset": 0
}

Example

curl

curl "https://fenixtrace.com/api/public/companies?search=rossi&hasIdentity=true&limit=10"

GET

/api/public/companies/:companyId

Get the public profile of a single company by its FenixTrace company id. Returns the company name, DID identity and profile image. Internal wallet/contract addresses are managed server-side and are never returned.

Parameters

Name	Type	Required	Description
companyId	string	required	FenixTrace company id (path parameter)

Response

json

{
  "company": {
    "companyId": "cmp_8f2a4c",
    "companyName": "Rossi Alimentari S.r.l.",
    "identityDid": "did:iota:testnet:0x8f2a...c4d7e9",
    "identityStatus": "active",
    "profileImageCid": "QmX9vB3kR...",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "expiryDate": "2027-01-15T09:30:00.000Z"
  }
}

Example

curl

curl "https://fenixtrace.com/api/public/companies/cmp_8f2a4c"

Products

GET

/api/public/companies/:companyId/products

List all products for a specific company. Supports filtering by product name, IPFS hash, notarization hash, date range, and red flag status.

Parameters

Name	Type	Required	Description
companyId	string	required	FenixTrace company id (path parameter)
search	string	optional	Search by product name, IPFS hash, or notarization hash
flagged	boolean	optional	true = only flagged products, false = only clean products
from	number	optional	Filter products created after this Unix timestamp
to	number	optional	Filter products created before this Unix timestamp
limit	number	optional	Max results (default: 50, max: 200)
offset	number	optional	Pagination offset (default: 0)

Response

json

{
  "products": [
    {
      "name": "Olio Extra Vergine DOP 750ml",
      "ipfsHash": "QmT7nK2pVwR...",
      "productTxHash": "0x3f8a91c2...",
      "timestamp": 1768492800,
      "notarization": {
        "status": "completed",
        "notarizationHash": "a9d3e7f1...",
        "iotaNotarizationTransaction": "Bk47X92cDE..."
      }
    }
  ],
  "total": 156,
  "limit": 50,
  "offset": 0,
  "company": {
    "companyId": "cmp_8f2a4c",
    "companyName": "Rossi Alimentari S.r.l."
  }
}

Example

curl

curl "https://fenixtrace.com/api/public/companies/cmp_8f2a4c/products?flagged=false&limit=10"

GET

/api/public/products/:txHash

Look up a single product by its on-chain transaction hash. Returns the product details and its parent company information.

Parameters

Name	Type	Required	Description
txHash	string	required	Product transaction hash (path parameter)

Response

json

{
  "product": {
    "name": "Olio Extra Vergine DOP 750ml",
    "ipfsHash": "QmT7nK2pVwR...",
    "productTxHash": "0x3f8a91c2...",
    "timestamp": 1768492800,
    "notarization": { "status": "completed", ... }
  },
  "company": {
    "companyId": "cmp_8f2a4c",
    "companyName": "Rossi Alimentari S.r.l."
  }
}

Example

curl

curl "https://fenixtrace.com/api/public/products/0x3f8a91c2..."

Labels

GET

/api/public/companies/:companyId/labels

Get raw label data for all products of a company. Returns structured JSON that external label printing systems can use to generate QR labels, including the QR content URL, company logo URL, and the product proof hash.

Parameters

Name	Type	Required	Description
companyId	string	required	FenixTrace company id (path parameter)
format	string	optional	Suggested label format: a4-sheet, a4-single, 10x15, 62x29, 50x30 (default: 10x15)
limit	number	optional	Max labels (default: 50, max: 200)
offset	number	optional	Pagination offset (default: 0)

Response

json

{
  "labels": [
    {
      "productName": "Olio Extra Vergine DOP 750ml",
      "companyName": "Rossi Alimentari S.r.l.",
      "ipfsHash": "QmT7nK2pVwR...",
      "productUrl": "https://dweb.link/ipfs/QmT7nK2pVwR...",
      "productTxHash": "0x3f8a91c2...",
      "timestamp": 1768492800,
      "createdAt": "2026-09-15T10:00:00.000Z",
      "qrContent": "https://fenixtrace.com/scanner/company/cmp_8f2a4c/product?...",
      "companyLogoUrl": "https://dweb.link/ipfs/QmX9vB3kR..."
    }
  ],
  "total": 156,
  "suggestedFormat": "10x15",
  "availableFormats": ["a4-sheet", "a4-single", "10x15", "62x29", "50x30"],
  "company": {
    "companyId": "cmp_8f2a4c",
    "companyName": "Rossi Alimentari S.r.l.",
    "profileImageCid": "QmX9vB3kR..."
  }
}

Example

curl

curl "https://fenixtrace.com/api/public/companies/cmp_8f2a4c/labels?format=a4-sheet&limit=100"

Integrations (v1)

POST

/api/v1/products

Primary integration endpoint. Register a product with a single authenticated call — FenixTrace uploads to IPFS (when you send raw data), signs add_product on-chain, and notarizes, all server-side. Your integration holds no wallet and signs nothing. Send either an already-uploaded ipfsHash OR a raw data object that FenixTrace pins to IPFS for you.

Parameters

Name	Type	Required	Description
Authorization	header	required	Bearer ftrace_<id>_<secret> — the API key generated from your FenixTrace dashboard. The key maps to your company server-side.
name	string	required	Product name
ipfsHash	string	optional	IPFS CID of the product data, if you already pinned it (Qm… / bafy…). Provide this OR data.
data	object	optional	Raw product JSON. FenixTrace pins it to IPFS server-side and uses the resulting CID. Provide this OR ipfsHash.
batchId	string	optional	Optional batch identifier, stored in the notarization metadata

Response

json

{
  "success": true,
  "digest": "Ah23W48bEE5U1xSqHr59gHAjQAMwkdZg...",
  "ipfsHash": "QmX9vB3kR7yKf...",
  "ipfsUrl": "https://dweb.link/ipfs/QmX9vB3kR7yKf...",
  "name": "Olive Oil Extra Virgin DOP 750ml",
  "company": { "name": "Rossi Alimentari S.r.l." },
  "meta": {
    "batchId": "OIL-001",
    "registeredAt": "2026-06-15T10:00:00.000Z"
  }
}

Example

curl

# FenixTrace pins the data to IPFS, signs on-chain, and notarizes — server-side.
curl -X POST "https://fenixtrace.com/api/v1/products" \
  -H "Authorization: Bearer ftrace_8f2a4c_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Olive Oil Extra Virgin DOP 750ml",
    "batchId": "OIL-001",
    "data": {
      "origin": "Puglia, Italy",
      "harvest": "2025",
      "certifications": ["DOP", "Bio"]
    }
  }'

# Already pinned to IPFS? Send the CID instead of data:
curl -X POST "https://fenixtrace.com/api/v1/products" \
  -H "Authorization: Bearer ftrace_8f2a4c_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Olive Oil Extra Virgin DOP 750ml",
    "ipfsHash": "QmX9vB3kR7yKf..."
  }'

POST

/api/v1/labels/deposit

Server-side label deposit. Send the product name and an IPFS CID (or raw data) and FenixTrace registers the product on-chain and notarizes it in the background — no transaction is returned to sign. Prefer POST /api/v1/products for new integrations; this route remains for backward compatibility.

Parameters

Name	Type	Required	Description
Authorization	header	required	Bearer ftrace_<id>_<secret> — maps to your company server-side
name	string	required	Product name
ipfsHash	string	required	IPFS CID of the product data (Qm… / bafy…)
template	string	optional	Template type: generic, agro, pharma, fashion, logistics, electronics, art, automotive, cosmetics, chemicals, machinery, custom
batchId	string	optional	Batch identifier

Response

json

{
  "success": true,
  "digest": "Ah23W48bEE5U1xSqHr59gHAjQAMwkdZg...",
  "ipfsHash": "QmX9vB3kR...",
  "ipfsUrl": "https://dweb.link/ipfs/QmX9vB3kR...",
  "name": "Olive Oil Extra Virgin",
  "notarization": { "status": "queued", "entityType": "label" },
  "company": { "name": "Rossi Alimentari S.r.l." }
}

Example

curl

curl -X POST "https://fenixtrace.com/api/v1/labels/deposit" \
  -H "Authorization: Bearer ftrace_8f2a4c_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Olive Oil Extra Virgin",
    "ipfsHash": "QmX9vB3kR7yKf...",
    "template": "agro"
  }'

GET

/api/v1/labels/status

Check the status of a deposited label. Returns the product data recorded on the blockchain and its notarization status.

Parameters

Name	Type	Required	Description
Authorization	header	required	Bearer ftrace_<id>_<secret> — maps to your company server-side
txHash	string	required	Transaction digest returned by the deposit call

Response

json

{
  "success": true,
  "found": true,
  "product": {
    "name": "Olive Oil Extra Virgin",
    "ipfsHash": "QmX9vB3kR...",
    "productTxHash": "0x0918f6c4...",
    "transactionId": "Ah23W48b...",
    "timestamp": 1772326876
  },
  "notarization": {
    "status": "completed",
    "notarizationHash": "abc123...",
    "iotaNotarizationTransaction": "Bx45Y..."
  }
}

Example

curl

curl "https://fenixtrace.com/api/v1/labels/status?txHash=Ah23W48bEE5U1x..." \
  -H "Authorization: Bearer ftrace_8f2a4c_abc123def456"

Notes

Caching: Responses are cached for 30-60 seconds (s-maxage). Use Cache-Control headers to control client-side caching.

Pagination: All list endpoints support limit and offset parameters. Maximum limit is 200 items per request.

Server-side blockchain: IPFS pinning, on-chain signing and notarization all run on FenixTrace's servers. Your integration never handles wallets, addresses, or transaction signing — it sends product data and receives a transaction digest back.

Error Responses: Errors return { "error": "message" } with appropriate HTTP status codes (400, 404, 500, 502).

CORS: All endpoints include Access-Control-Allow-Origin: * header for cross-origin requests.

DID format

On-chain DID: When a company has registered a DID via the trace_shack::did_registry Move module, the identityDid field returns did:iota:<network>:<object_id>. The object id resolves on IOTA Explorer as a shared DidRecord. Companies without an on-chain DID returnidentityDid: null (no synthetic hash is returned anymore).

DID lifecycle tx: Fields didRegistrationTransactionHash anddidNotarizationTransactionHash now return the real digests of the on-chain DidRegistered / NotarizationRecorded events, ornull when no such events exist for the wallet.

Account access

Login: Companies and administrators sign in to the FenixTrace dashboard with their email and a one-time code (OTP). There are no wallets to connect and nothing to sign by hand — the role is bound to the session.

API keys: Generate an integration key from your dashboard, then send it as Authorization: Bearer ftrace_<id>_<secret>. Treat the key like a password — keep it server-side and rotate it from the dashboard if exposed.

Integration v1 — Security

Authentication: v1 endpoints require Authorization: Bearer ftrace_<id>_<secret>. The key maps to your company server-side; it carries no wallet and grants no signing power to the caller.

Subscription validation: Every request is validated against the company subscription — the key only works while the subscription is active (non-expired) and the company is not paused.

IPFS, on-chain & notarization: All handled server-side. Send a raw data object and FenixTrace pins it to IPFS for you, then signs add_product on-chain and notarizes the record. If you already pinned the data yourself, send the ipfsHash instead.

Integration Kit: For automated batch processing, use the FenixTrace Integration Kit — a standalone helper that posts your products to /api/v1/products; IPFS, signing and notarization stay on FenixTrace's servers.