trade-compass（贸易指南针）

SKILL: Trade Compass

ClawHub Skill · v3.2.0 · Python 3.11+ · FastAPI backend required

Overview

Trade Compass answers the question: "What does it actually cost me to land this product in the US?"

It combines tariffs (USITC base + Section 232/301 + AD/CVD), exchange rates (18 currencies with 30-day trends), ocean freight (25+ routes from global ports to US coasts), compliance (CPSC/FDA/FCC/UFLPA), and customs costs (broker, ISF, bond, MPF, HMF) into a single landed-cost-per-unit calculation.

Designed for global traders from any country shipping to the United States — not just China.

Capabilities (v3.2)

How Claude Uses This Skill

When invoked, Claude should:

1. Identify the HTS code from the user's product description.

- Use Claude's built-in HTS knowledge to suggest the most specific 10-digit code. - If uncertain, start with a 4- or 6-digit prefix.

1. Call the effective tariff endpoint:

   GET http://localhost:8000/tariff/{hts_code}/effective?origin={ISO2}

Default origin: CN (China). Accept natural-language origin ("Vietnam" → VN).

1. Present the result clearly:

- List each duty layer (MFN base, Section 232, Section 301) with its rate and legal basis. - Show effective_total_pct as the confirmed total. - If adcvd is present, highlight the AD/CVD risk and worst-case total. - If compliance_flags is present, list the regulatory agencies. - Always display the advisory field if non-empty — the user needs to know about Section 122. - Remind the user to verify with a licensed customs broker.

1. For full landed cost (the most powerful endpoint), call:

   GET http://localhost:8000/landed-cost?hts_code={code}&origin={ISO2}&cog_local=32&units=500&cbm=5&destination=USWC

This combines tariff + FX + shipping + customs into one response.

1. For exchange rate impact, call:

   GET http://localhost:8000/fx/{currency}/impact?cog_local=32&units=500

1. For shipping rates, call:

   GET http://localhost:8000/shipping/{origin}?destination=USWC

1. For AD/CVD, compliance, or profit, call the respective endpoints below.

API Endpoints Reference

Data Sources & Auto-Refresh

ECB Currency Gap

The free ECB feed does not cover: VND, BDT, PKR, TWD. These 4 currencies use calibrated simulation and are marked with source: "simulated" in the response. Set EXCHANGERATE_API_KEY to get real rates for all 18 currencies.

Optional Premium API Keys

For more accurate data, users can register for paid APIs. The skill will automatically detect and use them:

Without any API keys, the skill works fully using free ECB data + calibrated simulation. No registration required.

Data Refresh Schedule

• FX rates: Updated daily (after ECB publishes)
• Shipping rates: Updated daily (simulation or Freightos)
• USITC tariffs: Updated weekly (Monday)
• First startup: Automatically backfills 30 days of history

Tariff Logic (Current as of 2026-02-26)

Confirmed in-force duties

AD/CVD orders (company-specific — "all others" rate shown)

Struck down — NOT applied

Advisory — shown but NOT added to calculated total

Limitations & Disclaimer

• Data source: USITC publishes the official HTS schedule; this skill reads it directly. Rate data is as current as the latest USITC revision.
• Section 122 is confirmed in effect but deliberately excluded from effective_total_pct due to its temporary, politically fluid nature — always check the advisory field.
• AD/CVD rates are company-specific. The "all others" rate shown is applied to exporters without an individual rate from a Commerce Dept. administrative review. Your actual rate may be lower.
• Compliance data covers major agencies but is not exhaustive. Some products have additional state-level or industry-specific requirements.
• For informational purposes only. Always verify tariff obligations with CBP binding rulings, a licensed customs broker, or qualified trade counsel before making import decisions.