Public API Reference

FenixTrace exposes REST endpoints for external integrations. Public endpoints require no authentication. Label Deposit v1 endpoints require API key authentication with an active company subscription.

REST API

Public + Auth

CORS Enabled

JSON Response

Integration Kit

Base URL

https://trace.fenixsoftwarelabs.com

Companies

Products

Labels

Label Deposit (v1)

Companies

GET

/api/public/companies

List all registered companies on FenixTrace. Supports search filtering by company name or owner address, and filtering by DID identity status.

Parameters

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

Response

json

{
  "companies": [
    {
      "companyName": "Rossi Alimentari S.r.l.",
      "ownerAddress": "0x7a3b...e91f4c",
      "contractAddress": "0x4e8d...a72b01",
      "identityDid": "did:iota:8f2a...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://trace.fenixsoftwarelabs.com/api/public/companies?search=rossi&hasIdentity=true&limit=10"

GET

/api/public/companies/:address

Get detailed information about a single company by its contract address or owner wallet address. Returns company profile, DID identity, and delegate list.

Parameters

Name	Type	Required	Description
address	string	required	Company contract address or owner wallet address (path parameter)

Response

json

{
  "company": {
    "companyName": "Rossi Alimentari S.r.l.",
    "ownerAddress": "0x7a3b...e91f4c",
    "contractAddress": "0x4e8d...a72b01",
    "identityDid": "did:iota:8f2a...c4d7e9",
    "identityStatus": "active",
    "profileImageCid": "QmX9vB3kR...",
    "delegates": ["0x91cf...b3a8", "0x5d2e...f710"],
    "createdAt": "2026-01-15T09:30:00.000Z",
    "expiryDate": "2027-01-15T09:30:00.000Z"
  }
}

Example

curl

curl "https://trace.fenixsoftwarelabs.com/api/public/companies/0x4e8d1f...a72b01"

Products

GET

/api/public/companies/:address/products

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

Parameters

Name	Type	Required	Description
address	string	required	Company contract or owner address (path parameter)
search	string	optional	Search by product name, IPFS hash, or tx 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...",
      "transactionId": "Bk47X92cDE...",
      "timestamp": 1768492800,
      "ownerAddress": "0x7a3b...e91f4c",
      "notarization": {
        "status": "completed",
        "notarizationHash": "a9d3e7f1...",
        "iotaNotarizationTransaction": "Bk47X92cDE..."
      }
    }
  ],
  "total": 156,
  "limit": 50,
  "offset": 0,
  "company": {
    "companyName": "Rossi Alimentari S.r.l.",
    "contractAddress": "0x4e8d...a72b01"
  }
}

Example

curl

curl "https://trace.fenixsoftwarelabs.com/api/public/companies/0x4e8d1f.../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": {
    "companyName": "Rossi Alimentari S.r.l.",
    "contractAddress": "0x4e8d...a72b01"
  }
}

Example

curl

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

Labels

GET

/api/public/companies/:address/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 product transaction hash.

Parameters

Name	Type	Required	Description
address	string	required	Company contract or owner address (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://trace.fenixsoftwarelabs.com/scanner/company/0x4e8d.../product?...",
      "companyLogoUrl": "https://dweb.link/ipfs/QmX9vB3kR..."
    }
  ],
  "total": 156,
  "suggestedFormat": "10x15",
  "availableFormats": ["a4-sheet", "a4-single", "10x15", "62x29", "50x30"],
  "company": {
    "companyName": "Rossi Alimentari S.r.l.",
    "profileImageCid": "QmX9vB3kR..."
  }
}

Example

curl

curl "https://trace.fenixsoftwarelabs.com/api/public/companies/0x4e8d1f.../labels?format=a4-sheet&limit=100"

Label Deposit (v1)

POST

/api/v1/labels/deposit

Deposit a product label via external API. Companies must upload their product data to IPFS using their own IPFS provider (Pinata, Infura, web3.storage, etc.) and provide the resulting CID. This API validates the company on-chain and returns the Move transaction payload ready to be signed.

Parameters

Name	Type	Required	Description
Authorization	header	required	Bearer ftrace_<walletAddress>_<secret>
name	string	required	Product name
ipfsHash	string	required	IPFS CID of the product data (uploaded by the company with their own IPFS provider keys)
template	string	optional	Template type: generic, agro, pharma, fashion, logistics, electronics, art, automotive, cosmetics, chemicals, machinery, custom
batchId	string	optional	Batch identifier
txHash	string	optional	If on-chain tx already submitted (full deposit mode — combines deposit + confirm)
notarizationTxHash	string	optional	If notarization tx already submitted

Response

json

{
  "success": true,
  "mode": "prepare",
  "depositId": "a1b2c3d4-...",
  "ipfsHash": "QmX9vB3kR...",
  "ipfsUrl": "https://dweb.link/ipfs/QmX9vB3kR...",
  "transaction": {
    "target": "0x...::company_supply_chain::add_product",
    "arguments": {
      "companyObject": "0x...",
      "name": "Olive Oil Extra Virgin",
      "ipfsHash": "QmX9vB3kR...",
      "clockObject": "0x6"
    },
    "codeExample": "// @iota/iota-sdk Transaction builder code..."
  },
  "company": {
    "name": "Rossi Alimentari",
    "contractAddress": "0x...",
    "ownerAddress": "0x..."
  }
}

Example

curl

# Step 1: Upload your product data to IPFS with YOUR keys
curl -X POST "https://api.pinata.cloud/pinning/pinJSONToIPFS" \
  -H "Authorization: Bearer YOUR_PINATA_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "pinataContent": { "origin": "Puglia", "batch": "OIL-001" } }'

# Step 2: Call FenixTrace API with the IPFS CID
curl -X POST "https://trace.fenixsoftwarelabs.com/api/v1/labels/deposit" \
  -H "Authorization: Bearer ftrace_0x7a3b...e91f_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Olive Oil Extra Virgin",
    "ipfsHash": "QmX9vB3kR7yKf...",
    "template": "agro"
  }'

POST

/api/v1/labels/confirm

Confirm an on-chain label deposit after the external system has signed and submitted the Move transaction. Enqueues notarization tracking.

Parameters

Name	Type	Required	Description
Authorization	header	required	Bearer ftrace_<walletAddress>_<secret>
transactionHash	string	required	IOTA transaction digest from the signed Move call
productName	string	required	Product name (must match the deposit)
depositId	string	optional	Deposit ID from the /deposit response
ipfsHash	string	optional	IPFS CID of the product metadata

Response

json

{
  "success": true,
  "notarization": {
    "status": "queued",
    "sourceTransactionHash": "Ah23W48b...",
    "entityType": "label"
  },
  "scannerUrl": "/scanner/company/0x.../product?name=...",
  "company": {
    "name": "Rossi Alimentari",
    "contractAddress": "0x..."
  }
}

Example

curl

curl -X POST "https://trace.fenixsoftwarelabs.com/api/v1/labels/confirm" \
  -H "Authorization: Bearer ftrace_0x7a3b...e91f_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionHash": "Ah23W48bEE5U1xSqHr59gHAjQAMwkdZg...",
    "productName": "Olive Oil Extra Virgin",
    "depositId": "a1b2c3d4-...",
    "ipfsHash": "QmX9vB3kR..."
  }'

GET

/api/v1/labels/status

Check the status of a deposited label. Returns product data from the blockchain and notarization status.

Parameters

Name	Type	Required	Description
Authorization	header	required	Bearer ftrace_<walletAddress>_<secret>
txHash	string	required	Transaction hash from the on-chain deposit

Response

json

{
  "success": true,
  "found": true,
  "product": {
    "name": "Olive Oil Extra Virgin",
    "ipfsHash": "QmX9vB3kR...",
    "productTxHash": "0x0918f6c4...",
    "transactionId": "Ah23W48b...",
    "timestamp": 1772326876,
    "ownerAddress": "0x7a3b...e91f"
  },
  "notarization": {
    "status": "completed",
    "notarizationHash": "abc123...",
    "iotaNotarizationTransaction": "Bx45Y..."
  },
  "scannerUrl": "/scanner/company/0x.../product?..."
}

Example

curl

curl "https://trace.fenixsoftwarelabs.com/api/v1/labels/status?txHash=Ah23W48bEE5U1x..." \
  -H "Authorization: Bearer ftrace_0x7a3b...e91f_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.

Addresses: Company addresses can be either the contract address (0x...) or the owner wallet address. Both formats are accepted.

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.

Label Deposit v1 — Security

Authentication: v1 endpoints require Authorization: Bearer ftrace_<walletAddress>_<secret>. API keys are generated from the company dashboard.

On-Chain Validation: Every request is validated against the IOTA blockchain — the wallet must be a registered company owner or enabled delegate, with an active (non-expired) subscription, and the company must not be paused.

IPFS: Companies must use their own IPFS provider (Pinata, Infura, web3.storage, etc.) to upload product data. The API only accepts an already-uploaded IPFS CID — it does not handle IPFS uploads.

Integration Kit: For automated batch processing, use the FenixTrace Integration Kit — a standalone Node.js server that handles IPFS upload (with your own keys), on-chain signing, and notarization automatically.