@elizaos/plugin-wallet 2.0.0-beta.1 → 2.0.3-beta.6

package/README.md

@@ -1,64 +1,89 @@
 # @elizaos/plugin-wallet
 
-Unified non-custodial wallet for elizaOS agents. Replaces the legacy fan-out across `plugin-evm`, `plugin-solana`, `plugin-raydium`, `plugin-orca`, `plugin-meteora`, `plugin-jupiter`, `plugin-lp-manager`, `plugin-clanker`, and the former `elizaos-plugin-agentwallet` stub with one canonical action+provider surface governed by [`docs/architecture/wallet-and-trading.md`](../../../docs/architecture/wallet-and-trading.md).
+Non-custodial wallet plugin for elizaOS agents. Provides EVM and Solana signing, token transfers, swaps, cross-chain bridging, on-chain governance, LP management, and market analytics behind a single unified action+provider surface.
 
-## Surface
+Replaces the former fan-out across `plugin-evm`, `plugin-solana`, `plugin-raydium`, `plugin-orca`, `plugin-meteora`, `plugin-jupiter`, `plugin-lp-manager`, and `plugin-clanker`.
 
-The plugin exposes **10 canonical planner-visible actions**:
+## Capabilities
 
-| Action | Purpose |
-|--------|---------|
-| `TRADE` | Open positions, swap, bridge. Discriminated by `kind`: `perp` (Hyperliquid), `prediction` (Polymarket), `spot` / `swap` (Li.Fi on EVM, Jupiter on Solana), `bridge` (Li.Fi / CCTP). |
-| `MANAGE_POSITION` | Close, modify, cancel orders. |
-| `QUERY_MARKET` | Read-only price / depth / funding / chart / news / sentiment. No wallet required. |
-| `QUERY_PORTFOLIO` | Balances, positions, P&L, history. |
-| `LEND` | Supply / borrow / repay / withdraw on Aave or Morpho. |
-| `MANAGE_LP` | Open / close / collect / rebalance LP positions. EVM (Uniswap V3, Aerodrome) + Solana (Raydium, Orca Whirlpools, Meteora DLMM) behind one surface. |
-| `TRANSFER` | Move value to an arbitrary external address. EVM + Solana. Always policy-checked. |
-| `SET_AUTOMATION` | DCA, threshold triggers, P&L exits. |
-| `MANAGE_AUTOMATION` | List / pause / resume / delete automations. |
-| `MINT` | Token launches via Clanker on Base. |
+### On-chain actions (via the `WALLET` action)
 
-These dispatch into **typed providers** (one per venue / data source). Adding a new venue means adding a provider, **not** a new planner verb.
+| Subaction | What it does |
+|-----------|-------------|
+| `transfer` | Send tokens to an external address. EVM or Solana. Always requires user confirmation. |
+| `swap` | Token swap via Li.Fi (EVM) or Jupiter (Solana). |
+| `bridge` | Cross-chain transfer via Li.Fi route finding or CCTP (Circle's native USDC bridge). |
+| `gov` | On-chain governance: propose, vote, queue, execute via OpenZeppelin Governor. |
 
-## Wallet abstraction
+All write operations default to `mode=prepare` (stages the transaction but does not sign or send). The agent asks the user to confirm before submitting. `dryRun=true` returns metadata without signing.
 
-Two backends behind `WalletBackend`:
+### Analytics subactions (no wallet required)
 
-- **`LocalEoaBackend`** — desktop default. EOA private keys hydrated from the OS keychain. Optional ERC-6551 token-bound account mode (via the bundled SDK at `./sdk`) for on-chain spend policy enforcement.
-- **`StewardBackend`** — cloud + mobile default. Multi-tenant Steward service is the only custody primitive in cloud. No fallback to local.
+| Subaction | What it does |
+|-----------|-------------|
+| `token_info` | Token and market data from DexScreener, Birdeye, or CoinGecko. |
+| `search_address` | Birdeye wallet portfolio lookup by address. |
 
-See `src/wallet/` for interface and impls. `ELIZA_WALLET_BACKEND=local|steward|auto` selects at runtime.
+### LP management
 
-## Layout
+Multi-DEX LP management for both EVM and Solana chains:
 
-```
-src/
-  index.ts                  # Plugin export
-  plugin.ts                 # Plugin object: actions + providers + services
-  sdk/                      # Lifted from agent-wallet-sdk (ERC-6551, x402, CCTP, swap, escrow, identity, multi-token, payment router)
-  wallet/                   # WalletBackend interface + LocalEoa + Steward
-  policy/                   # PolicyModule (local + steward bridge)
-  providers/                # Canonical providers (one per venue / data source)
-  actions/                  # Canonical actions (TRADE, MANAGE_POSITION, ...)
-  audit/                    # Append-only hash-chained audit log
-```
+- **EVM:** Uniswap V3, Aerodrome, PancakeSwap V3
+- **Solana:** Raydium CLMM, Orca Whirlpools, Meteora DLMM
 
-The `sdk/` subtree carries forward primitives from [agent-wallet-sdk](https://github.com/up2itnow0822/agent-wallet-sdk) (MIT). See `SDK-LICENSE`. The wallet/policy/providers/actions/audit subtrees implement the canonical architecture in the spec.
+Access via the `lpManagerPlugin` export; LP actions are surfaced as the `LIQUIDITY` action (via `liquidityAction`).
 
-## Migration status
+### Market analytics
 
-This plugin is being built incrementally. Tracked phases:
+- **Birdeye:** real-time prices, trending tokens, portfolio valuation.
+- **DexScreener:** pair search, token lookups.
+- **Token info:** multi-provider dispatcher (DexScreener, Birdeye, CoinGecko).
+- **DeFi news:** via `defiNewsPlugin`.
 
-- **Phase 0** — interfaces (`WalletBackend`, `CanonicalProvider`, `CanonicalAction`, `PolicyModule`, audit log schema, failure-code unions).
-- **Phase 1** — backend impls + `@elizaos/plugin-wallet` composes legacy `plugin-evm` + `plugin-solana`; migrate call sites to consume `WalletBackend` only.
-- **Phase 2** — provider lifts (13+ providers).
-- **Phase 3** — canonical action implementations.
-- **Phase 4** — approval-queue surface (SSE + decision endpoint + tray + Capacitor bridge).
-- **Phase 5** — EVM + Solana chain implementations live under `src/chains/`; migrate remaining callsites to `WalletBackend` only; expand test coverage.
+## Wallet backends
 
-See `docs/architecture/wallet-and-trading.md` §I for the dependency graph.
+The plugin supports two signing backends, selected by `ELIZA_WALLET_BACKEND`:
 
-## License
+- **`local`** — raw EOA private keys from environment variables or the OS keychain. Default for desktop.
+- **`steward`** — multi-tenant Steward signing service. Required for cloud and mobile deployments.
+- **`auto`** (default) — uses Steward when `ELIZA_CLOUD_PROVISIONED=1` or `ELIZA_WALLET_STEWARD_AUTO=1`, otherwise local.
 
-MIT. Source code under `src/sdk/` originates from [agent-wallet-sdk](https://github.com/up2itnow0822/agent-wallet-sdk) (MIT, attribution preserved in `SDK-LICENSE`).
+## Required configuration
+
+None of the variables below are strictly required at load time; the plugin degrades gracefully. To get signing:
+
+| Variable | When needed |
+|----------|-------------|
+| `EVM_PRIVATE_KEY` | EVM operations with local backend |
+| `SOLANA_PRIVATE_KEY` | Solana operations with local backend |
+| `STEWARD_API_URL` + `STEWARD_AGENT_TOKEN` | Steward backend or cloud deployments |
+| `SOLANA_RPC_URL` | Any Solana operation |
+
+Additional optional variables:
+
+| Variable | Purpose |
+|----------|---------|
+| `ELIZA_WALLET_BACKEND` | `local` \| `steward` \| `auto` |
+| `BIRDEYE_API_KEY` | Direct Birdeye access (falls back to Eliza Cloud route) |
+| `BIRDEYE_WALLET_ADDR` | Enables portfolio provider for a specific address |
+| `BIRDEYE_NO_TRENDING` | Disable trending provider |
+| `ELIZA_AGENT_WALLET_AUTO_ENABLE` | Set to `0` to disable auto-enable |
+| `X402_SUPPORTED_NETWORKS` | Comma-separated networks for x402 micropayments |
+| `X402_GLOBAL_DAILY_LIMIT` | Daily USDC spending cap for x402 |
+| `X402_PER_REQUEST_MAX` | Per-request USDC cap for x402 |
+
+EVM RPC per chain: `ETHEREUM_RPC_URL` / `EVM_PROVIDER_MAINNET`, `BASE_RPC_URL` / `EVM_PROVIDER_BASE`, `BSC_RPC_URL` / `EVM_PROVIDER_BSC`, `ARBITRUM_RPC_URL` / `EVM_PROVIDER_ARBITRUM`.
+
+## Enabling the plugin
+
+The plugin auto-enables when any signing path is present (EVM or Solana private key, or Steward credentials). To opt out of auto-enable, set `ELIZA_AGENT_WALLET_AUTO_ENABLE=0`. To explicitly disable, set `enabled: false` for plugin id `wallet` in the agent config.
+
+## Security model
+
+All on-chain writes (`transfer`, `swap`, `bridge`, `gov`) require an explicit user confirmation before execution. The LLM cannot authorize a transaction by itself — a confirmed human reply turn is always required. EVM recipient addresses on transfers are additionally validated via `assertEvmTransferRecipientAuthorized`.
+
+`src/audit/audit-log.ts` defines `AuditLogRow` plus hash-chain helpers for action validate/handler lifecycle events and signing requests. Runtime callers own where those rows are stored.
+
+## SDK
+
+`src/sdk/` provides lower-level ERC-6551 token-bound account primitives, x402 micropayment protocol types, CCTP bridge helpers, and spend-policy tooling. These are primarily for plugin internals but are re-exported from the package barrel for external use. SDK source is MIT-licensed (attribution: agent-wallet-sdk); see `SDK-LICENSE`.

package/auto-enable.ts

@@ -60,7 +60,7 @@ export function shouldEnable(ctx: PluginAutoEnableContext): boolean {
 
   if (env.ELIZA_AGENT_WALLET_AUTO_ENABLE === "0") return false;
 
-  const entries = (config?.plugins as Record<string, unknown> | undefined)
+  const entries = (config.plugins as Record<string, unknown> | undefined)
     ?.entries as Record<string, { enabled?: boolean } | undefined> | undefined;
   if (entries) {
     for (const id of ["wallet", "agent-wallet", "evm", "solana"] as const) {

package/dist/actions/failure-codes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Single source of truth for action failure modes. Every error returned to the
+ * planner carries a code from one of these unions; the `detail` string is for
+ * humans, the code is for the planner to react on.
+ *
+ * See docs/architecture/wallet-and-trading.md §E.
+ */
+export type ValidateFailureCode = "INVALID_PARAMS" | "PLUGIN_DISABLED" | "PROVIDER_UNAVAILABLE" | "PROVIDER_AUTH_MISSING" | "WALLET_NOT_AVAILABLE" | "VENUE_NOT_SUPPORTED_ON_BACKEND" | "VENUE_NOT_SUPPORTED_FOR_KIND" | "POLICY_REQUIRES_APPROVAL" | "POLICY_BLOCKED" | "INSUFFICIENT_BALANCE" | "MARKET_CLOSED" | "INSTRUMENT_NOT_FOUND" | "LEVERAGE_OUT_OF_RANGE" | "SLIPPAGE_EXCEEDED" | "WITHDRAWAL_NOT_ALLOWLISTED" | "VENUE_GEO_RESTRICTED" | "INVALID_ADDRESS" | "TOKEN_NOT_SUPPORTED" | "POOL_NOT_FOUND" | "RANGE_OUT_OF_BOUNDS";
+export type ActionFailureCode = "PROVIDER_REJECTED" | "SIGNATURE_REJECTED" | "STEWARD_UNAVAILABLE" | "ROUTE_NOT_FOUND" | "TRANSACTION_REVERTED" | "TIMEOUT";
+export type FailureCode = ValidateFailureCode | ActionFailureCode;
+export declare const isValidateFailureCode: (code: string) => code is ValidateFailureCode;
+export declare const isActionFailureCode: (code: string) => code is ActionFailureCode;

package/dist/actions/index.d.ts

@@ -0,0 +1 @@
+export * from "./failure-codes.js";

package/dist/analytics/birdeye/actions/wallet-search-address.d.ts

@@ -0,0 +1,7 @@
+import type { ActionResult, HandlerCallback, HandlerOptions, IAgentRuntime, Memory, State } from "@elizaos/core";
+/**
+ * Folded into WALLET as `action=search_address`. Forces the TokenInfoService
+ * route through the Birdeye provider with the `wallet` subaction so callers get
+ * Birdeye portfolio data for a wallet address.
+ */
+export declare function walletSearchAddressHandler(runtime: IAgentRuntime, message: Memory, state?: State, options?: HandlerOptions | Record<string, unknown>, callback?: HandlerCallback): Promise<ActionResult>;

package/dist/analytics/birdeye/birdeye-task.d.ts

@@ -0,0 +1,27 @@
+import { type Content, type IAgentRuntime, type UUID } from "@elizaos/core";
+import type { BirdeyeService } from "./service";
+export interface SentimentContent extends Content {
+    text: string;
+    source: "sentiment-analysis";
+    metadata: {
+        timeslot: string;
+        processed: boolean;
+        occuringTokens?: Array<{
+            token: string;
+            sentiment: number;
+            reason: string;
+        }>;
+    };
+}
+export default class Birdeye {
+    apiKey: string;
+    sentimentRoomId: UUID;
+    twitterFeedRoomId: UUID;
+    runtime: IAgentRuntime;
+    pSrvBirdeye: Promise<unknown>;
+    beService: BirdeyeService;
+    constructor(runtime: IAgentRuntime);
+    private syncWalletHistory;
+    private syncWalletPortfolio;
+    syncWallet(): Promise<boolean | undefined>;
+}

package/dist/analytics/birdeye/birdeye.d.ts

@@ -0,0 +1,140 @@
+import { type IAgentRuntime } from "@elizaos/core";
+import type { BaseQuoteParams, BaseQuoteResponse, DefiHistoryPriceParams, DefiHistoryPriceResponse, DefiMultiPriceParams, DefiMultiPriceParamsPOST, DefiMultiPriceResponse, DefiNetworksResponse, DefiPriceParams, DefiPriceResponse, DefiTradesTokenParams, DefiTradesTokenResponse, HistoricalPriceUnixParams, HistoricalPriceUnixResponse, MultiPriceVolumeParams, MultiPriceVolumeResponse, OHLCVParams, OHLCVResponse, PriceVolumeParams, PriceVolumeResponse } from "./types/api/defi";
+import type { OHLCVPairParams, OHLCVPairResponse, PairOverviewMultiParams, PairOverviewMultiResponse, PairOverviewSingleParams, PairOverviewSingleResponse } from "./types/api/pair";
+import type { TokenMarketSearchParams, TokenMarketSearchResponse } from "./types/api/search";
+import type { AllMarketsParams, AllMarketsResponse, MintBurnParams, MintBurnResponse, NewListingParams, NewListingResponse, TokenCreationInfoParams, TokenCreationInfoResponse, TokenHoldersParams, TokenHoldersResponse, TokenListParams, TokenListResponse, TokenListV2Response, TokenMarketDataParams, TokenMarketDataResponse, TokenMetadataMultiParams, TokenMetadataMultiResponse, TokenMetadataSingleParams, TokenMetadataSingleResponse, TokenOverviewParams, TokenOverviewResponse, TokenSecurityParams, TokenSecurityResponse, TokenTradeDataMultiParams, TokenTradeDataMultiResponse, TokenTradeDataSingleParams, TokenTradeDataSingleResponse, TokenTrendingParams, TokenTrendingResponse, TopTradersParams, TopTradersResponse } from "./types/api/token";
+import type { GainersLosersParams, GainersLosersResponse, TraderTransactionsSeekParams, TraderTransactionsSeekResponse } from "./types/api/trader";
+import type { WalletPortfolioParams, WalletPortfolioResponse, WalletSimulationParams, WalletSimulationResponse, WalletTokenBalanceParams, WalletTokenBalanceResponse, WalletTransactionHistoryParams, WalletTransactionHistoryResponse } from "./types/api/wallet";
+type FetchParams<T> = T & {
+    headers?: Record<string, string>;
+};
+export declare class BirdeyeProvider {
+    private runtime;
+    private maxRetries;
+    constructor(runtime: Pick<IAgentRuntime, "getCache" | "setCache">, _symbolMap?: Record<string, string>, maxRetries?: number);
+    private fetchWithRetry;
+    private fetchWithCacheAndRetry;
+    fetchDefiSupportedNetworks(): Promise<DefiNetworksResponse>;
+    fetchDefiPrice(params: DefiPriceParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<DefiPriceResponse>;
+    fetchDefiPriceMultiple(params: DefiMultiPriceParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<DefiMultiPriceResponse>;
+    fetchDefiPriceMultiple_POST(params: DefiMultiPriceParamsPOST, options?: {
+        headers?: Record<string, string>;
+    }): Promise<DefiMultiPriceResponse>;
+    fetchDefiPriceHistorical(params: DefiHistoryPriceParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<DefiHistoryPriceResponse>;
+    fetchDefiPriceHistoricalByUnixTime(params: HistoricalPriceUnixParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<HistoricalPriceUnixResponse>;
+    fetchDefiTradesToken(params: DefiTradesTokenParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<DefiTradesTokenResponse>;
+    fetchDefiTradesPair(params: DefiTradesTokenParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<DefiTradesTokenResponse>;
+    fetchDefiTradesTokenSeekByTime(params: DefiTradesTokenParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<DefiTradesTokenResponse>;
+    fetchDefiTradesPairSeekByTime(params: DefiTradesTokenParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<DefiTradesTokenResponse>;
+    fetchDefiOHLCV(params: OHLCVParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<OHLCVResponse>;
+    fetchDefiOHLCVPair(params: OHLCVPairParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<OHLCVPairResponse>;
+    fetchDefiOHLCVBaseQuote(params: BaseQuoteParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<BaseQuoteResponse>;
+    fetchDefiPriceVolume(params: PriceVolumeParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<PriceVolumeResponse>;
+    fetchDefiPriceVolumeMulti_POST(params: MultiPriceVolumeParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<MultiPriceVolumeResponse>;
+    fetchTokenList(params: TokenListParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TokenListResponse>;
+    fetchTokenSecurityByAddress(params: TokenSecurityParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TokenSecurityResponse>;
+    fetchTokenOverview(params: TokenOverviewParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TokenOverviewResponse>;
+    fetchTokenCreationInfo(params: TokenCreationInfoParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TokenCreationInfoResponse>;
+    fetchTokenTrending(params?: TokenTrendingParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TokenTrendingResponse>;
+    fetchTokenListV2_POST(params: FetchParams<Record<string, never>>): Promise<TokenListV2Response>;
+    fetchTokenNewListing(params?: NewListingParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<NewListingResponse>;
+    fetchTokenTopTraders(params: TopTradersParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TopTradersResponse>;
+    fetchTokenAllMarketsList(params: AllMarketsParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<AllMarketsResponse>;
+    fetchTokenMetadataSingle(params: TokenMetadataSingleParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TokenMetadataSingleResponse>;
+    fetchTokenMetadataMulti(params: TokenMetadataMultiParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TokenMetadataMultiResponse>;
+    fetchTokenMarketData(params: TokenMarketDataParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TokenMarketDataResponse>;
+    fetchTokenTradeDataSingle(params: TokenTradeDataSingleParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TokenTradeDataSingleResponse>;
+    fetchTokenTradeDataMultiple(params: TokenTradeDataMultiParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TokenTradeDataMultiResponse>;
+    fetchTokenHolders(params: TokenHoldersParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TokenHoldersResponse>;
+    fetchTokenMintBurn(params: MintBurnParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<MintBurnResponse>;
+    fetchWalletSupportedNetworks(options?: {
+        headers?: Record<string, string>;
+    }): Promise<DefiNetworksResponse>;
+    fetchWalletPortfolio(params: WalletPortfolioParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<WalletPortfolioResponse>;
+    fetchWalletTokenBalance(params: WalletTokenBalanceParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<WalletTokenBalanceResponse>;
+    fetchWalletTransactionHistory(params: WalletTransactionHistoryParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<WalletTransactionHistoryResponse>;
+    fetchWalletTransactionSimulate_POST(params: WalletSimulationParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<WalletSimulationResponse>;
+    fetchTraderGainersLosers(params: GainersLosersParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<GainersLosersResponse>;
+    fetchTraderTransactionsSeek(params: TraderTransactionsSeekParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TraderTransactionsSeekResponse>;
+    fetchPairOverviewSingle(params: PairOverviewSingleParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<PairOverviewSingleResponse>;
+    fetchMultiPairOverview(params: PairOverviewMultiParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<PairOverviewMultiResponse>;
+    fetchPairOverviewMultiple(params: PairOverviewMultiParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<PairOverviewMultiResponse>;
+    fetchSearchTokenMarketData(params: TokenMarketSearchParams, options?: {
+        headers?: Record<string, string>;
+    }): Promise<TokenMarketSearchResponse>;
+}
+export {};

package/dist/analytics/birdeye/constants.d.ts

@@ -0,0 +1,68 @@
+export declare const DEFAULT_MAX_RETRIES = 3;
+export declare const BIRDEYE_SERVICE_NAME = "birdeye";
+export declare const DEFAULT_SUPPORTED_SYMBOLS: {
+    SOL: string;
+    BTC: string;
+    ETH: string;
+    Example: string;
+};
+export declare const API_BASE_URL = "https://public-api.birdeye.so";
+export declare const RETRY_DELAY_MS = 2000;
+export declare const BIRDEYE_ENDPOINTS: {
+    defi: {
+        networks: string;
+        price: string;
+        price_multi: string;
+        price_multi_POST: string;
+        history_price: string;
+        historical_price_unix: string;
+        trades_token: string;
+        trades_pair: string;
+        trades_token_seek: string;
+        trades_pair_seek: string;
+        ohlcv: string;
+        ohlcv_pair: string;
+        ohlcv_base_quote: string;
+        price_volume: string;
+        price_volume_multi: string;
+        price_volume_multi_POST: string;
+    };
+    token: {
+        list_all: string;
+        security: string;
+        overview: string;
+        creation_info: string;
+        trending: string;
+        list_all_v2_POST: string;
+        new_listing: string;
+        top_traders: string;
+        all_markets: string;
+        metadata_single: string;
+        metadata_multi: string;
+        market_data: string;
+        trade_data_single: string;
+        trade_data_multi: string;
+        holders: string;
+        mint_burn: string;
+    };
+    wallet: {
+        networks: string;
+        portfolio: string;
+        portfolio_multichain: string;
+        token_balance: string;
+        transaction_history: string;
+        transaction_history_multichain: string;
+        transaction_simulation_POST: string;
+    };
+    trader: {
+        gainers_losers: string;
+        trades_seek: string;
+    };
+    pair: {
+        overview_multi: string;
+        overview_single: string;
+    };
+    search: {
+        token_market: string;
+    };
+};

package/dist/analytics/birdeye/providers/agent-portfolio-provider.d.ts

@@ -0,0 +1,8 @@
+import { formatPortfolio } from "./portfolio-factory";
+/**
+ * Agent portfolio data provider that queries Birdeye API for the agent's wallet address.
+ * When a wallet address is set, this provider fetches current token balances and makes
+ * compact JSON portfolio context available to the planner.
+ */
+export declare const agentPortfolioProvider: import("@elizaos/core").Provider;
+export { formatPortfolio };

package/dist/analytics/birdeye/providers/market.d.ts

@@ -0,0 +1,18 @@
+import type { IAgentRuntime, Provider } from "@elizaos/core";
+import type { GetCacheTimedOptions } from "../types/shared";
+export declare function getCacheTimed<T>(runtime: IAgentRuntime, key: string, options?: GetCacheTimedOptions): Promise<T | undefined>;
+/**
+ * Provider for Birdeye market data
+ *
+ * @type {Provider}
+ * @property {string} name - The name of the provider
+ * @property {string} description - Description of the provider
+ * @property {number} position - The position of the provider
+ * @property {Function} get - Asynchronous function to get actions that validate for a given message
+ *
+ * @param {IAgentRuntime} runtime - The agent runtime
+ * @param {Memory} message - The message memory
+ * @param {State} state - The state of the agent
+ * @returns {Object} Object containing data, values, and text related to actions
+ */
+export declare const marketProvider: Provider;

package/dist/analytics/birdeye/providers/portfolio-factory.d.ts

@@ -0,0 +1,10 @@
+import type { Provider } from "@elizaos/core";
+import type { WalletPortfolioResponse } from "../types/api/wallet";
+export interface BirdeyePortfolioProviderOptions {
+    name: string;
+    description: string;
+    descriptionCompressed: string;
+    includeTrades?: boolean;
+}
+export declare const formatPortfolio: (response: WalletPortfolioResponse) => string;
+export declare function createBirdeyePortfolioProvider(options: BirdeyePortfolioProviderOptions): Provider;

package/dist/analytics/birdeye/providers/trending.d.ts

@@ -0,0 +1,19 @@
+import type { IAgentRuntime, Provider } from "@elizaos/core";
+export declare function getCacheTimed<T>(runtime: IAgentRuntime, key: string, options?: {
+    notOlderThan?: number;
+}): Promise<T | false>;
+/**
+ * Provider for Birdeye trending coins
+ *
+ * @type {Provider}
+ * @property {string} name - The name of the provider
+ * @property {string} description - Description of the provider
+ * @property {number} position - The position of the provider
+ * @property {Function} get - Asynchronous function to get actions that validate for a given message
+ *
+ * @param {IAgentRuntime} runtime - The agent runtime
+ * @param {Memory} message - The message memory
+ * @param {State} state - The state of the agent
+ * @returns {Object} Object containing data, values, and text related to actions
+ */
+export declare const trendingProvider: Provider;

package/dist/analytics/birdeye/providers/wallet.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Optional wallet trade provider. It shares wallet, chain, service, error, and JSON
+ * formatting behavior with the agent portfolio provider through the portfolio factory.
+ */
+export declare const tradePortfolioProvider: import("@elizaos/core").Provider;

package/dist/analytics/birdeye/search-category.d.ts

@@ -0,0 +1,52 @@
+import type { IAgentRuntime, SearchCategoryRegistration } from "@elizaos/core";
+import { BirdeyeProvider } from "./birdeye";
+import type { TokenResult } from "./types/api/search";
+import type { TokenMarketDataResponse, TokenOverviewResponse, TokenSecurityResponse, TokenTradeDataSingleResponse } from "./types/api/token";
+import type { BaseAddress } from "./types/shared";
+export declare const BIRDEYE_TOKEN_SEARCH_CATEGORY: SearchCategoryRegistration;
+export declare const BIRDEYE_SEARCH_CATEGORIES: readonly [SearchCategoryRegistration];
+export interface BirdeyeSearchCategoryOptions {
+    enabled?: boolean;
+    disabledReason?: string;
+}
+export type BirdeyeTokenSearchMode = "auto" | "symbol" | "address";
+export interface BirdeyeTokenSearchRequest {
+    query: string;
+    mode?: BirdeyeTokenSearchMode;
+    filters?: Record<string, unknown>;
+    limit?: number;
+}
+type BirdeyeTokenAddressSearchResult = {
+    address: BaseAddress;
+    chain: string;
+    overview?: TokenOverviewResponse;
+    marketData?: TokenMarketDataResponse;
+    security?: TokenSecurityResponse;
+    tradeData?: TokenTradeDataSingleResponse;
+};
+type BirdeyeTokenSymbolSearchResult = {
+    symbol: string;
+    tokens: TokenResult[];
+};
+type BirdeyeTokenSearchProvider = Pick<BirdeyeProvider, "fetchSearchTokenMarketData" | "fetchTokenOverview" | "fetchTokenMarketData" | "fetchTokenSecurityByAddress" | "fetchTokenTradeDataSingle">;
+export declare function registerBirdeyeSearchCategories(runtime: IAgentRuntime, options?: BirdeyeSearchCategoryOptions): void;
+export declare function searchBirdeyeTokens(runtime: IAgentRuntime, request: BirdeyeTokenSearchRequest, provider?: BirdeyeTokenSearchProvider): Promise<{
+    query: string;
+    mode: "symbol" | "address";
+    resultCount: number;
+    results: never[];
+    text: string;
+} | {
+    query: string;
+    mode: "address";
+    resultCount: number;
+    results: BirdeyeTokenAddressSearchResult[];
+    text: string;
+} | {
+    query: string;
+    mode: "symbol";
+    resultCount: number;
+    results: BirdeyeTokenSymbolSearchResult[];
+    text: string;
+}>;
+export {};

package/dist/analytics/birdeye/service.d.ts

@@ -0,0 +1,94 @@
+import { type RouteSpec } from "@elizaos/cloud-routing";
+import { type IAgentRuntime, Service } from "@elizaos/core";
+import type { TokenMarketSearchParams, TokenMarketSearchResponse } from "./types/api/search";
+import type { TokenMarketDataParams, TokenMarketDataResponse, TokenOverviewParams, TokenOverviewResponse, TokenSecurityParams, TokenSecurityResponse, TokenTradeDataSingleParams, TokenTradeDataSingleResponse } from "./types/api/token";
+import type { WalletPortfolioResponse, WalletTransactionHistoryResponse } from "./types/api/wallet";
+import type { BirdeyeSupportedChain, GetCacheTimedOptions, IToken } from "./types/shared";
+/** Route spec for {@link resolveCloudRoute} — local X-API-KEY or Eliza Cloud `/apis/birdeye` proxy. */
+export declare const BIRDEYE_ROUTE_SPEC: RouteSpec;
+type Chain = string;
+type BirdeyeHeaders = {
+    headers?: Record<string, string>;
+};
+export interface BirdeyeTokenMarketSnapshot {
+    symbol?: string;
+    priceUsd: number;
+    priceSol?: number;
+    liquidity: number;
+    priceChange24h: number;
+    marketCapUsd?: number;
+}
+type WalletTransaction = WalletTransactionHistoryResponse["data"][string][number];
+export declare class BirdeyeService extends Service {
+    static serviceType: string;
+    capabilityDescription: string;
+    private readonly access;
+    constructor(runtime?: IAgentRuntime);
+    private birdeyeUrl;
+    private getBirdeyeFetchOptions;
+    private fetchBirdeyeJson;
+    fetchSearchTokenMarketData(params: TokenMarketSearchParams): Promise<TokenMarketSearchResponse>;
+    fetchTokenOverview(params: TokenOverviewParams, options?: BirdeyeHeaders): Promise<TokenOverviewResponse>;
+    fetchTokenMarketData(params: TokenMarketDataParams, options?: BirdeyeHeaders): Promise<TokenMarketDataResponse>;
+    fetchTokenSecurityByAddress(params: TokenSecurityParams, options?: BirdeyeHeaders): Promise<TokenSecurityResponse>;
+    fetchTokenTradeDataSingle(params: TokenTradeDataSingleParams, options?: BirdeyeHeaders): Promise<TokenTradeDataSingleResponse>;
+    search(query: string, options?: Record<string, unknown>): Promise<{
+        query: string;
+        mode: "symbol" | "address";
+        resultCount: number;
+        results: never[];
+        text: string;
+    } | {
+        query: string;
+        mode: "address";
+        resultCount: number;
+        results: {
+            address: import("./types/shared").BaseAddress;
+            chain: string;
+            overview?: TokenOverviewResponse;
+            marketData?: TokenMarketDataResponse;
+            security?: TokenSecurityResponse;
+            tradeData?: TokenTradeDataSingleResponse;
+        }[];
+        text: string;
+    } | {
+        query: string;
+        mode: "symbol";
+        resultCount: number;
+        results: {
+            symbol: string;
+            tokens: import("./types/api/search").TokenResult[];
+        }[];
+        text: string;
+    }>;
+    getTrending(): Promise<IToken[] | undefined>;
+    private getTrendingTokensForChain;
+    getTrendingTokens(chains: Chain[], options?: {
+        notOlderThan?: number;
+    }): Promise<Record<Chain, IToken[]>>;
+    getTokenMarketData(tokenAddress: string, chain?: string): Promise<{
+        price: number;
+        marketCap: number;
+        liquidity: number;
+        volume24h: number;
+        priceHistory: number[];
+    } | false>;
+    getTokenTradeData(chain: string, tokenAddress: string, frames?: string, options?: GetCacheTimedOptions): Promise<TokenTradeDataSingleResponse | false>;
+    getTokensMarketData(chain: string, tokenAddresses: string[], options?: GetCacheTimedOptions): Promise<Record<string, BirdeyeTokenMarketSnapshot | undefined>>;
+    getTokenSecurityData(chain: string, tokenAddress: string, options?: GetCacheTimedOptions): Promise<TokenSecurityResponse | false>;
+    lookupToken(chain: string, ca: string, options?: GetCacheTimedOptions): Promise<BirdeyeTokenMarketSnapshot | undefined>;
+    lookupTokens(chainAndAddresses: Array<{
+        chain: string;
+        address: string;
+    }>, options?: GetCacheTimedOptions): Promise<Record<string, BirdeyeTokenMarketSnapshot | undefined>>;
+    fetchSearchTokenMarketDataChain(chain: string, _params: unknown, _options?: GetCacheTimedOptions): Promise<TokenMarketSearchResponse>;
+    lookupSymbolAllChains(symbol: string, options?: GetCacheTimedOptions): Promise<TokenMarketSearchResponse["data"]["items"] | false>;
+    fetchWalletTokenList(chain: BirdeyeSupportedChain, publicKey: string, options?: GetCacheTimedOptions): Promise<WalletPortfolioResponse["data"] | false>;
+    fetchWalletTxList(chain: BirdeyeSupportedChain, publicKey: string, options?: GetCacheTimedOptions): Promise<WalletTransaction[] | false>;
+    static start(runtime: IAgentRuntime): Promise<BirdeyeService>;
+    static stop(runtime: IAgentRuntime): Promise<void>;
+    stop(): Promise<void>;
+    getCacheTimed<T>(key: string, options?: GetCacheTimedOptions): Promise<false | T>;
+    setCacheTimed<T>(key: string, val: T, tsInMs?: number): Promise<boolean>;
+}
+export {};