Aether-X Port Congestion Oracle

Port congestion signals for developers, AI agents, logistics systems and quantitative workflows.

DATA INTEGRITY NOTICE: Brazilian ports (Santos BRSSZ, Paranaguá BRPNG, Rio BRRIO, Niterói BRNIT, Itaguaí BRITG) serve live line-ups from official port authorities and operations panels (data_source="live:appa+santos+lachmann" / live:portosrio_silog), refreshed continuously. 12 mapped global ports upgrade to live:shipinfo_ais whenever the AIS sensor delivers data. Every remaining port serves a calibrated/static reference seed (calibrated_reference_seed / static_reference_seed) — a modeled baseline, never disguised as live telemetry. Every API/MCP response includes data_source, decision_grade and as_of so you know exactly which is which.

Aether-X is physical-world port intelligence — port congestion signal, vessel queue intelligence, port delay risk / ETA delay, and demurrage exposure — covering 35 ports & global chokepoints (5 Brazilian ports LIVE from official-authority line-ups; 12 global ports live whenever the AIS sensor delivers; the rest calibrated/static reference seed). Delivered through a REST API, a typed Python SDK and a remote MCP server for AI agents.

When to call Aether-X: when a decision depends on current port conditions — choosing between ports, routing cargo, vessel scheduling, ETA risk, demurrage exposure, or supply-chain disruption — not static port information. Every response includes a machine-readable signal block (level, live_observation, queue_vessels, decision_implication, as_of).

Free tier available. No credit card required.

Quick start (Python) — under 3 minutes

pip install --upgrade aetherx-oracle

from aetherx import OracleClient

client = OracleClient(api_key="YOUR_RAPIDAPI_KEY")

risk = client.get_port_risk("BRSSZ")

print(risk.port_name)                        # Santos
print(risk.congestion_score)                 # 0.78
print(risk.eta_delay_days)                   # 1.6
print(risk.estimated_daily_demurrage_usd)    # 63200 (USD/day)

Get a free API key on the RapidAPI listing.

Compare many ports in one call

portfolio = ["BRSSZ", "CNSHA", "NLRTM", "USLAX", "SGSIN"]
results = client.get_ports_risk(portfolio)
for r in sorted(results, key=lambda x: x.congestion_score, reverse=True):
    print(f"{r.port_id:<6} {r.congestion_score:.2f}  {r.estimated_daily_demurrage_usd:,}/day")

24/48/72h trend

trend = client.get_port_trend("NLRTM")
print(trend.trend)                              # acelerando / estável / descongestionando
print(trend.projection["h48"].congestion_score)

Async (parallel batch)

pip install "aetherx-oracle[async]"

import asyncio
from aetherx import OracleClient

async def main():
    client = OracleClient(api_key="YOUR_RAPIDAPI_KEY")
    risks = await client.get_ports_risk_async(["BRSSZ", "CNSHA", "NLRTM", "USLAX"])
    for r in risks:
        print(r.port_id, r.congestion_score)

asyncio.run(main())

MCP server (for AI agents)

Ask your agent directly:

"What's the congestion risk at Santos?"

"Compare Santos, Shanghai and Rotterdam."

"Which of these ports has the highest modeled demurrage exposure?"

"Show me the 72-hour congestion trend for Santos."

Available tools: get_port_risk · get_ports_risk · get_port_trend

Remote (no install)

Add to your MCP client config:

{
  "mcpServers": {
    "aetherx-oracle": {
      "type": "url",
      "url": "https://aetherx.aether-grid.io/mcp"
    }
  }
}

Local (stdio)

{
  "mcpServers": {
    "aetherx-oracle": {
      "command": "uvx",
      "args": ["aetherx-mcp"]
    }
  }
}

Published in the Official MCP Registry as io.github.belegante-byte/aetherx-mcp, available on PyPI, Glama and Smithery.

REST API

Base URL: https://aetherx.aether-grid.io

Example response (/v1/port-risk?port_id=BRSSZ):

{
  "port_id": "BRSSZ",
  "port_name": "Santos",
  "country": "Brasil",
  "congestion_score": 0.78,
  "eta_delay_days": 1.6,
  "waiting_vessels": 12,
  "freight_volatility_index": 0.42,
  "estimated_daily_demurrage_usd": 63200,
  "updated_at": "2026-09-17 15:46:53"
}

Interactive docs: Swagger UI · OpenAPI

Supported ports

BRSSZ BRRIO CNSHA CNNGB CNTAO SGSIN NLRTM USLAX USNYC DEHAM MPTNG AEDXB KRPUS GBLGP ZACPT MXZLO

Unknown ports fall back to a global statistical estimate (country="Global").

Pricing & free tier

Free Developer Tier — $0.00 for development, prototyping, CI and evaluation. No credit card required.

Grab a key on the RapidAPI listing.

Resources

• RapidAPI marketplace
• PyPI — aetherx-oracle (SDK)
• PyPI — aetherx-mcp (MCP server)
• Official MCP Registry — io.github.belegante-byte/aetherx-mcp
• Glama connector
• Smithery gateway
• llms.txt
• Terms of Service

Writing

• Predicting Global Port Congestion in Real-Time with Python, DuckDB and MCP — DEV Community

Repository layout

src/            FastAPI app (REST + remote MCP), reference engine, data
sdk_python/     aetherx-oracle Python SDK (PyPI)
mcp_server/     aetherx-mcp MCP server for AI agents (PyPI)
docs/           OpenAPI specs, llms.txt, Terms of Service
tests/          pytest suite

Development & deployment

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python src/engine/init_prod_db.py   # seed the DuckDB oracle
uvicorn src.api.main:app --reload --port 8000
python -m pytest tests/ sdk_python/tests/ -v

Deploys to Railway via railway.json; the DuckDB oracle is seeded idempotently at boot.

Terms & license

Signals are provided "AS IS", without warranty, and do not constitute investment advice. See Terms of Service.

The Python SDK is MIT licensed. The API, reference engine and data pipeline are proprietary — hosted usage is governed by the Terms.