get_market_intel

Instructions

Implementation Reference

• src/mcp/server.ts:282-317 (handler)

  MCP tool handler for 'get_market_intel' — calls enrichWithBirdeye() and returns overview (price, volume, liquidity, market cap, holders, price change), marketRisk (flags/score/verdict), and tradeData.

  // ── Tool: get_market_intel ────────────────────────────────────────────
  server.tool(
      'get_market_intel',
      `Get real-time market intelligence for a Solana token from Birdeye. Returns price, 24h volume, liquidity depth, market cap, holder count, and market risk flags (wash trading, low liquidity, extreme volume ratios). Use this for trade sizing and market health assessment.`,
      {
          mint: z.string().describe('Solana token mint address'),
      },
      async ({ mint }) => {
          try {
              const result = await enrichWithBirdeye(mint, BIRDEYE_API_KEY);
              return {
                  content: [{
                      type: 'text' as const,
                      text: JSON.stringify({
                          overview: result.overview ? {
                              price: result.overview.price,
                              volume24h: result.overview.volume24h,
                              liquidity: result.overview.liquidity,
                              marketCap: result.overview.marketCap,
                              holders: result.overview.holder,
                              priceChange24h: result.overview.priceChange24h,
                          } : null,
                          marketRisk: result.marketRisk,
                          tradeData: result.tradeData ?? null,
                      }, null, 2),
                  }],
              };
          } catch (e: unknown) {
              const msg = e instanceof Error ? e.message : String(e);
              return {
                  content: [{ type: 'text' as const, text: JSON.stringify({ error: msg }) }],
                  isError: true,
              };
          }
      },
  );

• src/core/birdeye.ts:308-363 (handler)

  Core enrichWithBirdeye() function — fetches Birdeye token_overview, trade-data, token_security, and creation_info, applies rate-limit staggering, then calls assessMarketRisk() to produce market risk assessment.

  export async function enrichWithBirdeye(
      mint: string,
      apiKey: string,
  ): Promise<BirdeyeEnrichment> {
      if (!apiKey) {
          return {
              overview: null,
              security: null,
              creation: null,
              tradeData: null,
              marketRisk: { score: 0, flags: ['NO_API_KEY'], verdict: 'SKIPPED' },
              tier: 'standard',
              fetchedAt: new Date().toISOString(),
              error: 'BIRDEYE_API_KEY not configured',
          };
      }
  
      // ── Phase 1: Free-tier endpoints (staggered for 1 RPS) ──
      const overview = await birdeyeFetch<BirdeyeOverview>(
          '/defi/token_overview', apiKey, { address: mint },
      );
  
      await delay(1_100); // Respect 1 RPS
  
      const tradeData = await birdeyeFetch<BirdeyeTradeData>(
          '/defi/v3/token/trade-data/single', apiKey, { address: mint },
      );
  
      // ── Phase 2: Paid-tier endpoints (attempt, fail gracefully) ──
      await delay(1_100);
  
      const security = await birdeyeFetch<BirdeyeSecurity>(
          '/defi/token_security', apiKey, { address: mint },
      );
  
      await delay(1_100);
  
      const creation = await birdeyeFetch<BirdeyeCreation>(
          '/defi/token_creation_info', apiKey, { address: mint },
      );
  
      // Determine detected tier based on what succeeded
      const tier = security ? (creation ? 'premium' : 'starter') : 'standard';
  
      const marketRisk = assessMarketRisk(overview, security, tradeData);
  
      return {
          overview,
          security,
          creation,
          tradeData,
          marketRisk,
          tier,
          fetchedAt: new Date().toISOString(),
      };
  }

• src/core/birdeye.ts:159-292 (helper)

  assessMarketRisk() — evaluates liquidity depth, holder count, trade staleness, price crash, volume-to-MC ratio, Birdeye security flags, sell pressure, wash trading, and wallet exodus to produce a risk score (0-100), flags, and verdict.

  function assessMarketRisk(
      overview: BirdeyeOverview | null,
      security: BirdeyeSecurity | null,
      tradeData: BirdeyeTradeData | null,
  ): { score: number; flags: string[]; verdict: string } {
      const flags: string[] = [];
      let score = 0;
  
      if (overview) {
          // ── Liquidity Risk ──
          if (overview.liquidity < 1_000) {
              flags.push('CRITICALLY_LOW_LIQUIDITY (<$1K)');
              score += 30;
          } else if (overview.liquidity < 10_000) {
              flags.push('LOW_LIQUIDITY (<$10K)');
              score += 15;
          } else if (overview.liquidity < 50_000) {
              flags.push('MODERATE_LIQUIDITY (<$50K)');
              score += 5;
          }
  
          // ── Holder count ──
          if (overview.holder < 10) {
              flags.push('EXTREMELY_FEW_HOLDERS (<10)');
              score += 25;
          } else if (overview.holder < 50) {
              flags.push('FEW_HOLDERS (<50)');
              score += 15;
          }
  
          // ── Stale trading ──
          if (overview.lastTradeUnixTime) {
              const ageSeconds = (Date.now() / 1000) - overview.lastTradeUnixTime;
              if (ageSeconds > 86_400) {
                  flags.push('NO_RECENT_TRADES (>24h)');
                  score += 10;
              }
          }
  
          // ── Extreme price crash ──
          if (overview.priceChange24h < -70) {
              flags.push(`SEVERE_PRICE_CRASH_24H (${overview.priceChange24h.toFixed(1)}%)`);
              score += 25;
          } else if (overview.priceChange24h < -50) {
              flags.push(`PRICE_CRASH_24H (${overview.priceChange24h.toFixed(1)}%)`);
              score += 15;
          }
  
          // ── Volume anomaly ──
          if (overview.marketCap > 0 && overview.v24hUSD) {
              const volumeToMcap = overview.v24hUSD / overview.marketCap;
              if (volumeToMcap > 10) {
                  flags.push(`EXTREME_VOLUME_TO_MCAP_RATIO (${volumeToMcap.toFixed(1)}x)`);
                  score += 10;
              }
          }
      }
  
      if (security) {
          // ── Birdeye security flags (only available on Starter+) ──
          if (!security.renounced) {
              flags.push('BIRDEYE_OWNERSHIP_NOT_RENOUNCED');
              score += 15;
          }
          if (security.freezeable) {
              flags.push('BIRDEYE_FREEZE_AUTHORITY_ACTIVE');
              score += 20;
          }
          if (security.mutableMetadata) {
              flags.push('MUTABLE_METADATA');
              score += 5;
          }
          if (security.transferFeeEnable) {
              flags.push('TRANSFER_FEE_ENABLED');
              score += 10;
          }
          if (security.nonTransferable) {
              flags.push('NON_TRANSFERABLE_TOKEN');
              score += 30;
          }
      }
  
      if (tradeData) {
          // ── Sell pressure analysis ──
          if (tradeData.buy_24h > 0 && tradeData.sell_24h > 0) {
              const ratio = tradeData.sell_24h / tradeData.buy_24h;
              if (ratio > 5) {
                  flags.push(`EXTREME_SELLING (sell:buy ${ratio.toFixed(1)}:1)`);
                  score += 20;
              } else if (ratio > 3) {
                  flags.push(`HEAVY_SELLING (sell:buy ${ratio.toFixed(1)}:1)`);
                  score += 10;
              }
          }
  
          // ── Volume sell pressure ──
          if (tradeData.volume_buy_24h_usd > 0 && tradeData.volume_sell_24h_usd > 0) {
              const sellBuyVolRatio = tradeData.volume_sell_24h_usd / tradeData.volume_buy_24h_usd;
              if (sellBuyVolRatio > 3) {
                  flags.push(`SELL_VOLUME_DOMINANCE (${sellBuyVolRatio.toFixed(1)}x)`);
                  score += 10;
              }
          }
  
          // ── Bot/wash trading detection ──
          if (tradeData.unique_wallet_24h < 5 && tradeData.trade_24h > 50) {
              flags.push('SUSPECTED_BOT_ACTIVITY (few wallets, many trades)');
              score += 15;
          }
  
          // ── Unique wallet decline (mass exodus) ──
          if (tradeData.unique_wallet_24h_change_percent < -50) {
              flags.push(`WALLET_EXODUS_24H (${tradeData.unique_wallet_24h_change_percent.toFixed(1)}%)`);
              score += 10;
          }
  
          // ── Short-term manipulation ──
          if (tradeData.trade_1h && tradeData.unique_wallet_1h) {
              if (tradeData.unique_wallet_1h < 3 && tradeData.trade_1h > 20) {
                  flags.push('WASH_TRADING_1H (very few wallets, high frequency)');
                  score += 15;
              }
          }
      }
  
      score = Math.min(score, 100);
  
      const verdict = score === 0 ? 'MARKET_SAFE'
          : score <= 15 ? 'MARKET_CAUTION'
          : score <= 40 ? 'MARKET_HIGH_RISK'
          : 'MARKET_CRITICAL';
  
      return { score, flags, verdict };
  }

• src/core/birdeye.ts:24-102 (schema)

  Type definitions for BirdeyeOverview, BirdeyeSecurity, BirdeyeCreation, BirdeyeTradeData, and BirdeyeEnrichment — the data structures returned by the handler.

  export interface BirdeyeOverview {
      address:      string;
      symbol:       string;
      name:         string;
      decimals:     number;
      price:        number;
      priceChange24h: number;
      volume24h:    number;
      liquidity:    number;
      marketCap:    number;
      supply:       number;
      holder:       number;
      lastTradeUnixTime: number;
      // Extended fields from the actual response
      trade24h?:    number;
      sell24h?:     number;
      buy24h?:      number;
      v24hUSD?:     number;
      numberMarkets?: number;
      uniqueWallet24h?: number;
  }
  
  export interface BirdeyeSecurity {
      ownerAddress:     string | null;
      freezeAuthority:  string | null;
      freezeable:       boolean;
      mutableMetadata:  boolean;
      renounced:        boolean;
      isToken2022:      boolean;
      transferFeeEnable: boolean;
      transferFeeData:  Record<string, unknown>;
      nonTransferable:  boolean;
  }
  
  export interface BirdeyeCreation {
      address:    string;
      decimals:   number;
      symbol:     string;
      name:       string;
      txHash:     string;
      slot:       number;
      blockUnixTime: number;
      creator:    string;
  }
  
  export interface BirdeyeTradeData {
      // v3 snake_case fields
      price:       number;
      volume_24h:  number;
      volume_24h_usd: number;
      volume_24h_change_percent: number;
      trade_24h:   number;
      sell_24h:    number;
      buy_24h:     number;
      unique_wallet_24h: number;
      unique_wallet_history_24h: number;
      unique_wallet_24h_change_percent: number;
      // Buy/sell volume for ratio analysis
      volume_buy_24h_usd:  number;
      volume_sell_24h_usd: number;
      // Short-term activity (manipulation detection)
      trade_1h?:   number;
      unique_wallet_1h?: number;
  }
  
  export interface BirdeyeEnrichment {
      overview:  BirdeyeOverview | null;
      security:  BirdeyeSecurity | null;
      creation:  BirdeyeCreation | null;
      tradeData: BirdeyeTradeData | null;
      marketRisk: {
          score:     number;
          flags:     string[];
          verdict:   string;
      };
      tier:      'standard' | 'starter' | 'premium' | 'business';
      fetchedAt: string;
      error?:    string;
  }

• src/api/server.ts:121-131 (registration)

  REST API tool listing registers 'get_market_intel' as a capability in the SicariusGuard API description endpoint.

          tools: [
              { name: 'check_token_safety', description: 'Analyze a Solana SPL token for rug pull, honeypot, and safety risks.' },
              { name: 'check_honeypot', description: 'Simulate a sell via Jupiter to detect honeypot tokens.' },
              { name: 'check_holder_concentration', description: 'Analyze token holder distribution for rug pull indicators.' },
              { name: 'full_token_scan', description: 'Comprehensive 7-layer safety analysis with Birdeye market intelligence.' },
              { name: 'get_wallet_reputation', description: 'Investigate wallet reputation via Helius DAS identity data.' },
              { name: 'get_market_intel', description: 'Real-time market data from Birdeye (price, volume, liquidity).' },
              { name: 'batch_scan', description: 'Scan up to 10 tokens in parallel for portfolio-level risk assessment.' },
          ],
      });
  });