@elizaos/plugin-wallet 2.0.0-beta.1

package/src/analytics/token-info/action.ts

@@ -0,0 +1,240 @@
+import type {
+  Action,
+  ActionResult,
+  HandlerCallback,
+  HandlerOptions,
+  IAgentRuntime,
+  Memory,
+  State,
+} from "@elizaos/core";
+import { parseTokenInfoParams, selectedContextMatches } from "./params";
+import { TOKEN_INFO_SERVICE_TYPE, type TokenInfoService } from "./service";
+import { TOKEN_INFO_SUBACTIONS } from "./types";
+
+const TOKEN_INFO_CONTEXTS = ["finance", "crypto", "wallet"] as const;
+const TOKEN_INFO_KEYWORDS = [
+  "token",
+  "coin",
+  "crypto",
+  "dexscreener",
+  "birdeye",
+  "coingecko",
+  "price",
+  "pair",
+  "pairs",
+  "market cap",
+  "liquidity",
+  "trending",
+  "wallet",
+  "portfolio",
+  "boosted",
+  "profile",
+] as const;
+
+function hasTokenInfoIntent(message: Memory, state?: State): boolean {
+  const text = [
+    typeof message.content?.text === "string" ? message.content.text : "",
+    typeof state?.values?.recentMessages === "string"
+      ? state.values.recentMessages
+      : "",
+  ]
+    .join("\n")
+    .toLowerCase();
+  return TOKEN_INFO_KEYWORDS.some((keyword) => text.includes(keyword));
+}
+
+function unavailable(
+  callback: HandlerCallback | undefined,
+  text: string,
+  data: Record<string, unknown>,
+): ActionResult {
+  const dataAsContent = data as Parameters<HandlerCallback>[0]["data"];
+  callback?.({ text, actions: ["TOKEN_INFO"], data: dataAsContent });
+  return {
+    success: false,
+    text,
+    error: String(data.error ?? "TOKEN_INFO_UNAVAILABLE"),
+    data: data as ActionResult["data"],
+  };
+}
+
+export const tokenInfoAction: Action = {
+  name: "TOKEN_INFO",
+  contexts: [...TOKEN_INFO_CONTEXTS],
+  contextGate: { anyOf: [...TOKEN_INFO_CONTEXTS] },
+  roleGate: { minRole: "USER" },
+  similes: [
+    "DEXSCREENER_SEARCH",
+    "DEXSCREENER_TOKEN_INFO",
+    "DEXSCREENER_TRENDING",
+    "DEXSCREENER_NEW_PAIRS",
+    "DEXSCREENER_CHAIN_PAIRS",
+    "DEXSCREENER_BOOSTED_TOKENS",
+    "DEXSCREENER_TOKEN_PROFILES",
+    "BIRDEYE_LOOKUP",
+    "BIRDEYE_TOKEN_SEARCH",
+    "TOKEN_SEARCH",
+    "TOKEN_LOOKUP",
+    "TOKEN_PRICE",
+    "COINGECKO",
+  ],
+  description:
+    "Fetch crypto token and market information from registered providers. target selects provider (dexscreener, birdeye, coingecko). subaction selects search, token, trending, new-pairs, chain-pairs, boosted, profiles, or wallet.",
+  descriptionCompressed:
+    "Crypto token info provider registry: target dexscreener|birdeye|coingecko; subaction search|token|trending|new-pairs|chain-pairs|boosted|profiles|wallet.",
+  parameters: [
+    {
+      name: "target",
+      description:
+        "Provider to use. Omit to use the default provider for the subaction.",
+      required: false,
+      schema: { type: "string", enum: ["dexscreener", "birdeye", "coingecko"] },
+      examples: ["dexscreener", "birdeye", "coingecko"],
+    },
+    {
+      name: "subaction",
+      description: "Token information operation.",
+      required: true,
+      schema: { type: "string", enum: [...TOKEN_INFO_SUBACTIONS] },
+      examples: ["search", "token", "trending", "wallet"],
+    },
+    {
+      name: "query",
+      description:
+        "Search query, coin id, token symbol, token address, or wallet address.",
+      required: false,
+      schema: { type: "string" },
+    },
+    {
+      name: "address",
+      description: "Token or wallet address.",
+      required: false,
+      schema: { type: "string" },
+    },
+    {
+      name: "tokenAddress",
+      description: "Token contract address.",
+      required: false,
+      schema: { type: "string" },
+    },
+    {
+      name: "chain",
+      description:
+        "Chain/network for provider operations that need one, such as chain-pairs or CoinGecko contract lookup.",
+      required: false,
+      schema: { type: "string" },
+      examples: ["ethereum", "solana", "base"],
+    },
+    {
+      name: "timeframe",
+      description: "Trending window when supported.",
+      required: false,
+      schema: { type: "string", enum: ["1h", "6h", "24h"], default: "24h" },
+    },
+    {
+      name: "limit",
+      description: "Maximum result count.",
+      required: false,
+      schema: { type: "number", minimum: 1, maximum: 100, default: 10 },
+    },
+    {
+      name: "sortBy",
+      description: "Pair ranking metric for chain-pairs.",
+      required: false,
+      schema: {
+        type: "string",
+        enum: ["volume", "liquidity", "priceChange", "txns"],
+      },
+    },
+    {
+      name: "top",
+      description: "For boosted tokens, return top boosted rather than latest.",
+      required: false,
+      schema: { type: "boolean", default: false },
+    },
+    {
+      name: "id",
+      description: "CoinGecko coin id.",
+      required: false,
+      schema: { type: "string" },
+    },
+  ],
+  validate: async (_runtime, message, state) =>
+    selectedContextMatches(state, TOKEN_INFO_CONTEXTS) ||
+    hasTokenInfoIntent(message, state),
+  handler: async (
+    runtime: IAgentRuntime,
+    message: Memory,
+    state?: State,
+    options?: HandlerOptions | Record<string, unknown>,
+    callback?: HandlerCallback,
+  ): Promise<ActionResult> => {
+    const service = runtime.getService(
+      TOKEN_INFO_SERVICE_TYPE,
+    ) as TokenInfoService | null;
+    if (!service || typeof service.route !== "function") {
+      return unavailable(callback, "Token info service is not available.", {
+        actionName: "TOKEN_INFO",
+        error: "SERVICE_UNAVAILABLE",
+      });
+    }
+
+    const params = parseTokenInfoParams(message, state, options);
+    const routed = await service.route({
+      runtime,
+      message,
+      state,
+      options,
+      params,
+      callback,
+    });
+
+    if (routed.ok) {
+      const result = routed.result;
+      return {
+        ...result,
+        data: {
+          ...(result.data ?? {}),
+          actionName: "TOKEN_INFO",
+          target: routed.provider.name,
+          supportedProviders: service.listProviders(),
+        },
+      };
+    }
+
+    return unavailable(callback, routed.detail, {
+      actionName: "TOKEN_INFO",
+      error: routed.error,
+      detail: routed.detail,
+      providers: routed.providers,
+    });
+  },
+  examples: [
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "Search for PEPE on DexScreener" },
+      },
+      {
+        name: "{{agent}}",
+        content: {
+          text: "Searching DexScreener.",
+          action: "TOKEN_INFO",
+        },
+      },
+    ],
+    [
+      {
+        name: "{{user1}}",
+        content: { text: "Look up bitcoin on CoinGecko" },
+      },
+      {
+        name: "{{agent}}",
+        content: {
+          text: "Looking up Bitcoin on CoinGecko.",
+          action: "TOKEN_INFO",
+        },
+      },
+    ],
+  ],
+};

package/src/analytics/token-info/index.ts

@@ -0,0 +1,3 @@
+export { tokenInfoAction } from "./action";
+export { TOKEN_INFO_SERVICE_TYPE, TokenInfoService } from "./service";
+export * from "./types";

package/src/analytics/token-info/params.ts

@@ -0,0 +1,215 @@
+import type { HandlerOptions, Memory, State } from "@elizaos/core";
+import {
+  TOKEN_INFO_SUBACTIONS,
+  type TokenInfoParams,
+  type TokenInfoSubaction,
+} from "./types";
+
+const SUBACTION_ALIASES: Record<string, TokenInfoSubaction> = {
+  lookup: "token",
+  info: "token",
+  "token-info": "token",
+  token_info: "token",
+  pairs: "chain-pairs",
+  "new pairs": "new-pairs",
+  new_pairs: "new-pairs",
+  chain_pairs: "chain-pairs",
+  chainpairs: "chain-pairs",
+  boosted_tokens: "boosted",
+  boostedtokens: "boosted",
+  token_profiles: "profiles",
+  tokenprofiles: "profiles",
+  wallet_address: "wallet",
+  "wallet-address": "wallet",
+  portfolio: "wallet",
+};
+
+export function readParams(options?: unknown): Record<string, unknown> {
+  const direct =
+    options && typeof options === "object"
+      ? (options as Record<string, unknown>)
+      : {};
+  const parameters =
+    direct.parameters && typeof direct.parameters === "object"
+      ? (direct.parameters as Record<string, unknown>)
+      : {};
+  return { ...direct, ...parameters };
+}
+
+export function readStringParam(
+  options: unknown,
+  ...keys: string[]
+): string | undefined {
+  const params = readParams(options);
+  for (const key of keys) {
+    const value = params[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return undefined;
+}
+
+export function readNumberParam(
+  options: unknown,
+  key: string,
+  fallback?: number,
+): number | undefined {
+  const value = readParams(options)[key];
+  const parsed =
+    typeof value === "number"
+      ? value
+      : typeof value === "string" && value.trim().length > 0
+        ? Number(value)
+        : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+export function readBooleanParam(
+  options: unknown,
+  key: string,
+): boolean | undefined {
+  const value = readParams(options)[key];
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes"].includes(normalized)) return true;
+    if (["false", "0", "no"].includes(normalized)) return false;
+  }
+  return undefined;
+}
+
+export function normalizeTokenInfoSubaction(
+  value: unknown,
+): TokenInfoSubaction | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-");
+  if ((TOKEN_INFO_SUBACTIONS as readonly string[]).includes(normalized)) {
+    return normalized as TokenInfoSubaction;
+  }
+  return (
+    SUBACTION_ALIASES[normalized] ?? SUBACTION_ALIASES[value.toLowerCase()]
+  );
+}
+
+export function inferTokenInfoSubaction(
+  message: Memory,
+  state?: State,
+): TokenInfoSubaction {
+  const text = [
+    typeof message.content?.text === "string" ? message.content.text : "",
+    typeof state?.values?.recentMessages === "string"
+      ? state.values.recentMessages
+      : "",
+  ]
+    .join("\n")
+    .toLowerCase();
+
+  if (/\b(wallet|portfolio|holdings)\b/.test(text)) return "wallet";
+  if (/\b(boosted|promoted|sponsored)\b/.test(text)) return "boosted";
+  if (/\b(profile|profiles)\b/.test(text)) return "profiles";
+  if (
+    /\b(new|latest|fresh)\b/.test(text) &&
+    /\b(pair|pairs|tokens?)\b/.test(text)
+  ) {
+    return "new-pairs";
+  }
+  if (
+    /\b(pair|pairs)\b/.test(text) &&
+    /\b(chain|ethereum|solana|base|bsc|polygon|arbitrum|optimism|avalanche)\b/.test(
+      text,
+    )
+  ) {
+    return "chain-pairs";
+  }
+  if (/\b(trending|hot|popular|gainers)\b/.test(text)) return "trending";
+  if (/\b(search|find|look for)\b/.test(text)) return "search";
+  return "token";
+}
+
+export function parseTokenInfoParams(
+  message: Memory,
+  state?: State,
+  options?: HandlerOptions | Record<string, unknown>,
+): TokenInfoParams {
+  const raw = readParams(options);
+  const content =
+    typeof message.content?.text === "string" ? message.content.text : "";
+  const subaction =
+    normalizeTokenInfoSubaction(
+      raw.subaction ?? raw.action ?? raw.operation ?? raw.kind,
+    ) ?? inferTokenInfoSubaction(message, state);
+  const target = readStringParam(raw, "target", "provider", "source");
+  const query =
+    readStringParam(raw, "query", "token", "symbol") ??
+    (subaction === "search" ? content : undefined);
+  const address = readStringParam(raw, "address", "tokenAddress", "wallet");
+  const timeframeRaw = readStringParam(raw, "timeframe");
+  const timeframe =
+    timeframeRaw === "1h" || timeframeRaw === "6h" || timeframeRaw === "24h"
+      ? timeframeRaw
+      : undefined;
+  const sortByRaw = readStringParam(raw, "sortBy", "sort");
+  const sortBy =
+    sortByRaw === "volume" ||
+    sortByRaw === "liquidity" ||
+    sortByRaw === "priceChange" ||
+    sortByRaw === "txns"
+      ? sortByRaw
+      : undefined;
+  const kindRaw = readStringParam(raw, "kind", "mode");
+  const kind =
+    kindRaw === "wallet-address" ||
+    kindRaw === "token-address" ||
+    kindRaw === "token-symbol"
+      ? kindRaw
+      : undefined;
+
+  return {
+    target,
+    subaction,
+    query,
+    address,
+    tokenAddress: readStringParam(raw, "tokenAddress") ?? address,
+    chain: readStringParam(raw, "chain", "network"),
+    timeframe,
+    limit: readNumberParam(raw, "limit"),
+    offset: readNumberParam(raw, "offset"),
+    sortBy,
+    top: readBooleanParam(raw, "top"),
+    kind,
+    id: readStringParam(raw, "id", "coinId"),
+  };
+}
+
+export function selectedContextMatches(
+  state: State | undefined,
+  contexts: readonly string[],
+): boolean {
+  const selected = new Set<string>();
+  const collect = (value: unknown) => {
+    if (!Array.isArray(value)) return;
+    for (const item of value) {
+      if (typeof item === "string") selected.add(item);
+    }
+  };
+  collect(
+    (state?.values as Record<string, unknown> | undefined)?.selectedContexts,
+  );
+  collect(
+    (state?.data as Record<string, unknown> | undefined)?.selectedContexts,
+  );
+  const contextObject = (state?.data as Record<string, unknown> | undefined)
+    ?.contextObject as
+    | {
+        trajectoryPrefix?: { selectedContexts?: unknown };
+        metadata?: { selectedContexts?: unknown };
+      }
+    | undefined;
+  collect(contextObject?.trajectoryPrefix?.selectedContexts);
+  collect(contextObject?.metadata?.selectedContexts);
+  return contexts.some((context) => selected.has(context));
+}