@coinbase/agentkit 0.1.2 → 0.2.0

package/README.md

@@ -8,22 +8,32 @@ AgentKit is a framework for easily enabling AI agents to take actions onchain. I
 - [Getting Started](#getting-started)
 - [Installation](#installation)
 - [Usage](#usage)
-  - [Create an AgentKit instance](##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)
   - [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)
-- [Wallet Providers](#wallet-providers)
+- [EVM Wallet Providers](#evm-wallet-providers)
   - [CdpWalletProvider](#cdpwalletprovider)
     - [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-cdpwalletprovider-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)
+- [SVM Wallet Providers](#svm-wallet-providers)
+  - [SolanaKeypairWalletProvider](#solanakeypairwalletprovider)
+    - [Network Configuration](#solana-network-configuration)
+    - [RPC URL Configuration](#rpc-url-configuration)
 - [Contributing](#contributing)
 
 ## Getting Started
@@ -49,6 +59,17 @@ const agentKit = await AgentKit.from({
 });
 ```
 
+### Create an AgentKit instance
+
+If no wallet or action provider are specified, the agent will use the `CdpWalletProvider` and `WalletActionProvider` action provider by default.
+
+```typescript
+const agentKit = await AgentKit.from({
+  cdpApiKeyName: "CDP API KEY NAME",
+  cdpApiKeyPrivate: "CDP API KEY PRIVATE KEY",
+});
+```
+
 ### Create an AgentKit instance with a specified wallet provider.
 
 ```typescript
@@ -109,6 +130,167 @@ const agent = createReactAgent({
 });
 ```
 
+## Action Providers
+<details>
+<summary><strong>Basename</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>register_basename</code></td>
+    <td width="768">Registers a custom .base.eth or .basetest.eth domain name for the wallet address.</td>
+</tr>
+</table>
+</details>
+<details>
+<summary><strong>CDP Wallet</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>deploy_contract</code></td>
+    <td width="768">Deploys a custom smart contract using specified Solidity version and constructor arguments.</td>
+</tr>
+<tr>
+    <td width="200"><code>deploy_nft</code></td>
+    <td width="768">Deploys a standard ERC-721 NFT contract with configurable name, symbol, and metadata URI.</td>
+</tr>
+<tr>
+    <td width="200"><code>deploy_token</code></td>
+    <td width="768">Deploys a standard ERC-20 token contract with configurable name, symbol, and initial supply.</td>
+</tr>
+<tr>
+    <td width="200"><code>trade</code></td>
+    <td width="768">Executes a token swap between two assets at current market rates on mainnet networks.</td>
+</tr>
+</table>
+</details>
+<details>
+<summary><strong>ERC20</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>get_balance</code></td>
+    <td width="768">Retrieves the token balance for a specified address and ERC-20 contract.</td>
+</tr>
+<tr>
+    <td width="200"><code>transfer</code></td>
+    <td width="768">Transfers a specified amount of ERC-20 tokens to a destination address.</td>
+</tr>
+</table>
+</details>
+<details>
+<summary><strong>ERC721</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>get_balance</code></td>
+    <td width="768">Retrieves the NFT balance for a specified address and ERC-721 contract.</td>
+</tr>
+<tr>
+    <td width="200"><code>mint</code></td>
+    <td width="768">Creates a new NFT token and assigns it to a specified destination address.</td>
+</tr>
+<tr>
+    <td width="200"><code>transfer</code></td>
+    <td width="768">Transfers ownership of a specific NFT token to a destination address.</td>
+</tr>
+</table>
+</details>
+<details>
+<summary><strong>Farcaster</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>account_details</code></td>
+    <td width="768">Fetches profile information and metadata for the authenticated Farcaster account.</td>
+</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>
+</tr>
+</table>
+</details>
+<details>
+<summary><strong>Morpho</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>deposit</code></td>
+    <td width="768">Deposits a specified amount of assets into a designated Morpho Vault.</td>
+</tr>
+<tr>
+    <td width="200"><code>withdraw</code></td>
+    <td width="768">Withdraws a specified amount of assets from a designated Morpho Vault.</td>
+</tr>
+</table>
+</details>
+<details>
+<summary><strong>Pyth</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>fetch_price</code></td>
+    <td width="768">Retrieves current price data from a specified Pyth price feed.</td>
+</tr>
+<tr>
+    <td width="200"><code>fetch_price_feed_id</code></td>
+    <td width="768">Retrieves the unique price feed identifier for a given token symbol.</td>
+</tr>
+</table>
+</details>
+<details>
+<summary><strong>Twitter</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>account_details</code></td>
+    <td width="768">Fetches profile information and metadata for the authenticated Twitter account.</td>
+</tr>
+<tr>
+    <td width="200"><code>account_mentions</code></td>
+    <td width="768">Retrieves recent mentions and interactions for the authenticated account.</td>
+</tr>
+<tr>
+    <td width="200"><code>post_tweet</code></td>
+    <td width="768">Creates a new tweet on the authenticated Twitter account.</td>
+</tr>
+<tr>
+    <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>
+</table>
+</details>
+<details>
+<summary><strong>Wallet</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>get_wallet_details</code></td>
+    <td width="768">Retrieves wallet address, network info, balances, and provider details.</td>
+</tr>
+<tr>
+    <td width="200"><code>native_transfer</code></td>
+    <td width="768">Transfers native blockchain tokens (e.g., ETH) to a destination address.</td>
+</tr>
+</table>
+</details>
+<details>
+<summary><strong>WETH</strong></summary>
+<table width="100%">
+<tr>
+    <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>
+</table>
+</details>
+<details>
+<summary><strong>WOW</strong></summary>
+<table width="100%">
+<tr>
+    <td width="200"><code>buy_token</code></td>
+    <td width="768">Purchases WOW tokens from a contract using ETH based on bonding curve pricing.</td>
+</tr>
+<tr>
+    <td width="200"><code>create_token</code></td>
+    <td width="768">Creates a new WOW memecoin with bonding curve functionality via Zora factory.</td>
+</tr>
+<tr>
+    <td width="200"><code>sell_token</code></td>
+    <td width="768">Sells WOW tokens back to the contract for ETH based on bonding curve pricing.</td>
+</tr>
+</table>
+</details>
+
 ## Creating an Action Provider
 
 Action providers are used to define the actions that an agent can take. They are defined as a class that extends the `ActionProvider` abstract class.
@@ -216,13 +398,14 @@ const agentKit = new AgentKit({
 });
 ```
 
-## Wallet Providers
+## EVM Wallet Providers
 
 Wallet providers give an agent access to a wallet. AgentKit currently supports the following wallet providers:
 
 EVM:
-- [CdpWalletProvider](./src/wallet-providers/cdpWalletProvider.ts)
-- [ViemWalletProvider](./src/wallet-providers/viemWalletProvider.ts)
+- [CdpWalletProvider](https://github.com/coinbase/agentkit/blob/main/typescript/agentkit/src/wallet-providers/cdpWalletProvider.ts)
+- [ViemWalletProvider](https://github.com/coinbase/agentkit/blob/main/typescript/agentkit/src/wallet-providers/viemWalletProvider.ts)
+- [PrivyWalletProvider](https://github.com/coinbase/agentkit/blob/main/typescript/agentkit/src/wallet-providers/privyWalletProvider.ts)
 
 ### CdpWalletProvider
 
@@ -296,6 +479,27 @@ const walletProvider = await CdpWalletProvider.configureWithWallet({
 });
 ```
 
+#### Configuring CdpWalletProvider gas parameters
+
+The `CdpWalletProvider` also exposes parameters for effecting the gas calculations.
+
+```typescript
+import { CdpWalletProvider } from "@coinbase/agentkit";
+
+const walletProvider = await CdpWalletProvider.configureWithWallet({
+    cdpWalletData: "WALLET DATA JSON STRING",
+    apiKeyName: "CDP API KEY NAME",
+    apiKeyPrivate: "CDP API KEY PRIVATE KEY",
+    gas: {
+        gasLimitMultiplier: 2.0,  // Adjusts gas limit estimation
+        feePerGasMultiplier: 2.0, // Adjusts max fee per gas
+    }
+});
+```
+
+**Note**: Gas parameters only impact the `walletProvider.sendTransaction` behavior. Actions that do not rely on direct transaction calls, such as `deploy_token`, `deploy_contract`, and `native_transfer`, remain unaffected.
+
+
 ### ViemWalletProvider
 
 The `ViemWalletProvider` is a wallet provider that uses the [Viem library](https://viem.sh/docs/getting-started). It is useful for interacting with any EVM-compatible chain.
@@ -320,6 +524,116 @@ const client = createWalletClient({
 const walletProvider = new ViemWalletProvider(client);
 ```
 
+#### Configuring ViemWalletProvider gas parameters
+
+The `ViemWalletProvider` also exposes parameters for effecting the gas calculations.
+
+```typescript
+import { ViemWalletProvider } from "@coinbase/agentkit";
+import { privateKeyToAccount } from "viem/accounts";
+import { baseSepolia } from "viem/chains";
+import { http } from "viem/transports";
+import { createWalletClient } from "viem";
+
+const account = privateKeyToAccount(
+  "0x4c0883a69102937d6231471b5dbb6208ffd70c02a813d7f2da1c54f2e3be9f38",
+);
+
+const client = createWalletClient({
+  account,
+  chain: baseSepolia,
+  transport: http(),
+});
+
+const walletProvider = new ViemWalletProvider(client, {
+    gasLimitMultiplier: 2.0,  // Adjusts gas limit estimation
+    feePerGasMultiplier: 2.0, // Adjusts max fee per gas
+});
+```
+
+### PrivyWalletProvider
+
+The `PrivyWalletProvider` is a wallet provider that uses [Privy Server Wallets](https://docs.privy.io/guide/server-wallets/). This implementation extends the `ViemWalletProvider`.
+
+```typescript
+import { PrivyWalletProvider } from "@coinbase/agentkit";
+
+// Configure Wallet Provider
+const config = {
+    appId: "PRIVY_APP_ID",
+    appSecret: "PRIVY_APP_SECRET",
+    chainId: "84532", // base-sepolia
+    walletId: "PRIVY_WALLET_ID", // optional, otherwise a new wallet will be created
+    authorizationPrivateKey: PRIVY_WALLET_AUTHORIZATION_PRIVATE_KEY, // optional, required if your account is using authorization keys
+    authorizationKeyId: PRIVY_WALLET_AUTHORIZATION_KEY_ID, // optional, only required to create a new wallet if walletId is not provided
+};
+
+const walletProvider = await PrivyWalletProvider.configureWithWallet(config);
+```
+
+#### Authorization Keys
+
+Privy offers the option to use authorization keys to secure your server wallets.
+
+You can manage authorization keys from your [Privy dashboard](https://dashboard.privy.io/account) or programmatically [using the API](https://docs.privy.io/guide/server-wallets/authorization/signatures).
+
+When using authorization keys, you must provide the `authorizationPrivateKey` and `authorizationKeyId` parameters to the `configureWithWallet` method if you are creating a new wallet. Please note that when creating a key, if you enable "Create and modify wallets", you will be required to use that key when creating new wallets via the PrivyWalletProvider.
+
+#### Exporting Privy Wallet information
+
+The `PrivyWalletProvider` can export wallet information by calling the `exportWallet` method. 
+
+```typescript
+const walletData = await walletProvider.exportWallet();
+
+// walletData will be in the following format:
+{
+    walletId: string;
+    authorizationKey: string | undefined;
+    chainId: string | undefined;
+}
+```
+
+## SVM Wallet Providers
+
+SVM:
+- [SolanaKeypairWalletProvider](https://github.com/coinbase/agentkit/blob/main/typescript/agentkit/src/wallet-providers/solanaKeypairWalletProvider.ts)
+
+### SolanaKeypairWalletProvider
+
+The `SolanaKeypairWalletProvider` is a wallet provider that uses the API [Solana web3.js](https://solana-labs.github.io/solana-web3.js/).
+
+#### Solana Network Configuration
+
+The `SolanaKeypairWalletProvider` can be configured to use a specific network by passing the `networkId` parameter to the `fromNetwork` method. The `networkId` is the ID of the Solana network you want to use. Valid values are `solana-mainnet`, `solana-devnet` and `solana-testnet`.
+
+The default RPC endpoints for each network are as follows:
+- `solana-mainnet`: `https://api.mainnet-beta.solana.com`
+- `solana-devnet`: `https://api.devnet.solana.com`
+- `solana-testnet`: `https://api.testnet.solana.com`
+
+```typescript
+import { SOLANA_NETWORK_ID, SolanaKeypairWalletProvider } from "@coinbase/agentkit";
+
+// Configure Solana Keypair Wallet Provider
+const privateKey = process.env.SOLANA_PRIVATE_KEY;
+const network = process.env.NETWORK_ID as SOLANA_NETWORK_ID;
+const walletProvider = await SolanaKeypairWalletProvider.fromNetwork(network, privateKey);
+```
+
+#### RPC URL Configuration
+
+The `SolanaKeypairWalletProvider` can be configured to use a specific RPC url by passing the `rpcUrl` parameter to the `fromRpcUrl` method. The `rpcUrl` will determine the network you are using.
+
+```typescript
+import { SOLANA_NETWORK_ID, SolanaKeypairWalletProvider } from "@coinbase/agentkit";
+
+// Configure Solana Keypair Wallet Provider
+const privateKey = process.env.SOLANA_PRIVATE_KEY;
+const rpcUrl = process.env.SOLANA_RPC_URL;
+const walletProvider = await SolanaKeypairWalletProvider.fromRpcUrl(network, privateKey);
+```
+
 ## Contributing
 
 See [CONTRIBUTING.md](../../CONTRIBUTING.md) for more information.

package/dist/action-providers/erc20/schemas.d.ts

@@ -7,12 +7,12 @@ export declare const TransferSchema: z.ZodObject<{
     contractAddress: z.ZodString;
     destination: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    amount: bigint;
     contractAddress: string;
+    amount: bigint;
     destination: string;
 }, {
-    amount: bigint;
     contractAddress: string;
+    amount: bigint;
     destination: string;
 }>;
 /**

package/dist/action-providers/index.d.ts

@@ -1,15 +1,16 @@
 export * from "./actionDecorator";
 export * from "./actionProvider";
-export * from "./pyth";
+export * from "./customActionProvider";
+export * from "./alchemy";
+export * from "./basename";
 export * from "./cdp";
-export * from "./weth";
 export * from "./erc20";
 export * from "./erc721";
-export * from "./morpho";
-export * from "./basename";
 export * from "./farcaster";
+export * from "./pyth";
+export * from "./moonwell";
+export * from "./morpho";
+export * from "./spl";
 export * from "./twitter";
 export * from "./wallet";
-export * from "./customActionProvider";
-export * from "./alchemy";
-export * from "./moonwell";
+export * from "./weth";

package/dist/action-providers/index.js

@@ -16,16 +16,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./actionDecorator"), exports);
 __exportStar(require("./actionProvider"), exports);
-__exportStar(require("./pyth"), exports);
+__exportStar(require("./customActionProvider"), exports);
+__exportStar(require("./alchemy"), exports);
+__exportStar(require("./basename"), exports);
 __exportStar(require("./cdp"), exports);
-__exportStar(require("./weth"), exports);
 __exportStar(require("./erc20"), exports);
 __exportStar(require("./erc721"), exports);
-__exportStar(require("./morpho"), exports);
-__exportStar(require("./basename"), exports);
 __exportStar(require("./farcaster"), exports);
+__exportStar(require("./pyth"), exports);
+__exportStar(require("./moonwell"), exports);
+__exportStar(require("./morpho"), exports);
+__exportStar(require("./spl"), exports);
 __exportStar(require("./twitter"), exports);
 __exportStar(require("./wallet"), exports);
-__exportStar(require("./customActionProvider"), exports);
-__exportStar(require("./alchemy"), exports);
-__exportStar(require("./moonwell"), exports);
+__exportStar(require("./weth"), exports);

package/dist/action-providers/morpho/schemas.d.ts

@@ -8,13 +8,13 @@ export declare const DepositSchema: z.ZodObject<{
     tokenAddress: z.ZodString;
     vaultAddress: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    assets: string;
     receiver: string;
+    assets: string;
     tokenAddress: string;
     vaultAddress: string;
 }, {
-    assets: string;
     receiver: string;
+    assets: string;
     tokenAddress: string;
     vaultAddress: string;
 }>;
@@ -26,11 +26,11 @@ export declare const WithdrawSchema: z.ZodObject<{
     assets: z.ZodString;
     receiver: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    assets: string;
     receiver: string;
+    assets: string;
     vaultAddress: string;
 }, {
-    assets: string;
     receiver: string;
+    assets: string;
     vaultAddress: string;
 }>;

package/dist/action-providers/spl/index.d.ts

@@ -0,0 +1 @@
+export * from "./splActionProvider";

package/dist/action-providers/spl/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./splActionProvider"), exports);

package/dist/action-providers/spl/schemas.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+/**
+ * Schema for transferring SPL tokens to another address.
+ */
+export declare const TransferTokenSchema: z.ZodObject<{
+    recipient: z.ZodString;
+    mintAddress: z.ZodString;
+    amount: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    amount: number;
+    recipient: string;
+    mintAddress: string;
+}, {
+    amount: number;
+    recipient: string;
+    mintAddress: string;
+}>;

package/dist/action-providers/spl/schemas.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransferTokenSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Schema for transferring SPL tokens to another address.
+ */
+exports.TransferTokenSchema = zod_1.z
+    .object({
+    recipient: zod_1.z.string().describe("The recipient's Solana address"),
+    mintAddress: zod_1.z.string().describe("The SPL token's mint address"),
+    amount: zod_1.z.number().positive().describe("Amount of tokens to transfer"),
+})
+    .describe("Transfer SPL tokens to another Solana address");

package/dist/action-providers/spl/splActionProvider.d.ts

@@ -0,0 +1,37 @@
+import { ActionProvider } from "../actionProvider";
+import { Network } from "../../network";
+import { SvmWalletProvider } from "../../wallet-providers/svmWalletProvider";
+import { z } from "zod";
+import { TransferTokenSchema } from "./schemas";
+/**
+ * SplActionProvider serves as a provider for SPL token actions.
+ * It provides SPL token transfer functionality.
+ */
+export declare class SplActionProvider extends ActionProvider<SvmWalletProvider> {
+    /**
+     * Creates a new SplActionProvider instance.
+     */
+    constructor();
+    /**
+     * Transfer SPL tokens to another address.
+     *
+     * @param walletProvider - The wallet provider to use for the transfer
+     * @param args - Transfer parameters including recipient address, mint address, and amount
+     * @returns A message indicating success or failure with transaction details
+     */
+    transfer(walletProvider: SvmWalletProvider, args: z.infer<typeof TransferTokenSchema>): Promise<string>;
+    /**
+     * Checks if the action provider supports the given network.
+     * Only supports Solana networks.
+     *
+     * @param network - The network to check support for
+     * @returns True if the network is a Solana network
+     */
+    supportsNetwork(network: Network): boolean;
+}
+/**
+ * Factory function to create a new SplActionProvider instance.
+ *
+ * @returns A new SplActionProvider instance
+ */
+export declare const splActionProvider: () => SplActionProvider;