Sustainability Data API | Tracehub Developer Documentation

Overview

The Tracehub Sustainability Data API provides ESPR-compliant product sustainability data via micropayments. It enables AI agents to autonomously query material composition, carbon footprints, recycling instructions, and certifications for any product.

For AI Agents

Pay-per-request with x402 USDC micropayments on Base network.

For Partners

API key authentication with rate limits for trusted integrations.

Authentication

The API supports three authentication methods:

1. x402 Payment (Recommended for AI Agents)

Pay per request using USDC on Base network. Include an X-PAYMENT header with a PayAI-signed payment authorization.

curl -X POST https://tracehub.app/api/sustainability/materials \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <payai-signed-payment>" \
  -d '{"product_name": "Organic Cotton T-Shirt"}'

2. API Key (Partners)

For trusted partners with pre-arranged access:

curl -X POST https://tracehub.app/api/sustainability/materials \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"product_name": "Organic Cotton T-Shirt"}'

3. Access Token

After a successful x402 payment, you receive an X-Access-Token header valid for 1 hour:

curl -X POST https://tracehub.app/api/sustainability/carbon \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: <token-from-previous-request>" \
  -d '{"product_name": "Organic Cotton T-Shirt"}'

Pricing

All prices in USDC (stablecoin on Base network):

Endpoint	Price	Description
`/materials`	$0.02	Material composition lookup
`/carbon`	$0.03	Carbon footprint estimation
`/recycling`	$0.02	End-of-life instructions
`/certifications`	$0.02	Applicable standards
`/enrich`	$0.08	Full DPP enrichment (all data)

Endpoints

GET /status

Service status and 24-hour statistics. No authentication required.

curl https://tracehub.app/api/sustainability/status

GET /pricing

Detailed pricing information. No authentication required.

curl https://tracehub.app/api/sustainability/pricing

POST /materials

Get material composition for a product.

Request

{
  "product_name": "Organic Cotton T-Shirt",
  "vendor": "EcoWear",
  "product_type": "Apparel",
  "description": "100% organic cotton t-shirt, GOTS certified"
}

Response

{
  "success": true,
  "data": {
    "product_name": "Organic Cotton T-Shirt",
    "materials": [
      { "name": "Organic Cotton", "percentage": 100, "certified": true }
    ],
    "confidence": 85,
    "sources": ["GOTS Database", "Manufacturer Website"]
  },
  "metadata": {
    "provider": "grok",
    "webSearchUsed": true,
    "timestamp": "2025-12-12T10:30:00Z"
  }
}

POST /carbon

Get carbon footprint estimation.

Request

{
  "product_name": "Laptop Computer",
  "vendor": "TechCorp",
  "product_type": "Electronics",
  "materials": "Aluminum, Plastic, Lithium-ion battery"
}

Response

{
  "success": true,
  "data": {
    "product_name": "Laptop Computer",
    "carbon_footprint": {
      "value": 350,
      "unit": "kg CO2e",
      "scope": "cradle-to-gate"
    },
    "methodology": "Based on average laptop LCA data",
    "confidence": 70
  }
}

POST /recycling

Get recycling and end-of-life instructions.

Response

{
  "success": true,
  "data": {
    "product_name": "Smartphone",
    "recycling_instructions": "Return to manufacturer recycling program",
    "disposal_method": "specialized_recycling",
    "recyclable_components": ["Glass screen", "Aluminum frame"],
    "hazardous_components": ["Lithium-ion battery"],
    "circularity_score": 65,
    "confidence": 80
  }
}

POST /certifications

Get applicable certifications and standards.

Response

{
  "success": true,
  "data": {
    "product_name": "Organic Cotton T-Shirt",
    "existing_certifications": [
      { "name": "GOTS", "status": "verified", "expiry": "2026-01" }
    ],
    "applicable_standards": [
      { "name": "OEKO-TEX Standard 100", "relevance": "high" }
    ],
    "confidence": 75
  }
}

POST /enrich

Full DPP enrichment - all data types in one request. Best value for complete product data.

Response

{
  "success": true,
  "data": {
    "product_name": "Bamboo Cutting Board",
    "materials": {
      "materials": [{ "name": "Bamboo", "percentage": 100 }],
      "confidence": 90
    },
    "carbon": {
      "carbon_footprint": { "value": 2.5, "unit": "kg CO2e" },
      "confidence": 65
    },
    "recycling": {
      "instructions": "Compostable or recyclable as wood waste",
      "confidence": 85
    },
    "certifications": {
      "existing": [{ "name": "FSC", "status": "claimed" }],
      "confidence": 70
    },
    "overall_confidence": 77
  }
}

Error Handling

402 Payment Required

{
  "error": "Payment required",
  "paymentRequirements": {
    "amount": "20000",
    "currency": "USDC",
    "networks": ["base", "base-sepolia"],
    "recipient": "0x...",
    "description": "Sustainability API - materials lookup"
  }
}

429 Rate Limit Exceeded

{
  "error": "Rate limit exceeded",
  "retryAfter": 45,
  "limits": {
    "maxRequestsPerMinute": 30,
    "maxRequestsPerHour": 500
  }
}

400 Bad Request

{
  "error": "Invalid request",
  "message": "product_name is required (minimum 2 characters)"
}

x402 Payment Flow

The x402 protocol enables autonomous micropayments for AI agents:

Initial Request: Send request without payment header
Receive 402: Get payment requirements in response
Create Payment: Use PayAI SDK to create signed payment
Retry with Payment: Include X-PAYMENT header
Receive Data + Token: Get data and X-Access-Token for future requests

PayAI Integration Example

import { PayAI } from '@anthropic/payai';

const payai = new PayAI({
  network: 'base',
  wallet: yourWallet
});

// Create payment for API request
const payment = await payai.createPayment({
  recipient: '0x...', // From 402 response
  amount: '20000',    // micro-USDC
  currency: 'USDC'
});

// Make authenticated request
const response = await fetch('https://tracehub.app/api/sustainability/materials', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-PAYMENT': payment.signature
  },
  body: JSON.stringify({ product_name: 'Organic Cotton T-Shirt' })
});

Supported Networks

Base (mainnet) - Production payments
Base Sepolia (testnet) - Development/testing

Rate Limits

Auth Type	Per Minute	Per Hour
x402 Payment	Unlimited	Unlimited
API Key	30	500
Access Token	30	500

Data Quality

Each response includes a confidence score:

80-100: High confidence - verified data
60-79: Medium confidence - inferred from reliable sources
Below 60: Low confidence - best effort estimation

Back to App Documentation