cerebrus_spread

Instructions

Implementation Reference

• src/cerebrus_pulse_mcp/server.py:237-254 (registration)

  Tool 'cerebrus_spread' is registered as a Tool object in the list_tools() function with name, description, and inputSchema requiring a 'coin' string parameter.

  Tool(
      name="cerebrus_spread",
      description=(
          "Get spread and liquidity analysis for a Hyperliquid perpetual. "
          "Returns bid-ask spread, estimated slippage at $10k/$50k/$100k/$500k, "
          "and liquidity score (1-10). Cost: $0.008 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:404-406 (handler)

  Handler for cerebrus_spread: validates the coin parameter via _validate_coin() and calls the API endpoint /spread/{coin} via _api_get().

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

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

  Helper function _validate_coin used by the handler to normalize and validate coin ticker 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 function _api_get used by the handler to make HTTP GET requests to the Cerebrus Pulse API, handling 402 (payment required) and 429 (rate limit) responses.

  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:476-476 (helper)

  CLI tool mapping entry for 'spread' tool (maps to '/spread/{coin}' endpoint with required 'coin' param), used by the CLI mode (--json flag).

  "spread":        ("/spread/{coin}",     [("coin", True, str, None)]),