:ambulance: RouteGuard: CEX Flow & Status Monitor

RouteGuard is the critical infrastructure layer of the ../README.md. It acts as a pre-flight check for your capital, validating exchange uptime, withdrawal status, and network congestion.

Unlike generic uptime monitors, RouteGuard answers the real operational question:

"If I send funds to this exchange right now, will they get stuck?"

---

:rocket: Key Features

• Granular Asset Gating: Checks asset-specific deposit/withdrawal flags (e.g., USDT vs BTC) rather than relying on generic exchange status.
• Network Awareness: Distinguishes between chains (e.g., USDT-TRC20 :white_check_mark: vs USDT-ERC20 :x:), preventing costly routing mistakes during congestion.
• Market Validation: Verifies that specific trading pairs (e.g., BTC/USDT) are active and tradable.
• Crash Protection: Detects maintenance modes and API-level failures, returning safe "DOWN" states to downstream bots.
• Machine-Native Output: Returns optimized, key-addressable JSON (O(1) lookups), designed for high-frequency systems.

---

:inbox_tray: Input Parameters

RouteGuard accepts a JSON configuration defined in INPUT_SCHEMA.json.

{
  "exchanges": ["binance", "bybit", "okx", "kraken"],
  "coins": ["USDT", "USDC", "BTC", "ETH"],
  "popularNetworks": ["ERC20", "TRC20", "SOL"],
  "proxyConfiguration": { "useApifyProxy": true }
}

Field	Type	Description
exchanges	Array	List of CCXT exchange IDs (e.g., binance, kraken).
coins	Array	List of assets to monitor (e.g., USDT, BTC).
popularNetworks	Array	Preferred networks to check (e.g., ERC20, TRC20, SOL).
proxyConfiguration	Object	Required for exchanges that block data center IPs (Binance, Bybit).

:outbox_tray: Output Structure

RouteGuard returns a consolidated registry optimized for speed. Downstream bots use this for O(1) safety checks.

[
  {
    "exchange_id": "binance",
    "status": "operational",
    "latency_ms": 124,
    "maintenance_mode": false,
    "assets": {
      "USDT": {
        "withdraw": true,
        "deposit": true,
        "networks": {
          "TRC20": { "withdraw": true, "deposit": true },
          "ERC20": { "withdraw": true, "deposit": false }
        }
      },
      "BTC": {
        "withdraw": true,
        "deposit": false
      }
    }
  }
]

Output Schema (JSON)

{
  "title": "RouteGuard Output",
  "description": "Per-exchange health snapshot.",
  "type": "object",
  "schemaVersion": 1,
  "properties": {
    "exchange_id": { "type": "string" },
    "status": { "type": "string" },
    "latency_ms": { "type": ["integer", "number", "null"] },
    "maintenance_mode": { "type": "boolean" },
    "assets": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "withdraw": { "type": "boolean" },
          "deposit": { "type": "boolean" },
          "networks": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "withdraw": { "type": "boolean" },
                "deposit": { "type": "boolean" }
              },
              "required": ["withdraw", "deposit"]
            }
          }
        },
        "required": ["withdraw", "deposit"]
      }
    },
    "markets": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "active": { "type": ["boolean", "null"] },
          "status": { "type": "string" }
        },
        "required": ["active", "status"]
      }
    }
  },
  "required": ["exchange_id", "status", "latency_ms", "maintenance_mode", "assets", "markets"]
}

Status Values

• operational - Safe to trade.
• maintenance - Exchange is under maintenance.
• down - API is unreachable.
• error - Unexpected data format.

---

:rocket: How to Use

Method 1: Infrastructure (Bundle Mode)

When running as part of the Monorepo, this module feeds a background Health Registry.

from APIs.RouteGuard.main import check_exchange_health

# Usage in orchestration loop
health_data = check_exchange_health("binance", coins=["USDT", "ETH"])
registry.update("binance", health_data)

Method 2: Standalone API

Can be deployed as an independent microservice to run RouteGuard checks for external systems.

# Install dependencies
pip install -r requirements.txt

# Run the monitor
python main.py

---

:hammer_and_wrench: Local Development

Prerequisites

• Python 3.11+
• Docker (optional)

Run Locally (Simulated)

# Create a local input file
echo '{"exchanges": ["binance"], "coins": ["USDT"]}' > storage/key_value_stores/default/INPUT.json

# Run the script
python main.py

---

:test_tube: Testing

The test suite includes strict contract tests to ensure the JSON output structure never changes unexpectedly, breaking downstream bots.

# Run all tests
pytest tests/test_monitor.py

# Verify output schema compliance
pytest tests/test_monitor.py::test_output_contract

---

:warning: Disclaimer

RouteGuard monitors exchange-reported status, not real-time blockchain congestion. While it checks wallet and network flags exposed by exchange APIs, it cannot guarantee that a blockchain mempool is uncongested. Always use as part of a broader risk management strategy.