get_open_interest

Instructions

Implementation Reference

• coin_mcp/derivatives.py:87-136 (handler)

  The `get_open_interest` async tool handler — decorated with @mcp.tool(), prewarms the exchange, then calls either `fetchOpenInterest` or falls back to `fetchOpenInterestHistory` via CCXT inside a `_ccxt_call` thread runner.

  @mcp.tool()
  async def get_open_interest(exchange_id: str, symbol: str) -> Any:
      """Get the current open interest (OI) for a perpetual contract on one exchange.
  
      Open interest is the total notional/contract count of outstanding positions
      on a venue. Reading OI alongside price:
        - OI rising with price rising  -> new longs entering, trend has fuel
        - OI rising with price falling -> new shorts loading up
        - OI falling with price rising -> short squeeze / covering rally
        - OI falling with price falling -> longs capitulating
      This is descriptive, not advice. For funding-rate context use
      `get_funding_rate` (snapshot) or `get_funding_rate_history` (series).
  
      Falls back to `fetch_open_interest_history(timeframe="1h", limit=1)` when
      the exchange exposes only the historical endpoint.
  
      Args:
          exchange_id: CCXT exchange ID supporting perps.
          symbol: Perp symbol with settle suffix, e.g. "BTC/USDT:USDT" or
              "BTC/USD:BTC" for inverse.
  
      Returns:
          Object with `symbol`, `openInterestAmount` (in base units / contracts),
          `openInterestValue` (notional in quote), `timestamp`, `datetime`, and
          exchange-specific `info`. On unsupported exchanges returns
          `{"error": "..."}`.
      """
      err = await _prewarm_exchange(exchange_id)
      if err is not None:
          return err
  
      def _do() -> Any:
          ex = _get_ccxt_exchange(exchange_id)
          if ex.has.get("fetchOpenInterest"):
              return ex.fetch_open_interest(symbol)
          if ex.has.get("fetchOpenInterestHistory"):
              rows = ex.fetch_open_interest_history(symbol, timeframe="1h", limit=1)
              if isinstance(rows, list) and rows:
                  return rows[-1]
              return {
                  "error": f"{exchange_id} fetchOpenInterestHistory returned no rows for {symbol}"
              }
          return {
              "error": (
                  f"{exchange_id} supports neither fetchOpenInterest nor "
                  f"fetchOpenInterestHistory via CCXT"
              )
          }
  
      return await _ccxt_call(_do, exchange_id=exchange_id)

• coin_mcp/core.py:128-129 (registration)

  Registration/listing of `get_open_interest` in the MCP instructions table mapping tool names to descriptions.

  | Current open interest for a perp | get_open_interest |
  | Compare funding rates across exchanges | compare_funding_rates |

• coin_mcp/derivatives.py:33-33 (registration)

  The @mcp.tool() decorator on line 87 registers the tool on the shared FastMCP instance imported from core.py.

  @mcp.tool()

• coin_mcp/derivatives.py:114-116 (helper)

  Calls `_prewarm_exchange` helper to build/cache the CCXT exchange instance outside the per-id lock to avoid deadlocks.

  err = await _prewarm_exchange(exchange_id)
  if err is not None:
      return err

• coin_mcp/derivatives.py:136-136 (helper)

  Delegates execution to `_ccxt_call` (from core.py) which runs the blocking CCXT call in a thread with per-exchange locking.

  return await _ccxt_call(_do, exchange_id=exchange_id)