{
  "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-five.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://tradepulse-five.vercel.app"
    }
  ],
  "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.1,
        "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.15,
        "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.15,
        "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.2,
        "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/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.1,
        "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"
      }
    }
  }
}