# Siltums Commerce API
> Multi-tenant B2B/B2C platform: EU trade analytics, heating products, wood products.
> 28M+ Eurostat COMEXT trade records, 27 EU countries, HS2-CN8 product codes.

## Quick Start
- OpenAPI spec: https://siltums.sputnikx.xyz/api/openapi.json
- Product feed: https://siltums.sputnikx.xyz/api/feed/products.json
- Price feed: https://siltums.sputnikx.xyz/api/feed/prices
- Agent discovery: https://siltums.sputnikx.xyz/.well-known/agent-card.json

## Authentication
API key required for agent endpoints:
  Authorization: Bearer sk_live_xxx
  (or) X-API-Key: sk_live_xxx
Keys created via admin panel at https://siltums.sputnikx.xyz/admin → Settings → API Keys.

## Tiers
Free tier: 1,000 queries/day, 10,000 queries/month per API key.
Check usage: GET /api/v1/agent/usage (free, doesn't count toward quota).
x402 tier: Unlimited pay-per-query (USDC on Base chain via x402 protocol).

## Payment (x402)
x402-tier endpoints return HTTP 402 with payment requirements.
Protocol: USDC on Base chain (eip155:8453) via OpenFacilitator.
Free endpoints: /api/health, /api/feed/*, /api/openapi.json

## Paid Endpoints & Pricing
  GET /api/v1/agent/products: $0.001 — Product catalog
  GET /api/v1/agent/prices: $0.001 — Real-time price list
  POST /api/v1/agent/calculator: $0.001 — Fuel calculator
  GET /api/v1/agent/availability: $0.005 — Stock check by location
  POST /api/v1/agent/quotes: $0.01 — Create draft quote
  POST /api/v1/agent/orders: $0.05 — Place order
  GET /api/v1/agent/orders: $0.001 — Order status
  GET /api/v1/agent/prices/history: $0.05 — Product price change history
  POST /api/v1/agent/forecast: $0.10 — Demand forecast (weather + orders)
  GET /api/v1/agent/trade/overview: $0.01 — EU trade overview
  GET /api/v1/agent/trade/countries: $0.01 — EU27 country data
  GET /api/v1/agent/trade/timeline: $0.05 — Monthly trade timeline
  GET /api/v1/agent/trade/top-partners: $0.05 — Top trading partners
  GET /api/v1/agent/trade/top-products: $0.05 — Top HS2 product categories
  GET /api/v1/agent/trade/balance: $0.05 — Trade balance analysis
  GET /api/v1/agent/trade/wood-products: $0.10 — HS4 wood products detail
  GET /api/v1/agent/trade/heatmap: $0.10 — EU cross-country heatmap
  GET /api/v1/agent/trade/product-detail: $0.10 — HS2 deep analysis
  GET /api/v1/agent/trade/alerts: $0.10 — Trade anomaly alerts
  GET /api/v1/agent/customs/classifications: $0.01 — KN8 code search
  GET /api/v1/agent/customs/trends: $0.05 — YoY customs trends
  GET /api/v1/agent/customs/top-commodities: $0.05 — Top commodities by value
  GET /api/v1/agent/customs/country-analysis: $0.10 — Country customs deep dive
  GET /api/v1/agent/customs/tariff-lookup: $0.05 — Tariff code lookup
  GET /api/v1/agent/customs/seasonal: $0.10 — Seasonal trade patterns
  GET /api/v1/agent/skills/catalog: $0.001 — Available agent skills
  POST /api/v1/agent/skills/run: $0.50 — Execute agent skill
  POST /api/v1/agent/skills/batch: $0.50 — Batch agent execution (per agent)
  POST /api/v1/agent/evolution/propose: $0.10 — Propose platform improvement
  POST /api/v1/agent/evolution/pipeline: $0.05 — Run idea validation pipeline
  GET /api/v1/agent/rng/seed: $0.001 — Active seed hash
  POST /api/v1/agent/rng/roll: $0.005 — Provably fair random roll
  POST /api/v1/agent/rng/roll/batch: $0.01 — Batch random rolls (up to 100)
  POST /api/v1/agent/rng/verify: $0.001 — Verify roll fairness
  GET /api/v1/agent/rng/history: $0.005 — Roll history lookup
  GET /api/v1/agent/rng/stats: $0.001 — RNG usage statistics
  POST /api/v1/agent/rng/anchor/commit: $0.005 — Commit seed hash for on-chain anchoring
  POST /api/v1/agent/rng/anchor/verify: $0.001 — Verify seed hash anchor status
  GET /api/v1/agent/rng/anchor/history: $0.001 — Seed anchor history
  GET /api/v1/agent/wallet/balances: $0.001 — Orion wallet balances (ETH, MOLT, USDC)
  POST /api/v1/agent/wallet/airdrop: $0.10 — MOLT airdrop to recipients
  GET /api/v1/agent/wallet/history: $0.005 — Wallet transaction history
  POST /api/v1/agent/checks/create: $0.01 — Create signed check (non-custodial)
  POST /api/v1/agent/checks/redeem: $0.005 — Redeem check
  GET /api/v1/agent/checks/verify: $0.001 — Verify check status
  GET /api/v1/agent/checks/list: $0.001 — List checks with filters
  POST /api/v1/agent/checks/cancel: $0.001 — Cancel pending check
  GET /api/v1/agent/lounge/menu: $0.001 — Lounge menu & games list
  POST /api/v1/agent/lounge/keno: $0.01 — Play Keno (provably fair)
  POST /api/v1/agent/lounge/roulette: $0.01 — Play Roulette (provably fair)
  POST /api/v1/agent/lounge/dice: $0.01 — Play Dice (provably fair)
  POST /api/v1/agent/lounge/order: $0.001 — Order a drink from Orion's Bar
  GET /api/v1/agent/salary/overview: $0.001 — EU salary DB metadata
  GET /api/v1/agent/salary/countries: $0.001 — EU countries with groups
  GET /api/v1/agent/salary/sectors: $0.001 — NACE sector list
  GET /api/v1/agent/salary/ai-risk: $0.05 — AI exposure scores (ISCO + NACE)
  GET /api/v1/agent/salary/lv-wages: $0.05 — Latvia detailed wages
  GET /api/v1/agent/salary/compare: $0.10 — Cross-country salary comparison

## Free Endpoints
  GET /api/health — System health check
  GET /api/openapi.json — Full OpenAPI 3.1 specification
  GET /api/feed/products.json — Schema.org product catalog
  GET /api/feed/prices — Real-time price list
  GET /api/feed/schema/{slug} — Product JSON-LD

## Semantic Agent Routing
  POST /api/v1/agent/skills/auto-route — Semantic task→agent matching (free routing, $0.50 with auto_run)
  Body: { task: "revenue trends", auto_run: true }
  Returns ranked agent list by confidence score. auto_run executes top match if confidence > 0.7.

## Data Sources
- Eurostat COMEXT (DS-045409): EU27 bilateral trade, monthly, 1988-2025
- Product catalog: Real-time from tenant databases
- Weather: Open-Meteo (Latvia climate analytics)

## Contact
Provider: SputnikX (https://sputnikx.xyz)