@coinbase/agentkit 0.9.0 → 0.10.0

package/README.md

@@ -5,60 +5,73 @@ AgentKit is a framework for easily enabling AI agents to take actions onchain. I
 ## Table of Contents
 
 - [Agentkit](#agentkit)
-- [Getting Started](#getting-started)
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Create an AgentKit instance](#create-an-agentkit-instance)
-  - [Create an AgentKit instance with a specified wallet provider](#create-an-agentkit-instance-with-a-specified-wallet-provider)
-  - [Create an AgentKit instance with a specified action providers](#create-an-agentkit-instance-with-a-specified-action-providers)
-  - [Use the agent's actions with a framework extension. For example, using LangChain + OpenAI](#use-the-agents-actions-with-a-framework-extension-for-example-using-langchain--openai)
-- [Action Providers](#action-providers)
-- [Creating an Action Provider](#creating-an-action-provider)
-  - [Adding Actions to your Action Provider](#adding-actions-to-your-action-provider)
-  - [Adding Actions to your Action Provider that use a Wallet Provider](#adding-actions-to-your-action-provider-that-use-a-wallet-provider)
-  - [Adding an Action Provider to your AgentKit instance](#adding-an-action-provider-to-your-agentkit-instance)
-- [EVM Wallet Providers](#evm-wallet-providers)
-  - [CdpEvmWalletProvider](#cdpevmwalletprovider)
-    - [Basic Configuration](#basic-configuration)
-    - [Using an existing wallet](#using-an-existing-wallet)
-    - [Creating a new wallet](#creating-a-new-wallet)
-    - [Environment Variables](#environment-variables)
-    - [Exporting a wallet](#exporting-a-wallet)
-  - [CdpSmartWalletProvider](#cdpsmartwalletprovider)
-    - [Basic Configuration](#basic-configuration-1)
-    - [Using an Existing Smart Wallet](#using-an-existing-smart-wallet)
-    - [Specifying an Owner Account](#specifying-an-owner-account)
-    - [Creating a New Smart Wallet](#creating-a-new-smart-wallet)
-    - [Environment Variables](#environment-variables-1)
-    - [Exporting Smart Wallet Information](#exporting-smart-wallet-information)
-    - [Key Differences from Regular Wallets](#key-differences-from-regular-wallets)
-  - [LegacyCdpWalletProvider](#legacycdpwalletprovider)
-    - [Network Configuration](#network-configuration)
-    - [Configuring from an existing CDP API Wallet](#configuring-from-an-existing-cdp-api-wallet)
-    - [Configuring from a mnemonic phrase](#configuring-from-a-mnemonic-phrase)
-    - [Exporting a wallet](#exporting-a-wallet)
-    - [Importing a wallet from WalletData JSON string](#importing-a-wallet-from-walletdata-json-string)
-    - [Configuring gas parameters](#configuring-legacycdpwalletprovider-gas-parameters)
-  - [ViemWalletProvider](#viemwalletprovider)
-    - [Configuring gas parameters](#configuring-viemwalletprovider-gas-parameters)
-  - [PrivyWalletProvider](#privywalletprovider)
-    - [Authorization Keys](#authorization-keys)
-    - [Exporting Privy Wallet information](#exporting-privy-wallet-information)
-  - [SmartWalletProvider](#smartwalletprovider)
-  - [ZeroDevWalletProvider](#zerodevwalletprovider)
-    - [Configuring from CdpWalletProvider](#configuring-from-cdpwalletprovider)
-    - [Configuring from PrivyWalletProvider](#configuring-from-privywalletprovider)
-    - [Configuring from ViemWalletProvider](#configuring-from-viemwalletprovider)
-- [SVM Wallet Providers](#svm-wallet-providers)
-  - [CdpSolanaWalletProvider](#cdpsolanawalletprovider)
-  - [SolanaKeypairWalletProvider](#solanakeypairwalletprovider)
-    - [Network Configuration](#solana-network-configuration)
-    - [RPC URL Configuration](#rpc-url-configuration)
-  - [PrivyWalletProvider](#privywalletprovider-solana)
-    - [Connection Configuration](#connection-configuration)
-    - [Authorization Keys](#authorization-keys)
-    - [Exporting Privy Wallet information](#exporting-privy-wallet-information)
-- [Contributing](#contributing)
+  - [Table of Contents](#table-of-contents)
+  - [Getting Started](#getting-started)
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Create an AgentKit instance. If no wallet or action providers are specified, the agent will use the `CdpWalletProvider` and `WalletProvider` action provider.](#create-an-agentkit-instance-if-no-wallet-or-action-providers-are-specified-the-agent-will-use-the-cdpwalletprovider-and-walletprovider-action-provider)
+    - [Create an AgentKit instance](#create-an-agentkit-instance)
+    - [Create an AgentKit instance with a specified wallet provider.](#create-an-agentkit-instance-with-a-specified-wallet-provider)
+    - [Create an AgentKit instance with a specified action providers.](#create-an-agentkit-instance-with-a-specified-action-providers)
+    - [Use the agent's actions with a framework extension. For example, using LangChain + OpenAI.](#use-the-agents-actions-with-a-framework-extension-for-example-using-langchain--openai)
+  - [Action Providers](#action-providers)
+  - [Creating an Action Provider](#creating-an-action-provider)
+    - [Adding Actions to your Action Provider](#adding-actions-to-your-action-provider)
+      - [Required Typescript Compiler Options](#required-typescript-compiler-options)
+      - [Steps to create an action](#steps-to-create-an-action)
+      - [Adding Actions to your Action Provider that use a Wallet Provider](#adding-actions-to-your-action-provider-that-use-a-wallet-provider)
+    - [Adding an Action Provider to your AgentKit instance.](#adding-an-action-provider-to-your-agentkit-instance)
+  - [EVM Wallet Providers](#evm-wallet-providers)
+    - [CdpEvmWalletProvider](#cdpevmwalletprovider)
+      - [Basic Configuration](#basic-configuration)
+      - [Using an Existing Wallet](#using-an-existing-wallet)
+      - [Creating a New Wallet](#creating-a-new-wallet)
+      - [Environment Variables](#environment-variables)
+      - [Exporting a wallet](#exporting-a-wallet)
+    - [CdpSmartWalletProvider](#cdpsmartwalletprovider)
+      - [Basic Configuration](#basic-configuration-1)
+      - [Using an Existing Smart Wallet](#using-an-existing-smart-wallet)
+      - [Specifying an Owner Account](#specifying-an-owner-account)
+      - [Creating a New Smart Wallet](#creating-a-new-smart-wallet)
+      - [Environment Variables](#environment-variables-1)
+      - [Exporting Smart Wallet Information](#exporting-smart-wallet-information)
+      - [Key Differences from Regular Wallets](#key-differences-from-regular-wallets)
+    - [LegacyCdpWalletProvider](#legacycdpwalletprovider)
+      - [Network Configuration](#network-configuration)
+      - [Configuring from an existing CDP API Wallet](#configuring-from-an-existing-cdp-api-wallet)
+      - [Configuring from a mnemonic phrase](#configuring-from-a-mnemonic-phrase)
+      - [Exporting a wallet](#exporting-a-wallet-1)
+      - [Importing a wallet from `WalletData` JSON string](#importing-a-wallet-from-walletdata-json-string)
+      - [Configuring LegacyCdpWalletProvider gas parameters](#configuring-legacycdpwalletprovider-gas-parameters)
+    - [ViemWalletProvider](#viemwalletprovider)
+      - [Configuring ViemWalletProvider gas parameters](#configuring-viemwalletprovider-gas-parameters)
+    - [PrivyWalletProvider](#privywalletprovider)
+      - [Server Wallet Configuration](#server-wallet-configuration)
+      - [Delegated Embedded Wallet Configuration](#delegated-embedded-wallet-configuration)
+    - [Prerequisites](#prerequisites)
+    - [Supported Operations](#supported-operations)
+      - [Authorization Keys](#authorization-keys)
+      - [Exporting Privy Wallet information](#exporting-privy-wallet-information)
+    - [SmartWalletProvider](#smartwalletprovider)
+    - [ZeroDevWalletProvider](#zerodevwalletprovider)
+      - [Configuring from CdpWalletProvider](#configuring-from-cdpwalletprovider)
+      - [Configuring from PrivyWalletProvider](#configuring-from-privywalletprovider)
+      - [Configuring from ViemWalletProvider](#configuring-from-viemwalletprovider)
+  - [SVM Wallet Providers](#svm-wallet-providers)
+    - [CdpV2SolanaWalletProvider](#cdpv2solanawalletprovider)
+      - [Basic Configuration](#basic-configuration-2)
+      - [Using an Existing Wallet](#using-an-existing-wallet-1)
+      - [Creating a New Wallet](#creating-a-new-wallet-1)
+      - [Environment Variables](#environment-variables-2)
+      - [Supported Networks](#supported-networks)
+    - [SolanaKeypairWalletProvider](#solanakeypairwalletprovider)
+      - [Solana Network Configuration](#solana-network-configuration)
+      - [RPC URL Configuration](#rpc-url-configuration)
+    - [PrivyWalletProvider (Solana)](#privywalletprovider-solana)
+      - [Connection Configuration](#connection-configuration)
+      - [Authorization Keys](#authorization-keys-1)
+      - [Exporting Privy Wallet information](#exporting-privy-wallet-information-1)
+  - [Contributing](#contributing)
 
 ## Getting Started
 
@@ -158,6 +171,32 @@ const agent = createReactAgent({
 
 ## Action Providers
 
+<details>
+<summary><strong>CDP EVM Wallet</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>list_spend_permissions</code></td>
+    <td width="768">Lists spend permissions that have been granted to the current EVM wallet by a smart account.</td>
+</tr>
+<tr>
+    <td width="200"><code>use_spend_permission</code></td>
+    <td width="768">Uses a spend permission to spend tokens on behalf of a smart account that the current EVM wallet has permission to spend.</td>
+</tr>
+</table>
+</details>
+<details>
+<summary><strong>CDP Smart Wallet</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>list_spend_permissions</code></td>
+    <td width="768">Lists spend permissions that have been granted to the current smart wallet by a smart account.</td>
+</tr>
+<tr>
+    <td width="200"><code>use_spend_permission</code></td>
+    <td width="768">Uses a spend permission to spend tokens on behalf of a smart account that the current smart wallet has permission to spend.</td>
+</tr>
+</table>
+</details>
 <details>
 <summary><strong>Across</strong></summary>
 <table width="100%">
@@ -261,7 +300,7 @@ const agent = createReactAgent({
 </tr>
 <tr>
     <td width="200"><code>post_cast</code></td>
-    <td width="768">Creates a new cast (message) on Farcaster with up to 280 characters.</td>
+    <td width="768">Creates a new cast (message) on Farcaster with up to 280 characters and support for up to 2 embedded URLs.</td>
 </tr>
 </table>
 </details>
@@ -362,6 +401,23 @@ const agent = createReactAgent({
     <td width="200"><code>post_tweet_reply</code></td>
     <td width="768">Creates a reply to an existing tweet using the tweet's unique identifier.</td>
 </tr>
+<tr>
+    <td width="200"><code>upload_media</code></td>
+    <td width="768">Uploads media (images, videos) to Twitter that can be attached to tweets.</td>
+</tr>
+</table>
+</details>
+<details>
+<summary><strong>TrueMarkets</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>get_active_markets</code></td>
+    <td width="768">Retrieves active prediction markets from Truemarkets with pagination and sorting options.</td>
+</tr>
+<tr>
+    <td width="200"><code>get_market_details</code></td>
+    <td width="768">Fetches comprehensive details for a specific Truemarkets prediction market including question, status, prices, and liquidity.</td>
+</tr>
 </table>
 </details>
 <details>
@@ -384,6 +440,10 @@ const agent = createReactAgent({
     <td width="200"><code>wrap_eth</code></td>
     <td width="768">Converts native ETH to Wrapped ETH (WETH) on Base Sepolia or Base Mainnet.</td>
 </tr>
+<tr>
+    <td width="200"><code>unwrap_eth</code></td>
+    <td width="768">Converts Wrapped ETH (WETH) to Native ETH on Base Sepolia or Base Mainnet.</td>
+</tr>
 </table>
 </details>
 <details>
@@ -431,6 +491,19 @@ it will return payment details that can be used on retry.</td>
 </table>
 </details>
 <details>
+<summary><strong>Zerion</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>getPortfolioOverview</code></td>
+    <td width="768">Fetches and summarizes a crypto wallet's portfolio in USD.</td>
+</tr>
+<tr>
+    <td width="200"><code>getFungiblePositions</code></td>
+    <td width="768">Retrieves and summarizes a wallet's fungible token holdings (including DeFi positions)</td>
+</tr>
+</table>
+</details>
+<details>
 <summary><strong>ZeroDev Wallet</strong></summary>
 <table width="100%">
 <tr>
@@ -439,6 +512,15 @@ it will return payment details that can be used on retry.</td>
 </tr>
 </table>
 </details>
+<details>
+<summary><strong>Zora</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>coinIt</code></td>
+    <td width="768">Creates a new Zora coin with customizable name, symbol, description, and image.</td>
+</tr>
+</table>
+</details>
 
 ## Creating an Action Provider
 

package/dist/action-providers/cdp/cdpApiActionProvider.js

@@ -111,6 +111,8 @@ class CdpApiActionProvider extends actionProvider_1.ActionProvider {
                         amount: args.amount,
                         slippageBps: 100, // 1% slippage tolerance
                         // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        paymasterUrl: walletProvider.getPaymasterUrl?.(),
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
                     });
                     return `Successfully swapped ${args.amount} ${args.fromAssetId.toUpperCase()} to ${args.toAssetId.toUpperCase()}. Transaction hash: ${swapResult.transactionHash}`;
                 }

package/dist/action-providers/cdp/cdpEvmWalletActionProvider.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { WalletProvider } from "../../wallet-providers";
+import { CdpEvmWalletProvider } from "../../wallet-providers/cdpEvmWalletProvider";
+import { ActionProvider } from "../actionProvider";
+import { UseSpendPermissionSchema, ListSpendPermissionsSchema } from "./schemas";
+import type { Network } from "../../network";
+/**
+ * CdpEvmWalletActionProvider is an action provider for CDP EVM Wallet specific actions.
+ *
+ * This provider is scoped specifically to EVM wallets and provides actions
+ * that are optimized for EVM functionality, including spend permission usage.
+ */
+export declare class CdpEvmWalletActionProvider extends ActionProvider<CdpEvmWalletProvider> {
+    #private;
+    /**
+     * Constructor for the CdpEvmWalletActionProvider class.
+     */
+    constructor();
+    /**
+     * Lists spend permissions for a smart account.
+     *
+     * @param walletProvider - The server wallet provider to use for listing permissions.
+     * @param args - The input arguments for listing spend permissions.
+     * @returns A list of spend permissions available to the current wallet.
+     */
+    listSpendPermissions(walletProvider: WalletProvider, args: z.infer<typeof ListSpendPermissionsSchema>): Promise<string>;
+    /**
+     * Uses a spend permission to transfer tokens from a smart account to the current EVM wallet.
+     *
+     * @param walletProvider - The EVM wallet provider to use for the spend operation.
+     * @param args - The input arguments for using the spend permission.
+     * @returns A confirmation message with transaction details.
+     */
+    useSpendPermission(walletProvider: WalletProvider, args: z.infer<typeof UseSpendPermissionSchema>): Promise<string>;
+    /**
+     * Checks if the EVM wallet action provider supports the given network.
+     *
+     * @param network - The network to check.
+     * @returns True if the EVM wallet action provider supports the network, false otherwise.
+     */
+    supportsNetwork: (network: Network) => boolean;
+}
+export declare const cdpEvmWalletActionProvider: () => CdpEvmWalletActionProvider;

package/dist/action-providers/cdp/cdpEvmWalletActionProvider.js

@@ -0,0 +1,151 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _CdpEvmWalletActionProvider_instances, _CdpEvmWalletActionProvider_getCdpSdkNetwork;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cdpEvmWalletActionProvider = exports.CdpEvmWalletActionProvider = void 0;
+const zod_1 = require("zod");
+const wallet_providers_1 = require("../../wallet-providers");
+const cdpShared_1 = require("../../wallet-providers/cdpShared");
+const actionDecorator_1 = require("../actionDecorator");
+const actionProvider_1 = require("../actionProvider");
+const schemas_1 = require("./schemas");
+const spendPermissionUtils_1 = require("./spendPermissionUtils");
+/**
+ * CdpEvmWalletActionProvider is an action provider for CDP EVM Wallet specific actions.
+ *
+ * This provider is scoped specifically to EVM wallets and provides actions
+ * that are optimized for EVM functionality, including spend permission usage.
+ */
+class CdpEvmWalletActionProvider extends actionProvider_1.ActionProvider {
+    /**
+     * Constructor for the CdpEvmWalletActionProvider class.
+     */
+    constructor() {
+        super("cdp_evm_wallet", []);
+        _CdpEvmWalletActionProvider_instances.add(this);
+        /**
+         * Checks if the EVM wallet action provider supports the given network.
+         *
+         * @param network - The network to check.
+         * @returns True if the EVM wallet action provider supports the network, false otherwise.
+         */
+        this.supportsNetwork = (network) => {
+            // EVM wallets support EVM networks in general
+            return network.protocolFamily === "evm";
+        };
+    }
+    /**
+     * Lists spend permissions for a smart account.
+     *
+     * @param walletProvider - The server wallet provider to use for listing permissions.
+     * @param args - The input arguments for listing spend permissions.
+     * @returns A list of spend permissions available to the current wallet.
+     */
+    async listSpendPermissions(walletProvider, args) {
+        const network = walletProvider.getNetwork();
+        if ((0, cdpShared_1.isWalletProviderWithClient)(walletProvider)) {
+            if (network.protocolFamily === "evm") {
+                return await (0, spendPermissionUtils_1.listSpendPermissionsForSpender)(walletProvider.getClient(), args.smartAccountAddress, walletProvider.getAddress());
+            }
+            else {
+                return "Spend permissions are currently only supported on EVM networks.";
+            }
+        }
+        else {
+            return "Wallet provider is not a CDP Wallet Provider.";
+        }
+    }
+    /**
+     * Uses a spend permission to transfer tokens from a smart account to the current EVM wallet.
+     *
+     * @param walletProvider - The EVM wallet provider to use for the spend operation.
+     * @param args - The input arguments for using the spend permission.
+     * @returns A confirmation message with transaction details.
+     */
+    async useSpendPermission(walletProvider, args) {
+        const network = walletProvider.getNetwork();
+        const cdpNetwork = __classPrivateFieldGet(this, _CdpEvmWalletActionProvider_instances, "m", _CdpEvmWalletActionProvider_getCdpSdkNetwork).call(this, network.networkId);
+        if ((0, cdpShared_1.isWalletProviderWithClient)(walletProvider)) {
+            if (network.protocolFamily === "evm") {
+                try {
+                    const spenderAddress = walletProvider.getAddress();
+                    const permission = await (0, spendPermissionUtils_1.findLatestSpendPermission)(walletProvider.getClient(), args.smartAccountAddress, spenderAddress);
+                    const account = await walletProvider.getClient().evm.getAccount({
+                        address: spenderAddress,
+                    });
+                    const spendResult = await account.useSpendPermission({
+                        spendPermission: permission,
+                        value: BigInt(args.value),
+                        network: cdpNetwork,
+                    });
+                    return `Successfully spent ${args.value} tokens using spend permission. Transaction hash: ${spendResult.transactionHash}`;
+                }
+                catch (error) {
+                    return `Failed to use spend permission: ${error}`;
+                }
+            }
+            else {
+                return "Spend permissions are currently only supported on EVM networks.";
+            }
+        }
+        else {
+            return "Wallet provider is not a CDP Wallet Provider.";
+        }
+    }
+}
+exports.CdpEvmWalletActionProvider = CdpEvmWalletActionProvider;
+_CdpEvmWalletActionProvider_instances = new WeakSet(), _CdpEvmWalletActionProvider_getCdpSdkNetwork = function _CdpEvmWalletActionProvider_getCdpSdkNetwork(networkId) {
+    switch (networkId) {
+        case "base-sepolia":
+            return "base-sepolia";
+        case "base-mainnet":
+            return "base";
+        case "ethereum-sepolia":
+            return "ethereum-sepolia";
+        case "ethereum-mainnet":
+            return "ethereum";
+        default:
+            return networkId; // For other networks, use as-is
+    }
+};
+__decorate([
+    (0, actionDecorator_1.CreateAction)({
+        name: "list_spend_permissions",
+        description: `This tool lists spend permissions that have been granted to the current EVM wallet by a smart account.
+It takes a smart account address and returns spend permissions where the current EVM wallet is the spender.
+This is useful to see what spending allowances have been granted before using them.
+This action is specifically designed for EVM wallets.`,
+        schema: schemas_1.ListSpendPermissionsSchema,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [wallet_providers_1.WalletProvider, void 0]),
+    __metadata("design:returntype", Promise)
+], CdpEvmWalletActionProvider.prototype, "listSpendPermissions", null);
+__decorate([
+    (0, actionDecorator_1.CreateAction)({
+        name: "use_spend_permission",
+        description: `This tool uses a spend permission to spend tokens on behalf of a smart account that the current EVM wallet has permission to spend.
+It automatically finds the latest valid spend permission granted by the smart account to the current EVM wallet and uses it to spend the specified amount.
+The smart account must have previously granted a spend permission to the current EVM wallet using createSpendPermission.
+This action is specifically designed for EVM wallets and uses the EVM wallet for spend permission execution.`,
+        schema: schemas_1.UseSpendPermissionSchema,
+    }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [wallet_providers_1.WalletProvider, void 0]),
+    __metadata("design:returntype", Promise)
+], CdpEvmWalletActionProvider.prototype, "useSpendPermission", null);
+const cdpEvmWalletActionProvider = () => new CdpEvmWalletActionProvider();
+exports.cdpEvmWalletActionProvider = cdpEvmWalletActionProvider;

package/dist/action-providers/cdp/cdpEvmWalletActionProvider.test.d.ts

@@ -0,0 +1 @@
+export {};