cerebrus_basis

Instructions

Implementation Reference

• src/cerebrus_pulse_mcp/server.py:309-327 (registration)

  Tool schema definition for cerebrus_basis, registered in the list_tools() handler. Defines name, description, and input schema requiring a 'coin' string.

  Tool(
      name="cerebrus_basis",
      description=(
          "Get Chainlink basis analysis — compares Hyperliquid perpetual oracle price "
          "vs Chainlink aggregated spot price on Arbitrum. Returns basis in bps, "
          "direction (hl_premium/hl_discount/aligned), and contrarian signal. "
          "Positive = longs paying shorts, negative = deleveraging. Cost: $0.02 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:419-421 (handler)

  Handler logic for cerebrus_basis: validates the coin argument, then calls the API endpoint /basis/{coin} via the _api_get helper.

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

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

  Helper function _api_get that makes HTTP GET requests to the Cerebrus Pulse API. Handles 402 (payment required), 429 (rate limit), and other HTTP errors.

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

  Helper function _validate_coin that validates and normalizes coin ticker input (strips whitespace, uppercases, checks regex).

  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