User Guide
Complete reference for the TradeStance Global Trade Intelligence platform. Navigate sections using the table of contents or expand all for full-page reading.
New to TradeStance? Head to the Terminal and type a commodity name (e.g., "pistachios") to get your first landed cost calculation with a trade signal. Or type a country code like TR to explore Turkish commodity markets.
What is TradeStance?
TradeStance is a Bloomberg-style global trade intelligence platform designed for commodity importers, exporters, and procurement teams. It combines real-time price discovery across 35+ data sources, AI-powered forecasting, landed cost calculation, and supply chain management into a unified terminal interface.
The platform automates what traditionally required a team of analysts: monitoring commodity exchanges, calculating total landed costs, tracking shipments, assessing trade route risks, and generating actionable buy/sell signals. Every data point is mathematically anchored to the Total Landed Cost formula and validated through the Data Guardian Pipeline before reaching your screen.
First Steps
Visit /dashboard to access the full terminal interface with live price ticker, calculator, charts, and portfolio sidebar.
Use the command input at the top of the terminal. Type a commodity name (e.g., "pistachios", "copper wire", "saffron") to search for real-time pricing and trade signals.
Type a country code (TR, US, BR, IN) into the command bar or navigate directly to /tr, /us, etc. to view country-specific commodity intelligence.
In the terminal, enter a product and destination to get a full cost breakdown: FOB price, duties, logistics, insurance, fees, and a trade signal indicating whether to buy.
Understanding the Dashboard Layout
The terminal dashboard is composed of several interconnected panels:
Scrolling marquee at the top showing live commodity prices with real-time WebSocket updates. Green indicates price increases; red indicates decreases.
Interactive panel using the P_L formula. Enter product, origin, and destination to get a full cost breakdown with a trade signal.
30-day price history with ML forecast cone, cost breakdown donut chart, and commodity correlation heatmap.
Watchlist of tracked commodities with sparkline price charts, alerts, and quick-access trade signals.
Anomaly banner for fraud alerts, risk audit log, and sentiment feed drawn from AI-scored news analysis.
Real-time trade signal badge (STRONG_BUY, BUY, NEUTRAL, AVOID) based on landed cost vs 30-day weighted average.
TradeStance provides dedicated intelligence pages for major commodity-exporting countries. Each market page aggregates local exchange data, government statistics, port risk assessments, duty calculators, and arbitrage opportunity detection.
USDA commodity prices, retail price indices, GAIN intelligence reports, CBOT futures data, and FDA import alerts. Covers grains, oilseeds, dairy, livestock, and specialty crops with Section 301 and antidumping duty tracking.
TURiB exchange prices, TMO (Turkish Grain Board) intervention rates, BIST commodity index tracking, and Turkish customs duty calculator. Covers dried fruits, nuts, pulses, industrial minerals, and textiles with TL/USD exchange rate integration.
CEPEA daily commodity indices, CONAB harvest forecasts, Mercosul Common External Tariff rates, and Santos/Paranagua port congestion monitoring. Covers coffee, soybeans, sugar, orange juice, beef, and poultry.
Agmarknet mandi prices across 7,000+ markets, Spice Board auction data, APEDA export statistics, and DGFT trade policy updates. Covers spices, rice, tea, cotton, and pharmaceuticals with GST and BCD duty tracking.
What Each Market Page Shows
Identifies price differentials between origin and destination markets, factoring in logistics and duties to highlight profitable trade corridors.
IMF PortWatch congestion scores, average vessel dwell times, and geopolitical risk factors for origin and destination ports.
Local exchange quotes with USD conversion, intraday change indicators, and 30-day sparkline charts sourced from national commodity boards.
Country-specific tariff lookup by HS code. Includes MFN rates, preferential FTA rates, safeguard duties, and anti-dumping duties where applicable.
Landed Cost Calculator
The core calculation engine of TradeStance. Enter a product name, origin country, and destination country to receive a full cost breakdown using the Total Landed Cost formula:
P_L = (P_F + C_L + C_S + C_I) x (1 + T) + D + F
Tip: Click the "Live" button in the calculator to fetch real-time prices. The calculator also returns a trade signal based on how the landed cost compares to the 30-day weighted average.
Batch Calculator
Import a CSV file with multiple product/origin/destination combinations to calculate landed costs in bulk. Export results as CSV for integration with procurement systems. Supports up to 100 rows per batch.
Scenario Modeler
Compare what-if scenarios side by side. Adjust variables such as exchange rates, tariff changes, freight costs, or supplier switches to see how each factor affects your total landed cost. The modeler runs calculations in parallel and highlights the cost delta between scenarios.
Trade Finance Comparison
Evaluate four financing methods side by side for any trade:
Bank-guaranteed, highest security. Typical cost: 1.5-3% of invoice value plus issuance fees. Best for new supplier relationships.
Bank-intermediated, lower cost than LC. Documents released against payment or acceptance. Moderate risk profile.
Buyer-led financing using buyer's credit rating. Extends supplier payment terms while accelerating cash flow. Requires platform integration.
Direct payment terms (net 30/60/90). Lowest cost, highest buyer risk. Recommended only for established, trusted suppliers.
HS Code Explorer
Browse HS codes by chapter (2-digit), heading (4-digit), and subheading (6-digit). AI-powered classification: describe your product in plain language and get the correct HS code with confidence scoring. Includes tariff rate lookup for major trade corridors.
News Analysis
Curated commodity intelligence reports generated from 100+ news sources. Each article is scored by Gemini AI for trade impact sentiment (-1.0 to +1.0) and tagged by commodity, region, and risk type. Reports cover supply disruptions, policy changes, weather events, and price drivers.
Insights
Short-form analysis pieces authored by the TradeStance intelligence engine. Covers emerging trade corridors, regulatory shifts, tariff developments, and commodity market turning points. Updated daily with focus on actionable information.
Global Heatmap
Interactive world map color-coded by supply risk score. Factors include political stability, trade sanctions, port congestion, weather disruption probability, and commodity concentration risk. Click any country to drill down into specific commodity risks.
Analytics
Track portfolio value over time, cost savings from optimal timing signals, and breakdown of spend by commodity, origin, and trade route. Includes monthly P&L attribution showing which signals generated the most value.
AI Trade Advisor
Available within the terminal dashboard. Ask natural language questions about commodities, trade routes, regulations, and pricing. The advisor uses Gemini 2.0 Flash to synthesize answers from the platform's data layer, providing sourced responses with confidence indicators.
Example queries: "What is the landed cost of Turkish pistachios to Australia?", "Compare freight rates from Santos to Rotterdam vs Shanghai", "Is there an anti-dumping duty on Indian steel in the EU?"
Orders
Create, track, and manage purchase orders through their complete lifecycle. Link orders to suppliers, shipments, and documents for full traceability.
Suppliers
Searchable directory of verified suppliers with performance ratings, commodity categories, certifications (ISO, HACCP, organic), payment terms, and lead time history. Compare suppliers side by side and track quality scores over time.
Shipments
Register and track cargo manifests with vessel name, IMO number, Bill of Lading reference, HS code, origin/destination ports, and ETA. AIS vessel tracking integration provides real-time position updates on a maritime map.
LCL Consolidation
Find consolidation partners shipping on the same route to share container space. Includes LCL vs FCL cost calculator showing breakeven volume and potential savings. Filter by route, commodity compatibility, and schedule.
Document Vault
Centralized storage for all trade documents. Upload, organize, and retrieve Bills of Lading, Certificates of Origin, commercial invoices, packing lists, phytosanitary certificates, and insurance documents. Documents are linked to their associated orders and shipments for full audit trails.
Compliance Checker
Country-specific document requirement engine. Select an origin and destination to see the exact documents needed for customs clearance. Covers major markets:
The checker flags missing documents, validates expiry dates, and highlights country-specific requirements such as FDA prior notice (US), EUR.1 movement certificates (EU), or FSSAI import licenses (India).
TradeStance provides a suite of interactive charts and visualizations for deep market analysis. All charts support zoom, pan, and CSV data export.
30-day ahead price prediction generated by the DIA-LSTM model. The central line shows the median forecast, while the shaded cone represents the 95% confidence interval. Wider cones indicate higher uncertainty. Historical actuals are overlaid for validation. Updated every 6 hours.
Visual breakdown of each landed cost component as a percentage of total cost. Segments include FOB price, freight, duties, insurance, storage, taxes, and fees. Hover over any segment to see the exact dollar amount and percentage. Useful for identifying the largest cost drivers in any trade corridor.
Spider chart with five axes: Origin Risk (political stability, sanctions), Market Saturation (supply concentration), Cargo Volume (port throughput), Sanctions Exposure (OFAC/EU sanctions lists), and Quality Risk (historical rejection rates). Each axis is scored 0-100 with color-coded severity zones.
Time series chart of aggregated news sentiment scores for a commodity or trade route. Plotted on a -1.0 (very negative) to +1.0 (very positive) scale with a 7-day moving average trendline. Sudden sentiment shifts often precede price movements by 2-5 days.
Historical congestion levels at destination ports showing average vessel waiting times, berth occupancy rates, and container dwell times. Data sourced from IMF PortWatch. Useful for planning shipment timing and avoiding delays during peak congestion periods.
Price correlation matrix across 8 index commodities (LME Copper, CBOT Wheat, ICE Coffee, Brent Crude, LME Aluminum, CBOT Soybeans, ICE Sugar, Gold). Values range from -1.0 (inverse correlation) to +1.0 (perfect correlation). Helps identify diversification opportunities and hedge strategies in your commodity portfolio.
Cost allocation flow diagram showing how money flows from origin to destination. Tracks value at each stage: supplier payment, freight forwarder, port fees, customs duties, insurance, warehousing, and final delivery. Width of each flow is proportional to cost. Identifies the most expensive links in your supply chain.
Adding Products to Your Portfolio
From any product page or calculator result, click the "Add to Portfolio" button to start tracking a commodity. You can customize the tracked origin, destination, and quantity. The portfolio supports up to 50 items on the Professional plan and unlimited items on Enterprise.
Portfolio Sidebar
The portfolio sidebar appears on the right side of the terminal dashboard. Each tracked commodity shows:
Price Alerts
Set price alerts on any portfolio item. Configure upper and lower thresholds, percentage change triggers, or signal change notifications. Alerts can be delivered via the dashboard notification center, email, or webhook integration (Enterprise plan). Alerts fire once and auto-reset after 24 hours to prevent notification flooding.
Accessing the Terminal
The primary workspace of TradeStance. Combines real-time data feeds, calculation tools, charts, and portfolio management into a single Bloomberg-style terminal interface.
Real-Time WebSocket Ticker
The price ticker at the top of the terminal receives live updates via WebSocket using the TradePulse-WS v1.1.0 protocol. The connection is maintained through a Cloudflare Durable Object with hibernation support for efficiency. Three real-time channels deliver data:
The ticker includes a fallback mode: if the WebSocket connection drops, it switches to mock data with simulated price jitter so the interface remains responsive while reconnecting.
Trade Signal Interpretation
Signals are generated by comparing the calculated total landed cost against the 30-day weighted average price at the destination market:
Command Bar Shortcuts
The command bar at the top of the terminal accepts both product searches and shortcut commands:
The TradeStance command input follows a Bloomberg-inspired pattern. Type a country code or commodity name to navigate directly to the relevant intelligence page.
Country Codes
Command Pattern
TR <GO>Navigates to Turkey commodity intelligence pageUS <GO>Navigates to US market data and USDA reportspistachiosSearches commodity database for pistachio pricing080252Direct HS code lookup for shelled pistachiosPlain text input is treated as a commodity search. The system uses AI-powered HS code classification to match natural language descriptions to the correct harmonized system code, then retrieves pricing and trade data for that product.
GraphQL Explorer
In-browser GraphQL IDE for querying the TradeStance data layer. Query trades, suppliers, alerts, forecasts, cargo manifests, and price history. Includes schema documentation, auto-complete, and query history.
REST API Endpoints
The TradeStance backend exposes a REST API for programmatic access. All endpoints return JSON with CORS headers enabled.
| Method | Route | Description |
|---|---|---|
| GET | /trades | List all trades |
| GET | /trades/:id | Get trade by ID |
| POST | /trades | Create a new trade |
| PUT | /trades/:id | Update a trade |
| DELETE | /trades/:id | Delete a trade |
| POST | /calculate | Product + destination -> landed price + signal |
| POST | /engine/calculate | Full landed cost with financing + signal |
| POST | /price-signal | Compare landed cost vs 30-day average |
| GET | /alerts | Recent AI-scored news alerts (top 20) |
| GET | /cargo | Cargo manifests by HS code / status |
| POST | /cargo | Register a new cargo manifest |
| GET | /track/:imo | Vessel AIS tracking by IMO number |
| GET | /version | API version and build info |
| WS | /ws | WebSocket real-time ticker |
Webhook Integration
Enterprise plan users can configure webhook endpoints to receive real-time notifications for price alerts, signal changes, shipment status updates, and anomaly detections. Webhooks support Slack and Microsoft Teams formats natively, with a generic JSON payload option for custom integrations.
API rate limits: 5 requests per 5-minute window on AI-powered endpoints (calculate, price-signal, GraphQL). Standard CRUD endpoints allow 60 requests per minute. Rate limit headers (X-RateLimit-Remaining) are included in every response.
Admin features are available at /admin and require authentication. These tools are designed for platform operators and data engineers.
Monitor CRON job execution: news sync (every 6h), sentiment scoring, price hygiene bot, and forecast generation. View last run timestamps, success/failure status, and execution duration.
Read-only browser for all 13 Supabase tables. Filter, sort, and export data from trades, price_history, news_alerts, cargo_manifests, and more.
28-service quota tracking dashboard. Monitors API call counts against rate limits for Comtrade, Freightos, Gemini, ScrapingBee, Nexar, Event Registry, and all other integrated data sources.
ML model explainability dashboard. View DIA-LSTM attention weights, temporal feature importance, semantic input contributions, and prediction accuracy metrics over time.
Access real-time commodity pricing, AI-powered forecasts, and landed cost analysis across 50+ exporting countries.