Do I need to use FenixTrace's IPFS keys?

No. You must use your own Pinata keys. Each company must have their own IPFS account.

How much does it cost to process a product?

About 0.2 IOTA per product. On testnet, tokens are free from the faucet.

Can I use the kit on mainnet?

Yes. Change IOTA_NODE_URL in .env and make sure the wallet has real IOTA.

Integration Gateway

Q: Does the kit work without FenixTrace?

No. The kit requires an active subscription on FenixTrace.

Q: How do I verify a product was registered?

Verify in the FenixTrace Scanner or IOTA Explorer with the transaction hash.

Back to Documentation

Integration Gateway

FenixTrace Integration Kit

A standalone Node.js server that allows companies to register products on IOTA Rebased and pin them to IPFS in a fully automated way. Just drop a JSON file into the uploads/ folder — the kit handles everything: IPFS upload, the company_supply_chain::add_product Move call, and notarization via the FenixTrace platform.

Node.js

IOTA Rebased

Move

IPFS / Pinata

Docker Ready

PM2 Ready

REST API

Auto-Processing

Who Is It For

Companies with CRM/ERP

Integrate blockchain traceability directly into your management system. Your CRM writes JSON files to the uploads/ folder and the kit processes them automatically.

E-Commerce & Marketplace

Automatically register every sold product on the blockchain. Generate traceable labels with QR codes for your end customers.

Manufacturers & Supply Chain

Track every batch from production to GDO delivery. Upload quality data, certifications and logistics as immutable metadata on IPFS.

Developers & Integrators

Use the kit's REST APIs to build custom integrations. Compatible with any language that can make HTTP POST calls.

How It Works

flow

Your System          Integration Kit              IOTA Rebased + IPFS
──────────           ───────────────              ───────────────
 JSON file   ──►  1. Upload to IPFS (Pinata)  ──►  IPFS CID
                  2. add_product on-chain     ──►  Tx Hash
                  3. Notarize on-chain        ──►  Notarization Tx
                  4. Move file to processed/

Each product gets: an IPFS CID (immutable content hash), a blockchain transaction on IOTA Rebased, a notarization transaction proving integrity, and a public page on the FenixTrace Scanner. The kit automatically monitors the uploads/ folder and processes new files every minute.

Prerequisites

Requirement	Details
Node.js	v16+ (v18 LTS recommended)
FenixTrace Subscription	Active plan on fenixtrace.com
IOTA Wallet	Generated via node generate-wallet.js
Delegate Access	Wallet must be added as delegate from Company Dashboard
Pinata Account	Your own API keys from app.pinata.cloud (own account mandatory)
IOTA Tokens	Testnet faucet or mainnet IOTA for gas fees

Step-by-Step Setup

1. Clone & Install

bash

git clone https://github.com/fenixtrace
cd FenixTrace-IOTA-auto-add-product-Integration-Kit
npm install

2. Generate a Wallet

Create a new dedicated IOTA wallet. The wallet-keys.json file contains address, mnemonic and private key. Never commit this file.

bash

node generate-wallet.js
# Creates wallet-keys.json with:
# - address: 0x...
# - mnemonic: "word1 word2 ..."
# - privateKey: 0x...
# - privateKeyBech32: iotaprivkey1qp...

3. Add as Delegate

This step is mandatory. The generated wallet must be authorized as a delegate from the FenixTrace Company Dashboard. Without this authorization, on-chain transactions will fail with "Wallet not authorized" error.

From the FenixTrace Company Dashboard:

1. Log in with the company owner wallet

2. Go to the "Delegate Management" tab

3. Click "Add Delegate"

4. Paste the address from wallet-keys.json

5. Confirm with wallet signature

4. Request Testnet Tokens

The wallet needs IOTA for gas fees. On testnet, tokens are free.

bash

curl -X POST "https://faucet.testnet.iota.cafe/gas" \
  -H "Content-Type: application/json" \
  -d '{"FixedAmountRequest":{"recipient":"0xYOUR_WALLET_ADDRESS"}}'

# Response: {"transferredGasObjects":[{"amount":10000000000,...}],"error":null}
# You receive 10 IOTA (enough for ~50 products)

Operation	Cost (base units)	IOTA
add_product	~100,000,000	~0.1
Notarization	~100,000,000	~0.1
Total per product	~200,000,000	~0.2
10 products	~2,000,000,000	~2.0
50 products	~10,000,000,000	~10.0

5. Configure .env file

bash

cp .env.example .env

Variable	Where to Find It
IOTA_PRIVATE_KEY	wallet-keys.json → privateKeyBech32 field
IOTA_PACKAGE_ID	FenixTrace Dashboard or provided during onboarding
IOTA_MODULE_COMPANY_SUPPLY_CHAIN	Same package ID + ::company_supply_chain
IOTA_COMPANY_OBJECT_ID	Company Dashboard → Settings, or via public API
PINATA_API_KEY	app.pinata.cloud → API Keys
PINATA_SECRET_API_KEY	Same page on Pinata
PINATA_JWT	Same page on Pinata
FENIXTRACE_API_BASE_URL	http://localhost:3000 (dev) or https://fenixtrace.com (prod)

6. Start the Server

bash

npm start
# Server starts on port 3005
# Auto-processing monitors uploads/ folder every minute

Usage

Method 1: JSON Files

Drop a .json file in the uploads/ folder. The kit detects and processes it automatically within 1 minute.

cp my-product.json uploads/
# Auto-processed in ~1 min
# Or trigger manually:
curl -X POST http://localhost:3005/process-all

Method 2: REST API

Use REST endpoints for programmatic integrations. The kit exposes APIs to process, monitor, and verify.

# Process all files
curl -X POST localhost:3005/process-all

# Process single file
curl -X POST localhost:3005/process/my.json

# Check balance for 20 files
curl "localhost:3005/balance?files=20"

Method 3: CRM/ERP

Your CRM or ERP writes JSON files to the uploads/ folder (via shared volume, SFTP, or API) and the kit processes them automatically.

# Mount shared volume
docker run -v /crm/exports:/app/uploads ...

# Or use SFTP to push files
sftp user@server:/app/uploads/

# Files are auto-processed

Product JSON Format

Each JSON file represents a product to register on-chain. Only the "name" field is required. All other fields are optional and stored as immutable metadata on IPFS.

json

{
  "name": "Annurca Apple",              // REQUIRED
  "company": "Your Company Name",       // Optional
  "template": "agro",                   // Optional: agro|pharma|fashion|logistics|...
  "batchId": "BATCH-2026-001",          // Optional
  "product": {
    "variety": "Annurca IGP",
    "category": "Fresh Fruit",
    "organicCertified": true,
    "certifications": ["GlobalGAP", "IGP Campania"],
    "weightKg": 12.5
  },
  "origin": {
    "region": "Campania",
    "province": "Avellino",
    "farmName": "Azienda Agricola Rossi"
  },
  "qualityControl": {
    "brixLevel": "14.2",
    "residueTestPassed": true,
    "testLabName": "Lab Analysis SRL"
  }
}

Templates:

generic

agro

pharma

fashion

logistics

electronics

art

automotive

cosmetics

chemicals

machinery

custom

API Reference

Method	Endpoint	Description
GET	/	Server info and available endpoints
GET	/status	Wallet address, balance, contract config
GET	/health	Full health check (blockchain, filesystem, memory)
GET	/ping	Liveness check — returns "pong"
GET	/balance	Wallet balance. Add ?files=N to estimate costs
POST	/process-all	Process all JSON files in uploads/
POST	/process/:filename	Process a single file by name
GET	/processed	List processed products with metadata
GET	/logs	View available log files
POST	/logs/cleanup	Clean up old log files

Docker

Production

bash

# Configure
cp .env.example .env
# Edit .env with your values

# Build and start
docker compose up -d

# Check health
curl http://localhost:3005/health

# View logs
docker compose logs -f

Development

bash

# Hot-reload mode
docker compose -f docker-compose.dev.yml up

# Useful commands
docker compose down          # Stop
docker compose up -d --build # Rebuild
docker exec -it fenixtrace-integration-kit sh

CRM & eCommerce Plugins

Ready-to-use plugins to integrate FenixTrace directly into your CRM or eCommerce platform. Each plugin communicates with the Integration Kit to register products on the blockchain.

FenixTrace for Odoo

Odoo 16/17 module with single sync, batch, auto cron and retry

Python

Odoo 16/17

Download from GitHub

FenixTrace for WooCommerce

WordPress/WooCommerce plugin with meta box, bulk action and auto-sync on publish

PHP

WordPress

Download from GitHub

FenixTrace for PrestaShop

PrestaShop 1.7/8.x module with database sync, product tab and auto-sync on save

PHP

PrestaShop

Download from GitHub

FenixTrace for Salesforce

Salesforce package with Apex classes, LWC component, scheduled batch sync and custom fields on Product2

Apex

Salesforce

Download from GitHub

FenixTrace for WordPress

Pure WordPress plugin with Custom Post Type, meta box, REST API and auto-sync — no WooCommerce required

PHP

WordPress

Download from GitHub

Frequently Asked Questions

No. You must use your own Pinata keys (or other IPFS provider). Each company must have their own IPFS account. Register for free at app.pinata.cloud and generate your API keys.

About 0.2 IOTA per product (2 transactions: add_product + notarization). On testnet, tokens are free from the faucet. 10 IOTA from the faucet covers about 50 products.

No. The kit requires an active subscription on FenixTrace because it operates on FenixTrace smart contracts. The wallet must be an authorized delegate of a registered company.

Yes. Change IOTA_NODE_URL to https://api.iota.cafe in the .env file and make sure the wallet has real IOTA for gas fees.

After processing, the file is moved to processed/ with metadata (txHash, ipfsHash). You can verify in the FenixTrace Scanner or IOTA Explorer with the transaction hash.

Next Steps

Configure delegates, generate the wallet, and start registering products. Check the API documentation for advanced integrations via FenixTrace's public APIs.

Delegate Management API Reference Scanner Back to Documentation