Aether-X Port Congestion Oracle

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

DATA INTEGRITY NOTICE: Port conditions vary by source availability. Based on local audits of our strict temporal freshness rules, Santos (BRSSZ) successfully serves live line-ups from official port authorities (data_source="live:aps_atracados+..."). Other ports (BRPNG, BRRIO, BRNIT, BRITG, and global ports) may also serve live telemetry if their source sensor provides valid recent timestamps; otherwise, they degrade to a calibrated/static reference seed (calibrated_reference_seed / static_reference_seed) or degraded semantic states. Production telemetry verification is still ongoing. Every API/MCP response includes data_source, decision_grade, semantic_state, 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 38 registered ports & global chokepoints. 5 Brazilian ports serve verifiable live official-authority line-ups — Santos (BRSSZ), Paranaguá (BRPNG), Rio de Janeiro (BRRIO), Itaguaí (BRITG) and Niterói (BRNIT). The remaining ports and chokepoints degrade gracefully to calibrated/static reference seeds. 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.