cerebrus_oi

Instructions

Implementation Reference

• src/cerebrus_pulse_mcp/server.py:219-236 (registration)

  Tool registration for 'cerebrus_oi' — defines the Tool object with name, description, and inputSchema within the list_tools handler. The tool takes a required 'coin' string parameter and returns OI delta (1h/4h/24h), percentile rank, trend direction, and price-OI divergence signals. Cost: $0.01 USDC via x402.

  Tool(
      name="cerebrus_oi",
      description=(
          "Get open interest analysis for a Hyperliquid perpetual. "
          "Returns OI delta (1h/4h/24h), percentile rank, trend direction, "
          "and price-OI divergence signals. Cost: $0.01 USDC via x402."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "coin": {
                  "type": "string",
                  "description": "Coin ticker (e.g., BTC, ETH, SOL). Case-insensitive.",
              },
          },
          "required": ["coin"],
      },
  ),

• src/cerebrus_pulse_mcp/server.py:400-402 (handler)

  Handler for 'cerebrus_oi' tool — validates the coin parameter via _validate_coin (uppercases and regex-checks), then calls _api_get('/oi/{coin}') to fetch open interest analysis from the Cerebrus Pulse API. The result is JSON-serialized via _format_response.

  elif name == "cerebrus_oi":
      coin = _validate_coin(arguments["coin"])
      result = _api_get(f"/oi/{coin}")

• src/cerebrus_pulse_mcp/server.py:52-57 (helper)

  Helper _validate_coin — validates and normalizes a coin ticker: strips whitespace, uppercases, and checks against the regex pattern ^[A-Za-z0-9_-]+$. Raises ValueError on bad input.

  def _validate_coin(coin: str) -> str:
      """Validate and normalize a coin ticker. Raises ValueError on bad input."""
      coin = coin.strip().upper()
      if not _COIN_RE.match(coin):
          raise ValueError(f"Invalid coin ticker: {coin!r}")
      return coin

• src/cerebrus_pulse_mcp/server.py:60-83 (helper)

  Helper _api_get — makes an HTTP GET request to the Cerebrus Pulse API. Handles 402 (payment required), 429 (rate limited), and other HTTP errors. Returns parsed JSON response.

  def _api_get(path: str, params: dict | None = None) -> dict[str, Any]:
      """Make a GET request to the Cerebrus Pulse API."""
      with _make_client() as client:
          resp = client.get(path, params=params)
  
          if resp.status_code == 402:
              # Return payment details so the agent/user knows cost
              return {
                  "status": "payment_required",
                  "message": "This endpoint requires x402 USDC payment on Base or Solana.",
                  "url": f"{BASE_URL}{path}",
                  "payment_details": resp.headers.get("X-Payment", "See x402 SDK docs"),
                  "help": "Install the x402 SDK and set CEREBRUS_WALLET_KEY (Base) or CEREBRUS_WALLET_KEY_SOLANA (Solana) to enable auto-payment. See https://cerebruspulse.xyz/guides/x402-payments",
              }
  
          if resp.status_code == 429:
              return {
                  "status": "rate_limited",
                  "message": "Rate limit exceeded. Back off and retry.",
                  "detail": resp.json() if resp.headers.get("content-type", "").startswith("application/json") else resp.text,
              }
  
          resp.raise_for_status()
          return resp.json()

• src/cerebrus_pulse_mcp/server.py:475-483 (helper)

  CLI tool mapping for 'oi' — maps the CLI 'oi' command to the API path '/oi/{coin}' with a required 'coin' string parameter. This is used by the --json CLI mode as an alternative to the MCP handler.

      "oi":            ("/oi/{coin}",         [("coin", True, str, None)]),
      "spread":        ("/spread/{coin}",     [("coin", True, str, None)]),
      "correlation":   ("/correlation",       []),
      "stress":        ("/arb",              [("limit", False, int, 10)]),
      "cex-dex":       ("/cex-dex/{coin}",    [("coin", True, str, None)]),
      "basis":         ("/basis/{coin}",      [("coin", True, str, None)]),
      "depeg":         ("/depeg",             []),
      "liquidations":  ("/liquidations/{coin}", [("coin", True, str, None)]),
  }