Analyze ocean and multimodal freight rates, costs, customs, and shipping decisions.
Captured live from the server via tools/list.
get_spot_rate
Get the CURRENT ocean container spot rate for a lane (origin port → destination port) so you can answer 'should I book this shipment now or wait?'. Returns ONE normalized USD figure for the requested container size, a CONFIDENCE SCORE, and the MARKET DIRECTION (rising / falling / stable). Unlike calling a single freight API, this CROSS-VALIDATES multiple live indices — Drewry's World Container Index (WCI) and the Freightos Baltic Index (FBX), read server-side, plus your own SeaRates key if you supply one — and reconciles them into a single number with an agreement/confidence read, so you know how much to trust it. Port names are normalized via UN/LOCODE: 'Shanghai', 'CNSHA' and 'Shanghai, China' all resolve to the same lane. Container types: 20ft, 40ft, 40HC (defaults to 40ft, the size the indices quote). FREE. Use it for transpacific (Shanghai/Ningbo/Yantian → Los Angeles/Long Beach/New York), Asia→Europe (→ Rotterdam/Hamburg/Genoa) and the other major deep-sea container lanes. For the weeks-long trend and a book-now-or-wait recommendation, use get_lane_trend. Indicative market intelligence, not a carrier quote.
Parameters (3)
origin_portstringrequired
Origin port: a city name ('Shanghai', 'Ningbo', 'Rotterdam'), a UN/LOCODE ('CNSHA', 'NLRTM') or 'City, Country'.
dest_portstringrequired
Destination port: a city name ('Los Angeles', 'New York', 'Hamburg'), a UN/LOCODE ('USLAX'), or 'City, Country'.
container_typestring
Container size: '20ft', '40ft' or '40HC' (high-cube). Optional; defaults to '40ft' (the size the public indices quote). Synonyms like TEU/FEU/40HQ are accepted.
get_lane_trend
Forecast the ocean spot rate for a lane (origin → destination) and get a grounded BOOK-NOW-OR-WAIT call for a given ship date. Returns: a weeks-long cross-validated time series; a STATISTICAL FORECAST several weeks ahead (Holt-Winters / ETS triple exponential smoothing) with prediction intervals that widen with the horizon, plus naïve/drift/seasonal-naïve baselines and an honest BACKTEST (MAPE/RMSE/MASE) of the forecast's accuracy; the ocean-freight SEASONALITY CALENDAR overlaid on your ship date (Chinese New Year pre-rush & post-slump, Golden Week, transpacific/Asia peak season, likely GRIs and blank-sailing pressure); ANOMALY detection (is today's rate an out-of-pattern spike or collapse vs its seasonal norm?); and a concrete book-now/book-soon/wait/split/monitor recommendation with the drivers shown. All of this runs server-side on freight-pulse's OWN accumulating per-lane history plus a curated freight-seasonality model — your own agent can't reproduce the forecast or the calendar from a single snapshot. Same port normalization as get_spot_rate (UN/LOCODE). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Without one you'll get unlock instructions. Tip: call get_spot_rate (free) on a lane first — it seeds the history. Indicative market intelligence, not a carrier quote.
Parameters (5)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate.
dest_portstringrequired
Destination port (city name, UN/LOCODE, or 'City, Country').
weeksnumber
How many weeks of history to analyze (2–52, default 8). The window is capped by how much history we've accumulated for the lane.
ship_datestring
The intended shipment date (ISO 'YYYY-MM-DD' or any parseable date). The seasonality calendar (CNY, peak season, GRIs, blank sailings) is evaluated for THIS date. Optional; defaults to today.
forecast_weeksnumber
How many weeks ahead to forecast the rate (1–26, default 6). Prediction intervals widen with the horizon.
get_all_in_rate
Get the ALL-IN ocean freight cost for a lane — the TRUE landed cost of the move, not just the base spot rate. get_spot_rate returns the index-blended BASE; this returns base + every applicable carrier SURCHARGE & accessorial, which routinely inflates the real cost by +30-60%. Models the opaque thicket importers actually pay: Terminal Handling (origin+destination), BAF/LSS bunker fuel (modeled from a marine-fuel proxy and the corridor's burn), CAF currency adjustment, Peak-Season Surcharge (only inside the seasonal peak window), a damped GRI residual, port Congestion surcharge, ISPS security, Documentation/B-L fee, ECA emissions, War-Risk / Red-Sea–Suez DIVERSION surcharge (only on Suez-exposed Asia↔Europe / Asia↔US-East lanes, higher when Cape-of-Good-Hope diverted), Panama Canal low-water surcharge (only on Panama-routed lanes), optional Overweight, and expected Demurrage & Detention (tiered escalating per-day cost past your free days). The engine knows WHICH route each lane follows (transpacific vs Suez vs Panama vs transatlantic) and applies ONLY the surcharges that actually bite that lane and ship date — and lists the ones it deliberately EXCLUDED and why. Returns the full line-item breakdown, the all-in total, and a base-vs-all-in comparison. Every figure is tagged 'typical' (representative published value) or 'modeled' (estimate) — these are indicative modeling values, not a carrier tariff. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (8)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate.
dest_portstringrequired
Destination port (city name, UN/LOCODE, or 'City, Country').
container_typestring
Container size: '20ft', '40ft' or '40HC'. Optional; defaults to '40ft'.
ship_datestring
Intended shipment date (ISO 'YYYY-MM-DD'). Drives Peak-Season Surcharge & GRI applicability. Optional; defaults to today.
free_daysnumber
Carrier free days at destination before Demurrage & Detention accrues (default 5 when an estimated dwell is supplied).
estimated_days_at_portnumber
Total days you expect the box to sit at the destination terminal. If it exceeds free_days, the engine adds the expected (tiered, escalating) Demurrage & Detention. Omit to skip D&D.
overweightboolean
Flag an overweight load to include the overweight surcharge. Optional; default false.
fuel_proxynumber
Optional live VLSFO marine-fuel price ($/tonne) to drive the BAF model. Omit to use a recent representative level (~$600/t, tagged modeled).
get_landed_cost
Get the full LANDED COST (cost puesto en destino) of an import — the number the importer's margin actually depends on, not just the freight. Returns merchandise value (FOB) + all-in ocean freight (base + every surcharge) + insurance (CIF) + CUSTOMS DUTY + import VAT/consumption tax, as a line-item breakdown, plus the % of landed cost that is freight vs duties vs taxes. Includes an HS-CODE CLASSIFIER: pass a product description ('bluetooth earbuds', 'office chairs', 'cotton t-shirts') and it proposes the most likely HS6 heading with a confidence score (and 2-3 candidates when the text is ambiguous), or pass an explicit hs_code. Duty is modeled per destination bloc (US HTS, EU TARIC, UK Global Tariff, Canada, Australia, Japan) with the right MFN rate for the product family, then the ORIGIN-SENSITIVE trade remedies: US Section 301 applied ONLY to China-origin goods, Section 232 on steel/aluminium, an ANTIDUMPING/CVD flag on high-risk family×origin combos (it warns, it does not invent a rate), and FTA PREFERENCE (EVFTA, USMCA, CETA, EU-Japan EPA, RCEP, …) when origin↔destination share an agreement — subject to rules of origin. De-minimis is handled (US $800, EU €150, …): below threshold → no duty/tax. Import VAT is computed on the correct CIF+duty base (EU VAT by country; the US has no federal import VAT). Every figure is tagged typical/modeled; this is an INDICATIVE landed-cost estimate and HS-classification aid, NOT a binding customs ruling. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (12)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country'). The origin COUNTRY drives Section 301 / FTA / antidumping.
dest_portstringrequired
Destination port (city name, UN/LOCODE). The destination COUNTRY drives the duty bloc (US/EU/UK/CA/AU/JP) and import VAT.
productstring
Product description to classify, e.g. 'bluetooth earbuds', 'office chairs', 'cotton t-shirts', 'car tyres'. The classifier maps it to an HS6 heading. Provide this OR hs_code.
hs_codestring
Explicit HS code (6+ digits, e.g. '851830'). Overrides the text classifier. Provide this OR product.
fob_valuenumberrequired
Merchandise value (FOB) in USD — the goods value at origin. REQUIRED: duties & taxes are computed on this (via CIF).
container_typestring
Container size '20ft'/'40ft'/'40HC' for the freight leg. Optional; defaults to '40ft'.
ship_datestring
Intended ship date (ISO). Drives seasonal freight surcharges. Optional; defaults to today.
estimated_days_at_portnumber
Days the box will dwell at destination (adds Demurrage & Detention to the freight leg). Optional.
free_daysnumber
Carrier free days before D&D (default 5 if a dwell is given).
overweightboolean
Flag an overweight load (freight surcharge). Optional.
fuel_proxynumber
Optional VLSFO $/tonne for the BAF model. Optional.
insurance_rate_pctnumber
Marine insurance as a fraction of FOB+freight for the CIF model (default 0.005 = 0.5%). Optional.
compare_modes
Decide the TRANSPORT MODE for a shipment — OCEAN vs AIR vs SEA-AIR — on TOTAL economic cost, not just freight. The other tools price the ocean move; this one answers the importer's prior question: should these goods even go by sea? It costs all three modes and recommends the economically optimal one. Air is priced correctly on the IATA CHARGEABLE WEIGHT = max(actual gross weight, volumetric weight at 167 kg/m³) with an air fuel (FSC) + security (SSC) + handling stack — so bulky-but-light cargo is properly penalised (the lever a naïve 'air is just faster' estimate misses). Sea-air is modeled via the real hubs (Asia→Europe via Dubai/Jebel Ali, Asia→US-East via a US-West gateway): a cheap ocean leg to the hub + a short air final leg. The recommendation runs a real DECISION MODEL: cost of CAPITAL tied up in transit (value × annual rate × days), a p90 safety-stock HOLDING cost from each mode's variability, and — if you pass a deadline — an EXPECTED STOCKOUT cost from the probability the mode arrives late. So for high-value goods (or a tight deadline) air/sea-air can win even though the freight is far dearer, while for cheap goods ocean's much lower freight dominates. Returns the full ocean/air/sea-air table (freight, p50/p90 transit, capital, holding, stockout, total economic cost) + the recommended mode + the trade-off math. Every figure is modeled and tagged; air rates are volatile so they are honest BANDS, not a quote. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (17)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate.
dest_portstringrequired
Destination port (city name, UN/LOCODE, or 'City, Country').
container_typestring
Container size '20ft'/'40ft'/'40HC' for the ocean leg. Optional; defaults to '40ft'.
valuenumberrequired
Merchandise value in USD — REQUIRED. It is the capital tied up in transit and the basis of the whole mode trade-off.
weight_kgnumber
Shipment gross weight in kg. Provide this and/or volume_m3 — air is billed on the chargeable weight (max of actual and volumetric).
volume_m3number
Shipment volume in cubic metres. Drives the IATA volumetric weight (m³ × 167 kg). Provide this and/or weight_kg.
deadlinestring
Optional hard arrival deadline (ISO 'YYYY-MM-DD'). If given, the engine adds an expected-stockout cost from each mode's probability of arriving late.
stockout_penaltynumber
USD penalty if the goods miss the deadline (lost sale / line-down / expedite). Defaults to the goods' value when a deadline is given without one. Optional.
annual_capital_rate_pctnumber
Annual cost-of-capital as a fraction (e.g. 0.12 = 12%/yr) for goods in transit. Optional; default 0.12.
annual_holding_rate_pctnumber
Annual inventory holding/carrying rate as a fraction (e.g. 0.25 = 25%/yr) for the p90 safety-stock buffer. Optional; default 0.25.
bandstring
Air/sea-air rate band to use: 'low', 'typical' or 'high'. Optional; default 'typical'.
jet_fuel_proxynumber
Optional jet-fuel proxy to drive the air FSC. Omit for a modeled reference level.
ship_datestring
Intended ship date (ISO). Drives the ocean seasonal surcharges & transit window. Optional; defaults to today.
estimated_days_at_portnumber
Days the box dwells at destination (adds D&D to the ocean freight leg). Optional.
free_daysnumber
Carrier free days before D&D on the ocean leg (default 5 if a dwell is given). Optional.
overweightboolean
Flag an overweight ocean load (freight surcharge). Optional.
fuel_proxynumber
Optional VLSFO $/tonne for the ocean BAF model. Optional.
procurement_strategy
Decide the OCEAN SOURCING STRATEGY for a lane over a YEAR — lock an annual/quarterly CONTRACT rate, stay on SPOT, or SPLIT — and in what proportion. This is the procurement/CFO decision the other tools don't touch: not 'book this box now' but 'how do I source my whole volume?'. It costs THREE strategies over your expected annual volume: 100% SPOT, 100% CONTRACT, and the OPTIMAL MIX. The spot side is a real DISTRIBUTION, not a mean: it builds a 52-week expected-spot path from our own forecast (Holt-Winters), the corridor's spot volatility and the seasonal calendar, so a peak-season spike shows up as a fat P95 TAIL. It reads the MARKET REGIME (soft / balanced / tight / extreme) — because the contract↔spot relationship FLIPS with the cycle: in a soft market a contract sits ABOVE cheap spot (you'd overpay), in a tight market spot spikes above contract (the contract PROTECTS you). It computes the BREAK-EVEN contract rate (where 100% contract beats expected 100% spot), optimizes the contract/spot MIX on a mean-variance objective for your risk tolerance (contract the steady base, leave the peak on spot), models MQC shortfall penalties (the cost of over-committing in a light year) and the loading-PRIORITY a contract buys (less peak rollover), and quantifies the VALUE OF PROTECTION in dollars. Honest by design (regla 7): the contract↔spot relationship is regime-dependent and uncertain, so contract rates are MODELED BANDS anchored to the lane's mid-cycle — NOT a filed carrier tariff. Pass your own offered contract rate to score it against break-even. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (9)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate.
dest_portstringrequired
Destination port (city name, UN/LOCODE, or 'City, Country').
container_typestring
Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'.
annual_volumenumberrequired
Expected ANNUAL volume in containers of this type (TEU-equivalent ok) — REQUIRED. It is the basis of the contract-vs-spot trade-off.
risk_tolerancestring
'low' (pay to avoid the tail → favors contract), 'medium' (default), or 'high' (chase the mean → favors spot). Sets the mean-variance λ.
contract_rate_offerednumber
An actual contract rate you've been offered (USD/container). If given, it is scored against break-even instead of using the modeled band. Optional.
volume_cvnumber
Relative std-dev of YOUR annual volume (e.g. 0.2 = ±20%), driving MQC shortfall risk. Optional; default 0.20.
ship_datestring
Ship-date / contract-start anchor (ISO 'YYYY-MM-DD') for the seasonal & forecast overlay. Optional; defaults to today.
weeksnumber
Weeks of lane history to analyze for the forecast & mid-cycle reference (4–52, default 16). Optional.
get_port_intel
Get the PORT-CONGESTION & DISRUPTION intelligence for a lane — the OPERATIONAL state of the origin and destination ports and the live disruption events that move your transit time and your price. The rate tools tell you what a move costs; this tells you whether the PORTS can actually clear it on schedule. Returns a 0-100 CONGESTION INDEX for both the origin and destination ports on your ship date (structural berth/anchorage pressure + seasonal peak + active disruptions), the extra WAITING DAYS that congestion tacks onto your p90 transit, a 0-100 lane OPERATIONAL-RISK score with a building / steady / easing trend, and the upward RATE PRESSURE it implies. It surfaces the ACTIVE DISRUPTIONS that bite THIS lane on THIS date — the Red-Sea / Bab-el-Mandeb diversion around the Cape of Good Hope, the Panama Canal drought (draft & transit-slot restrictions on Panama-routed lanes), US West-Coast ILWU and US East/Gulf ILA dockworker labour cycles, the Asia typhoon season (Jun-Oct) and Atlantic hurricane season (Jun-Nov), and peak-season demand congestion — each with its time window, day-impact and rate pressure, and a flag for whether it's in its ACUTE window or only a recurring-season risk. A disruption OUTSIDE its window is not applied. Built on ~35 curated major-port congestion profiles (Shanghai, Ningbo, Yantian, Singapore, Busan, LA/Long Beach, NY/NJ, Savannah, Houston, Rotterdam, Hamburg, Antwerp, Felixstowe, Jebel Ali, …) and a dated catalogue of real disruption events — so a congestion wave that's BUILDING into your wait window can nudge you to anticipate and book. Every figure is a MODELED structural typical + a dated disruption overlay; it is INDICATIVE, NOT a live waiting-time feed for a specific port today (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (4)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate.
dest_portstringrequired
Destination port (city name, UN/LOCODE, or 'City, Country').
container_typestring
Container size '20ft'/'40ft'/'40HC' (informational for the lane label). Optional; defaults to '40ft'.
ship_datestring
Intended ship date (ISO 'YYYY-MM-DD'). The congestion peak windows and dated disruptions (Panama drought, ILA strike, typhoon/hurricane season, Red-Sea diversion) are evaluated for THIS date. Optional; defaults to today.
carrier_recommendation
Recommend WHICH CARRIER or ALLIANCE to sail with on a lane — the shipper's third decision after 'when to book' and 'which mode'. Carriers and their alliances differ enormously by corridor in coverage, schedule reliability and network breadth, so this ranks the ones that actually serve YOUR corridor and recommends 2-3 with the reasoning. Models the 2025-26 alliance realignment (NOT the pre-2025 map): GEMINI COOPERATION (Maersk + Hapag-Lloyd, live Feb 2025, a hub-and-spoke model explicitly targeting >90% on-time), OCEAN ALLIANCE (CMA CGM + COSCO + Evergreen + OOCL — the broadest direct-call network & highest frequency), PREMIER ALLIANCE (ONE + HMM + Yang Ming, the former THE Alliance minus Hapag, strong transpacific), and MSC operating standalone (the world's largest fleet, vast breadth, selective slot deals) — plus niche independents (ZIM's Asia→US-East express, Wan Hai intra-Asia). For each option it returns the EXPECTED ON-TIME PERFORMANCE on this lane (the corridor's market OTP refined by the carrier's own reliability band and how much it governs the string — so Gemini surfaces ~90% vs ~55% market average on Asia-Europe), the estimated SAILING FREQUENCY (sailings/week) and network breadth, a cost-positioning read, an overall fit SCORE, and the trade-off. The ranking FLIPS with your PRIORITY: 'reliability' floats Gemini up; 'frequency' or 'cost' floats Ocean Alliance / MSC up; a carrier with no network on the corridor is NOT recommended there. It also REFINES the lane OTP to the top pick so you can feed it into your p90 lead-time buffer. Every figure is a MODELED INDICATIVE BAND (capacity shares ~Alphaliner picture, reliability ~Sea-Intelligence rankings, corridor strengths) — NOT a carrier quote, a filed tariff or a weekly KPI (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (5)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate.
dest_portstringrequired
Destination port (city name, UN/LOCODE, or 'City, Country').
prioritystring
What the shipper optimizes for: 'reliability' (on-time, favours Gemini), 'frequency' (sailings/week, favours Ocean/MSC), 'cost' (cheapest-leaning), or 'balanced' (default). Synonyms accepted.
container_typestring
Container size '20ft'/'40ft'/'40HC' (informational for the lane label). Optional; defaults to '40ft'.
ship_datestring
Intended ship date (ISO 'YYYY-MM-DD'). Sets the corridor's market-baseline OTP (Cape diversion + seasonal blank-sailing pressure) the ranking is refined from. Optional; defaults to today.
carbon_footprint
Compute the CO2e CARBON FOOTPRINT of a shipment and the EU-ETS carbon COST for a lane — the Scope-3 (upstream transport) number importers increasingly must report, and the maritime carbon cost they now must pay on EU-touching lanes. The rate tools price the money; this prices the CARBON. Returns the WELL-TO-WAKE (WTW) kg CO2e of the move computed the GLEC Framework / ISO 14083 way — grams CO2e per TONNE-KILOMETRE × the routed distance × the cargo mass — with a per-LEG breakdown (drayage + main sea/air leg) and the well-to-tank vs tank-to-wake split that reporting frameworks ask for. Ocean intensity is taken by VESSEL CLASS (a ULCV moves a tonne-km for a fraction of a feeder's gCO2e/t-km — the economy-of-scale effect a naïve estimate misses); the engine picks the corridor's mainline class and lengthens the sea distance when a lane is Cape-of-Good-Hope diverted (more km → more CO2e). It puts the THREE modes side by side — OCEAN vs AIR vs SEA-AIR — on the same lane & cargo, surfacing that air emits roughly 10-50× the ocean footprint per tonne-km (the central ESG-vs-speed trade-off, linking to compare_modes), with sea-air as the carbon-smart middle. For lanes that touch an EU/EEA port it computes the EU-ETS maritime carbon COST: the voyage CO2 in scope (100% intra-EU, 50% for an EU↔non-EU voyage) × the year's phase-in (2024 40% → 2025 70% → 2026 100%) × the EUA market price — the surcharge carriers now pass to cargo. A lane that doesn't touch the EU (e.g. Asia→US) is correctly OUT of scope (no ETS). It also clarifies FuelEU Maritime and — honestly — that CBAM taxes the PRODUCT's embedded carbon, NOT the freight (the confusion importers keep making). Every emission factor and the EUA price are MODELED bands tagged typical/modeled (regla 7) — indicative footprinting & carbon-cost modeling, NOT an audited per-vessel carbon statement or a filed surcharge. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (9)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate. The origin COUNTRY drives EU-ETS scope.
dest_portstringrequired
Destination port (city name, UN/LOCODE, or 'City, Country'). The destination COUNTRY drives EU-ETS scope (touching the EU/EEA brings the voyage into scope).
container_typestring
Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'. Drives the modeled typical laden cargo mass when no weight is given.
ship_datestring
Intended ship date (ISO 'YYYY-MM-DD'). The YEAR drives the EU-ETS phase-in (2024 40%, 2025 70%, 2026+ 100%). Optional; defaults to today.
weight_kgnumber
Actual cargo gross weight in kg. Strongly recommended — emissions are per tonne-km, so the real mass sharpens the footprint and the EU-ETS cost. If omitted, a modeled typical laden mass for the container is used.
volume_m3number
Shipment volume in m³. Used for the AIR mode's IATA chargeable mass (max of actual and volumetric @167 kg/m³). Optional.
bandstring
Emission-factor band to report: 'low', 'typical' or 'high'. Optional; default 'typical' (factors are honest bands, not a single audited number).
eua_price_eurnumber
Override the EUA (EU Allowance) market price in €/tonne for the EU-ETS cost. Optional; defaults to a modeled typical (~€75) within a €55-100 band.
air_rolestring
Air emission factor role: 'freighter' (default, higher intensity) or 'belly' (passenger-jet hold, lower allocation). Optional.
equipment_availability
Check whether the shipper can even GET A CONTAINER on a lane — and what the equipment imbalance costs — BEFORE pricing the move. The rate tools assume a box exists; this answers the constraint that often binds first: in a deficit origin you can have a rate and a sailing and still not secure a box. Returns a 0-100 AVAILABILITY INDEX for the empty box at the origin and a SHORTAGE-RISK score, driven by the structural EQUIPMENT IMBALANCE of container trade: trade is directional, so empties PILE UP at net-importer ports (LA/Long Beach, Rotterdam, Hamburg) and run SHORT at net-exporter hubs (north/central China, Vietnam) — carriers must reposition empties back against the loaded headhaul. It models the balance per TYPE: 40HC (the deep-sea workhorse) is the tightest dry type in a crunch, 20DV is structurally easier to source (the classic alternative), and REEFER is a separate, far scarcer, plug-limited pool. It overlays the SEASONAL swing on the real lunar calendar: the acute PRE-CHINESE-NEW-YEAR crunch (every exporter loads before the factory shutdown — equipment, not space, becomes the binding constraint), the POST-CNY glut (the empties that surged out sit stranded at destinations while China demand collapses), Golden-Week front-loading, and peak-season tightening — evaluated for YOUR ship date. It prices the EQUIPMENT-IMBALANCE SURCHARGE (EIS) and reposition cost the deficit imposes, plus the soft +% it pushes onto the effective booked rate, and lists the reposition INCENTIVES (triangulation/street-turn, fast empty return) that relieve it. When the requested box is short it proposes ALTERNATIVES — split a scarce 40HC into 2×20DV, shift the ship window out of the crunch, triangulate an import empty, or book a mega-fleet carrier (Maersk/MSC/CMA CGM) whose deep own-box pool and local depots ease the SAME deficit (a thin niche line is more exposed). Pass a carrier to refine the numbers. The shortage risk also feeds the book-now timing — a worsening crunch means anticipate and lock equipment early. Everything is a MODELED structural + seasonal profile expressed as honest bands — NOT a live depot inventory; we never claim a specific box count is available at a depot today (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (7)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country'). The origin REGION's net export/import role drives the equipment deficit/surplus.
dest_portstringrequired
Destination port (city name, UN/LOCODE, or 'City, Country'). The destination is where empties pile up (the reposition-from side).
container_typestring
Container size '20ft'/'40ft'/'40HC' — maps to the 20DV / 40DV / 40HC equipment pool. Optional; defaults to '40ft'. Use 'reefer' for refrigerated.
reeferboolean
Set true for a REEFER (refrigerated) move — a separate, far scarcer, plug-limited pool than dry. Optional; default false.
ship_datestring
Intended ship date (ISO 'YYYY-MM-DD'). The seasonal equipment swing (pre-CNY crunch, post-CNY glut, Golden Week, peak tightening) is evaluated for THIS date. Optional; defaults to today.
carrierstring
Optional carrier to refine availability by its own-box fleet & depot depth (e.g. 'Maersk', 'MSC', 'CMA CGM', 'ZIM'). A mega line eases the crunch; a thin niche line is more exposed.
bandstring
EIS / reposition-cost band to report: 'low', 'typical' or 'high'. Optional; default 'typical'.
incoterm_responsibility
Explain the EXACT cost & risk split between the SELLER (exporter) and the BUYER (importer) for an Incoterms® 2020 rule on a lane — the decision an importer makes when they agree 'FOB Shanghai' vs 'DDP my-warehouse', which a thin agent routinely gets wrong. Returns the precise POINT at which risk of loss/damage transfers (EXW at the seller's works; FCA/CPT/CIP at the first-carrier hand-over; FAS alongside the ship; FOB/CFR/CIF once ON BOARD; DAP/DDP at destination ready; DPU once unloaded), who pays each step (export clearance, origin haulage, the main international freight, destination terminal handling, on-carriage, import clearance, and the destination DUTY + import VAT/tax), and whether the rule MANDATES cargo insurance and at what level (CIF mandates only ICC C minimum; CIP mandates ICC A all-risk). It flags the classic traps: FOB/CFR/CPT put the TRANSIT RISK on the buyer (CFR/CPT even though the seller pays the freight); DDP loads the seller with destination customs and import VAT; EXW puts export clearance on the buyer; and FOB on CONTAINERS is the wrong rule (the ICC recommends FCA for terminal hand-over) — with a container-appropriateness warning. Indicative summary of the ICC rules — NOT legal, contractual or customs advice (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (5)
origin_portstringrequired
Origin/load port (city, UN/LOCODE, or 'City, Country').
dest_portstringrequired
Destination/delivery port (city, UN/LOCODE, or 'City, Country').
incotermstringrequired
The Incoterms 2020 rule to analyse: one of EXW, FCA, FAS, FOB, CFR, CIF, CPT, CIP, DAP, DPU, DDP. REQUIRED.
container_typestring
Container size '20ft'/'40ft'/'40HC' (drives the container-appropriateness check). Optional; defaults to '40ft'.
Produce the CHECKLIST of trade documents a shipment of THESE goods to THIS destination commonly needs — the paperwork that, if missed, gets the box fined, held or the duty overpaid. Returns the always-on commercial set (commercial invoice, packing list, Bill of Lading or Sea Waybill), the GOODS-TRIGGERED specials (lithium-battery Dangerous-Goods declaration for electronics/batteries, Safety Data Sheet + DG for chemicals, ISPM-15 wood treatment / phytosanitary for furniture/wood, textile & origin declarations for apparel/footwear), the DESTINATION import-regime filings (US Importer Security Filing ISF 10+2 — filed ≥24h before loading, $5,000 penalty if late; EU Entry Summary Declaration ENS via ICS2; UK Safety & Security), and the Certificate of Origin (recommended, and REQUIRED in preferential form to claim a reduced FTA duty rate). Pass a product description (it's classified to an HS family to trigger the right specials) or an explicit hs_code; without it you still get the core + destination set. Pass an Incoterm to tag each document with WHO is responsible under it (e.g. under DDP the seller files the import-side ISF). Indicative common-case checklist — NOT a customs broker's binding filing list (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (6)
origin_portstringrequired
Origin port (city, UN/LOCODE, or 'City, Country'). The origin country drives the certificate-of-origin / FTA note.
dest_portstringrequired
Destination port (city, UN/LOCODE). The destination country drives which advance filing applies (US ISF, EU ENS, UK S&S).
productstring
Product description, e.g. 'bluetooth earbuds', 'office chairs', 'cotton t-shirts' — classified to trigger goods-specific docs (DG, ISPM-15, textile). Provide this OR hs_code.
hs_codestring
Explicit HS code (overrides the text classifier). Provide this OR product.
container_typestring
Container size '20ft'/'40ft'/'40HC' (informational). Optional; defaults to '40ft'.
incotermstring
Optional Incoterms 2020 rule to tag responsibilities (EXW…DDP).
dnd_strategy
Optimize the DEMURRAGE & DETENTION free-time strategy for a destination — beyond the simple D&D line: how many FREE DAYS should you negotiate, and what is the EXPECTED D&D cost of accepting fewer, given how long the box will actually DWELL at this (possibly congested) port? It reads the destination port's CONGESTION on your ship date and builds a DWELL DISTRIBUTION (mean + the right tail that a busy port fattens), then for a ladder of candidate free-day grants computes the PROBABILITY of breaching free time (incurring any D&D), the EXPECTED chargeable days, the EXPECTED D&D cost (on the destination region's tiered, escalating per-day schedule — US West-Coast steep, North-Europe gentler) and the p90 bad-case cost. It finds the marginal value of each extra free day and recommends a free-day TARGET — 'in this congested port the dwell tail is fat, so the default 4-5 free days carries $X expected D&D; negotiate 7+'. Demurrage (box sits FULL in the terminal) and detention (box held OUTSIDE past the empty-return grace) are modeled together as combined free time. Pass a carrier to refine the default grant, or your own mean dwell if you know your unpack speed. Modeled from industry-typical regional free days + a congestion-driven dwell distribution — NOT a carrier's filed free-time tariff (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (8)
origin_portstringrequired
Origin port (city, UN/LOCODE, or 'City, Country').
dest_portstringrequired
Destination port — its congestion drives the dwell distribution and the regional D&D schedule.
container_typestring
Container size '20ft'/'40ft'/'40HC' (drives the per-day D&D rate). Optional; defaults to '40ft'.
ship_datestring
Intended ship date (ISO 'YYYY-MM-DD'). The destination congestion (peak windows, disruptions) is evaluated for THIS date. Optional; defaults to today.
carrierstring
Optional carrier — refines the default free-day grant (mega lines often grant a touch more).
mean_dwell_daysnumber
Override the modeled mean dwell (days) with your own unpack/return speed. Optional.
min_free_daysnumber
Lowest free-day grant to evaluate (default 3).
max_free_daysnumber
Highest free-day grant to evaluate (default 10 or default+4).
insurance_recommendation
Recommend cost-effective MARINE CARGO INSURANCE for a shipment — the cover an importer needs but often under-buys. It prices the three Institute Cargo Clauses side by side: ICC (A) ALL-RISK (covers everything bar named exclusions — for valuable/fragile/theft-prone cargo), ICC (B) named-perils-broad (adds water-ingress but NOT theft), and ICC (C) MINIMUM (only major vessel casualties — no water, no theft) — showing what each COVERS and EXCLUDES. The premium = INSURED VALUE (CIF + 10% customary markup, the freight pulled server-side so the base is real) × the cargo's LOSS PROFILE (electronics/batteries load the rate; robust steel discounts it) × the MODE risk (air has a structurally lower loss rate than ocean — links to compare_modes) × the ROUTE risk (a Red-Sea/Cape-diverted lane spikes the separate WAR-RISK additional premium — links to the disruptions engine) × the deductible. It recommends the cost-effective cover level for your cargo and clarifies the Incoterms tie: CIF obliges the seller to buy only ICC (C) minimum, CIP obliges ICC (A) all-risk, and a FOB/CFR/CPT buyer gets NO seller insurance at all (must self-arrange). Modeled market-typical bands — NOT a broker's quote (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (10)
origin_portstringrequired
Origin port (city, UN/LOCODE, or 'City, Country'). The route (incl. Red-Sea diversion) drives the war-risk premium.
dest_portstringrequired
Destination port (city, UN/LOCODE, or 'City, Country').
cargo_valuenumberrequired
Merchandise value (USD) — REQUIRED. The insured value is CIF (cargo + freight) + 10%.
container_typestring
Container size '20ft'/'40ft'/'40HC' (for the freight leg). Optional; defaults to '40ft'.
productstring
Product description to classify the cargo loss profile (e.g. 'bluetooth earbuds', 'steel coils'). Optional but improves the rate.
hs_codestring
Explicit HS code (alternative to product). Optional.
modestring
Transport mode for the loss profile: 'ocean' (default), 'air' (lower loss rate) or 'sea-air'. Optional.
deductible_fractionnumber
Policy deductible as a fraction of insured value (0 = nil, 0.005 = 0.5% typical, 0.01, 0.02). A higher excess lowers the premium. Optional.
ship_datestring
Intended ship date (ISO). Optional; defaults to today.
markup_pctnumber
Insured-value markup over CIF (default 0.10 = the customary +10%). Optional.
ship_decision
The UNIFIED decision tool — integrates EVERY freight-pulse layer (rate/forecast, all-in cost, transit & reliability, mode-choice, procurement, port congestion, carrier/alliance, emissions, equipment availability, Incoterms, demurrage & detention, and cargo insurance) into ONE actionable answer for a CONCRETE shipment. This is the tool that makes freight-pulse insustituible: it doesn't just price one layer, it WEIGHS them all coherently. Give the lane + merchandise value (+ optional weight/volume, ship date, urgency, deadline, product, Incoterm, carrier) and it returns: the recommended MODE (urgency-aware — a critical deadline can override the economic optimum toward air/sea-air), the recommended CARRIER for the corridor, the book-now / book-soon / wait / monitor TIMING (the forecast call, overlaid with a building congestion/equipment crunch), the total COST PUESTO EN DESTINO (landed: goods + freight + duty + import tax, when a product is given), and the KEY RISKS with concrete MITIGATIONS (Red-Sea diversion, port congestion, equipment scarcity, D&D exposure, transit-risk insurance). Every component is computed by its own modeled engine and folded in transparently (the breakdown is shown). Indicative decision support — not a booking or a quote (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (14)
origin_portstringrequired
Origin port (city, UN/LOCODE, or 'City, Country').
dest_portstringrequired
Destination port (city, UN/LOCODE, or 'City, Country').
valuenumberrequired
Merchandise value (USD) — REQUIRED. Drives mode-choice (capital in transit), insurance and (with a product) landed cost.
container_typestring
Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'.
Shipment volume (m³) — drives the air volumetric weight. Optional.
productstring
Product description or HS context — enables the landed-cost (duty) component. Optional.
hs_codestring
Explicit HS code (alternative to product). Optional.
urgencystring
'relaxed', 'normal' (default), 'urgent' or 'critical'. A critical/urgent shipment shifts the recommendation toward speed (air/sea-air) and a reliability-led carrier.
deadlinestring
Hard arrival deadline (ISO 'YYYY-MM-DD') — adds an expected-stockout cost to the mode decision. Optional.
ship_datestring
Intended ship date (ISO). Drives seasonality, congestion and the book-now call. Optional; defaults to today.
incotermstring
Optional Incoterms 2020 rule (EXW…DDP) — sets who carries transit risk in the risk assessment.
Optional annual volume (containers) — informational for the decision context.
simulate_scenario
Run a WHAT-IF on a lane: recompute the COST and TIME impact of a structural change to the freight market, on top of freight-pulse's engines. Scenarios: 'red-sea-reopen' (Suez/Bab-el-Mandeb reopens and Asia-Europe / the Suez share of Asia-US-East services return from the Cape-of-Good-Hope diversion → shorter transit, war-risk & diversion surcharges fall — only material on Suez-exposed lanes); 'fuel-spike' (bunker VLSFO up X% → the BAF/bunker portion of the all-in rises; pass fuel_spike_pct); 'cny' (Chinese New Year front-loading: the pre-CNY rush spikes the spot rate and the equipment crunch and dips schedule reliability — material on China-origin lanes); 'tariff-change' (destination duty changes by X percentage points — e.g. a new Section-301 tranche or an FTA change — raising/lowering the landed cost while freight is UNCHANGED; pass tariff_delta_pp and value). It recomputes the affected engine outputs under the perturbed inputs it can thread (fuel proxy, ship date) and models the structural ones (the Red-Sea routing flag, a tariff delta) as explicit, transparent adjustments — never silently — and reports the baseline, the scenario and the deltas. A what-if is a MODELED counterfactual, not a prediction the event will occur (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Parameters (8)
origin_portstringrequired
Origin port (city, UN/LOCODE, or 'City, Country').
dest_portstringrequired
Destination port (city, UN/LOCODE, or 'City, Country').
scenariostringrequired
The what-if: 'red-sea-reopen', 'fuel-spike', 'cny' or 'tariff-change'. REQUIRED.
container_typestring
Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'.
ship_datestring
Intended ship date (ISO). Drives the CNY-year and the baseline all-in. Optional; defaults to today.
fuel_spike_pctnumber
For 'fuel-spike': percent increase in VLSFO bunker (e.g. 30 = +30%). Default 30.
tariff_delta_ppnumber
For 'tariff-change': change in duty in PERCENTAGE POINTS (e.g. 10 = +10pp, -5 = a cut). Default 10.
valuenumber
For 'tariff-change': merchandise value (USD) to size the duty/landed impact. Default 50000.
door_to_door
Get the TRUE DOOR-TO-DOOR cost and time of an import move, not the port-to-port figure importers usually quote. The ocean tools price PORT-TO-PORT; this layers the INLAND legs at BOTH ends onto the all-in ocean move: origin drayage (the short truck move factory/CY → load port), destination drayage (discharge port → DC), the US CHASSIS rental (a separate daily charge + a chassis-split fee that exists in the US but is bundled elsewhere), terminal GATE-congestion fees and turn-time days, and — when the cargo's real destination is INLAND — the interior haul with a RAIL-vs-TRUCK decision (US IPI intermodal to Chicago/Dallas/Memphis; the Rotterdam/Antwerp barge-rail hinterland to Duisburg/Basel/Milan), choosing the cheaper mode by distance (deadline-aware). Inland routinely adds 15-40% over the port-to-port cost and several days — both of which this returns folded into a door-to-door total and a door p50/p90 transit. Every inland figure is a modeled market-typical band (regla 7), not a trucker quote. PREMIUM: x402 (USDC on Base) or a prepaid key. Same UN/LOCODE port normalization as get_spot_rate.
Parameters (8)
origin_portstringrequired
Origin (load) port — city, UN/LOCODE, or 'City, Country'.
dest_portstringrequired
Destination (discharge) port — city, UN/LOCODE, or 'City, Country'.
container_typestring
Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'.
ship_datestring
Intended ship date (ISO). Drives ocean seasonality & transit. Optional; defaults to today.
bandstring
Inland cost band: 'low', 'typical' (default) or 'high'.
inland_destinationstring
Optional inland point the cargo really goes to (e.g. 'Chicago', 'Dallas', 'Duisburg', 'Milan', 'Basel') → adds the interior rail-vs-truck haul from the discharge port.
interior_modestring
Force the interior haul mode: 'rail' or 'truck'. Optional; default = cheaper of the two (deadline-aware).
urgentboolean
Hard deadline → biases the interior haul to truck for door-speed. Optional.
load_plan
Optimize how a product LOADS into a container — the stowage/cube-and-weight question every importer faces. Give the CARTON dimensions (cm) and gross weight (kg) and optionally a target quantity, and it computes: how many units fit BY VOLUME and BY WEIGHT and which constraint BINDS FIRST (the crux — dense cargo like tiles/stone tops out by WEIGHT at low cube, while light cargo like apparel/foam fills the CUBE with payload to spare); the utilization on BOTH axes (% volume AND % payload) so you see the wasted constraint; the 40HC-vs-2×20DV head-to-head for the cargo's density (two 20ft give ~2× the payload for ~the same cube — the right answer for heavy cargo, which a naïve volume-only divide gets wrong); an OVERWEIGHT warning when a box that's 'full' by cube would be ILLEGAL to truck because the destination ROAD/axle weight limit (e.g. US ~38-44k lb cargo on a standard chassis) is far below the ISO 26.7t container plate; and a recommended container MIX for a target quantity with the last box right-sized. Uses real interior dimensions and max payloads of 20DV/40DV/40HC (and reefers) plus per-country road weight caps. Indicative stowage PLANNING (practical-cube loadability, not 3D bin-packing), not a load-securing certification (regla 7). PREMIUM: x402 (USDC on Base) or a prepaid key.
Parameters (10)
length_cmnumberrequired
Carton length in cm. REQUIRED.
width_cmnumberrequired
Carton width in cm. REQUIRED.
height_cmnumberrequired
Carton height in cm. REQUIRED.
weight_kgnumberrequired
Gross weight per carton in kg. REQUIRED — it drives the weight-binding & overweight logic.
units_per_cartonnumber
Units (pieces) per carton, for unit-level totals. Optional; default 1.
reeferboolean
Evaluate reefer containers (20RF/40RF) instead of dry. Optional.
destination_countrystring
Destination ISO-2 country (e.g. 'US', 'DE') → enables the road-weight overweight check. Optional.
heavy_chassisboolean
Use the heavy/tri-axle road limit instead of the standard chassis cap. Optional.
target_cartonsnumber
Total cartons to ship → produces a container MIX. Optional.
target_unitsnumber
Total units to ship (converted via units_per_carton) → produces a container mix. Optional.
optimize_network
Optimize a shipper's ENTIRE annual lane PORTFOLIO at once — the question the single-lane tools can't answer. Give a SET of lanes with their annual volumes (an importer's network) and the engine optimizes globally: it procures each lane (contract / spot / optimal mix) and costs it, scores its schedule reliability and its CO2, then enforces NETWORK CONSTRAINTS — a total freight BUDGET (shifts soft-market lanes to locked contracts to fit), a minimum SERVICE level (won't cut a lane's reliability below the floor to save money), and an ESG CO2 ceiling (targets the carbon-heaviest lanes). It surfaces the TOP SAVING lanes (spot-vs-contract spread × volume), where to CONSOLIDATE volume under one alliance contract for a better tier, and the network coste/servicio/CO2 trade-off. Reuses the same modeled engines as the per-lane tools, so the portfolio answer is coherent with each lane. Indicative portfolio guidance, not a tendered rate or committed allocation (regla 7). PREMIUM: x402 (USDC on Base) or a prepaid key.
Parameters (7)
lanesarrayrequired
The lane portfolio. Each item: { origin_port, dest_port, annual_volume, container_type?, contract_rate_offered? }. REQUIRED, max 30.
ship_datestring
Reference ship date (ISO) for the seasonal/market context. Optional.
risk_tolerancestring
'low', 'medium' (default) or 'high' — the portfolio's appetite for spot exposure.
budgetnumber
Total annual freight budget (USD). If exceeded, the engine recommends shifting lanes toward locked contracts. Optional.
min_reliabilitynumber
Minimum acceptable schedule reliability (0-100) on any lane. Lanes below it are flagged; cost is not cut at the expense of service. Optional.
max_co2_tonnesnumber
Network CO2 ceiling (tonnes/yr). If exceeded, the engine targets the carbon-heaviest lanes. Optional.
consolidation_thresholdnumber
Volume (containers/yr) at which a lane earns a consolidated-contract tier. Optional; default 500.
payment_terms
Recommend the TRADE-FINANCE / PAYMENT TERMS for an import deal — the other half of the transaction the freight tools ignore. Give the lane (→ exporter country at origin, importer country at destination), the invoice value and the counterparty RELATIONSHIP, and it scores the payment-instrument spectrum — CASH-IN-ADVANCE / LETTER OF CREDIT (irrevocable, possibly CONFIRMED) / DOCUMENTARY COLLECTION D/P (documents against payment) / D/A (documents against acceptance) / OPEN ACCOUNT — on its RISK ALLOCATION (CIA = all risk on the buyer … open account = all risk on the seller) and arrange cost, then recommends one by the relationship × COUNTRY-RISK matrix: a new counterparty in a high-risk importer country → an irrevocable, confirmed LC; an established relationship in a safe country → cheaper open account; in between → documentary collection. It PRICES the LC commission for the deal (issuing rises with importer-country risk; confirmation — a bank in the seller's country adding its guarantee — adds a country-risk-scaled premium), and ties to Incoterms (CIF/CIP put insurance on the seller; an LC pairs with the FOB/CFR document set). Country-risk and LC-commission bands are MODELED market-typical figures; this is not financial, legal or banking advice (regla 7). PREMIUM: x402 (USDC on Base) or a prepaid key.
Parameters (9)
origin_portstringrequired
Origin port — its COUNTRY is taken as the exporter/seller country.
dest_portstringrequired
Destination port — its COUNTRY is taken as the importer/buyer country (drives the country-risk band).
invoice_valuenumberrequired
Commercial invoice value in USD. REQUIRED — finance costs are priced on it.
container_typestring
Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'.
relationshipstring
Counterparty relationship strength: 'new', 'developing' (default), 'established' or 'long-term'. The single biggest driver of the recommendation.
importer_countrystring
Override the importer ISO-2 country (else taken from the destination port).
exporter_countrystring
Override the exporter ISO-2 country (else taken from the origin port).
confirmedboolean
Force the LC pricing confirmed/unconfirmed. Optional; default = auto by importer-country risk.
incotermstring
Optional Incoterms 2020 rule (CIF, FOB, CIP…) for the document-set tie-in note.
special_cargo
Assess SPECIAL / NON-STANDARD CARGO for a lane — dangerous goods, refrigerated (reefer), and out-of-gauge — the moves a plain 'dry box' rate model can't price or clear. DANGEROUS GOODS (IMDG): give a hazard class ('3', '2.1', 'class 9') or a commodity that classifies to one (e.g. 'paint' → Class 3 flammable liquid, 'lithium batteries' → Class 9), and it returns the IMDG hazard family, the STOWAGE category (on/under deck), the SEGREGATION requirements against any other classes you list in the same booking, the documentation burden (the shipper's Dangerous Goods Declaration + class-specific papers), the per-class DG SURCHARGE, and — the decision that matters — whether that class is ACCEPTED on a standard liner service, needs prior approval, or is commonly REFUSED (Class 1 explosives, 6.2 infectious, 7 radioactive). REEFER: give a commodity ('frozen shrimp', 'bananas', 'pharma 2-8') and it returns the carrying SETPOINT + tolerance band, the regime (frozen/chilled/pharma/ambient-controlled), the cold-chain RISK (a pharma GDP breach can total the cargo; a banana below 12°C is chilling injury), and the reefer plug + pharma cold-chain + controlled-atmosphere PREMIUMS. OUT-OF-GAUGE (OOG): give over-dimensions (length/width/height in cm + weight) or request a flat-rack/open-top, and it picks the equipment, computes how many neighbouring SLOTS the protrusion sterilises, the OOG surcharge (equipment + slots + lashing/survey), and the BREAKBULK fallback when nothing fits a box. Every figure is MODELED planning data — NOT the IMDG Code, a carrier DG acceptance ruling, or a certified declaration (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key. Same UN/LOCODE port normalization as get_spot_rate.
Parameters (13)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country').
dest_portstringrequired
Destination port (city name, UN/LOCODE, or 'City, Country').
container_typestring
Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'.
dg_classstring
IMDG hazard class for a dangerous-goods check: '1','2.1','2.2','2.3','3','4.1','4.2','4.3','5.1','5.2','6.1','6.2','7','8','9' (also 'class 3' etc). Provide this OR a 'product' that classifies to a class.
other_classesarray
Other IMDG classes in the same booking / on board, to evaluate SEGREGATION against. Optional.
productstring
Free-text commodity. Drives the reefer lookup ('frozen shrimp', 'bananas', 'pharma 2-8') OR infers a DG class for some families ('lithium batteries' → 9, 'paint' → 3).
Over-dimension piece length in cm (triggers an OOG assessment). Optional.
width_cmnumber
Over-dimension piece width in cm. Optional.
height_cmnumber
Over-dimension piece height in cm. Optional.
weight_kgnumber
Piece weight in kg (drives flat-rack vs breakbulk). Optional.
reeferboolean
Force a reefer assessment even without a recognised product. Optional.
controlled_atmosphereboolean
Add the controlled-atmosphere (CA) reefer premium. Optional.
export_compliance
Check whether it is LEGAL to EXPORT a given product to a destination, and whether it needs an export LICENCE — the goods-side trade-compliance question (NOT denied-party / sanctioned-person screening, which is a separate regulated process this tool does NOT perform). Pass a product description (reusing the same HS classifier as get_landed_cost) or an HS code + the lane. It classifies the goods against the DUAL-USE control lists (a modeled ECCN / EU Annex-I dual-use category: advanced electronics, encryption/information-security, sensors & lasers, navigation, aerospace, nuclear, special materials, machine tools, controlled telecom), reads the DESTINATION's embargo / restriction level (comprehensive embargo, arms/dual-use embargo, licence-required, partial, or permissive — modeled at a high level), and runs the decision tree: a dual-use good to an embargoed destination is BLOCKED; a dual-use good to a licence-required destination needs a LICENCE; an ordinary good to a permissive destination is likely PERMITTED; and anything ambiguous returns REVIEW-REQUIRED. ⚠️ THIS IS THE MOST LEGALLY SENSITIVE TOOL. The classification, the dual-use flag and the embargo list are a MODELED, SIMPLIFIED, NON-AUTHORITATIVE planning aid — NOT legal advice, NOT an official commodity classification (e.g. BIS CCATS), and NOT a current sanctions determination. Lists change; control hinges on exact technical parameters and end-use. You MUST verify with your government licensing authority (US BIS / the relevant EU member-state authority) and qualified trade-compliance counsel before exporting (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key. Same UN/LOCODE port normalization as get_spot_rate.
Parameters (5)
origin_portstringrequired
Origin port — its COUNTRY is the exporter jurisdiction.
dest_portstringrequired
Destination port — its COUNTRY drives the embargo / licence-required check.
Product description to classify, e.g. 'thermal imaging camera', 'encryption appliance', 'cotton t-shirts'. Provide this OR hs_code.
hs_codestring
Explicit HS code (6+ digits). Provide this OR product.
fx_exposure
Quantify and hedge the CURRENCY RISK of your ocean-freight spend. Freight is quoted and largely invoiced in USD, but a non-US shipper PAYS in its home currency (EUR/GBP/JPY/CNY/…) — so a large, recurring USD freight bill is a foreign-exchange exposure: if the home currency weakens, the same freight costs more locally. Pass your home currency + your annual USD freight spend, and it returns: the exposure in your local currency at a modeled spot, the annualised VOLATILITY band of the pair, the 95% adverse FX move on the spend (in money), and a HEDGE-RATIO recommendation — what % of the exposure to cover with forwards — using a media-variance objective analogous to the procurement engine: higher volatility and a lower risk tolerance push the hedge up, but a variable spend caps it (you can't lock forwards for volume you might not ship), so it never blindly recommends 100%. It also sketches the forward-points carry (so the hedge isn't assumed free) and a laddered hedging plan. Honest (regla 7): MODELED reference analysis, NOT live market quotes and NOT financial / hedging advice — consult a treasury/FX professional. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (5)
local_currencystringrequired
Your home currency you pay freight in: EUR, GBP, JPY, CNY, INR, KRW, CAD, AUD, SGD, BRL, MXN (or a name). REQUIRED.
annual_freight_spend_usdnumberrequired
Your yearly USD ocean-freight bill (the USD exposure). REQUIRED.
horizon_monthsnumber
Hedging horizon in months (1-36, default 12). The exposure & risk are pro-rated to it.
risk_tolerancestring
'low' (hedge more), 'medium' (default) or 'high' (hedge less).
spend_cvnumber
Relative std-dev of your freight spend itself (e.g. 0.2 = ±20% volume). Caps the hedge ratio. Optional; default 0.15.
build_tender
Build the structure of a freight RFP / TENDER to put your ocean network out to bid. Pass your lanes with annual volumes and it returns, per lane, the volume + a modeled MARKET-RATE BAND (from our all-in rate engine, server-side) so you walk in knowing the credible price — the anchor that lets you spot a low-ball. Plus: the standard service requirements (fixed-day sailings, equipment commitment, reliability target, transparent surcharge formulas, free time), the AWARD CRITERIA weighted by your priority (cost / reliability / balanced), the BID SHEET columns carriers fill in, the RFP timeline (issue → Q&A → bids → evaluate → BAFO → award), and the modeled total annual spend. Pair with evaluate_bids to score the answers. Honest (regla 7): market bands are modeled, not filed tariffs. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (2)
lanesarrayrequired
The lanes to tender. Each: { origin_port, dest_port, annual_volume, container_type? }.
prioritystring
Award weighting: 'cost', 'reliability' or 'balanced' (default).
evaluate_bids
Evaluate carrier BIDS on a freight tender and pick the best award per lane. Pass your lanes (with annual volumes) and the bids each carrier submitted (carrier + all-in rate, optionally transit/sailings/free-days). For each lane it scores every bid on COST + RELIABILITY (the carrier's expected on-time performance from iter8 carrier matching) + COVERAGE (does it actually serve the corridor), DETECTS LOW-BALLS — a bid implausibly under the lane's modeled market band, the kind that gets rolled or surcharged back up and won't hold — by scoring them DOWN on credibility, and picks the best CREDIBLE award per lane. At the network level it shows the awarded annual cost vs the naive-cheapest cost (the cost of choosing credible over chasing a low-ball) and how many low-balls it flagged. Honest (regla 7): a modeled decision aid, not a procurement decision — verify rates & service commitments contractually. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Scoring weighting: 'cost', 'reliability' or 'balanced' (default).
customs_optimization
Find the DUTY-SAVING levers a customs broker knows but the importer usually does not — and quantify each against your shipment's REAL landed-cost duty. Give a product (or HS code) + the lane + the FOB value + your trade FLOW (import & sell / re-export / import-components-assemble-re-export / store), and it returns, ranked by saving: DUTY DRAWBACK (US 99% recovery of duties on goods you re-export — honestly flagging that Section 301 is NOT drawback-eligible, the big China carve-out); FOREIGN-TRADE ZONE / FREE ZONE (eliminate duty on the re-exported share, defer it on the rest, inverted-tariff election); BONDED / CUSTOMS WAREHOUSE (defer the duty cash-flow until withdrawal, or avoid it on re-export); EU/UK INWARD PROCESSING (suspend duty on inputs you process & re-export) and OUTWARD PROCESSING (duty only on value added abroad); FIRST-SALE valuation (US — value on the lower factory price, cutting MFN AND 301 proportionally); and TARIFF ENGINEERING (legally reclassify to a lower-duty HS line). Each lever shows the money saved, whether it's cash-back vs cash-flow-deferral vs a rate/base cut, and the catch — plus a clearance-workflow checklist. Reuses the real landed-cost engine so the duty base, 301/232/FTA stack and import VAT are genuine. ⚠️ Aduanas are complex: every figure is MODELED, INDICATIVE planning intelligence, NOT customs/legal/tax advice — confirm eligibility and obtain binding rulings with a licensed broker (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key. Same UN/LOCODE port normalization as get_spot_rate.
Parameters (7)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country').
dest_portstringrequired
Destination port — its country sets the customs bloc & regimes.
Product description to classify (e.g. 'bluetooth earbuds'). Provide this OR hs_code.
hs_codestring
Explicit HS code (6+ digits). Provide this OR product.
fob_valuenumberrequired
Merchandise value (FOB) in USD. REQUIRED — it's the duty base.
flowstring
The goods flow: 'import-consume' (sell domestically, default), 'import-reexport', 'import-assemble' (components→assemble→re-export), or 'import-store'. Free text accepted.
sourcing_analysis
The strategic CHINA+1 / NEARSHORING decision, quantified. Give the SAME product (or HS code) + a destination market + the China-equivalent FOB cost, and it compares making it in China vs Vietnam / India / Mexico / Turkey (and Thailand / Indonesia / Malaysia) on the three axes that actually decide it: TOTAL LANDED COST per origin — manufactured cost (relative labour/productivity index) + the real freight from each origin's export gateway + the real DUTY, so Section 301 penalises China→US, USMCA makes Mexico→US duty-free, and EVFTA makes Vietnam→EU duty-free (all through the genuine duty tables, not a fudge); LEAD TIME — the real ocean transit plus each origin's structural adder (Mexico/Turkey nearshore shortens the chain dramatically); and RISK — a geopolitical/concentration score, with a penalty that marks DOWN a China-only answer for single-country dependence (the whole point of China+1). It ranks the origins on a weightable blend (cost / lead-time / risk priority), names the recommended origin, and proposes a de-risking dual-source MIX. The highest-value strategic question in global sourcing right now. Honest (regla 7): cost indices, risk scores and lead adders are MODELED, product-specific and directional — frame the trade-off, then get factory quotes + a rules-of-origin check. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (7)
productstringrequired
Product to source, e.g. 'cotton t-shirts', 'lithium batteries'. Provide this OR hs_code.
hs_codestring
Explicit HS code. Provide this OR product.
dest_portstringrequired
Destination market port (its country drives the duty/FTA treatment). REQUIRED.
fob_valuenumberrequired
The China-equivalent manufactured (FOB) cost in USD — other origins are scaled by their cost index. REQUIRED.
Candidate origin countries (ISO2 or name): CN, VN, IN, MX, TR, TH, ID, MY. Optional; default = CN, VN, IN, MX, TR.
prioritystring
Weighting: 'cost', 'lead-time'/'speed', 'risk'/'resilience', or 'balanced' (default).
market_report
Compose freight-pulse's whole engine stack into ONE executive market-intelligence report for a lane — the committee-ready brief a head of logistics presents. Give the lane (and optionally a product + merchandise value to deepen it) and it returns a structured, sectioned report: 1) MARKET STATE & OUTLOOK — today's cross-validated spot + direction, the Holt-Winters forecast with intervals, the seasonality calendar overlaid on your ship date (CNY / Golden Week / peak / GRIs / blank sailings), and an anomaly read; 2) COST — all-in freight and, with product+value, the full landed cost (duty / 301 / FTA / import VAT); 3) TRANSIT, RELIABILITY & PORT CONGESTION — operational risk, added delay, active disruptions; 4) RECOMMENDATIONS — the unified mode + carrier + book-now/wait timing; 5) RISKS & MITIGATIONS; 6) ESG — ocean CO2e and EU-ETS carbon cost; plus an EXECUTIVE SUMMARY, a HEADLINE call, and a Monday-morning ACTION LIST. Every section is sourced from a real modeled engine and tagged; the report names which engines contributed and which weren't available for the lane. Honest (regla 7): indicative decision support, not a quote/booking/legal advice. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (9)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country').
Register a standing WATCH on a lane so freight-pulse alerts you when something changes — the feature that makes it a recurring daily tool, not a one-shot lookup. Give a lane + one or more THRESHOLDS and it persists the watch SERVER-SIDE (in our own store, per your key): 'spot-below' / 'spot-above' a USD level (buying window / cost ceiling), 'reliability-below' a score (rollover/delay risk), 'disruption' (any active disruption appears on the corridor/ports), 'book-now' (the forecast/timing engine flips to a book-now window), or 'forecast-rising' / 'forecast-falling' beyond a % move (act early / wait). It returns the watch id and the registered thresholds. Pair it with check_watches, which your agent polls (e.g. daily) to get back only the alerts that fired. Honest (regla 7): evaluated against modeled engine outputs — an alert is a signal to look, not a booking trigger. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Conditions to fire on. Each: { metric, value? }. metric ∈ spot-below | spot-above | reliability-below | disruption | book-now | forecast-rising | forecast-falling. value: USD for spot-*, 0-100 for reliability-below, % for forecast-*. e.g. [{ metric:'spot-below', value:2800 }, { metric:'disruption' }].
labelstring
Optional name for the watch.
check_watches
Evaluate the lane watches you registered with create_watch against the LIVE modeled market and return the alerts that FIRED. For each watch it gathers the current cross-validated spot + direction, the modeled lane reliability, any active disruptions, and (when a watch needs it) the forecast/timing book call + expected move, then checks every threshold and reports which ones tripped — with the observed value, the reason and a severity. Pass a watch_id to check just one, or omit it to evaluate them all. This is the daily poll that turns freight-pulse into a standing watchtower on your network. Honest (regla 7): modeled signals, verify before acting. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (1)
watch_idstring
Evaluate only this watch id. Optional — omit to evaluate all your watches.
qualify_fta_origin
Does your product actually QUALIFY for the FTA preference? The expensive detail iter14's sourcing/landed-cost silently assumes away: the USMCA / EVFTA / CETA / RCEP / KORUS preferential (usually 0%) duty applies ONLY if the good MEETS the agreement's RULE OF ORIGIN — and a huge share of would-be-preferential imports FAIL it (Chinese fabric cut in Vietnam misses EVFTA's yarn-forward rule; a Mexican assembly that's 60% imported misses USMCA's RVC). Give the product (or HS), the country of MANUFACTURE, the destination market, and the bill of MATERIALS (each input's value + origin + optional HS), and it computes against the resolved FTA's product rule: REGIONAL VALUE CONTENT (both transaction-value and net-cost methods vs the threshold), TARIFF SHIFT / change in tariff classification (CC chapter / CTH heading / CTSH subheading), DE-MINIMIS tolerance, and agreement-specific rules (USMCA autos 75% RVC + steel/aluminium; EVFTA apparel yarn-forward). It returns the VERDICT — QUALIFIES or NOT, WHY, exactly how many RVC points (and how much $) you're short, and the concrete paths to qualify. Links to iter4 (HS) and iter14 (sourcing/duty). ⚠️ Rules of origin are among the most complex parts of trade law — MODELED, INDICATIVE qualification aid, NOT a legal origin determination; the agreement's PSR annex + a licensed broker govern the binding answer, and a wrong preference claim carries duty + penalty exposure (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (7)
productstring
Product description to classify (e.g. 'cotton t-shirt'). Provide this OR hs_code.
hs_codestring
Explicit HS code (6+ digits) of the finished good. Provide this OR product.
manufacture_countrystringrequired
Country where the finished good is MADE (ISO2 like 'VN' or a name). REQUIRED.
destinationstringrequired
Destination market — country (ISO2/name) or a port. Its bloc sets the FTA. REQUIRED.
transaction_valuenumberrequired
FOB value of the FINISHED good in USD (the RVC denominator). REQUIRED.
materialsarrayrequired
Bill of materials: each { description, value (USD), origin (ISO2/name), hs_code? }. REQUIRED.
net_cost_fractionnumber
Net cost as a fraction of transaction value for the net-cost RVC method (default 0.85). Optional.
check_lc_documents
Will your letter-of-credit documents GET PAID? Banks reject roughly 60-70% of first-presentation documentary-credit submissions over DOCUMENTARY DISCREPANCIES. Give the fields of the credit + the presented documents (commercial invoice, bill of lading, insurance, packing list) and it applies the UCP 600 rules a trade-finance checker uses, returning the DISCREPANCIES that would make an examining bank reject the presentation — each tied to its UCP article with a remedy: invoice amount over the credit (art. 18/30 tolerances), currency mismatch (art. 18a), goods description not CORRESPONDING to the credit (art. 18c), data conflict across documents (art. 14), late shipment vs the latest-shipment date, STALE presentation (>21 days, art. 14c) or after expiry, port-of-loading/discharge mismatch on the B/L (art. 20), a non-clean B/L (art. 27), and insurance <110% of CIF / wrong currency / dated after shipment (art. 28). It reports clean-vs-rejected, the severity mix, what it checked and what it couldn't. Links to iter12 trade finance. ⚠️ The examining bank determines compliance under UCP 600 + ISBP 821 document-by-document; many discrepancies are judgement calls or waivable — MODELED pre-check, NOT a bank determination or legal advice (regla 7). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Credit incoterm (CIF/CIP trigger the insurance check).
insuranceRequiredboolean
Does the credit require an insurance document?
invoiceAmountnumber
Commercial invoice amount.
invoiceCurrencystring
Invoice currency.
invoiceGoodsDescriptionstring
Goods description on the invoice.
invoiceBeneficiarystring
Who issued the invoice.
blPortOfLoadingstring
Port of loading on the B/L.
blPortOfDischargestring
Port of discharge on the B/L.
shipmentDatestring
On-board / shipment date on the B/L (YYYY-MM-DD).
presentationDatestring
Date documents are presented to the bank (YYYY-MM-DD).
blCleanboolean
Is the B/L clean (no defect clause)?
insuredAmountnumber
Insured amount on the insurance document.
insuredCurrencystring
Insurance currency.
insuranceDatestring
Insurance document date (YYYY-MM-DD).
packingListGoodsDescriptionstring
Goods description on the packing list.
record_performance
Log a shipment's REAL outcome into your private supplier/carrier/lane SCORECARD — the tool that makes freight-pulse RECURRING (you feed it, it accumulates a history no single source hands you). Give the SUBJECT (a carrier like 'Maersk', a supplier, or a lane) and the outcome — promised vs actual transit days, on-time, damage, documentary discrepancy, rollover — and it appends the event to your log, PERSISTED SERVER-SIDE per your key, then returns the subject's running KPIs (OTP %, reliability score, damage/discrepancy/roll rates). Pair with get_scorecard to rank and trend your network over time. Links to iter8 (structural carrier intel) — this is the EMPIRICAL counterpart. Honest (regla 7): it's YOUR own log — KPIs reflect only what you record, small samples flagged. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (10)
subjectstringrequired
Carrier / supplier / lane name to record against. REQUIRED.
subject_typestring
'carrier' (default), 'supplier' or 'lane'.
lanestring
Lane label for context (e.g. 'Shanghai → Los Angeles'). Optional.
promised_daysnumber
Promised transit/delivery in days.
actual_daysnumber
Actual transit/delivery in days.
on_timeboolean
Explicit on-time flag (else derived from promised+actual).
damagedboolean
Were goods damaged?
discrepancyboolean
Was there a documentary discrepancy?
rolledboolean
Was the container rolled / shut out?
notestring
Free-text note. Optional.
get_scorecard
Read your accumulating supplier/carrier/lane SCORECARD — the KPIs you've fed with record_performance. Returns, per subject, on-time %, average delay, damage/discrepancy/rollover rates, a 0-100 reliability score and an improving/declining/stable TREND, ranked best-OTP-first, with the best & worst performer. Omit 'subject' for the whole network or pass one to drill in. The standing performance history that turns freight-pulse into a recurring decision tool (who do I award next year's volume to?). Honest (regla 7): your own empirical log, small samples flagged. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (2)
subjectstring
Drill into one carrier/supplier/lane. Optional — omit for the whole scorecard.
subject_typestring
'carrier' (default), 'supplier' or 'lane' — disambiguates the subject.
lane_risk_index
How FRAGILE is this route? The 0-100 lane-risk score a supply-chain director needs for their risk map. Give the lane and it COMPOSES the risk dimensions every other freight-pulse engine already models: CHOKEPOINT criticality (Suez / Red-Sea / Bab-el-Mandeb / Panama / Malacca, reusing the routing engine), GEOPOLITICAL risk per origin/destination/transit country (modeled bands), CONCENTRATION (single-port & single-carrier dependence), LABOUR risk (active strikes), CLIMATE risk (typhoon/hurricane/drought windows), CONGESTION (port-intel operational risk) and EQUIPMENT risk (box imbalance). It returns the composite score + the per-driver breakdown (which factor dominates) + ranked MITIGATIONS (alternate routings, add a second carrier/port, pre-position inventory, nearshore a second source). Honest (regla 7): MODELED, indicative — geopolitical risk is judgemental and time-varying; not a live threat feed or insurance-grade rating. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (7)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country').
A transit-country ISO2 to fold into geopolitical risk (e.g. 'EG' for Suez). Optional.
carrier_countnumber
How many distinct carriers you use on this lane (concentration). Default 1.
port_countnumber
How many distinct origin ports you use for this flow. Default 1.
inventory_optimization
Size the INVENTORY a freight decision forces you to hold. The freight choice (mode, reliability, transit time) DETERMINES your safety stock — this computes it. Give the lane + your annual demand (units) + unit value, and it returns, per mode (ocean baseline vs a faster/more-reliable air option): the SAFETY STOCK = z(service level) × σ of lead-time-demand (σ_LTD = sqrt(L·σ_demand² + demand²·σ_lead²), reusing the lane's modeled transit time AND its variability from the transit engine), the REORDER POINT, the Wilson EOQ, and the TOTAL inventory cost (ordering + cycle holding + safety-stock holding). It proves THE trade-off: a faster, more reliable mode shrinks the lead time and its variability → a SMALLER safety stock → released working capital + lower holding — so the 'expensive' freight can pay for itself in less immobilised inventory. Honest (regla 7): textbook OR (normal-approx safety stock, Wilson EOQ) with indicative default cost parameters you should override. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (13)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country').
Annual demand in UNITS. REQUIRED — inventory policy is sized off it.
unit_value_usdnumberrequired
Per-unit value (USD). REQUIRED — drives holding cost and immobilised capital.
demand_cvnumber
Demand coefficient of variation (σ_demand/mean). Optional; default 0.30.
service_levelnumber
Target cycle service level (in-stock probability, e.g. 0.95). Optional; default 0.95.
annual_holding_rate_pctnumber
Annual holding cost as a fraction of unit value (e.g. 0.25). Optional; default 0.25.
ordering_cost_usdnumber
Fixed cost per purchase order (USD). Optional; default 250.
units_per_containernumber
Units per ocean container (for the annual freight trade-off). Optional.
air_weight_kgnumber
Air shipment weight per consignment (kg) to price the air freight side of the trade-off. Optional.
air_volume_m3number
Air shipment volume per consignment (m³). Optional.
ship_datestring
Ship date (YYYY-MM-DD). Optional; default today.
total_cost_ownership
The CFO / supply-chain-director cumbre tool: ONE comparable number per strategy that ties the WHOLE chain together. Give a product + destination + per-unit baseline FOB + annual demand, and it composes, PER STRATEGY (origin × mode): PRODUCT cost (origin cost index), all-in FREIGHT (door-to-door), DUTY/landed (Section 301 / FTA preference), INVENTORY cost (safety stock + cycle holding driven by the lead time & its variability), CAPITAL-IN-TRANSIT (pipeline value × cost of capital), and a RISK premium (lane-risk score × inventory value). It ranks the strategies by TOTAL TCO and shows WHY the ranking flips: nearshore (Mexico) can BEAT China on TCO even with a pricier product (no Section 301, shorter lead → less inventory+capital, lower risk); AIR can win for HIGH-VALUE goods (the capital+inventory saving dwarfs the freight premium); and the ranking shifts with volume and unit value. This is the tool that ties the entire freight-pulse stack into one decision. Honest (regla 7): composes the indicative outputs of the sourcing/landed/transit/inventory/lane-risk engines; not an audited cost or a binding tariff classification. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (17)
productstringrequired
Product text ('bluetooth earbuds') or an HS code. REQUIRED.
hs_codestring
Explicit HS code (alternative to product).
dest_portstringrequired
Destination port. REQUIRED.
fob_valuenumberrequired
Per-unit baseline FOB (the China-equivalent manufactured cost) in USD. REQUIRED — other origins scale from it.
Candidate origin ISO2 codes (CN, VN, IN, MX, TR, TH, ID, MY). Optional; default the China+1 set.
include_airboolean
Also evaluate AIR per origin. Optional; default true.
units_per_containernumber
Units per container. Optional; default a value-density proxy.
air_weight_kgnumber
Air weight per container-equivalent (kg) to price air. Optional.
demand_cvnumber
Demand CV. Optional; default 0.30.
service_levelnumber
Service level. Optional; default 0.95.
annual_holding_rate_pctnumber
Holding rate. Optional; default 0.25.
annual_capital_rate_pctnumber
Cost of capital. Optional; default 0.12.
ordering_cost_usdnumber
Ordering cost per PO. Optional; default 250.
risk_cost_factornumber
Fraction of avg inventory value charged as expected-disruption cost (scaled by lane-risk/100). Optional; default 0.5.
ship_datestring
Ship date (YYYY-MM-DD). Optional.
contingency_plan
'My route just broke — what do I do AHEAD of the next sailing?' Give a lane and it detects the ACTIVE disruption (Red-Sea/Bab-el-Mandeb, Panama Canal drought, port labour strike, typhoon/hurricane, peak congestion — reusing the disruption catalogue) and generates an ACTIONABLE response playbook: alternate ROUTING (Cape of Good Hope), MODAL-SHIFT (air/sea-air the urgent slice), PORT-SWAP (divert to the unaffected coast/gateway), PRE-POSITION (build buffer ahead of the window), RE-PRIORITISE — each PRICED against the lane's real freight & lead time: the modeled cost (USD) and time (days) of plan B versus HOLDING. It ranks the plays by your urgency (cost-first vs time-first) and recommends one. Pass disruption_type to model a specific what-if even if it isn't currently active. Honest (regla 7): MODELED, indicative response options & deltas — not a guarantee of alternate-routing space; validate availability with your carrier/forwarder. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (6)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country').
Ship date (YYYY-MM-DD) — selects which seasonal/dated disruptions are active. Optional; default today.
disruption_typestring
Force a specific disruption: 'red-sea' / 'panama' / 'labor' / 'weather' / 'peak' (else the most severe active one is chosen; an inactive type is modeled as a what-if). Optional.
A PROGRAMME to cut the carbon of your transport network to a target. Give a lane (or an annual network footprint in tonnes CO2e) and a reduction TARGET %, and it walks the abatement levers cheapest-$/tCO2e first on a marginal-abatement-cost curve: MODAL SHIFT (air→ocean / →sea-air — the biggest lever, often NEGATIVE cost because it also saves freight), CONSOLIDATION, EFFICIENT CARRIER, SAF book-and-claim (sustainable aviation fuel), ALTERNATIVE MARINE FUEL (green-methanol book-and-claim), and — last — VERIFIED OFFSETS. It returns the ordered roadmap with each lever's tonnes abated, cost and running marginal cost, the total programme cost and blended $/tCO2e, an honest REDUCTION-vs-OFFSET split (insetting > offsetting), and the EU-ETS € SAVING from the lower in-scope footprint. Honest (regla 7): MODELED, indicative abatement costs/ceilings (SAF & offset prices are volatile and quality-dependent); offsets are flagged compensation, NOT reduction, and a target beyond what reduction levers reach is clearly labelled. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (9)
origin_portstring
Origin port (for a lane-based baseline). Optional if baseline_co2e_tonnes is given.
dest_portstring
Destination port. Optional if baseline_co2e_tonnes is given.
Reduction target as a fraction (0.30) or percent (30). Optional; default 0.30.
baseline_co2e_tonnesnumber
Supply an annual NETWORK footprint (tonnes CO2e) instead of deriving from a lane. Optional.
weight_kgnumber
Cargo weight for the lane emissions baseline (kg). Optional.
allowed_leversarray
Restrict to specific lever ids (modal-shift-air-to-ocean, consolidation, saf-book-and-claim, alt-marine-fuel, verified-offsets, …). Optional; default all.
Ship date (YYYY-MM-DD) — drives the EU-ETS phase-in year. Optional.
reverse_logistics
The reverse flow almost nobody models: goods have to come BACK from the destination market — what do you do with them? Give the lane + how many units + their value + condition (defective / RMA / over-stock / surplus), and it prices the three dispositions per unit and picks the best NET RECOVERY: RETURN (reverse freight ≈1.6× forward + recondition/handling, reclaiming the re-export DUTY DRAWBACK already paid — 99% recovery, but Section-301 duty is carved out), DESTROY in destination (cheap, zero product value, still drawback-eligible) or LIQUIDATE into the destination secondary market (some cash back, no reverse freight, no drawback). It proves the rule: high unit value + recoverable duty + cheap reverse freight → RETURN; reverse freight per unit above the recoverable value → never ship it home (destroy for the drawback, or liquidate locally — whichever nets more). Flags the storage bleed that forces the decision window. Honest (regla 7): INDICATIVE recovery fractions, freight multipliers & handling defaults you should override; drawback eligibility and the §301 carve-out are real but filing-specific — NOT customs/legal advice. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (14)
origin_portstringrequired
Origin port (where the goods would RETURN to). City name, UN/LOCODE, or 'City, Country'.
Duty already paid per unit on the original import (USD) — drives the drawback reclaim. Optional; default 0.
section301_per_unit_usdnumber
Of that duty, the Section-301 slice per unit (USD) — NOT drawback-eligible. Optional; default 0.
drawback_eligibleboolean
Is re-export/destruction drawback available to you? Optional; default true.
recondition_hubstring
Return to a reconditioning HUB instead of origin (shorter, cheaper return leg). Optional.
forward_freight_per_unit_usdnumber
Override the forward per-unit freight (USD) instead of deriving it from the lane. Optional.
units_per_containernumber
Units per container — to spread container freight over units. Optional.
pending_daysnumber
Days the goods sit pending a decision (storage bleed). Optional; default 0.
ship_datestring
Ship date (YYYY-MM-DD) for the freight anchor. Optional.
pallet_plan
Optimize PALLETIZATION across the full chain product → case → pallet → container (distinct from the box→container load optimizer). Give a case (carton) size & weight, a pallet standard (EUR 1200×800, EUR2 1200×1000, US/GMA 48×40, AU 1165) and a container, and it computes: cases per pallet (best layer pattern from both case orientations + pinwheel × layers, capped by the pallet weight AND the container height), pallets per container (floor footprint × single-vs-double-stack under the ceiling, capped by payload), and the % container CUBE UTILISATION. It then contrasts PALLETIZED vs FLOOR-LOADED: floor-loading reclaims the ~12–18% cube a pallet wastes (deck + top-air + footprint rounding) but is ~4× slower to handle and bruises more cargo — the real trade-off, quantified in extra cases and cube points. Pass a total case count for the pallets/containers your shipment needs. Honest (regla 7): INDICATIVE rectangular-packing geometry capped by weight/height — not a stow guarantee; real patterns depend on crush strength, interlocking and overhang. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (9)
case_length_mmnumber
Case (carton) length in mm. Optional; default 400.
Allow double-stacking pallets if height permits. Optional; default true.
total_casesnumber
Total shipment case count → pallets & containers needed. Optional.
customs_valuation
Compute the correct DUTIABLE BASE on which the duty is charged — it is NOT just the invoice. Under the WTO Customs Valuation Agreement, give the destination country + invoice price + Incoterm and it builds the TRANSACTION VALUE: it normalises the price to an FOB-origin base (stripping freight/insurance/destination/duty a CIF or DDP price already carries), then ADDS the statutory additions importers forget — ASSISTS (free tooling/moulds/design — inflate the base), royalties, SELLING commission, packing — while EXCLUDING buying commission and post-import costs, and applies the COUNTRY BASIS: CIF (EU & most — international freight+insurance IN the base) vs FOB (US — excluded). It returns the line-by-line base, the duty on the correct base vs the naive invoice (the over/under-payment), and the DEDUCTIVE (resale-back-calc) and COMPUTED (cost build-up) methods when there is no transaction value. Honest (regla 7): INDICATIVE model of the method hierarchy & adjustments; related-party tests, first-sale and assist apportionment are case-specific — NOT a customs ruling or legal advice. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (20)
dest_countrystringrequired
Destination country ISO2 (US, DE, GB, …). REQUIRED — sets the CIF/FOB basis.
invoice_price_usdnumber
The price actually paid/payable (total, or per-unit if per_unit=true). REQUIRED for transaction value.
quantity_unitsnumber
Quantity of units (for per-unit assists apportionment & per-unit output). Optional; default 1.
per_unitboolean
Is invoice_price_usd a PER-UNIT figure? Optional; default false (total).
incotermstring
Incoterm of the price (EXW/FOB/CIF/DDP…). Optional; default FOB.
methodstring
'transaction-value' (default), 'deductive' or 'computed'.
assists_usdnumber
Assists supplied free (tooling/moulds/materials/design), TOTAL USD — ADD to base. Optional.
royalties_usdnumber
Royalties/licence fees that are a condition of sale, TOTAL USD. Optional.
selling_commission_usdnumber
Selling commission (to seller's agent), TOTAL USD — dutiable. Optional.
buying_commission_usdnumber
Buying commission (to buyer's own agent), TOTAL USD — NOT dutiable (shown excluded). Optional.
packing_usdnumber
Packing & containers cost, TOTAL USD. Optional.
international_freight_usdnumber
International freight to the import port, TOTAL USD (in base on CIF basis only). Optional.
insurance_usdnumber
International insurance, TOTAL USD (in base on CIF basis only). Optional.
post_import_transport_usdnumber
Post-import transport/destination charges baked into a DAP/DDP price, TOTAL USD — stripped out. Optional.
baked_import_duty_usdnumber
Import duty/tax baked into a DDP price, TOTAL USD — stripped out. Optional.
duty_rate_pctnumber
Modeled duty rate (0.075 or 7.5) to value the over/under-payment vs the naive invoice. Optional.
resale_price_usdnumber
Deductive method: destination unit resale price (USD).
resale_margin_pctnumber
Deductive: resale gross margin to deduct (0.30). Optional; default 0.30.
deductible_inland_usdnumber
Deductive: per-unit post-import freight+duties to deduct (USD). Optional.
computed_unit_cost_usdnumber
Computed method: built-up unit cost (materials+fabrication+profit+expenses), USD.
booking_strategy
When and how to RESERVE space so your box isn't rolled and your cargo isn't stranded on the dock. Give the lane + ship date + criticality, and it reads the demand PRESSURE (composing the seasonality calendar — CNY / Golden Week / transpacific peak — with the equipment-crunch signal) into a band (slack → acute), then returns: the optimal BOOKING WINDOW (lead days, plus a criticality buffer, and the date to book by), the SPOT vs CONTRACT rollover probability and roll-delay days, and the GUARANTEED/PREMIUM-booking trade-off — the certain premium surcharge vs the expected rollover-delay cost of riding spot (roll prob × delay days × per-day criticality cost). It recommends spot, a guaranteed booking, or — if your committed volume justifies it — a named-account allocation. Proves: peak/CNY → book earlier + pay for the guarantee; slack market → ride spot. Honest (regla 7): INDICATIVE rollover probabilities & premiums by band (reusing the real seasonality/equipment calendars) — not a space guarantee or carrier quote. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (7)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country').
Ship date (YYYY-MM-DD) — selects the seasonal/equipment pressure. Optional; default today.
criticalitystring
'low' / 'normal' / 'high' / 'critical' — how badly a rollover delay hurts. Optional; default normal.
base_freight_per_container_usdnumber
Base ocean freight per container (USD) to price the premium & delay cost. Optional — derived if omitted.
annual_containersnumber
Annual committed volume on this lane (containers/yr) — triggers the named-account allocation call. Optional.
cold_chain
Cold-chain / pharma (GDP) compliance for a TEMPERATURE-CONTROLLED shipment — beyond a reefer setpoint. Give the lane + the product (e.g. 'pharma vaccines 2-8°C', 'frozen seafood', 'bananas') or a sensitivity class, and it returns the temperature requirement, the THERMAL-EXCURSION risk across the transit, the recommended MODE + thermal packaging, and the GDP datalogger/chain-validation needs. The core insight: excursion risk RISES with transit DURATION. It reads the iter3 transit p90 for the ocean routing and runs a survival model per packaging option (ocean active reefer, ocean qualified-passive PCM/VIP, active air) — a long Cape-diverted reefer accumulates far more deviation exposure (and a gen-set/fuel/plug failure tail) than a 3-day air leg. Each option is totalled = freight + packaging premium + monitoring + EXPECTED THERMAL LOSS (excursion × loss-fraction × cargo value), and the lowest-total option wins. Proves: pharma 2-8°C on a long transit → high excursion risk → fly it with active cooling OR use qualified passive packaging; a frozen load on a short lane → ocean reefer is fine. For GDP cargo it mandates continuous data-logging, pre-cool, a validated lane and a documented chain. Honest (regla 7): INDICATIVE GDP/cold-chain model — excursion probabilities, MKT, packaging performance and loss fractions are modeled typicals, NOT a GDP qualification, stability statement or QA release. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (11)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country').
Ship date (YYYY-MM-DD) — selects the transit/diversion state. Optional; default today.
productstring
Product description — 'pharma vaccines 2-8°C', 'frozen seafood', 'bananas', 'fresh produce', 'insulin'. Sets the temperature requirement & sensitivity.
sensitivitystring
Explicit sensitivity class — ambient | cool | chilled | frozen | pharma | pharma-critical. Overrides the product match. Provide this OR 'product'.
cargo_value_usdnumber
Total cargo value (USD) — drives the expected-loss economics. Optional; a class default is used if omitted.
unit_value_usdnumber
Per-unit value (USD) — with 'units', an alternative to cargo_value_usd. Optional.
unitsnumber
Number of units (with unit_value_usd). Optional.
ocean_freight_usdnumber
Override the ocean all-in freight per container (USD). Optional — derived if omitted.
air_freight_multiplenumber
Air freight as a multiple of ocean (default ~6-7×). Optional.
rate_benchmark
Benchmark a rate you ALREADY PAY against the market — the 'am I being clamped?' check every shipper wants. Give the lane + the rate you pay (paid_rate_usd) and it places that rate in the MARKET BAND of the corridor (percentile against p20 / median / p80), built from the cross-validated index mid (Drewry WCI + Freightos FBX) and the corridor's modeled rate dispersion. It returns where you sit (p20 = a strong price, median = fair, p80 = over-paying), how much you OVER- or UNDER-pay vs the market mid in $/container and per YEAR at your volume, and the LEVER to correct it — renegotiate to the median, tender the lane, switch carrier/alliance, or lock a good price. A contract rate sitting above the median in a soft/falling market is flagged for renegotiation, not just labelled expensive. Proves: a rate at the p80 → 'you over-pay $X/ctr; renegotiate toward the median to save $X×volume/yr'; a rate at the p20 → 'good price, hold it'. The SAME rate is placed differently as the live band moves. Honest (regla 7): the band is a MODELED dispersion around the index mid, NOT a panel of real quotes — a true benchmark needs a rate panel (Xeneta/SeaRates). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (8)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country').
dest_portstringrequired
Destination port.
paid_rate_usdnumberrequired
The rate you currently PAY for this lane (USD per container). REQUIRED — this is what gets benchmarked.
Ship date (YYYY-MM-DD) for the market read. Optional; default today.
basisstring
'spot' (default — bare ocean freight) or 'all-in' (base + surcharges) — match it to what your paid rate INCLUDES. Optional.
annual_containersnumber
Annual containers on this lane — to annualise the over/under-payment & savings. Optional.
is_contractboolean
Is the paid rate a CONTRACT rate? Flags a high contract in a soft/falling market. Optional.
appointment_plan
Plan the terminal APPOINTMENT and the box sequence so you don't eat demurrage & detention. US/EU terminals require a timed appointment to pick up the import container and to return the empty; miss the window and dwell climbs and D&D starts. Give the lane + ship date and it reads the destination port congestion (iter7) at arrival, derives APPOINTMENT-SLOT availability (how far out the first slot is and how likely a desired slot is missed — the real dwell driver), then returns: the OPTIMAL PICKUP WINDOW (late enough not to pre-pay storage, with a reserve for a missed slot, by-date inside your free days), the PICKUP→EMPTY-RETURN sequence (a dual transaction where the port supports it to cut detention), and the expected D&D of the plan vs sending the trucker blind, with the saving. Proves: a congested port (LA/LB at peak) → tight slot window, book earlier, dual-transaction the empty → saves $X of D&D; a fluid port → same-day slots, relaxed window, no premium. Honest (regla 7): INDICATIVE — appointment availability, slot scarcity and dual-transaction behaviour are modeled by port & congestion band, NOT a live terminal appointment feed (eModal/Voyage/TideWorks). PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Parameters (7)
origin_portstringrequired
Origin port (city name, UN/LOCODE, or 'City, Country').
dest_portstringrequired
Destination port — where the box is picked up & the empty returned.
Ship date (YYYY-MM-DD) — sets the arrival window & congestion. Optional; default today.
discharge_clear_daysnumber
Days to discharge + customs-clear before the box is available for pickup. Optional; default 2.
import_free_daysnumber
Your contract's import (demurrage) free days. Optional — a regional default is used.
empty_return_free_daysnumber
Your contract's empty-return (detention) free days. Optional — a regional default is used.
select_provider
Choose the right freight INTERMEDIARY — freight forwarder, 3PL/4PL, customs broker, NVOCC or carrier-direct — and know how to grade them. Give a NEED profile (priority cost vs service, cargo specialisation reefer/dangerous-goods/project/e-commerce/high-value, annual volume, corridor count, whether you need warehousing, whether customs is the hard part) and it scores every provider archetype on weighted criteria (corridor coverage, specialisation, technology/visibility, customs depth, cost, service, financial stability), RANKS them, recommends the provider TYPE (+ a pairing, e.g. niche forwarder + customs broker), and emits a weighted SCORECARD you fill in for real candidates. Proves: a reefer-heavy, low-volume, service-led need → a niche cold-chain forwarder tops the rank (NOT a generic mega-3PL); a high-volume cost-led need on a few lanes → carrier-direct / NVOCC; a customs-heavy need pulls in a customs-broker pairing. The criterion weights shift with the need, so the recommendation changes when the profile changes. Honest (regla 7): INDICATIVE archetypes & weights — NOT an endorsement of, or performance claim about, any named provider; run your own RFI/references. PREMIUM: pay per call with x402 (USDC on Base) or a prepaid key.
Ocean & multimodal freight intelligence suite for AI agents. One MCP server that answers
any shipping question an importer, CFO, or supply-chain agent actually asks — from
"what's the spot rate Shanghai → LA?" to "what's my total landed cost with duty?" to
"should I book this lane now or wait?" — across 47 tools covering rates, total landed
cost, transit reliability, customs, risk, emissions, and a unified ship decision.
Give it a lane, an HS code, a value — get back one trustworthy, cross-validated answer
with a confidence read, not one vendor's quote. The rate engine, port normalization,
customs logic, and the accumulating per-lane history all run server-side (the moat);
the npm package is a thin client.
Hosted endpoint:https://freight-pulse-mcp.vercel.app/mcp · streamable-HTTP, no signup for the free tier.
Why an agent picks this
A single freight API returns one vendor's number with no second opinion and stops at the
rate. freight-pulse goes the whole distance an importer needs:
Cross-validated rates. Reads Drewry's World Container Index (WCI) and the Freightos
Baltic Index (FBX) server-side (plus your own SeaRates key if you supply one) and reconciles
them into one normalized USD figure with a confidence score (do the sources agree?)
and a market direction (rising / falling / stable).
The whole decision, not just the price. Landed cost with HS-code duty, all-in door-to-door,
transit time + reliability (p90), air-vs-ocean trade-off, customs, risk, CO₂ — folded into a
single ship_decision verdict: BOOK NOW / WAIT / SWITCH MODE.
Its own accumulating history. Every lane queried is cached with a timestamp; trend tools
serve a weeks-long normalized series no single index hands an agent for free.
Public, non-sensitive inputs. Ports, HS codes, declared values — nothing secret. Safe for
an agent to call without handing over credentials.
Worked example — Shanghai → Los Angeles, 40ft, $180k of cargo
get_spot_rate is free (the hook). The deep analytical tools are premium.
Quickstart (MCP)
jsonc
{"mcpServers":{"freight-pulse":{"command":"npx","args":["-y","freight-pulse-mcp"],"env":{// optional: unlock premium tools with a prepaid key"FREIGHT_PULSE_KEY":"fp_…",// optional: your own SeaRates key — cross-validated as a THIRD source, RAISES confidence"SEARATES_API_KEY":"…"}}}}
Or connect over HTTP at POST https://freight-pulse-mcp.vercel.app/mcp (streamable).
🪙 x402 (USDC on Base) per call — agents pay automatically, no signup · or 💳 card via Stripe checkout for a prepaid key
Two ways to pay a premium call:
🪙 x402 (USDC on Base) — an x402-aware agent pays per call automatically, zero signup.
💳 Card (Stripe) — buy a prepaid API key, send it as Authorization: Bearer <key>
(or set FREIGHT_PULSE_KEY).
On the data
freight-pulse is indicative market intelligence cross-validated from public freight indices
and customs references — not a carrier quote or a booking. Always verify with your forwarder
before committing. Drewry WCI and Freightos FBX publish weekly assessments; the optional SeaRates
source is bring-your-own-key (it only raises confidence, never required).
The analysis engine — index fetching, port/HS normalization, cross-validation, the confidence
model, customs/duty logic, and the per-lane history cache — runs server-side. The npm package
is a thin client that forwards to the hosted service.
