0.1.0 initial scaffolding

cdp-agentkit-core/typescript/package.json

@@ -7,7 +7,9 @@
  "license": "Apache-2.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
- "files": ["dist"],
+ "files": [
+ "dist"
+ ],
  "scripts": {
  "build": "tsc",
  "lint": "npx --yes eslint -c .eslintrc.json src/**/*.ts",
@@ -38,8 +40,9 @@
  ],
  "dependencies": {
  "@coinbase/coinbase-sdk": "^0.15.0",
+ "reflect-metadata": "^0.2.2",
  "twitter-api-v2": "^1.18.2",
- "viem": "^2.21.51",
+ "viem": "^2.22.16",
  "zod": "^3.23.8"
  },
  "devDependencies": {

cdp-agentkit-core/typescript/src/action_providers/action_decorator.ts

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+
+import "reflect-metadata";
+
+/**
+ * Parameters for the create action decorator
+ */
+export interface CreateActionDecoratorParams {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+}
+
+/**
+ * Metadata key for the action decorator
+ */
+export const ACTION_DECORATOR_KEY = Symbol("agentkit:action");
+
+/**
+ * Metadata for AgentKit actions
+ */
+export interface ActionMetadata {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+
+ /**
+ * The function to invoke the action
+ */
+ invoke: Function;
+
+ /**
+ * The wallet provider to use for the action
+ */
+ walletProvider: boolean;
+}
+
+/**
+ * A map of action names to their metadata
+ */
+export type StoredActionMetadata = Map<string, ActionMetadata>;
+
+/**
+ * Decorator to embed metadata on class methods to indicate they are actions accessible to the agent
+ *
+ * @param params - The parameters for the action decorator
+ * @returns A decorator function
+ *
+ * @example
+ * ```typescript
+ * class MyActionProvider extends ActionProvider {
+ * @CreateAction({ name: "my_action", description: "My action", schema: myActionSchema })
+ * public myAction(args: z.infer<typeof myActionSchema>) {
+ * // ...
+ * }
+ * }
+ * ```
+ */
+export function CreateAction(params: CreateActionDecoratorParams) {
+ return (target: Object, propertyKey: string, descriptor: PropertyDescriptor) => {
+ const existingMetadata: StoredActionMetadata =
+ Reflect.getMetadata(ACTION_DECORATOR_KEY, target.constructor) || new Map();
+
+ const { isWalletProvider } = validateActionMethodArguments(target, propertyKey);
+
+ const metaData: ActionMetadata = {
+ name: params.name,
+ description: params.description,
+ schema: params.schema,
+ invoke: descriptor.value,
+ walletProvider: isWalletProvider,
+ };
+
+ existingMetadata.set(propertyKey, metaData);
+
+ Reflect.defineMetadata(ACTION_DECORATOR_KEY, existingMetadata, target.constructor);
+
+ return target;
+ };
+}
+
+function validateActionMethodArguments(
+ target: Object,
+ propertyKey: string,
+): {
+ isWalletProvider: boolean;
+} {
+ const className = target instanceof Object ? target.constructor.name : undefined;
+
+ const params = Reflect.getMetadata("design:paramtypes", target, propertyKey);
+
+ if (params == null) {
+ throw new Error(
+ `Failed to get parameters for action method ${propertyKey} on class ${className}`,
+ );
+ }
+
+ if (params.length > 2) {
+ throw new Error(
+ `Action method ${propertyKey} on class ${className} has more than 2 parameters`,
+ );
+ }
+
+ const walletProviderParam = params.find(param => {
+ if (!param || !param.prototype) {
+ return false;
+ }
+
+ if (param === WalletProvider) return true;
+ return param.prototype instanceof WalletProvider;
+ });
+
+ return {
+ isWalletProvider: !!walletProviderParam,
+ };
+}

cdp-agentkit-core/typescript/src/action_providers/action_provider.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+import { Network } from "../wallet_providers/wallet_provider";
+import { StoredActionMetadata, ACTION_DECORATOR_KEY } from "./action_decorator";
+
+/**
+ * Action is the interface for all actions.
+ */
+export interface Action<TActionSchema extends z.ZodSchema = z.ZodSchema> {
+ name: string;
+ description: string;
+ schema: TActionSchema;
+ invoke: (args: z.infer<TActionSchema>) => Promise<string>;
+}
+
+/**
+ * ActionProvider is the abstract base class for all action providers.
+ *
+ * @abstract
+ */
+export abstract class ActionProvider<TWalletProvider extends WalletProvider = WalletProvider> {
+ /**
+ * The name of the action provider.
+ */
+ public readonly name: string;
+
+ /**
+ * The action providers to combine.
+ */
+ public readonly actionProviders: ActionProvider<TWalletProvider>[];
+
+ /**
+ * The constructor for the action provider.
+ *
+ * @param name - The name of the action provider.
+ * @param actionProviders - The action providers to combine.
+ */
+ constructor(name: string, actionProviders: ActionProvider<TWalletProvider>[]) {
+ this.name = name;
+ this.actionProviders = actionProviders;
+ }
+
+ /**
+ * Checks if the action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the action provider supports the network, false otherwise.
+ */
+ abstract supportsNetwork(network: Network): boolean;
+
+ /**
+ * Gets the actions of the action provider bound to the given wallet provider.
+ *
+ * @param walletProvider - The wallet provider.
+ * @returns The actions of the action provider.
+ */
+ getActions(walletProvider: TWalletProvider): Action[] {
+ const actions: Action[] = [];
+
+ const actionProviders = [this, ...this.actionProviders];
+
+ for (const actionProvider of actionProviders) {
+ const actionsMetadataMap: StoredActionMetadata | undefined = Reflect.getMetadata(
+ ACTION_DECORATOR_KEY,
+ actionProvider.constructor,
+ );
+
+ if (!actionsMetadataMap) {
+ if (!(actionProvider instanceof ActionProvider)) {
+ console.warn(`Warning: ${actionProvider} is not an instance of ActionProvider.`);
+ } else {
+ console.warn(`Warning: ${actionProvider} has no actions.`);
+ }
+
+ continue;
+ }
+
+ for (const actionMetadata of actionsMetadataMap.values()) {
+ actions.push({
+ name: actionMetadata.name,
+ description: actionMetadata.description,
+ schema: actionMetadata.schema,
+ invoke: schemaArgs => {
+ const args: any[] = [];
+ if (actionMetadata.walletProvider) {
+ args[0] = walletProvider;
+ }
+
+ args.push(schemaArgs);
+
+ return actionMetadata.invoke.apply(actionProvider, args);
+ },
+ });
+ }
+ }
+
+ return actions;
+ }
+}

cdp-agentkit-core/typescript/src/action_providers/index.ts

@@ -0,0 +1,4 @@
+export * from "./action_decorator";
+export * from "./action_provider";
+
+export * from "./pyth";

cdp-agentkit-core/typescript/src/action_providers/pyth/README.md

@@ -0,0 +1 @@
+# Pyth Action Provider

cdp-agentkit-core/typescript/src/action_providers/pyth/index.ts

@@ -0,0 +1,2 @@
+export * from "./pyth_action_provider";
+export * from "./schemas";

cdp-agentkit-core/typescript/src/action_providers/pyth/pyth_action_provider.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { ActionProvider } from "../action_provider";
+import { Network } from "../../wallet_providers/wallet_provider";
+import { CreateAction } from "../action_decorator";
+import { PythFetchPriceFeedIDSchema, PythFetchPriceSchema } from "./schemas";
+
+/**
+ * PythActionProvider is an action provider for Pyth.
+ */
+export class PythActionProvider extends ActionProvider {
+ constructor() {
+ super("pyth", []);
+ }
+
+ /**
+ * Checks if the Pyth action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the Pyth action provider supports the network, false otherwise.
+ */
+ supportsNetwork = (_: Network) => true;
+
+ /**
+ * Fetch the price feed ID for a given token symbol from Pyth.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price feed ID as a string.
+ */
+ @CreateAction({
+ name: "fetch_price_feed",
+ description: "Fetch the price feed ID for a given token symbol from Pyth.",
+ schema: PythFetchPriceFeedIDSchema,
+ })
+ async fetchPriceFeed(args: z.infer<typeof PythFetchPriceFeedIDSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/price_feeds?query=${args.tokenSymbol}&asset_type=crypto`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+
+ if (data.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ const filteredData = data.filter(
+ (item: any) => item.attributes.base.toLowerCase() === args.tokenSymbol.toLowerCase(),
+ );
+
+ if (filteredData.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ return filteredData[0].id;
+ }
+
+ /**
+ * Fetches the price from Pyth given a Pyth price feed ID.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price as a string.
+ */
+ @CreateAction({
+ name: "fetch_price",
+ description: `Fetch the price of a given price feed from Pyth.
+
+Inputs:
+- Pyth price feed ID
+
+Important notes:
+- Do not assume that a random ID is a Pyth price feed ID. If you are confused, ask a clarifying question.
+- This action only fetches price inputs from Pyth price feeds. No other source.
+- If you are asked to fetch the price from Pyth for a ticker symbol such as BTC, you must first use the pyth_fetch_price_feed_id
+action to retrieve the price feed ID before invoking the pyth_Fetch_price action
+`,
+ schema: PythFetchPriceSchema
+ })
+ async fetchPrice(args: z.infer<typeof PythFetchPriceSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/updates/price/latest?ids[]=${args.priceFeedID}`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+ const parsedData = data.parsed;
+
+ if (parsedData.length === 0) {
+ throw new Error(`No price data found for ${args.priceFeedID}`);
+ }
+
+ const priceInfo = parsedData[0].price;
+ const price = BigInt(priceInfo.price);
+ const exponent = priceInfo.expo;
+
+ if (exponent < 0) {
+ const adjustedPrice = price * BigInt(100);
+ const divisor = BigInt(10) ** BigInt(-exponent);
+ const scaledPrice = adjustedPrice / BigInt(divisor);
+ const priceStr = scaledPrice.toString();
+ const formattedPrice = `${priceStr.slice(0, -2)}.${priceStr.slice(-2)}`;
+ return formattedPrice.startsWith(".") ? `0${formattedPrice}` : formattedPrice;
+ }
+
+ const scaledPrice = price / BigInt(10) ** BigInt(exponent);
+ return scaledPrice.toString();
+ }
+}
+
+export const pythActionProvider = () => new PythActionProvider();

cdp-agentkit-core/typescript/package.json

@@ -7,7 +7,9 @@
  "license": "Apache-2.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
- "files": ["dist"],
+ "files": [
+ "dist"
+ ],
  "scripts": {
  "build": "tsc",
  "lint": "npx --yes eslint -c .eslintrc.json src/**/*.ts",
@@ -38,8 +40,9 @@
  ],
  "dependencies": {
  "@coinbase/coinbase-sdk": "^0.15.0",
+ "reflect-metadata": "^0.2.2",
  "twitter-api-v2": "^1.18.2",
- "viem": "^2.21.51",
+ "viem": "^2.22.16",
  "zod": "^3.23.8"
  },
  "devDependencies": {

cdp-agentkit-core/typescript/src/action_providers/action_decorator.ts

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+
+import "reflect-metadata";
+
+/**
+ * Parameters for the create action decorator
+ */
+export interface CreateActionDecoratorParams {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+}
+
+/**
+ * Metadata key for the action decorator
+ */
+export const ACTION_DECORATOR_KEY = Symbol("agentkit:action");
+
+/**
+ * Metadata for AgentKit actions
+ */
+export interface ActionMetadata {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+
+ /**
+ * The function to invoke the action
+ */
+ invoke: Function;
+
+ /**
+ * The wallet provider to use for the action
+ */
+ walletProvider: boolean;
+}
+
+/**
+ * A map of action names to their metadata
+ */
+export type StoredActionMetadata = Map<string, ActionMetadata>;
+
+/**
+ * Decorator to embed metadata on class methods to indicate they are actions accessible to the agent
+ *
+ * @param params - The parameters for the action decorator
+ * @returns A decorator function
+ *
+ * @example
+ * ```typescript
+ * class MyActionProvider extends ActionProvider {
+ * @CreateAction({ name: "my_action", description: "My action", schema: myActionSchema })
+ * public myAction(args: z.infer<typeof myActionSchema>) {
+ * // ...
+ * }
+ * }
+ * ```
+ */
+export function CreateAction(params: CreateActionDecoratorParams) {
+ return (target: Object, propertyKey: string, descriptor: PropertyDescriptor) => {
+ const existingMetadata: StoredActionMetadata =
+ Reflect.getMetadata(ACTION_DECORATOR_KEY, target.constructor) || new Map();
+
+ const { isWalletProvider } = validateActionMethodArguments(target, propertyKey);
+
+ const metaData: ActionMetadata = {
+ name: params.name,
+ description: params.description,
+ schema: params.schema,
+ invoke: descriptor.value,
+ walletProvider: isWalletProvider,
+ };
+
+ existingMetadata.set(propertyKey, metaData);
+
+ Reflect.defineMetadata(ACTION_DECORATOR_KEY, existingMetadata, target.constructor);
+
+ return target;
+ };
+}
+
+function validateActionMethodArguments(
+ target: Object,
+ propertyKey: string,
+): {
+ isWalletProvider: boolean;
+} {
+ const className = target instanceof Object ? target.constructor.name : undefined;
+
+ const params = Reflect.getMetadata("design:paramtypes", target, propertyKey);
+
+ if (params == null) {
+ throw new Error(
+ `Failed to get parameters for action method ${propertyKey} on class ${className}`,
+ );
+ }
+
+ if (params.length > 2) {
+ throw new Error(
+ `Action method ${propertyKey} on class ${className} has more than 2 parameters`,
+ );
+ }
+
+ const walletProviderParam = params.find(param => {
+ if (!param || !param.prototype) {
+ return false;
+ }
+
+ if (param === WalletProvider) return true;
+ return param.prototype instanceof WalletProvider;
+ });
+
+ return {
+ isWalletProvider: !!walletProviderParam,
+ };
+}

cdp-agentkit-core/typescript/src/action_providers/action_provider.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+import { Network } from "../wallet_providers/wallet_provider";
+import { StoredActionMetadata, ACTION_DECORATOR_KEY } from "./action_decorator";
+
+/**
+ * Action is the interface for all actions.
+ */
+export interface Action<TActionSchema extends z.ZodSchema = z.ZodSchema> {
+ name: string;
+ description: string;
+ schema: TActionSchema;
+ invoke: (args: z.infer<TActionSchema>) => Promise<string>;
+}
+
+/**
+ * ActionProvider is the abstract base class for all action providers.
+ *
+ * @abstract
+ */
+export abstract class ActionProvider<TWalletProvider extends WalletProvider = WalletProvider> {
+ /**
+ * The name of the action provider.
+ */
+ public readonly name: string;
+
+ /**
+ * The action providers to combine.
+ */
+ public readonly actionProviders: ActionProvider<TWalletProvider>[];
+
+ /**
+ * The constructor for the action provider.
+ *
+ * @param name - The name of the action provider.
+ * @param actionProviders - The action providers to combine.
+ */
+ constructor(name: string, actionProviders: ActionProvider<TWalletProvider>[]) {
+ this.name = name;
+ this.actionProviders = actionProviders;
+ }
+
+ /**
+ * Checks if the action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the action provider supports the network, false otherwise.
+ */
+ abstract supportsNetwork(network: Network): boolean;
+
+ /**
+ * Gets the actions of the action provider bound to the given wallet provider.
+ *
+ * @param walletProvider - The wallet provider.
+ * @returns The actions of the action provider.
+ */
+ getActions(walletProvider: TWalletProvider): Action[] {
+ const actions: Action[] = [];
+
+ const actionProviders = [this, ...this.actionProviders];
+
+ for (const actionProvider of actionProviders) {
+ const actionsMetadataMap: StoredActionMetadata | undefined = Reflect.getMetadata(
+ ACTION_DECORATOR_KEY,
+ actionProvider.constructor,
+ );
+
+ if (!actionsMetadataMap) {
+ if (!(actionProvider instanceof ActionProvider)) {
+ console.warn(`Warning: ${actionProvider} is not an instance of ActionProvider.`);
+ } else {
+ console.warn(`Warning: ${actionProvider} has no actions.`);
+ }
+
+ continue;
+ }
+
+ for (const actionMetadata of actionsMetadataMap.values()) {
+ actions.push({
+ name: actionMetadata.name,
+ description: actionMetadata.description,
+ schema: actionMetadata.schema,
+ invoke: schemaArgs => {
+ const args: any[] = [];
+ if (actionMetadata.walletProvider) {
+ args[0] = walletProvider;
+ }
+
+ args.push(schemaArgs);
+
+ return actionMetadata.invoke.apply(actionProvider, args);
+ },
+ });
+ }
+ }
+
+ return actions;
+ }
+}

cdp-agentkit-core/typescript/src/action_providers/index.ts

@@ -0,0 +1,4 @@
+export * from "./action_decorator";
+export * from "./action_provider";
+
+export * from "./pyth";

cdp-agentkit-core/typescript/src/action_providers/pyth/README.md

@@ -0,0 +1 @@
+# Pyth Action Provider

cdp-agentkit-core/typescript/src/action_providers/pyth/index.ts

@@ -0,0 +1,2 @@
+export * from "./pyth_action_provider";
+export * from "./schemas";

cdp-agentkit-core/typescript/src/action_providers/pyth/pyth_action_provider.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { ActionProvider } from "../action_provider";
+import { Network } from "../../wallet_providers/wallet_provider";
+import { CreateAction } from "../action_decorator";
+import { PythFetchPriceFeedIDSchema, PythFetchPriceSchema } from "./schemas";
+
+/**
+ * PythActionProvider is an action provider for Pyth.
+ */
+export class PythActionProvider extends ActionProvider {
+ constructor() {
+ super("pyth", []);
+ }
+
+ /**
+ * Checks if the Pyth action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the Pyth action provider supports the network, false otherwise.
+ */
+ supportsNetwork = (_: Network) => true;
+
+ /**
+ * Fetch the price feed ID for a given token symbol from Pyth.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price feed ID as a string.
+ */
+ @CreateAction({
+ name: "fetch_price_feed",
+ description: "Fetch the price feed ID for a given token symbol from Pyth.",
+ schema: PythFetchPriceFeedIDSchema,
+ })
+ async fetchPriceFeed(args: z.infer<typeof PythFetchPriceFeedIDSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/price_feeds?query=${args.tokenSymbol}&asset_type=crypto`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+
+ if (data.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ const filteredData = data.filter(
+ (item: any) => item.attributes.base.toLowerCase() === args.tokenSymbol.toLowerCase(),
+ );
+
+ if (filteredData.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ return filteredData[0].id;
+ }
+
+ /**
+ * Fetches the price from Pyth given a Pyth price feed ID.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price as a string.
+ */
+ @CreateAction({
+ name: "fetch_price",
+ description: `Fetch the price of a given price feed from Pyth.
+
+Inputs:
+- Pyth price feed ID
+
+Important notes:
+- Do not assume that a random ID is a Pyth price feed ID. If you are confused, ask a clarifying question.
+- This action only fetches price inputs from Pyth price feeds. No other source.
+- If you are asked to fetch the price from Pyth for a ticker symbol such as BTC, you must first use the pyth_fetch_price_feed_id
+action to retrieve the price feed ID before invoking the pyth_Fetch_price action
+`,
+ schema: PythFetchPriceSchema
+ })
+ async fetchPrice(args: z.infer<typeof PythFetchPriceSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/updates/price/latest?ids[]=${args.priceFeedID}`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+ const parsedData = data.parsed;
+
+ if (parsedData.length === 0) {
+ throw new Error(`No price data found for ${args.priceFeedID}`);
+ }
+
+ const priceInfo = parsedData[0].price;
+ const price = BigInt(priceInfo.price);
+ const exponent = priceInfo.expo;
+
+ if (exponent < 0) {
+ const adjustedPrice = price * BigInt(100);
+ const divisor = BigInt(10) ** BigInt(-exponent);
+ const scaledPrice = adjustedPrice / BigInt(divisor);
+ const priceStr = scaledPrice.toString();
+ const formattedPrice = `${priceStr.slice(0, -2)}.${priceStr.slice(-2)}`;
+ return formattedPrice.startsWith(".") ? `0${formattedPrice}` : formattedPrice;
+ }
+
+ const scaledPrice = price / BigInt(10) ** BigInt(exponent);
+ return scaledPrice.toString();
+ }
+}
+
+export const pythActionProvider = () => new PythActionProvider();

cdp-agentkit-core/typescript/package.json

@@ -7,7 +7,9 @@
  "license": "Apache-2.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
- "files": ["dist"],
+ "files": [
+ "dist"
+ ],
  "scripts": {
  "build": "tsc",
  "lint": "npx --yes eslint -c .eslintrc.json src/**/*.ts",
@@ -38,8 +40,9 @@
  ],
  "dependencies": {
  "@coinbase/coinbase-sdk": "^0.15.0",
+ "reflect-metadata": "^0.2.2",
  "twitter-api-v2": "^1.18.2",
- "viem": "^2.21.51",
+ "viem": "^2.22.16",
  "zod": "^3.23.8"
  },
  "devDependencies": {

cdp-agentkit-core/typescript/src/action_providers/action_decorator.ts

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+
+import "reflect-metadata";
+
+/**
+ * Parameters for the create action decorator
+ */
+export interface CreateActionDecoratorParams {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+}
+
+/**
+ * Metadata key for the action decorator
+ */
+export const ACTION_DECORATOR_KEY = Symbol("agentkit:action");
+
+/**
+ * Metadata for AgentKit actions
+ */
+export interface ActionMetadata {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+
+ /**
+ * The function to invoke the action
+ */
+ invoke: Function;
+
+ /**
+ * The wallet provider to use for the action
+ */
+ walletProvider: boolean;
+}
+
+/**
+ * A map of action names to their metadata
+ */
+export type StoredActionMetadata = Map<string, ActionMetadata>;
+
+/**
+ * Decorator to embed metadata on class methods to indicate they are actions accessible to the agent
+ *
+ * @param params - The parameters for the action decorator
+ * @returns A decorator function
+ *
+ * @example
+ * ```typescript
+ * class MyActionProvider extends ActionProvider {
+ * @CreateAction({ name: "my_action", description: "My action", schema: myActionSchema })
+ * public myAction(args: z.infer<typeof myActionSchema>) {
+ * // ...
+ * }
+ * }
+ * ```
+ */
+export function CreateAction(params: CreateActionDecoratorParams) {
+ return (target: Object, propertyKey: string, descriptor: PropertyDescriptor) => {
+ const existingMetadata: StoredActionMetadata =
+ Reflect.getMetadata(ACTION_DECORATOR_KEY, target.constructor) || new Map();
+
+ const { isWalletProvider } = validateActionMethodArguments(target, propertyKey);
+
+ const metaData: ActionMetadata = {
+ name: params.name,
+ description: params.description,
+ schema: params.schema,
+ invoke: descriptor.value,
+ walletProvider: isWalletProvider,
+ };
+
+ existingMetadata.set(propertyKey, metaData);
+
+ Reflect.defineMetadata(ACTION_DECORATOR_KEY, existingMetadata, target.constructor);
+
+ return target;
+ };
+}
+
+function validateActionMethodArguments(
+ target: Object,
+ propertyKey: string,
+): {
+ isWalletProvider: boolean;
+} {
+ const className = target instanceof Object ? target.constructor.name : undefined;
+
+ const params = Reflect.getMetadata("design:paramtypes", target, propertyKey);
+
+ if (params == null) {
+ throw new Error(
+ `Failed to get parameters for action method ${propertyKey} on class ${className}`,
+ );
+ }
+
+ if (params.length > 2) {
+ throw new Error(
+ `Action method ${propertyKey} on class ${className} has more than 2 parameters`,
+ );
+ }
+
+ const walletProviderParam = params.find(param => {
+ if (!param || !param.prototype) {
+ return false;
+ }
+
+ if (param === WalletProvider) return true;
+ return param.prototype instanceof WalletProvider;
+ });
+
+ return {
+ isWalletProvider: !!walletProviderParam,
+ };
+}

cdp-agentkit-core/typescript/src/action_providers/action_provider.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+import { Network } from "../wallet_providers/wallet_provider";
+import { StoredActionMetadata, ACTION_DECORATOR_KEY } from "./action_decorator";
+
+/**
+ * Action is the interface for all actions.
+ */
+export interface Action<TActionSchema extends z.ZodSchema = z.ZodSchema> {
+ name: string;
+ description: string;
+ schema: TActionSchema;
+ invoke: (args: z.infer<TActionSchema>) => Promise<string>;
+}
+
+/**
+ * ActionProvider is the abstract base class for all action providers.
+ *
+ * @abstract
+ */
+export abstract class ActionProvider<TWalletProvider extends WalletProvider = WalletProvider> {
+ /**
+ * The name of the action provider.
+ */
+ public readonly name: string;
+
+ /**
+ * The action providers to combine.
+ */
+ public readonly actionProviders: ActionProvider<TWalletProvider>[];
+
+ /**
+ * The constructor for the action provider.
+ *
+ * @param name - The name of the action provider.
+ * @param actionProviders - The action providers to combine.
+ */
+ constructor(name: string, actionProviders: ActionProvider<TWalletProvider>[]) {
+ this.name = name;
+ this.actionProviders = actionProviders;
+ }
+
+ /**
+ * Checks if the action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the action provider supports the network, false otherwise.
+ */
+ abstract supportsNetwork(network: Network): boolean;
+
+ /**
+ * Gets the actions of the action provider bound to the given wallet provider.
+ *
+ * @param walletProvider - The wallet provider.
+ * @returns The actions of the action provider.
+ */
+ getActions(walletProvider: TWalletProvider): Action[] {
+ const actions: Action[] = [];
+
+ const actionProviders = [this, ...this.actionProviders];
+
+ for (const actionProvider of actionProviders) {
+ const actionsMetadataMap: StoredActionMetadata | undefined = Reflect.getMetadata(
+ ACTION_DECORATOR_KEY,
+ actionProvider.constructor,
+ );
+
+ if (!actionsMetadataMap) {
+ if (!(actionProvider instanceof ActionProvider)) {
+ console.warn(`Warning: ${actionProvider} is not an instance of ActionProvider.`);
+ } else {
+ console.warn(`Warning: ${actionProvider} has no actions.`);
+ }
+
+ continue;
+ }
+
+ for (const actionMetadata of actionsMetadataMap.values()) {
+ actions.push({
+ name: actionMetadata.name,
+ description: actionMetadata.description,
+ schema: actionMetadata.schema,
+ invoke: schemaArgs => {
+ const args: any[] = [];
+ if (actionMetadata.walletProvider) {
+ args[0] = walletProvider;
+ }
+
+ args.push(schemaArgs);
+
+ return actionMetadata.invoke.apply(actionProvider, args);
+ },
+ });
+ }
+ }
+
+ return actions;
+ }
+}

cdp-agentkit-core/typescript/src/action_providers/index.ts

@@ -0,0 +1,4 @@
+export * from "./action_decorator";
+export * from "./action_provider";
+
+export * from "./pyth";

cdp-agentkit-core/typescript/src/action_providers/pyth/README.md

@@ -0,0 +1 @@
+# Pyth Action Provider

cdp-agentkit-core/typescript/src/action_providers/pyth/index.ts

@@ -0,0 +1,2 @@
+export * from "./pyth_action_provider";
+export * from "./schemas";

cdp-agentkit-core/typescript/src/action_providers/pyth/pyth_action_provider.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { ActionProvider } from "../action_provider";
+import { Network } from "../../wallet_providers/wallet_provider";
+import { CreateAction } from "../action_decorator";
+import { PythFetchPriceFeedIDSchema, PythFetchPriceSchema } from "./schemas";
+
+/**
+ * PythActionProvider is an action provider for Pyth.
+ */
+export class PythActionProvider extends ActionProvider {
+ constructor() {
+ super("pyth", []);
+ }
+
+ /**
+ * Checks if the Pyth action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the Pyth action provider supports the network, false otherwise.
+ */
+ supportsNetwork = (_: Network) => true;
+
+ /**
+ * Fetch the price feed ID for a given token symbol from Pyth.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price feed ID as a string.
+ */
+ @CreateAction({
+ name: "fetch_price_feed",
+ description: "Fetch the price feed ID for a given token symbol from Pyth.",
+ schema: PythFetchPriceFeedIDSchema,
+ })
+ async fetchPriceFeed(args: z.infer<typeof PythFetchPriceFeedIDSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/price_feeds?query=${args.tokenSymbol}&asset_type=crypto`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+
+ if (data.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ const filteredData = data.filter(
+ (item: any) => item.attributes.base.toLowerCase() === args.tokenSymbol.toLowerCase(),
+ );
+
+ if (filteredData.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ return filteredData[0].id;
+ }
+
+ /**
+ * Fetches the price from Pyth given a Pyth price feed ID.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price as a string.
+ */
+ @CreateAction({
+ name: "fetch_price",
+ description: `Fetch the price of a given price feed from Pyth.
+
+Inputs:
+- Pyth price feed ID
+
+Important notes:
+- Do not assume that a random ID is a Pyth price feed ID. If you are confused, ask a clarifying question.
+- This action only fetches price inputs from Pyth price feeds. No other source.
+- If you are asked to fetch the price from Pyth for a ticker symbol such as BTC, you must first use the pyth_fetch_price_feed_id
+action to retrieve the price feed ID before invoking the pyth_Fetch_price action
+`,
+ schema: PythFetchPriceSchema
+ })
+ async fetchPrice(args: z.infer<typeof PythFetchPriceSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/updates/price/latest?ids[]=${args.priceFeedID}`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+ const parsedData = data.parsed;
+
+ if (parsedData.length === 0) {
+ throw new Error(`No price data found for ${args.priceFeedID}`);
+ }
+
+ const priceInfo = parsedData[0].price;
+ const price = BigInt(priceInfo.price);
+ const exponent = priceInfo.expo;
+
+ if (exponent < 0) {
+ const adjustedPrice = price * BigInt(100);
+ const divisor = BigInt(10) ** BigInt(-exponent);
+ const scaledPrice = adjustedPrice / BigInt(divisor);
+ const priceStr = scaledPrice.toString();
+ const formattedPrice = `${priceStr.slice(0, -2)}.${priceStr.slice(-2)}`;
+ return formattedPrice.startsWith(".") ? `0${formattedPrice}` : formattedPrice;
+ }
+
+ const scaledPrice = price / BigInt(10) ** BigInt(exponent);
+ return scaledPrice.toString();
+ }
+}
+
+export const pythActionProvider = () => new PythActionProvider();

cdp-agentkit-core/typescript/package.json

@@ -7,7 +7,9 @@
  "license": "Apache-2.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
- "files": ["dist"],
+ "files": [
+ "dist"
+ ],
  "scripts": {
  "build": "tsc",
  "lint": "npx --yes eslint -c .eslintrc.json src/**/*.ts",
@@ -38,8 +40,9 @@
  ],
  "dependencies": {
  "@coinbase/coinbase-sdk": "^0.15.0",
+ "reflect-metadata": "^0.2.2",
  "twitter-api-v2": "^1.18.2",
- "viem": "^2.21.51",
+ "viem": "^2.22.16",
  "zod": "^3.23.8"
  },
  "devDependencies": {

cdp-agentkit-core/typescript/src/action_providers/action_decorator.ts

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+
+import "reflect-metadata";
+
+/**
+ * Parameters for the create action decorator
+ */
+export interface CreateActionDecoratorParams {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+}
+
+/**
+ * Metadata key for the action decorator
+ */
+export const ACTION_DECORATOR_KEY = Symbol("agentkit:action");
+
+/**
+ * Metadata for AgentKit actions
+ */
+export interface ActionMetadata {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+
+ /**
+ * The function to invoke the action
+ */
+ invoke: Function;
+
+ /**
+ * The wallet provider to use for the action
+ */
+ walletProvider: boolean;
+}
+
+/**
+ * A map of action names to their metadata
+ */
+export type StoredActionMetadata = Map<string, ActionMetadata>;
+
+/**
+ * Decorator to embed metadata on class methods to indicate they are actions accessible to the agent
+ *
+ * @param params - The parameters for the action decorator
+ * @returns A decorator function
+ *
+ * @example
+ * ```typescript
+ * class MyActionProvider extends ActionProvider {
+ * @CreateAction({ name: "my_action", description: "My action", schema: myActionSchema })
+ * public myAction(args: z.infer<typeof myActionSchema>) {
+ * // ...
+ * }
+ * }
+ * ```
+ */
+export function CreateAction(params: CreateActionDecoratorParams) {
+ return (target: Object, propertyKey: string, descriptor: PropertyDescriptor) => {
+ const existingMetadata: StoredActionMetadata =
+ Reflect.getMetadata(ACTION_DECORATOR_KEY, target.constructor) || new Map();
+
+ const { isWalletProvider } = validateActionMethodArguments(target, propertyKey);
+
+ const metaData: ActionMetadata = {
+ name: params.name,
+ description: params.description,
+ schema: params.schema,
+ invoke: descriptor.value,
+ walletProvider: isWalletProvider,
+ };
+
+ existingMetadata.set(propertyKey, metaData);
+
+ Reflect.defineMetadata(ACTION_DECORATOR_KEY, existingMetadata, target.constructor);
+
+ return target;
+ };
+}
+
+function validateActionMethodArguments(
+ target: Object,
+ propertyKey: string,
+): {
+ isWalletProvider: boolean;
+} {
+ const className = target instanceof Object ? target.constructor.name : undefined;
+
+ const params = Reflect.getMetadata("design:paramtypes", target, propertyKey);
+
+ if (params == null) {
+ throw new Error(
+ `Failed to get parameters for action method ${propertyKey} on class ${className}`,
+ );
+ }
+
+ if (params.length > 2) {
+ throw new Error(
+ `Action method ${propertyKey} on class ${className} has more than 2 parameters`,
+ );
+ }
+
+ const walletProviderParam = params.find(param => {
+ if (!param || !param.prototype) {
+ return false;
+ }
+
+ if (param === WalletProvider) return true;
+ return param.prototype instanceof WalletProvider;
+ });
+
+ return {
+ isWalletProvider: !!walletProviderParam,
+ };
+}

cdp-agentkit-core/typescript/src/action_providers/action_provider.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+import { Network } from "../wallet_providers/wallet_provider";
+import { StoredActionMetadata, ACTION_DECORATOR_KEY } from "./action_decorator";
+
+/**
+ * Action is the interface for all actions.
+ */
+export interface Action<TActionSchema extends z.ZodSchema = z.ZodSchema> {
+ name: string;
+ description: string;
+ schema: TActionSchema;
+ invoke: (args: z.infer<TActionSchema>) => Promise<string>;
+}
+
+/**
+ * ActionProvider is the abstract base class for all action providers.
+ *
+ * @abstract
+ */
+export abstract class ActionProvider<TWalletProvider extends WalletProvider = WalletProvider> {
+ /**
+ * The name of the action provider.
+ */
+ public readonly name: string;
+
+ /**
+ * The action providers to combine.
+ */
+ public readonly actionProviders: ActionProvider<TWalletProvider>[];
+
+ /**
+ * The constructor for the action provider.
+ *
+ * @param name - The name of the action provider.
+ * @param actionProviders - The action providers to combine.
+ */
+ constructor(name: string, actionProviders: ActionProvider<TWalletProvider>[]) {
+ this.name = name;
+ this.actionProviders = actionProviders;
+ }
+
+ /**
+ * Checks if the action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the action provider supports the network, false otherwise.
+ */
+ abstract supportsNetwork(network: Network): boolean;
+
+ /**
+ * Gets the actions of the action provider bound to the given wallet provider.
+ *
+ * @param walletProvider - The wallet provider.
+ * @returns The actions of the action provider.
+ */
+ getActions(walletProvider: TWalletProvider): Action[] {
+ const actions: Action[] = [];
+
+ const actionProviders = [this, ...this.actionProviders];
+
+ for (const actionProvider of actionProviders) {
+ const actionsMetadataMap: StoredActionMetadata | undefined = Reflect.getMetadata(
+ ACTION_DECORATOR_KEY,
+ actionProvider.constructor,
+ );
+
+ if (!actionsMetadataMap) {
+ if (!(actionProvider instanceof ActionProvider)) {
+ console.warn(`Warning: ${actionProvider} is not an instance of ActionProvider.`);
+ } else {
+ console.warn(`Warning: ${actionProvider} has no actions.`);
+ }
+
+ continue;
+ }
+
+ for (const actionMetadata of actionsMetadataMap.values()) {
+ actions.push({
+ name: actionMetadata.name,
+ description: actionMetadata.description,
+ schema: actionMetadata.schema,
+ invoke: schemaArgs => {
+ const args: any[] = [];
+ if (actionMetadata.walletProvider) {
+ args[0] = walletProvider;
+ }
+
+ args.push(schemaArgs);
+
+ return actionMetadata.invoke.apply(actionProvider, args);
+ },
+ });
+ }
+ }
+
+ return actions;
+ }
+}

cdp-agentkit-core/typescript/src/action_providers/index.ts

@@ -0,0 +1,4 @@
+export * from "./action_decorator";
+export * from "./action_provider";
+
+export * from "./pyth";

cdp-agentkit-core/typescript/src/action_providers/pyth/README.md

@@ -0,0 +1 @@
+# Pyth Action Provider

cdp-agentkit-core/typescript/src/action_providers/pyth/index.ts

@@ -0,0 +1,2 @@
+export * from "./pyth_action_provider";
+export * from "./schemas";

cdp-agentkit-core/typescript/src/action_providers/pyth/pyth_action_provider.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { ActionProvider } from "../action_provider";
+import { Network } from "../../wallet_providers/wallet_provider";
+import { CreateAction } from "../action_decorator";
+import { PythFetchPriceFeedIDSchema, PythFetchPriceSchema } from "./schemas";
+
+/**
+ * PythActionProvider is an action provider for Pyth.
+ */
+export class PythActionProvider extends ActionProvider {
+ constructor() {
+ super("pyth", []);
+ }
+
+ /**
+ * Checks if the Pyth action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the Pyth action provider supports the network, false otherwise.
+ */
+ supportsNetwork = (_: Network) => true;
+
+ /**
+ * Fetch the price feed ID for a given token symbol from Pyth.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price feed ID as a string.
+ */
+ @CreateAction({
+ name: "fetch_price_feed",
+ description: "Fetch the price feed ID for a given token symbol from Pyth.",
+ schema: PythFetchPriceFeedIDSchema,
+ })
+ async fetchPriceFeed(args: z.infer<typeof PythFetchPriceFeedIDSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/price_feeds?query=${args.tokenSymbol}&asset_type=crypto`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+
+ if (data.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ const filteredData = data.filter(
+ (item: any) => item.attributes.base.toLowerCase() === args.tokenSymbol.toLowerCase(),
+ );
+
+ if (filteredData.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ return filteredData[0].id;
+ }
+
+ /**
+ * Fetches the price from Pyth given a Pyth price feed ID.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price as a string.
+ */
+ @CreateAction({
+ name: "fetch_price",
+ description: `Fetch the price of a given price feed from Pyth.
+
+Inputs:
+- Pyth price feed ID
+
+Important notes:
+- Do not assume that a random ID is a Pyth price feed ID. If you are confused, ask a clarifying question.
+- This action only fetches price inputs from Pyth price feeds. No other source.
+- If you are asked to fetch the price from Pyth for a ticker symbol such as BTC, you must first use the pyth_fetch_price_feed_id
+action to retrieve the price feed ID before invoking the pyth_Fetch_price action
+`,
+ schema: PythFetchPriceSchema
+ })
+ async fetchPrice(args: z.infer<typeof PythFetchPriceSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/updates/price/latest?ids[]=${args.priceFeedID}`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+ const parsedData = data.parsed;
+
+ if (parsedData.length === 0) {
+ throw new Error(`No price data found for ${args.priceFeedID}`);
+ }
+
+ const priceInfo = parsedData[0].price;
+ const price = BigInt(priceInfo.price);
+ const exponent = priceInfo.expo;
+
+ if (exponent < 0) {
+ const adjustedPrice = price * BigInt(100);
+ const divisor = BigInt(10) ** BigInt(-exponent);
+ const scaledPrice = adjustedPrice / BigInt(divisor);
+ const priceStr = scaledPrice.toString();
+ const formattedPrice = `${priceStr.slice(0, -2)}.${priceStr.slice(-2)}`;
+ return formattedPrice.startsWith(".") ? `0${formattedPrice}` : formattedPrice;
+ }
+
+ const scaledPrice = price / BigInt(10) ** BigInt(exponent);
+ return scaledPrice.toString();
+ }
+}
+
+export const pythActionProvider = () => new PythActionProvider();

cdp-agentkit-core/typescript/package.json

@@ -7,7 +7,9 @@
  "license": "Apache-2.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
- "files": ["dist"],
+ "files": [
+ "dist"
+ ],
  "scripts": {
  "build": "tsc",
  "lint": "npx --yes eslint -c .eslintrc.json src/**/*.ts",
@@ -38,8 +40,9 @@
  ],
  "dependencies": {
  "@coinbase/coinbase-sdk": "^0.15.0",
+ "reflect-metadata": "^0.2.2",
  "twitter-api-v2": "^1.18.2",
- "viem": "^2.21.51",
+ "viem": "^2.22.16",
  "zod": "^3.23.8"
  },
  "devDependencies": {

cdp-agentkit-core/typescript/src/action_providers/action_decorator.ts

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+
+import "reflect-metadata";
+
+/**
+ * Parameters for the create action decorator
+ */
+export interface CreateActionDecoratorParams {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+}
+
+/**
+ * Metadata key for the action decorator
+ */
+export const ACTION_DECORATOR_KEY = Symbol("agentkit:action");
+
+/**
+ * Metadata for AgentKit actions
+ */
+export interface ActionMetadata {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+
+ /**
+ * The function to invoke the action
+ */
+ invoke: Function;
+
+ /**
+ * The wallet provider to use for the action
+ */
+ walletProvider: boolean;
+}
+
+/**
+ * A map of action names to their metadata
+ */
+export type StoredActionMetadata = Map<string, ActionMetadata>;
+
+/**
+ * Decorator to embed metadata on class methods to indicate they are actions accessible to the agent
+ *
+ * @param params - The parameters for the action decorator
+ * @returns A decorator function
+ *
+ * @example
+ * ```typescript
+ * class MyActionProvider extends ActionProvider {
+ * @CreateAction({ name: "my_action", description: "My action", schema: myActionSchema })
+ * public myAction(args: z.infer<typeof myActionSchema>) {
+ * // ...
+ * }
+ * }
+ * ```
+ */
+export function CreateAction(params: CreateActionDecoratorParams) {
+ return (target: Object, propertyKey: string, descriptor: PropertyDescriptor) => {
+ const existingMetadata: StoredActionMetadata =
+ Reflect.getMetadata(ACTION_DECORATOR_KEY, target.constructor) || new Map();
+
+ const { isWalletProvider } = validateActionMethodArguments(target, propertyKey);
+
+ const metaData: ActionMetadata = {
+ name: params.name,
+ description: params.description,
+ schema: params.schema,
+ invoke: descriptor.value,
+ walletProvider: isWalletProvider,
+ };
+
+ existingMetadata.set(propertyKey, metaData);
+
+ Reflect.defineMetadata(ACTION_DECORATOR_KEY, existingMetadata, target.constructor);
+
+ return target;
+ };
+}
+
+function validateActionMethodArguments(
+ target: Object,
+ propertyKey: string,
+): {
+ isWalletProvider: boolean;
+} {
+ const className = target instanceof Object ? target.constructor.name : undefined;
+
+ const params = Reflect.getMetadata("design:paramtypes", target, propertyKey);
+
+ if (params == null) {
+ throw new Error(
+ `Failed to get parameters for action method ${propertyKey} on class ${className}`,
+ );
+ }
+
+ if (params.length > 2) {
+ throw new Error(
+ `Action method ${propertyKey} on class ${className} has more than 2 parameters`,
+ );
+ }
+
+ const walletProviderParam = params.find(param => {
+ if (!param || !param.prototype) {
+ return false;
+ }
+
+ if (param === WalletProvider) return true;
+ return param.prototype instanceof WalletProvider;
+ });
+
+ return {
+ isWalletProvider: !!walletProviderParam,
+ };
+}

cdp-agentkit-core/typescript/src/action_providers/action_provider.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+import { Network } from "../wallet_providers/wallet_provider";
+import { StoredActionMetadata, ACTION_DECORATOR_KEY } from "./action_decorator";
+
+/**
+ * Action is the interface for all actions.
+ */
+export interface Action<TActionSchema extends z.ZodSchema = z.ZodSchema> {
+ name: string;
+ description: string;
+ schema: TActionSchema;
+ invoke: (args: z.infer<TActionSchema>) => Promise<string>;
+}
+
+/**
+ * ActionProvider is the abstract base class for all action providers.
+ *
+ * @abstract
+ */
+export abstract class ActionProvider<TWalletProvider extends WalletProvider = WalletProvider> {
+ /**
+ * The name of the action provider.
+ */
+ public readonly name: string;
+
+ /**
+ * The action providers to combine.
+ */
+ public readonly actionProviders: ActionProvider<TWalletProvider>[];
+
+ /**
+ * The constructor for the action provider.
+ *
+ * @param name - The name of the action provider.
+ * @param actionProviders - The action providers to combine.
+ */
+ constructor(name: string, actionProviders: ActionProvider<TWalletProvider>[]) {
+ this.name = name;
+ this.actionProviders = actionProviders;
+ }
+
+ /**
+ * Checks if the action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the action provider supports the network, false otherwise.
+ */
+ abstract supportsNetwork(network: Network): boolean;
+
+ /**
+ * Gets the actions of the action provider bound to the given wallet provider.
+ *
+ * @param walletProvider - The wallet provider.
+ * @returns The actions of the action provider.
+ */
+ getActions(walletProvider: TWalletProvider): Action[] {
+ const actions: Action[] = [];
+
+ const actionProviders = [this, ...this.actionProviders];
+
+ for (const actionProvider of actionProviders) {
+ const actionsMetadataMap: StoredActionMetadata | undefined = Reflect.getMetadata(
+ ACTION_DECORATOR_KEY,
+ actionProvider.constructor,
+ );
+
+ if (!actionsMetadataMap) {
+ if (!(actionProvider instanceof ActionProvider)) {
+ console.warn(`Warning: ${actionProvider} is not an instance of ActionProvider.`);
+ } else {
+ console.warn(`Warning: ${actionProvider} has no actions.`);
+ }
+
+ continue;
+ }
+
+ for (const actionMetadata of actionsMetadataMap.values()) {
+ actions.push({
+ name: actionMetadata.name,
+ description: actionMetadata.description,
+ schema: actionMetadata.schema,
+ invoke: schemaArgs => {
+ const args: any[] = [];
+ if (actionMetadata.walletProvider) {
+ args[0] = walletProvider;
+ }
+
+ args.push(schemaArgs);
+
+ return actionMetadata.invoke.apply(actionProvider, args);
+ },
+ });
+ }
+ }
+
+ return actions;
+ }
+}

cdp-agentkit-core/typescript/src/action_providers/index.ts

@@ -0,0 +1,4 @@
+export * from "./action_decorator";
+export * from "./action_provider";
+
+export * from "./pyth";

cdp-agentkit-core/typescript/src/action_providers/pyth/README.md

@@ -0,0 +1 @@
+# Pyth Action Provider

cdp-agentkit-core/typescript/src/action_providers/pyth/index.ts

@@ -0,0 +1,2 @@
+export * from "./pyth_action_provider";
+export * from "./schemas";

cdp-agentkit-core/typescript/src/action_providers/pyth/pyth_action_provider.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { ActionProvider } from "../action_provider";
+import { Network } from "../../wallet_providers/wallet_provider";
+import { CreateAction } from "../action_decorator";
+import { PythFetchPriceFeedIDSchema, PythFetchPriceSchema } from "./schemas";
+
+/**
+ * PythActionProvider is an action provider for Pyth.
+ */
+export class PythActionProvider extends ActionProvider {
+ constructor() {
+ super("pyth", []);
+ }
+
+ /**
+ * Checks if the Pyth action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the Pyth action provider supports the network, false otherwise.
+ */
+ supportsNetwork = (_: Network) => true;
+
+ /**
+ * Fetch the price feed ID for a given token symbol from Pyth.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price feed ID as a string.
+ */
+ @CreateAction({
+ name: "fetch_price_feed",
+ description: "Fetch the price feed ID for a given token symbol from Pyth.",
+ schema: PythFetchPriceFeedIDSchema,
+ })
+ async fetchPriceFeed(args: z.infer<typeof PythFetchPriceFeedIDSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/price_feeds?query=${args.tokenSymbol}&asset_type=crypto`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+
+ if (data.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ const filteredData = data.filter(
+ (item: any) => item.attributes.base.toLowerCase() === args.tokenSymbol.toLowerCase(),
+ );
+
+ if (filteredData.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ return filteredData[0].id;
+ }
+
+ /**
+ * Fetches the price from Pyth given a Pyth price feed ID.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price as a string.
+ */
+ @CreateAction({
+ name: "fetch_price",
+ description: `Fetch the price of a given price feed from Pyth.
+
+Inputs:
+- Pyth price feed ID
+
+Important notes:
+- Do not assume that a random ID is a Pyth price feed ID. If you are confused, ask a clarifying question.
+- This action only fetches price inputs from Pyth price feeds. No other source.
+- If you are asked to fetch the price from Pyth for a ticker symbol such as BTC, you must first use the pyth_fetch_price_feed_id
+action to retrieve the price feed ID before invoking the pyth_Fetch_price action
+`,
+ schema: PythFetchPriceSchema
+ })
+ async fetchPrice(args: z.infer<typeof PythFetchPriceSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/updates/price/latest?ids[]=${args.priceFeedID}`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+ const parsedData = data.parsed;
+
+ if (parsedData.length === 0) {
+ throw new Error(`No price data found for ${args.priceFeedID}`);
+ }
+
+ const priceInfo = parsedData[0].price;
+ const price = BigInt(priceInfo.price);
+ const exponent = priceInfo.expo;
+
+ if (exponent < 0) {
+ const adjustedPrice = price * BigInt(100);
+ const divisor = BigInt(10) ** BigInt(-exponent);
+ const scaledPrice = adjustedPrice / BigInt(divisor);
+ const priceStr = scaledPrice.toString();
+ const formattedPrice = `${priceStr.slice(0, -2)}.${priceStr.slice(-2)}`;
+ return formattedPrice.startsWith(".") ? `0${formattedPrice}` : formattedPrice;
+ }
+
+ const scaledPrice = price / BigInt(10) ** BigInt(exponent);
+ return scaledPrice.toString();
+ }
+}
+
+export const pythActionProvider = () => new PythActionProvider();

cdp-agentkit-core/typescript/package.json

@@ -7,7 +7,9 @@
  "license": "Apache-2.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
- "files": ["dist"],
+ "files": [
+ "dist"
+ ],
  "scripts": {
  "build": "tsc",
  "lint": "npx --yes eslint -c .eslintrc.json src/**/*.ts",
@@ -38,8 +40,9 @@
  ],
  "dependencies": {
  "@coinbase/coinbase-sdk": "^0.15.0",
+ "reflect-metadata": "^0.2.2",
  "twitter-api-v2": "^1.18.2",
- "viem": "^2.21.51",
+ "viem": "^2.22.16",
  "zod": "^3.23.8"
  },
  "devDependencies": {

cdp-agentkit-core/typescript/src/action_providers/action_decorator.ts

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+
+import "reflect-metadata";
+
+/**
+ * Parameters for the create action decorator
+ */
+export interface CreateActionDecoratorParams {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+}
+
+/**
+ * Metadata key for the action decorator
+ */
+export const ACTION_DECORATOR_KEY = Symbol("agentkit:action");
+
+/**
+ * Metadata for AgentKit actions
+ */
+export interface ActionMetadata {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+
+ /**
+ * The function to invoke the action
+ */
+ invoke: Function;
+
+ /**
+ * The wallet provider to use for the action
+ */
+ walletProvider: boolean;
+}
+
+/**
+ * A map of action names to their metadata
+ */
+export type StoredActionMetadata = Map<string, ActionMetadata>;
+
+/**
+ * Decorator to embed metadata on class methods to indicate they are actions accessible to the agent
+ *
+ * @param params - The parameters for the action decorator
+ * @returns A decorator function
+ *
+ * @example
+ * ```typescript
+ * class MyActionProvider extends ActionProvider {
+ * @CreateAction({ name: "my_action", description: "My action", schema: myActionSchema })
+ * public myAction(args: z.infer<typeof myActionSchema>) {
+ * // ...
+ * }
+ * }
+ * ```
+ */
+export function CreateAction(params: CreateActionDecoratorParams) {
+ return (target: Object, propertyKey: string, descriptor: PropertyDescriptor) => {
+ const existingMetadata: StoredActionMetadata =
+ Reflect.getMetadata(ACTION_DECORATOR_KEY, target.constructor) || new Map();
+
+ const { isWalletProvider } = validateActionMethodArguments(target, propertyKey);
+
+ const metaData: ActionMetadata = {
+ name: params.name,
+ description: params.description,
+ schema: params.schema,
+ invoke: descriptor.value,
+ walletProvider: isWalletProvider,
+ };
+
+ existingMetadata.set(propertyKey, metaData);
+
+ Reflect.defineMetadata(ACTION_DECORATOR_KEY, existingMetadata, target.constructor);
+
+ return target;
+ };
+}
+
+function validateActionMethodArguments(
+ target: Object,
+ propertyKey: string,
+): {
+ isWalletProvider: boolean;
+} {
+ const className = target instanceof Object ? target.constructor.name : undefined;
+
+ const params = Reflect.getMetadata("design:paramtypes", target, propertyKey);
+
+ if (params == null) {
+ throw new Error(
+ `Failed to get parameters for action method ${propertyKey} on class ${className}`,
+ );
+ }
+
+ if (params.length > 2) {
+ throw new Error(
+ `Action method ${propertyKey} on class ${className} has more than 2 parameters`,
+ );
+ }
+
+ const walletProviderParam = params.find(param => {
+ if (!param || !param.prototype) {
+ return false;
+ }
+
+ if (param === WalletProvider) return true;
+ return param.prototype instanceof WalletProvider;
+ });
+
+ return {
+ isWalletProvider: !!walletProviderParam,
+ };
+}

cdp-agentkit-core/typescript/src/action_providers/action_provider.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+import { Network } from "../wallet_providers/wallet_provider";
+import { StoredActionMetadata, ACTION_DECORATOR_KEY } from "./action_decorator";
+
+/**
+ * Action is the interface for all actions.
+ */
+export interface Action<TActionSchema extends z.ZodSchema = z.ZodSchema> {
+ name: string;
+ description: string;
+ schema: TActionSchema;
+ invoke: (args: z.infer<TActionSchema>) => Promise<string>;
+}
+
+/**
+ * ActionProvider is the abstract base class for all action providers.
+ *
+ * @abstract
+ */
+export abstract class ActionProvider<TWalletProvider extends WalletProvider = WalletProvider> {
+ /**
+ * The name of the action provider.
+ */
+ public readonly name: string;
+
+ /**
+ * The action providers to combine.
+ */
+ public readonly actionProviders: ActionProvider<TWalletProvider>[];
+
+ /**
+ * The constructor for the action provider.
+ *
+ * @param name - The name of the action provider.
+ * @param actionProviders - The action providers to combine.
+ */
+ constructor(name: string, actionProviders: ActionProvider<TWalletProvider>[]) {
+ this.name = name;
+ this.actionProviders = actionProviders;
+ }
+
+ /**
+ * Checks if the action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the action provider supports the network, false otherwise.
+ */
+ abstract supportsNetwork(network: Network): boolean;
+
+ /**
+ * Gets the actions of the action provider bound to the given wallet provider.
+ *
+ * @param walletProvider - The wallet provider.
+ * @returns The actions of the action provider.
+ */
+ getActions(walletProvider: TWalletProvider): Action[] {
+ const actions: Action[] = [];
+
+ const actionProviders = [this, ...this.actionProviders];
+
+ for (const actionProvider of actionProviders) {
+ const actionsMetadataMap: StoredActionMetadata | undefined = Reflect.getMetadata(
+ ACTION_DECORATOR_KEY,
+ actionProvider.constructor,
+ );
+
+ if (!actionsMetadataMap) {
+ if (!(actionProvider instanceof ActionProvider)) {
+ console.warn(`Warning: ${actionProvider} is not an instance of ActionProvider.`);
+ } else {
+ console.warn(`Warning: ${actionProvider} has no actions.`);
+ }
+
+ continue;
+ }
+
+ for (const actionMetadata of actionsMetadataMap.values()) {
+ actions.push({
+ name: actionMetadata.name,
+ description: actionMetadata.description,
+ schema: actionMetadata.schema,
+ invoke: schemaArgs => {
+ const args: any[] = [];
+ if (actionMetadata.walletProvider) {
+ args[0] = walletProvider;
+ }
+
+ args.push(schemaArgs);
+
+ return actionMetadata.invoke.apply(actionProvider, args);
+ },
+ });
+ }
+ }
+
+ return actions;
+ }
+}

cdp-agentkit-core/typescript/src/action_providers/index.ts

@@ -0,0 +1,4 @@
+export * from "./action_decorator";
+export * from "./action_provider";
+
+export * from "./pyth";

cdp-agentkit-core/typescript/src/action_providers/pyth/README.md

@@ -0,0 +1 @@
+# Pyth Action Provider

cdp-agentkit-core/typescript/src/action_providers/pyth/index.ts

@@ -0,0 +1,2 @@
+export * from "./pyth_action_provider";
+export * from "./schemas";

cdp-agentkit-core/typescript/src/action_providers/pyth/pyth_action_provider.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { ActionProvider } from "../action_provider";
+import { Network } from "../../wallet_providers/wallet_provider";
+import { CreateAction } from "../action_decorator";
+import { PythFetchPriceFeedIDSchema, PythFetchPriceSchema } from "./schemas";
+
+/**
+ * PythActionProvider is an action provider for Pyth.
+ */
+export class PythActionProvider extends ActionProvider {
+ constructor() {
+ super("pyth", []);
+ }
+
+ /**
+ * Checks if the Pyth action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the Pyth action provider supports the network, false otherwise.
+ */
+ supportsNetwork = (_: Network) => true;
+
+ /**
+ * Fetch the price feed ID for a given token symbol from Pyth.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price feed ID as a string.
+ */
+ @CreateAction({
+ name: "fetch_price_feed",
+ description: "Fetch the price feed ID for a given token symbol from Pyth.",
+ schema: PythFetchPriceFeedIDSchema,
+ })
+ async fetchPriceFeed(args: z.infer<typeof PythFetchPriceFeedIDSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/price_feeds?query=${args.tokenSymbol}&asset_type=crypto`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+
+ if (data.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ const filteredData = data.filter(
+ (item: any) => item.attributes.base.toLowerCase() === args.tokenSymbol.toLowerCase(),
+ );
+
+ if (filteredData.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ return filteredData[0].id;
+ }
+
+ /**
+ * Fetches the price from Pyth given a Pyth price feed ID.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price as a string.
+ */
+ @CreateAction({
+ name: "fetch_price",
+ description: `Fetch the price of a given price feed from Pyth.
+
+Inputs:
+- Pyth price feed ID
+
+Important notes:
+- Do not assume that a random ID is a Pyth price feed ID. If you are confused, ask a clarifying question.
+- This action only fetches price inputs from Pyth price feeds. No other source.
+- If you are asked to fetch the price from Pyth for a ticker symbol such as BTC, you must first use the pyth_fetch_price_feed_id
+action to retrieve the price feed ID before invoking the pyth_Fetch_price action
+`,
+ schema: PythFetchPriceSchema
+ })
+ async fetchPrice(args: z.infer<typeof PythFetchPriceSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/updates/price/latest?ids[]=${args.priceFeedID}`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+ const parsedData = data.parsed;
+
+ if (parsedData.length === 0) {
+ throw new Error(`No price data found for ${args.priceFeedID}`);
+ }
+
+ const priceInfo = parsedData[0].price;
+ const price = BigInt(priceInfo.price);
+ const exponent = priceInfo.expo;
+
+ if (exponent < 0) {
+ const adjustedPrice = price * BigInt(100);
+ const divisor = BigInt(10) ** BigInt(-exponent);
+ const scaledPrice = adjustedPrice / BigInt(divisor);
+ const priceStr = scaledPrice.toString();
+ const formattedPrice = `${priceStr.slice(0, -2)}.${priceStr.slice(-2)}`;
+ return formattedPrice.startsWith(".") ? `0${formattedPrice}` : formattedPrice;
+ }
+
+ const scaledPrice = price / BigInt(10) ** BigInt(exponent);
+ return scaledPrice.toString();
+ }
+}
+
+export const pythActionProvider = () => new PythActionProvider();

cdp-agentkit-core/typescript/package.json

@@ -7,7 +7,9 @@
  "license": "Apache-2.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
- "files": ["dist"],
+ "files": [
+ "dist"
+ ],
  "scripts": {
  "build": "tsc",
  "lint": "npx --yes eslint -c .eslintrc.json src/**/*.ts",
@@ -38,8 +40,9 @@
  ],
  "dependencies": {
  "@coinbase/coinbase-sdk": "^0.15.0",
+ "reflect-metadata": "^0.2.2",
  "twitter-api-v2": "^1.18.2",
- "viem": "^2.21.51",
+ "viem": "^2.22.16",
  "zod": "^3.23.8"
  },
  "devDependencies": {

cdp-agentkit-core/typescript/src/action_providers/action_decorator.ts

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+
+import "reflect-metadata";
+
+/**
+ * Parameters for the create action decorator
+ */
+export interface CreateActionDecoratorParams {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+}
+
+/**
+ * Metadata key for the action decorator
+ */
+export const ACTION_DECORATOR_KEY = Symbol("agentkit:action");
+
+/**
+ * Metadata for AgentKit actions
+ */
+export interface ActionMetadata {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+
+ /**
+ * The function to invoke the action
+ */
+ invoke: Function;
+
+ /**
+ * The wallet provider to use for the action
+ */
+ walletProvider: boolean;
+}
+
+/**
+ * A map of action names to their metadata
+ */
+export type StoredActionMetadata = Map<string, ActionMetadata>;
+
+/**
+ * Decorator to embed metadata on class methods to indicate they are actions accessible to the agent
+ *
+ * @param params - The parameters for the action decorator
+ * @returns A decorator function
+ *
+ * @example
+ * ```typescript
+ * class MyActionProvider extends ActionProvider {
+ * @CreateAction({ name: "my_action", description: "My action", schema: myActionSchema })
+ * public myAction(args: z.infer<typeof myActionSchema>) {
+ * // ...
+ * }
+ * }
+ * ```
+ */
+export function CreateAction(params: CreateActionDecoratorParams) {
+ return (target: Object, propertyKey: string, descriptor: PropertyDescriptor) => {
+ const existingMetadata: StoredActionMetadata =
+ Reflect.getMetadata(ACTION_DECORATOR_KEY, target.constructor) || new Map();
+
+ const { isWalletProvider } = validateActionMethodArguments(target, propertyKey);
+
+ const metaData: ActionMetadata = {
+ name: params.name,
+ description: params.description,
+ schema: params.schema,
+ invoke: descriptor.value,
+ walletProvider: isWalletProvider,
+ };
+
+ existingMetadata.set(propertyKey, metaData);
+
+ Reflect.defineMetadata(ACTION_DECORATOR_KEY, existingMetadata, target.constructor);
+
+ return target;
+ };
+}
+
+function validateActionMethodArguments(
+ target: Object,
+ propertyKey: string,
+): {
+ isWalletProvider: boolean;
+} {
+ const className = target instanceof Object ? target.constructor.name : undefined;
+
+ const params = Reflect.getMetadata("design:paramtypes", target, propertyKey);
+
+ if (params == null) {
+ throw new Error(
+ `Failed to get parameters for action method ${propertyKey} on class ${className}`,
+ );
+ }
+
+ if (params.length > 2) {
+ throw new Error(
+ `Action method ${propertyKey} on class ${className} has more than 2 parameters`,
+ );
+ }
+
+ const walletProviderParam = params.find(param => {
+ if (!param || !param.prototype) {
+ return false;
+ }
+
+ if (param === WalletProvider) return true;
+ return param.prototype instanceof WalletProvider;
+ });
+
+ return {
+ isWalletProvider: !!walletProviderParam,
+ };
+}

cdp-agentkit-core/typescript/src/action_providers/action_provider.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+import { Network } from "../wallet_providers/wallet_provider";
+import { StoredActionMetadata, ACTION_DECORATOR_KEY } from "./action_decorator";
+
+/**
+ * Action is the interface for all actions.
+ */
+export interface Action<TActionSchema extends z.ZodSchema = z.ZodSchema> {
+ name: string;
+ description: string;
+ schema: TActionSchema;
+ invoke: (args: z.infer<TActionSchema>) => Promise<string>;
+}
+
+/**
+ * ActionProvider is the abstract base class for all action providers.
+ *
+ * @abstract
+ */
+export abstract class ActionProvider<TWalletProvider extends WalletProvider = WalletProvider> {
+ /**
+ * The name of the action provider.
+ */
+ public readonly name: string;
+
+ /**
+ * The action providers to combine.
+ */
+ public readonly actionProviders: ActionProvider<TWalletProvider>[];
+
+ /**
+ * The constructor for the action provider.
+ *
+ * @param name - The name of the action provider.
+ * @param actionProviders - The action providers to combine.
+ */
+ constructor(name: string, actionProviders: ActionProvider<TWalletProvider>[]) {
+ this.name = name;
+ this.actionProviders = actionProviders;
+ }
+
+ /**
+ * Checks if the action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the action provider supports the network, false otherwise.
+ */
+ abstract supportsNetwork(network: Network): boolean;
+
+ /**
+ * Gets the actions of the action provider bound to the given wallet provider.
+ *
+ * @param walletProvider - The wallet provider.
+ * @returns The actions of the action provider.
+ */
+ getActions(walletProvider: TWalletProvider): Action[] {
+ const actions: Action[] = [];
+
+ const actionProviders = [this, ...this.actionProviders];
+
+ for (const actionProvider of actionProviders) {
+ const actionsMetadataMap: StoredActionMetadata | undefined = Reflect.getMetadata(
+ ACTION_DECORATOR_KEY,
+ actionProvider.constructor,
+ );
+
+ if (!actionsMetadataMap) {
+ if (!(actionProvider instanceof ActionProvider)) {
+ console.warn(`Warning: ${actionProvider} is not an instance of ActionProvider.`);
+ } else {
+ console.warn(`Warning: ${actionProvider} has no actions.`);
+ }
+
+ continue;
+ }
+
+ for (const actionMetadata of actionsMetadataMap.values()) {
+ actions.push({
+ name: actionMetadata.name,
+ description: actionMetadata.description,
+ schema: actionMetadata.schema,
+ invoke: schemaArgs => {
+ const args: any[] = [];
+ if (actionMetadata.walletProvider) {
+ args[0] = walletProvider;
+ }
+
+ args.push(schemaArgs);
+
+ return actionMetadata.invoke.apply(actionProvider, args);
+ },
+ });
+ }
+ }
+
+ return actions;
+ }
+}

cdp-agentkit-core/typescript/src/action_providers/index.ts

@@ -0,0 +1,4 @@
+export * from "./action_decorator";
+export * from "./action_provider";
+
+export * from "./pyth";

cdp-agentkit-core/typescript/src/action_providers/pyth/README.md

@@ -0,0 +1 @@
+# Pyth Action Provider

cdp-agentkit-core/typescript/src/action_providers/pyth/index.ts

@@ -0,0 +1,2 @@
+export * from "./pyth_action_provider";
+export * from "./schemas";

cdp-agentkit-core/typescript/src/action_providers/pyth/pyth_action_provider.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { ActionProvider } from "../action_provider";
+import { Network } from "../../wallet_providers/wallet_provider";
+import { CreateAction } from "../action_decorator";
+import { PythFetchPriceFeedIDSchema, PythFetchPriceSchema } from "./schemas";
+
+/**
+ * PythActionProvider is an action provider for Pyth.
+ */
+export class PythActionProvider extends ActionProvider {
+ constructor() {
+ super("pyth", []);
+ }
+
+ /**
+ * Checks if the Pyth action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the Pyth action provider supports the network, false otherwise.
+ */
+ supportsNetwork = (_: Network) => true;
+
+ /**
+ * Fetch the price feed ID for a given token symbol from Pyth.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price feed ID as a string.
+ */
+ @CreateAction({
+ name: "fetch_price_feed",
+ description: "Fetch the price feed ID for a given token symbol from Pyth.",
+ schema: PythFetchPriceFeedIDSchema,
+ })
+ async fetchPriceFeed(args: z.infer<typeof PythFetchPriceFeedIDSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/price_feeds?query=${args.tokenSymbol}&asset_type=crypto`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+
+ if (data.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ const filteredData = data.filter(
+ (item: any) => item.attributes.base.toLowerCase() === args.tokenSymbol.toLowerCase(),
+ );
+
+ if (filteredData.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ return filteredData[0].id;
+ }
+
+ /**
+ * Fetches the price from Pyth given a Pyth price feed ID.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price as a string.
+ */
+ @CreateAction({
+ name: "fetch_price",
+ description: `Fetch the price of a given price feed from Pyth.
+
+Inputs:
+- Pyth price feed ID
+
+Important notes:
+- Do not assume that a random ID is a Pyth price feed ID. If you are confused, ask a clarifying question.
+- This action only fetches price inputs from Pyth price feeds. No other source.
+- If you are asked to fetch the price from Pyth for a ticker symbol such as BTC, you must first use the pyth_fetch_price_feed_id
+action to retrieve the price feed ID before invoking the pyth_Fetch_price action
+`,
+ schema: PythFetchPriceSchema
+ })
+ async fetchPrice(args: z.infer<typeof PythFetchPriceSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/updates/price/latest?ids[]=${args.priceFeedID}`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+ const parsedData = data.parsed;
+
+ if (parsedData.length === 0) {
+ throw new Error(`No price data found for ${args.priceFeedID}`);
+ }
+
+ const priceInfo = parsedData[0].price;
+ const price = BigInt(priceInfo.price);
+ const exponent = priceInfo.expo;
+
+ if (exponent < 0) {
+ const adjustedPrice = price * BigInt(100);
+ const divisor = BigInt(10) ** BigInt(-exponent);
+ const scaledPrice = adjustedPrice / BigInt(divisor);
+ const priceStr = scaledPrice.toString();
+ const formattedPrice = `${priceStr.slice(0, -2)}.${priceStr.slice(-2)}`;
+ return formattedPrice.startsWith(".") ? `0${formattedPrice}` : formattedPrice;
+ }
+
+ const scaledPrice = price / BigInt(10) ** BigInt(exponent);
+ return scaledPrice.toString();
+ }
+}
+
+export const pythActionProvider = () => new PythActionProvider();

cdp-agentkit-core/typescript/package.json

@@ -7,7 +7,9 @@
  "license": "Apache-2.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
- "files": ["dist"],
+ "files": [
+ "dist"
+ ],
  "scripts": {
  "build": "tsc",
  "lint": "npx --yes eslint -c .eslintrc.json src/**/*.ts",
@@ -38,8 +40,9 @@
  ],
  "dependencies": {
  "@coinbase/coinbase-sdk": "^0.15.0",
+ "reflect-metadata": "^0.2.2",
  "twitter-api-v2": "^1.18.2",
- "viem": "^2.21.51",
+ "viem": "^2.22.16",
  "zod": "^3.23.8"
  },
  "devDependencies": {

cdp-agentkit-core/typescript/src/action_providers/action_decorator.ts

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+
+import "reflect-metadata";
+
+/**
+ * Parameters for the create action decorator
+ */
+export interface CreateActionDecoratorParams {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+}
+
+/**
+ * Metadata key for the action decorator
+ */
+export const ACTION_DECORATOR_KEY = Symbol("agentkit:action");
+
+/**
+ * Metadata for AgentKit actions
+ */
+export interface ActionMetadata {
+ /**
+ * The name of the action
+ */
+ name: string;
+
+ /**
+ * The description of the action
+ */
+ description: string;
+
+ /**
+ * The schema of the action
+ */
+ schema: z.ZodSchema;
+
+ /**
+ * The function to invoke the action
+ */
+ invoke: Function;
+
+ /**
+ * The wallet provider to use for the action
+ */
+ walletProvider: boolean;
+}
+
+/**
+ * A map of action names to their metadata
+ */
+export type StoredActionMetadata = Map<string, ActionMetadata>;
+
+/**
+ * Decorator to embed metadata on class methods to indicate they are actions accessible to the agent
+ *
+ * @param params - The parameters for the action decorator
+ * @returns A decorator function
+ *
+ * @example
+ * ```typescript
+ * class MyActionProvider extends ActionProvider {
+ * @CreateAction({ name: "my_action", description: "My action", schema: myActionSchema })
+ * public myAction(args: z.infer<typeof myActionSchema>) {
+ * // ...
+ * }
+ * }
+ * ```
+ */
+export function CreateAction(params: CreateActionDecoratorParams) {
+ return (target: Object, propertyKey: string, descriptor: PropertyDescriptor) => {
+ const existingMetadata: StoredActionMetadata =
+ Reflect.getMetadata(ACTION_DECORATOR_KEY, target.constructor) || new Map();
+
+ const { isWalletProvider } = validateActionMethodArguments(target, propertyKey);
+
+ const metaData: ActionMetadata = {
+ name: params.name,
+ description: params.description,
+ schema: params.schema,
+ invoke: descriptor.value,
+ walletProvider: isWalletProvider,
+ };
+
+ existingMetadata.set(propertyKey, metaData);
+
+ Reflect.defineMetadata(ACTION_DECORATOR_KEY, existingMetadata, target.constructor);
+
+ return target;
+ };
+}
+
+function validateActionMethodArguments(
+ target: Object,
+ propertyKey: string,
+): {
+ isWalletProvider: boolean;
+} {
+ const className = target instanceof Object ? target.constructor.name : undefined;
+
+ const params = Reflect.getMetadata("design:paramtypes", target, propertyKey);
+
+ if (params == null) {
+ throw new Error(
+ `Failed to get parameters for action method ${propertyKey} on class ${className}`,
+ );
+ }
+
+ if (params.length > 2) {
+ throw new Error(
+ `Action method ${propertyKey} on class ${className} has more than 2 parameters`,
+ );
+ }
+
+ const walletProviderParam = params.find(param => {
+ if (!param || !param.prototype) {
+ return false;
+ }
+
+ if (param === WalletProvider) return true;
+ return param.prototype instanceof WalletProvider;
+ });
+
+ return {
+ isWalletProvider: !!walletProviderParam,
+ };
+}

cdp-agentkit-core/typescript/src/action_providers/action_provider.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { WalletProvider } from "../wallet_providers/wallet_provider";
+import { Network } from "../wallet_providers/wallet_provider";
+import { StoredActionMetadata, ACTION_DECORATOR_KEY } from "./action_decorator";
+
+/**
+ * Action is the interface for all actions.
+ */
+export interface Action<TActionSchema extends z.ZodSchema = z.ZodSchema> {
+ name: string;
+ description: string;
+ schema: TActionSchema;
+ invoke: (args: z.infer<TActionSchema>) => Promise<string>;
+}
+
+/**
+ * ActionProvider is the abstract base class for all action providers.
+ *
+ * @abstract
+ */
+export abstract class ActionProvider<TWalletProvider extends WalletProvider = WalletProvider> {
+ /**
+ * The name of the action provider.
+ */
+ public readonly name: string;
+
+ /**
+ * The action providers to combine.
+ */
+ public readonly actionProviders: ActionProvider<TWalletProvider>[];
+
+ /**
+ * The constructor for the action provider.
+ *
+ * @param name - The name of the action provider.
+ * @param actionProviders - The action providers to combine.
+ */
+ constructor(name: string, actionProviders: ActionProvider<TWalletProvider>[]) {
+ this.name = name;
+ this.actionProviders = actionProviders;
+ }
+
+ /**
+ * Checks if the action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the action provider supports the network, false otherwise.
+ */
+ abstract supportsNetwork(network: Network): boolean;
+
+ /**
+ * Gets the actions of the action provider bound to the given wallet provider.
+ *
+ * @param walletProvider - The wallet provider.
+ * @returns The actions of the action provider.
+ */
+ getActions(walletProvider: TWalletProvider): Action[] {
+ const actions: Action[] = [];
+
+ const actionProviders = [this, ...this.actionProviders];
+
+ for (const actionProvider of actionProviders) {
+ const actionsMetadataMap: StoredActionMetadata | undefined = Reflect.getMetadata(
+ ACTION_DECORATOR_KEY,
+ actionProvider.constructor,
+ );
+
+ if (!actionsMetadataMap) {
+ if (!(actionProvider instanceof ActionProvider)) {
+ console.warn(`Warning: ${actionProvider} is not an instance of ActionProvider.`);
+ } else {
+ console.warn(`Warning: ${actionProvider} has no actions.`);
+ }
+
+ continue;
+ }
+
+ for (const actionMetadata of actionsMetadataMap.values()) {
+ actions.push({
+ name: actionMetadata.name,
+ description: actionMetadata.description,
+ schema: actionMetadata.schema,
+ invoke: schemaArgs => {
+ const args: any[] = [];
+ if (actionMetadata.walletProvider) {
+ args[0] = walletProvider;
+ }
+
+ args.push(schemaArgs);
+
+ return actionMetadata.invoke.apply(actionProvider, args);
+ },
+ });
+ }
+ }
+
+ return actions;
+ }
+}

cdp-agentkit-core/typescript/src/action_providers/index.ts

@@ -0,0 +1,4 @@
+export * from "./action_decorator";
+export * from "./action_provider";
+
+export * from "./pyth";

cdp-agentkit-core/typescript/src/action_providers/pyth/README.md

@@ -0,0 +1 @@
+# Pyth Action Provider

cdp-agentkit-core/typescript/src/action_providers/pyth/index.ts

@@ -0,0 +1,2 @@
+export * from "./pyth_action_provider";
+export * from "./schemas";

cdp-agentkit-core/typescript/src/action_providers/pyth/pyth_action_provider.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { ActionProvider } from "../action_provider";
+import { Network } from "../../wallet_providers/wallet_provider";
+import { CreateAction } from "../action_decorator";
+import { PythFetchPriceFeedIDSchema, PythFetchPriceSchema } from "./schemas";
+
+/**
+ * PythActionProvider is an action provider for Pyth.
+ */
+export class PythActionProvider extends ActionProvider {
+ constructor() {
+ super("pyth", []);
+ }
+
+ /**
+ * Checks if the Pyth action provider supports the given network.
+ *
+ * @param network - The network to check.
+ * @returns True if the Pyth action provider supports the network, false otherwise.
+ */
+ supportsNetwork = (_: Network) => true;
+
+ /**
+ * Fetch the price feed ID for a given token symbol from Pyth.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price feed ID as a string.
+ */
+ @CreateAction({
+ name: "fetch_price_feed",
+ description: "Fetch the price feed ID for a given token symbol from Pyth.",
+ schema: PythFetchPriceFeedIDSchema,
+ })
+ async fetchPriceFeed(args: z.infer<typeof PythFetchPriceFeedIDSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/price_feeds?query=${args.tokenSymbol}&asset_type=crypto`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+
+ if (data.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ const filteredData = data.filter(
+ (item: any) => item.attributes.base.toLowerCase() === args.tokenSymbol.toLowerCase(),
+ );
+
+ if (filteredData.length === 0) {
+ throw new Error(`No price feed found for ${args.tokenSymbol}`);
+ }
+
+ return filteredData[0].id;
+ }
+
+ /**
+ * Fetches the price from Pyth given a Pyth price feed ID.
+ *
+ * @param args - The arguments for the action.
+ * @returns The price as a string.
+ */
+ @CreateAction({
+ name: "fetch_price",
+ description: `Fetch the price of a given price feed from Pyth.
+
+Inputs:
+- Pyth price feed ID
+
+Important notes:
+- Do not assume that a random ID is a Pyth price feed ID. If you are confused, ask a clarifying question.
+- This action only fetches price inputs from Pyth price feeds. No other source.
+- If you are asked to fetch the price from Pyth for a ticker symbol such as BTC, you must first use the pyth_fetch_price_feed_id
+action to retrieve the price feed ID before invoking the pyth_Fetch_price action
+`,
+ schema: PythFetchPriceSchema
+ })
+ async fetchPrice(args: z.infer<typeof PythFetchPriceSchema>): Promise<string> {
+ const url = `https://hermes.pyth.network/v2/updates/price/latest?ids[]=${args.priceFeedID}`;
+ const response = await fetch(url);
+
+ if (!response.ok) {
+ throw new Error(`HTTP error! status: ${response.status}`);
+ }
+
+ const data = await response.json();
+ const parsedData = data.parsed;
+
+ if (parsedData.length === 0) {
+ throw new Error(`No price data found for ${args.priceFeedID}`);
+ }
+
+ const priceInfo = parsedData[0].price;
+ const price = BigInt(priceInfo.price);
+ const exponent = priceInfo.expo;
+
+ if (exponent < 0) {
+ const adjustedPrice = price * BigInt(100);
+ const divisor = BigInt(10) ** BigInt(-exponent);
+ const scaledPrice = adjustedPrice / BigInt(divisor);
+ const priceStr = scaledPrice.toString();
+ const formattedPrice = `${priceStr.slice(0, -2)}.${priceStr.slice(-2)}`;
+ return formattedPrice.startsWith(".") ? `0${formattedPrice}` : formattedPrice;
+ }
+
+ const scaledPrice = price / BigInt(10) ** BigInt(exponent);
+ return scaledPrice.toString();
+ }
+}
+
+export const pythActionProvider = () => new PythActionProvider();