{
  "openapi": "3.1.0",
  "info": {
    "title": "TradePulse API",
    "description": "Global trade intelligence API. AI-synthesized tariff rates, HS code classification, FTA duty analysis, landed cost calculation, trade compliance guidance, sanctions screening, market entry analysis, and supply chain news. Covers 195 countries with real-time trade data. Serves importers, exporters, sourcing teams, freight brokers, and trade compliance officers. Flexport, Freightos, Payoneer, and compliance tool affiliates included in relevant endpoints. All endpoints support any language via ?lang=. Pricing: $0.10\u2013$0.20 USDC/call via x402 micropayment.",
    "version": "1.2.0",
    "contact": {
      "url": "https://tradepulse.theaslangroupllc.com"
    }
  },
  "servers": [
    {
      "url": "https://tradepulse.theaslangroupllc.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 micropayment signature. Omit to receive 402 with payment requirements. Sign and retry to receive data."
      }
    }
  },
  "paths": {
    "/api/trade/classify": {
      "get": {
        "summary": "HS code classification",
        "description": "Classify any product into its Harmonized System (HS) code using natural language description. Returns HS6 code with confidence score, alternative classifications, GRI rules applied, chapter notes, US HTS and EU CN hints, trade implications (dual-use, CITES, restricted countries), and verification guidance.",
        "operationId": "tradeClassify",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "product",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Natural language product description \u2014 e.g. 'laptop computer', 'cotton t-shirts', 'industrial water pump'"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Response language code (en, zh, ja, de, fr, es, ar, hi, etc.)"
          }
        ],
        "responses": {
          "200": {
            "description": "HS code classification with confidence score and trade implications"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "HS code classification \u2014 chain before /api/trade/tariff; pairs with /api/trade/compliance for classification-dependent regulations"
      }
    },
    "/api/trade/tariff": {
      "get": {
        "summary": "Tariff rates by HS code and country pair",
        "description": "Look up import tariff rates for any HS code between any two countries. Returns MFN rate, all applicable FTA preferential rates with rules of origin summary, GSP/LDC programs, anti-dumping and countervailing duties, Section 301 tariffs, VAT/GST on import, and full cost estimate on a $100,000 shipment.",
        "operationId": "tradeTariff",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "hs_code",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "6-digit HS code \u2014 e.g. 847130, 610910, 090111"
          },
          {
            "name": "from_country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Exporting country \u2014 e.g. China, Vietnam, Germany, Mexico. Also accepts 'from'"
          },
          {
            "name": "to_country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Importing country \u2014 e.g. USA, Japan, Germany, Australia. Also accepts 'to'"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tariff rates with FTA preferential rates and additional duties"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Start here for any import/export analysis; chain to /api/trade/landed for total cost; follow with /api/trade/compliance for documentation requirements; freight affiliate links included"
      }
    },
    "/api/trade/landed": {
      "get": {
        "summary": "Full landed cost calculator",
        "description": "Calculate the complete landed cost for an international shipment. Returns freight estimates (sea/air/courier), import duty, VAT/GST with recoverability note, customs broker fees, port charges, country-specific fees (US MPF/HMF), and total landed cost with margin impact. Includes optimization opportunities: FTA savings, bonded warehouse, duty drawback.",
        "operationId": "tradeLanded",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "product",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Product description or type. Use hs_code instead if known."
          },
          {
            "name": "hs_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "6-digit HS code as alternative to product"
          },
          {
            "name": "from_country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Origin country. Also accepts 'from'"
          },
          {
            "name": "to_country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Destination country. Also accepts 'to'"
          },
          {
            "name": "value",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Declared customs value in USD"
          },
          {
            "name": "quantity",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Number of units (for per-unit cost calculation)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full landed cost breakdown with optimization opportunities"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Full total cost calculation \u2014 chain after /api/trade/tariff and /api/trade/fta for accurate margin modeling; pairs with WealthPulse for ROI analysis"
      }
    },
    "/api/trade/fta": {
      "get": {
        "summary": "Free Trade Agreement analyzer",
        "description": "Identify all applicable Free Trade Agreements for any country pair. Returns agreement names, preferential tariff rates, staging categories, rules of origin (CTH/RVC/WO), documentation required, self-certification eligibility, cumulation zones, and FTA utilization ROI calculation. Covers RCEP, CPTPP, USMCA, AfCFTA, all EU FTAs, India CEPAs, GCC, and 290+ more.",
        "operationId": "tradeFTA",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "from_country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Exporting country. Also accepts 'from'"
          },
          {
            "name": "to_country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Importing country. Also accepts 'to'"
          },
          {
            "name": "hs_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "6-digit HS code for product-specific rate lookup"
          },
          {
            "name": "product",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Product description for additional context"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "FTA analysis with preferential rates and rules of origin"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Run after /api/trade/tariff to find duty savings via FTA; pairs with /api/trade/compliance for rules-of-origin documentation"
      }
    },
    "/api/trade/sanctions": {
      "get": {
        "summary": "Sanctions and trade restrictions screening",
        "description": "Screen countries, entities, or products against OFAC (US), EU sanctions, UN Security Council measures, UK OFSI, Australia DFAT, and Canada OSFI. Returns risk level (CLEAR/LOW/MEDIUM/HIGH/PROHIBITED), program-specific details, financial sanctions (SWIFT/correspondent banking), legal exposure up to $356,579/violation, and safe harbor guidance.",
        "operationId": "tradeSanctions",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Country to screen \u2014 e.g. Russia, Iran, Cuba, Myanmar, Belarus"
          },
          {
            "name": "entity",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Company or individual name to screen"
          },
          {
            "name": "hs_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "HS code for product-specific restrictions"
          },
          {
            "name": "transaction_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "export | import | investment | service"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sanctions risk assessment with program-by-program detail"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Screen before any transaction \u2014 pairs with RiskPulse /api/risk/sanctions; run first in any compliance workflow"
      }
    },
    "/api/trade/market": {
      "get": {
        "summary": "Market entry intelligence",
        "description": "Comprehensive market entry research for any product in any country. Returns annual import volumes and top source countries, regulatory requirements (certifications, labelling standards), competitive landscape (local producers vs foreign brands), distribution channels (retail/e-commerce/agents with margins), pricing intelligence, consumer profile, and market opportunity score 1\u201310.",
        "operationId": "tradeMarket",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "product",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Product to research \u2014 e.g. 'organic coffee', 'solar panels', 'medical devices'"
          },
          {
            "name": "hs_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "HS code as alternative to product"
          },
          {
            "name": "target_country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Target market country. Also accepts 'country' or 'to'"
          },
          {
            "name": "from_country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Your origin country for FTA context. Also accepts 'from'"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Market entry intelligence with opportunity score"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Market entry intelligence \u2014 pairs with RiskPulse /api/risk/country for political risk overlay; pairs with /api/trade/fta for duty advantages in target market"
      }
    },
    "/api/trade/compliance": {
      "get": {
        "summary": "Export compliance \u2014 EAR/ITAR/dual-use",
        "description": "Export control compliance assessment. Covers US EAR (ECCN classification, country chart, license exceptions STA/TMP/TSU/GOV, de minimis rule, foreign direct product rule, deemed export), US ITAR (USML categories I\u2013XXI), EU Dual-Use Regulation 2021/821, UK Export Control Order, China ECL, and Japan FEFTA. Returns GREEN/YELLOW/RED proceed status.",
        "operationId": "tradeCompliance",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "product",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Product to assess \u2014 e.g. 'encryption software', 'thermal imaging camera', 'carbon fiber'"
          },
          {
            "name": "hs_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "HS code as alternative to product"
          },
          {
            "name": "from_country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Exporting country (defaults to USA). Also accepts 'from'"
          },
          {
            "name": "to_country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Destination country. Also accepts 'to'"
          },
          {
            "name": "end_use",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Stated end-use \u2014 affects license requirement"
          },
          {
            "name": "end_user",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "End-user type or entity name"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Export compliance assessment with proceed status"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Documentation requirements by product and country; pairs with /api/trade/sanctions; regulatory compliance tool affiliates included"
      }
    },
    "/api/trade/freight-rates": {
      "get": {
        "summary": "Live freight rate intelligence by lane",
        "description": "Current container and air freight rates for any origin-destination lane with 90-day benchmark, rate trend (rising/falling/stable), transit times, top carriers, route disruption alerts (Red Sea, Panama Canal, port strikes), and full door-to-port cost estimate. Includes Flexport and Freightos affiliate links.",
        "operationId": "tradeFreightRates",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "origin",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Origin port city or country \u2014 e.g. Shanghai, Rotterdam, Los Angeles"
          },
          {
            "name": "destination",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Destination port city or country \u2014 e.g. Los Angeles, Hamburg, Sydney"
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ocean | air | both (default: ocean)"
          },
          {
            "name": "container_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "20ft | 40ft | 40hc | lcl (default: 40ft)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Freight rate intelligence with benchmark, carriers, and route status"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Freight rate benchmark \u2014 chain after /api/trade/tariff for full cost-of-import picture; pairs with /api/trade/landed for comprehensive landed cost; poll weekly for lane monitoring"
      }
    },
    "/api/trade/nearshore": {
      "get": {
        "summary": "Nearshoring and reshoring advisor",
        "description": "Ranked alternative manufacturing country recommendations when diversifying away from a current source country. Returns tariff comparison table (including Section 301 China tariffs), labor costs, USMCA Mexico spotlight, infrastructure scores, transition roadmap with cost estimates, and due diligence checklist. Highest automation value for procurement agents monitoring tariff changes.",
        "operationId": "tradeNearshore",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "current_country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Current manufacturing/sourcing country \u2014 e.g. China, India, Bangladesh"
          },
          {
            "name": "industry",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Industry or product sector \u2014 e.g. electronics, textiles, automotive parts"
          },
          {
            "name": "target_market",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Primary market you sell into (default: USA)"
          },
          {
            "name": "priority",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "cost | risk | speed | balanced (default: balanced)"
          },
          {
            "name": "hs_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "HS code for product-specific tariff comparison"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked nearshoring alternatives with tariff comparison and transition roadmap"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.2,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Strategic sourcing \u2014 chain after /api/trade/tariff to quantify duty savings per alternative; pairs with /api/trade/supplier-risk for compliance screening of candidate countries"
      }
    },
    "/api/trade/supplier-risk": {
      "get": {
        "summary": "Supplier country risk \u2014 UFLPA, ESG, and geopolitical",
        "description": "Comprehensive supply chain compliance risk assessment for any supplier country and sector. Covers UFLPA forced labor exposure (Xinjiang/CBP enforcement), ESG risks (labor standards, environment, governance), geopolitical risk, Modern Slavery Act obligations, and EU CS3D/CSRD supply chain disclosure requirements. Returns overall risk rating HIGH/ELEVATED/MODERATE/LOW with prioritised compliance checklist and alternative lower-risk sourcing countries.",
        "operationId": "tradeSupplierRisk",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Supplier or manufacturing country \u2014 e.g. China, Bangladesh, Vietnam, India"
          },
          {
            "name": "sector",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "textiles | electronics | food | chemicals | automotive | mining | any (default: any)"
          },
          {
            "name": "checks",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "forced_labor | esg | sanctions | geo_risk | all (default: all)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Supplier risk assessment with UFLPA status, ESG flags, and compliance checklist"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Supplier compliance screening \u2014 run before onboarding any new supplier country; pairs with /api/trade/sanctions for entity-level OFAC screening; pairs with /api/trade/nearshore to validate alternative countries"
      }
    },
    "/api/trade/incoterms": {
      "get": {
        "summary": "Incoterms 2020 decoder",
        "description": "Plain-English explanation of any of the 11 Incoterms 2020 rules (EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DPU, DDP). Returns buyer/seller obligation split, exact risk transfer point, cost split diagram, documentation checklist, insurance guidance, common mistakes, and comparison with the 3 most similar alternatives. Includes ICC 2020 guidance changes (e.g. FCA recommended over FOB for containers).",
        "operationId": "tradeIncoterms",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "term",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Incoterms 2020 rule \u2014 EXW | FCA | FAS | FOB | CFR | CIF | CPT | CIP | DAP | DPU | DDP"
          },
          {
            "name": "from_country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Seller/exporting country for corridor-specific guidance"
          },
          {
            "name": "to_country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Buyer/importing country"
          },
          {
            "name": "product",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Product type for transport-mode guidance"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Incoterms guide with obligation split, documentation checklist, and alternatives"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Contract terms decoder \u2014 use before drafting purchase orders or sales contracts; pairs with /api/trade/landed to understand cost impact of different terms; no chaining required, standalone reference"
      }
    },
    "/api/trade/news": {
      "get": {
        "summary": "Trade policy intelligence",
        "description": "Real-time global trade policy intelligence \u2014 tariff changes, Section 301 updates, new FTA signings, sanctions changes, WTO dispute settlements, supply chain disruptions (canal/port), EU Carbon Border Adjustment Mechanism (CBAM), shipping rate trends, and regional roundup covering Asia-Pacific, Europe, Americas, Middle East/Africa, and South Asia.",
        "operationId": "tradeNews",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "from_country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by sending country. Also accepts 'from'"
          },
          {
            "name": "to_country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by receiving country. Also accepts 'to'"
          },
          {
            "name": "topic",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "tariffs | fta | sanctions | wto | supply-chain | all"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trade policy intelligence with regional roundup and calendar ahead"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "scheduled",
        "x-agent-chaining": "Daily trade intelligence \u2014 highest automation value; poll via agent workflow; pairs with /api/trade/tariff when tariff-relevant news is detected"
      }
    }
  }
}