get_wallet_reputation

Instructions

Implementation Reference

• src/core/helius_wallet.ts:221-256 (handler)

  Main handler function that fetches wallet identity and funding from Helius API in parallel, then assesses reputation scoring.

  export async function enrichCreatorReputation(
      creatorAddress: string | null,
      heliusApiKey: string,
  ): Promise<WalletIntelligence> {
      if (!creatorAddress) {
          return {
              creatorAddress: null,
              reputation: null,
              fetchedAt: new Date().toISOString(),
              error: 'No creator address available',
          };
      }
  
      if (!heliusApiKey) {
          return {
              creatorAddress,
              reputation: null,
              fetchedAt: new Date().toISOString(),
              error: 'HELIUS_API_KEY not configured',
          };
      }
  
      // Fetch identity and funding in parallel (both cost 100 credits each)
      const [identity, funding] = await Promise.all([
          fetchWalletIdentity(creatorAddress, heliusApiKey),
          fetchWalletFunding(creatorAddress, heliusApiKey),
      ]);
  
      const reputation = assessCreatorReputation(identity, funding);
  
      return {
          creatorAddress,
          reputation,
          fetchedAt: new Date().toISOString(),
      };
  }

• src/core/helius_wallet.ts:130-210 (helper)

  Helper function that evaluates wallet identity and funding data, producing a risk score (0-100), flags, and verdict (TRUSTED/NEUTRAL/SUSPICIOUS/DANGEROUS).

  function assessCreatorReputation(
      identity: WalletIdentity | null,
      funding: WalletFunding | null,
  ): CreatorReputation {
      const flags: string[] = [];
      let score = 0;
  
      // ── Identity-based scoring ──
      if (identity) {
          const typeLower = (identity.type ?? '').toLowerCase();
          const categoryLower = (identity.category ?? '').toLowerCase();
          const allTags = identity.tags?.map(t => t.toLowerCase()) ?? [];
  
          // Check for known dangerous actors
          if (DANGEROUS_TYPES.has(typeLower) || DANGEROUS_TYPES.has(categoryLower)) {
              flags.push(`KNOWN_${typeLower.toUpperCase()}: ${identity.name ?? identity.address}`);
              score += 50;
          }
  
          // Check tags for danger signals
          for (const tag of allTags) {
              if (tag.includes('rug') || tag.includes('scam') || tag.includes('exploit') || tag.includes('hack')) {
                  flags.push(`TAGGED_${tag.toUpperCase()}`);
                  score += 30;
              }
          }
  
          // Suspicious but not definitively malicious
          if (SUSPICIOUS_TYPES.has(typeLower) || SUSPICIOUS_TYPES.has(categoryLower)) {
              flags.push(`SUSPICIOUS_CATEGORY: ${identity.category ?? identity.type}`);
              score += 15;
          }
  
          // Trusted entities reduce risk
          if (TRUSTED_TYPES.has(typeLower) || TRUSTED_TYPES.has(categoryLower)) {
              flags.push(`TRUSTED_ENTITY: ${identity.name ?? identity.type}`);
              score -= 15;
          }
      }
  
      // ── Funding source analysis ──
      if (funding) {
          // Funded by known exchange = likely legitimate user
          if (funding.funderType === 'exchange') {
              flags.push(`EXCHANGE_FUNDED: ${funding.funderName ?? 'unknown exchange'}`);
              score -= 10;
          }
  
          // Check wallet age
          const ageInDays = (Date.now() / 1000 - funding.timestamp) / 86_400;
  
          if (ageInDays < 1) {
              flags.push('WALLET_AGE_<1_DAY');
              score += 25;
          } else if (ageInDays < 7) {
              flags.push('WALLET_AGE_<7_DAYS');
              score += 15;
          } else if (ageInDays < 30) {
              flags.push('WALLET_AGE_<30_DAYS');
              score += 5;
          }
      } else {
          // No funding data — unknown origin
          flags.push('UNKNOWN_FUNDING_SOURCE');
          score += 5;
      }
  
      // Clamp score
      score = Math.max(0, Math.min(score, 100));
  
      const verdict = score >= 40 ? 'DANGEROUS'
          : score >= 20 ? 'SUSPICIOUS'
          : score > 0 ? 'NEUTRAL'
          : 'TRUSTED';
  
      const creatorAge = funding
          ? Math.floor((Date.now() / 1000 - funding.timestamp) / 86_400)
          : null;
  
      return { identity, funding, riskScore: score, flags, verdict, creatorAge };
  }

• src/core/helius_wallet.ts:19-50 (schema)

  Type definitions for wallet identity, funding data, creator reputation, and overall wallet intelligence response.

  export interface WalletIdentity {
      address:    string;
      name:       string | null;
      type:       string;   // "exchange", "defi", "rugger", "scammer", "kol", etc.
      category:   string | null;
      tags:       string[];
  }
  
  export interface WalletFunding {
      funder:      string;
      funderName:  string | null;
      funderType:  string | null;   // "exchange" | null
      amount:      number;
      timestamp:   number;
      signature:   string;
  }
  
  export interface CreatorReputation {
      identity:     WalletIdentity | null;
      funding:      WalletFunding | null;
      riskScore:    number;           // 0-100
      flags:        string[];
      verdict:      string;           // TRUSTED | NEUTRAL | SUSPICIOUS | DANGEROUS
      creatorAge:   number | null;    // days since wallet was funded
  }
  
  export interface WalletIntelligence {
      creatorAddress:    string | null;
      reputation:        CreatorReputation | null;
      fetchedAt:         string;
      error?:            string;
  }

• src/mcp/server.ts:256-280 (registration)

  MCP tool registration — defines the tool name, description, Zod schema (address required), and handler that calls enrichCreatorReputation.

  // ── Tool: get_wallet_reputation ────────────────────────────────────────
  server.tool(
      'get_wallet_reputation',
      `Analyze a Solana wallet's reputation using Helius DAS identity data and funding chain analysis. Checks deployer/wallet age, funding source identity, and known entity classification. Use this to evaluate whether a token deployer or counterparty is trustworthy before transacting.`,
      {
          address: z.string().describe('Solana wallet address to investigate (base58)'),
      },
      async ({ address }) => {
          try {
              const result = await enrichCreatorReputation(address, HELIUS_API_KEY);
              return {
                  content: [{
                      type: 'text' as const,
                      text: JSON.stringify(result, 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/api/server.ts:121-131 (registration)

  Tool listing in the MCP server card endpoint (Smithery/registry discovery) and the Express REST API's well-known 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.' },
          ],
      });
  });