coinbase-agentkit 0.2.1.dev202503220

Coinbase AgentKit

AgentKit

AgentKit is a framework for easily enabling AI agents to take actions onchain. It is designed to be framework-agnostic, so you can use it with any AI framework, and wallet-agnostic, so you can use it with any wallet.

Table of Contents

• Getting Started
• Installation
• Usage
  • Create an AgentKit instance
  • Create an AgentKit instance with a specified wallet provider
  • Create an AgentKit instance with specified action providers
  • Use with a framework extension (e.g., LangChain + OpenAI)
• Creating an Action Provider
  • Adding Actions to your Action Provider
  • Adding Actions that use a Wallet Provider
  • Adding an Action Provider to your AgentKit instance
• Action Providers
• Wallet Providers
  • CdpWalletProvider
    • Network Configuration
    • Configuring from an existing CDP API Wallet
    • Configuring from a mnemonic phrase
    • Exporting a wallet
    • Importing a wallet from WalletData JSON string
    • Configuring gas parameters
  • EthAccountWalletProvider
    • Configuring gas parameters
  • SmartWalletProvider
• Contributing

Getting Started

Prerequisites:

• Python 3.10+
• CDP Secret API Key

Installation

pip install coinbase-agentkit

Usage

Create an AgentKit instance

If no wallet or action providers are specified, the agent will use the CdpWalletProvider and WalletActionProvider action provider by default.

from coinbase_agentkit import AgentKit, AgentKitConfig

agent_kit = AgentKit()

Create an AgentKit instance with a specified wallet provider

from coinbase_agentkit import (
    AgentKit,
    AgentKitConfig,
    CdpWalletProvider,
    CdpWalletProviderConfig
)

wallet_provider = CdpWalletProvider(CdpWalletProviderConfig(
    api_key_name="CDP API KEY NAME",
    api_key_private="CDP API KEY PRIVATE KEY",
    network_id="base-mainnet"
))

agent_kit = AgentKit(AgentKitConfig(
    wallet_provider=wallet_provider
))

Create an AgentKit instance with specified action providers

from coinbase_agentkit import (
    AgentKit,
    AgentKitConfig,
    cdp_api_action_provider,
    pyth_action_provider
)

agent_kit = AgentKit(AgentKitConfig(
    wallet_provider=wallet_provider,
    action_providers=[
        cdp_api_action_provider(
            api_key_name="CDP API KEY NAME",
            api_key_private="CDP API KEY PRIVATE KEY"
        ),
        pyth_action_provider()
    ]
))

Use with a framework extension

Example using LangChain + OpenAI:

Prerequisites:

• OpenAI API Key
• Set OPENAI_API_KEY environment variable

poetry add coinbase-agentkit-langchain langchain-openai langgraph

from coinbase_agentkit_langchain import get_langchain_tools
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

tools = get_langchain_tools(agent_kit)

llm = ChatOpenAI(model="gpt-4")

agent = create_react_agent(
    llm=llm,
    tools=tools
)

Creating an Action Provider

Action providers define the actions that an agent can take. They are created by subclassing the ActionProvider abstract class.

from coinbase_agentkit import ActionProvider, WalletProvider
from coinbase_agentkit.network import Network

class MyActionProvider(ActionProvider[WalletProvider]):
    def __init__(self):
        super().__init__("my-action-provider", [])

    # Define if the action provider supports the given network
    def supports_network(self, network: Network) -> bool:
        return True

Adding Actions to your Action Provider

Actions are defined using the @create_action decorator. They can optionally use a wallet provider and must return a string.

1. Define the action schema using Pydantic:

from pydantic import BaseModel

class MyActionSchema(BaseModel):
    my_field: str

2. Define the action:

from coinbase_agentkit import ActionProvider, WalletProvider, create_action
from coinbase_agentkit.network import Network

class MyActionProvider(ActionProvider[WalletProvider]):
    def __init__(self):
        super().__init__("my-action-provider", [])

    @create_action(
        name="my-action",
        description="My action description",
        schema=MyActionSchema
    )
    def my_action(self, args: dict[str, Any]) -> str:
        return args["my_field"]

    def supports_network(self, network: Network) -> bool:
        return True

def my_action_provider():
    return MyActionProvider()

Adding Actions that use a Wallet Provider

Actions that need access to a wallet provider can include it as their first parameter:

from coinbase_agentkit import ActionProvider, WalletProvider, create_action

class MyActionProvider(ActionProvider[WalletProvider]):
    @create_action(
        name="my-action",
        description="My action description",
        schema=MyActionSchema
    )
    def my_action(self, wallet_provider: WalletProvider, args: dict[str, Any]) -> str:
        return wallet_provider.sign_message(args["my_field"])

Adding an Action Provider to your AgentKit instance

agent_kit = AgentKit(AgentKitConfig(
    cdp_api_key_name="CDP API KEY NAME",
    cdp_api_key_private="CDP API KEY PRIVATE KEY",
    action_providers=[my_action_provider()]
))

Action Providers

This section provides a detailed list of all available action providers and their actions.

Basename

register_basename

Registers a custom .base.eth or .basetest.eth domain name for the wallet address.

CDP Wallet

deploy_contract	Deploys a custom smart contract using specified Solidity version and constructor arguments.
deploy_nft	Deploys a standard ERC-721 NFT contract with configurable name, symbol, and metadata URI.
deploy_token	Deploys a standard ERC-20 token contract with configurable name, symbol, and initial supply.
trade	Executes a token swap between two assets at current market rates on mainnet networks.

CDP API

fetch_price	Retrieves the current price of a cryptocurrency from the CDP API.
fetch_base_scan	Fetches on-chain data from Base blockchain explorer via CDP API.

Compound

supply	Supplies collateral assets (WETH, CBETH, CBBTC, WSTETH, or USDC) to Compound.
withdraw	Withdraws previously supplied collateral assets from Compound.
borrow	Borrows base assets (WETH or USDC) from Compound using supplied collateral.
repay	Repays borrowed assets back to Compound.
get_portfolio	Retrieves portfolio details including collateral balances and borrowed amounts.

ERC20

get_balance	Retrieves the token balance for a specified address and ERC-20 contract.
transfer	Transfers a specified amount of ERC-20 tokens to a destination address.

ERC721

get_balance	Retrieves the NFT balance for a specified address and ERC-721 contract.
transfer	Transfers ownership of a specific NFT token to a destination address.
mint	Creates a new NFT token and assigns it to a specified destination address.

Hyperbolic

generate_text	Generate text using AI models.
generate_image	Generate images using AI models.
generate_audio	Generate text-to-speech audio.
get_available_gpus	Get available GPU resources.
get_available_gpus_by_type	Get GPUs filtered by model type.
get_available_gpus_types	Get list of available GPU types.
get_gpu_status	Check status of GPU resources.
rent_compute	Rent GPU compute resources.
terminate_compute	Terminate a rented GPU compute instance.
get_current_balance	Get current account balance.
get_purchase_history	Get purchase history.
get_spend_history	Get spending history.
link_wallet_address	Link a wallet address to your account.

Morpho

deposit	Deposits a specified amount of assets into a designated Morpho Vault.
withdraw	Withdraws a specified amount of assets from a designated Morpho Vault.

Pyth

fetch_price	Retrieves current price data from a specified Pyth price feed.
fetch_price_feed_id	Retrieves the unique price feed identifier for a given token symbol.

SSH

ssh_connect	Establishes an SSH connection to a remote server.
remote_shell	Executes shell commands on a remote server via SSH.
ssh_status	Checks status of SSH connections.
ssh_list_connections	Lists active SSH connections.
ssh_disconnect	Disconnects from an SSH server.
ssh_add_host_key	Adds an SSH host key to known_hosts.
sftp_upload	Uploads files to a remote server via SFTP.
sftp_download	Downloads files from a remote server via SFTP.

Superfluid

create_flow	Creates a new token streaming flow to a recipient address.
delete_flow	Deletes an existing token streaming flow.
get_flow	Gets details of an existing token streaming flow.

Twitter

account_details	Fetches profile information and metadata for the authenticated Twitter account.
account_mentions	Retrieves recent mentions and interactions for the authenticated account.
post_tweet	Creates a new tweet on the authenticated Twitter account.
post_tweet_reply	Creates a reply to an existing tweet using the tweet's unique identifier.

Wallet

get_wallet_details	Retrieves wallet address, network info, balances, and provider details.
get_balance	Gets the native currency balance of the connected wallet.
native_transfer	Transfers native blockchain tokens (e.g., ETH) to a destination address.

WETH

wrap_eth

Converts native ETH to Wrapped ETH (WETH) on supported networks.

WOW

buy_token	Purchases WOW tokens from a contract using ETH based on bonding curve pricing.
create_token	Creates a new WOW memecoin with bonding curve functionality via Zora factory.
sell_token	Sells WOW tokens back to the contract for ETH based on bonding curve pricing.

Wallet Providers

AgentKit supports the following wallet providers:

EVM:

• CdpWalletProvider - Uses the Coinbase Developer Platform (CDP) API Wallet
• EthAccountWalletProvider - Uses a local private key for any EVM-compatible chain

CdpWalletProvider

The CdpWalletProvider is a wallet provider that uses the Coinbase Developer Platform (CDP) API Wallet.

Network Configuration

The CdpWalletProvider can be configured to use a specific network by passing the network_id parameter to the CdpWalletProviderConfig. The network_id is the ID of the network you want to use. You can find a list of supported networks on the CDP API docs.

from coinbase_agentkit import CdpWalletProvider, CdpWalletProviderConfig

wallet_provider = CdpWalletProvider(CdpWalletProviderConfig(
    api_key_name="CDP API KEY NAME",
    api_key_private="CDP API KEY PRIVATE KEY",
    network_id="base-mainnet",
))

Configuring from an existing CDP API Wallet

If you already have a CDP API Wallet, you can configure the CdpWalletProvider by passing the wallet parameter to the configureWithWallet method.

from coinbase_agentkit import CdpWalletProvider, CdpWalletProviderConfig
from cdp import Wallet

wallet_provider = CdpWalletProvider(CdpWalletProviderConfig(
    wallet=wallet,
    api_key_name="CDP API KEY NAME",
    api_key_private="CDP API KEY PRIVATE KEY",
))

Configuring from a mnemonic phrase

The CdpWalletProvider can be configured from a mnemonic phrase by passing the mnemonic_phrase and network_id parameters to the CdpWalletProviderConfig. If network_id is not defined, the CdpWalletProvider will fall back to the env var NETWORK_ID, and if that is not defined, it will default to base-sepolia.

from coinbase_agentkit import CdpWalletProvider, CdpWalletProviderConfig

wallet_provider = CdpWalletProvider(CdpWalletProviderConfig(
    mnemonic_phrase="MNEMONIC PHRASE",
    network_id="base-sepolia",
))

Exporting a wallet

The CdpWalletProvider can export a wallet by calling the export_wallet method.

from coinbase_agentkit import CdpWalletProvider

wallet_provider = CdpWalletProvider(CdpWalletProviderConfig(
    mnemonic_phrase="MNEMONIC PHRASE",
    network_id="base-sepolia",
))

wallet_data = wallet_provider.export_wallet()

Importing a wallet from WalletData JSON string

The CdpWalletProvider can import a wallet from a WalletData JSON string by passing the cdp_wallet_data parameter to the CdpWalletProviderConfig.

from coinbase_agentkit import CdpWalletProvider, CdpWalletProviderConfig

wallet_provider = CdpWalletProvider(CdpWalletProviderConfig(
    wallet_data="WALLET DATA JSON STRING",
    api_key_name="CDP API KEY NAME",
    api_key_private="CDP API KEY PRIVATE KEY",
))

Configuring CdpWalletProvider gas parameters

The CdpWalletProvider also exposes parameters for effecting the gas calculations.

from coinbase_agentkit import CdpWalletProvider, CdpWalletProviderConfig

wallet_provider = CdpWalletProvider(CdpWalletProviderConfig(
    wallet_data="WALLET DATA JSON STRING",
    api_key_name="CDP API KEY NAME",
    api_key_private="CDP API KEY PRIVATE KEY",
    gas={
        "gas_limit_multiplier": 2.0,   # Adjusts gas limit estimation
        "fee_per_gas_multiplier": 2.0  # Adjusts max fee per gas
    }
))

Note: Gas parameters only impact the wallet_provider.send_transaction behavior. Actions that do not rely on direct transaction calls, such as deploy_token, deploy_contract, and native_transfer, remain unaffected.

EthAccountWalletProvider

Example usage with a private key:

import os
from eth_account import Account

from coinbase_agentkit import (
    AgentKit,
    AgentKitConfig,
    EthAccountWalletProvider,
    EthAccountWalletProviderConfig
)

# See here for creating a private key:
# https://web3py.readthedocs.io/en/stable/web3.eth.account.html#creating-a-private-key
private_key = os.environ.get("PRIVATE_KEY")
assert private_key is not None, "You must set PRIVATE_KEY environment variable"
assert private_key.startswith("0x"), "Private key must start with 0x hex prefix"

account = Account.from_key(private_key)

wallet_provider = EthAccountWalletProvider(
    config=EthAccountWalletProviderConfig(
        account=account,
        chain_id="84532",
    )
)

agent_kit = AgentKit(AgentKitConfig(
    wallet_provider=wallet_provider
))

Configuring EthAccountWalletProvider gas parameters

The EthAccountWalletProvider also exposes parameters for effecting the gas calculations.

import os
from eth_account import Account

from coinbase_agentkit import (
    AgentKit,
    AgentKitConfig,
    EthAccountWalletProvider,
    EthAccountWalletProviderConfig
)

private_key = os.environ.get("PRIVATE_KEY")
assert private_key is not None, "You must set PRIVATE_KEY environment variable"
assert private_key.startswith("0x"), "Private key must start with 0x hex prefix"

account = Account.from_key(private_key)

wallet_provider = EthAccountWalletProvider(
    config=EthAccountWalletProviderConfig(
        account=account,
        chain_id="84532",
        gas={
            "gas_limit_multiplier": 2,
            "fee_per_gas_multiplier": 2
        }
    )
)

agent_kit = AgentKit(AgentKitConfig(
    wallet_provider=wallet_provider
))

Configuring EthAccountWalletProvider rpc url

The EthAccountWalletProvider also exposes parameters for defining the rpc url manually.

import os
from eth_account import Account

from coinbase_agentkit import (
    AgentKit,
    AgentKitConfig,
    EthAccountWalletProvider,
    EthAccountWalletProviderConfig
)

private_key = os.environ.get("PRIVATE_KEY")
assert private_key is not None, "You must set PRIVATE_KEY environment variable"
assert private_key.startswith("0x"), "Private key must start with 0x hex prefix"

account = Account.from_key(private_key)

wallet_provider = EthAccountWalletProvider(
    config=EthAccountWalletProviderConfig(
        account=account,
        rpc_url="https://sepolia.base.org",
    )
)

agent_kit = AgentKit(AgentKitConfig(
    wallet_provider=wallet_provider
))

SmartWalletProvider

The SmartWalletProvider is a wallet provider that uses CDP Smart Wallets.

import os
from eth_account import Account

from coinbase_agentkit import (
    AgentKit, 
    AgentKitConfig, 
    SmartWalletProvider, 
    SmartWalletProviderConfig
)

# See here for creating a private key:
# https://web3py.readthedocs.io/en/stable/web3.eth.account.html#creating-a-private-key
private_key = os.environ.get("PRIVATE_KEY")
assert private_key is not None, "You must set PRIVATE_KEY environment variable"
assert private_key.startswith("0x"), "Private key must start with 0x hex prefix"

signer = Account.from_key(private_key)

network_id = os.getenv("NETWORK_ID", "base-sepolia")

wallet_provider = SmartWalletProvider(SmartWalletProviderConfig(
    network_id=network_id,
    signer=signer,
    smart_wallet_address=None, # If not provided, a new smart wallet will be created
    paymaster_url=None, # Sponsor transactions: https://docs.cdp.coinbase.com/paymaster/docs/welcome
))

agent_kit = AgentKit(AgentKitConfig(
    wallet_provider=wallet_provider
))

Contributing

See CONTRIBUTING.md for more information.