starknet-agent-kit (alpha)

A toolkit for creating AI agents that can interact with the Starknet blockchain, available both as an NPM package and a ready-to-use NestJS server with a web interface.

⚠️ Warning: This kit is currently under development. Use it at your own risk! Please be aware that sharing sensitive information such as private keys, personal data, or confidential details with AI models or tools carries inherent security risks. The contributors of this repository are not responsible for any loss, damage, or issues arising from its use.

Features

• Retrieve account information (Balance, public key, etc.)
• Create one or multiple accounts (Argent & OpenZeppelin)
• Transfer assets between accounts
• DeFi operations (Swap on Avnu)
• dApp interactions (Create a .stark domain)
• All RPC read methods supported (getBlockNumber, getStorageAt, etc.)
• Web interface for easy interaction
• Full API server implementation

Installation

As an NPM Package

npm install starknet-agent-kit

Required peer dependencies:

npm install @nestjs/common @nestjs/core @nestjs/platform-fastify starknet @langchain/anthropic

Running the Full Stack (Server + Web Interface)

1. Clone the repository:

git clone https://github.com/kasarlabs/starknet-agent-kit.git
cd starknet-agent-kit

2. Install dependencies:

pnpm install

3. Run the setup script:

pnpm run setup

This will install all dependencies and build both the backend and frontend.

Prerequisites

You will need:

• A Starknet wallet private key (you can get one from Argent X)
• An AI provider API key (supported providers: Anthropic, OpenAI, Google (Gemini), Ollama)

Usage

As an NPM Package

import { StarknetAgent } from 'starknet-agent-kit';

const agent = new StarknetAgent({
  aiProviderApiKey: 'your-ai-provider-key',
  aiProvider: 'anthropic', // or 'openai', 'gemini', 'ollama'
  aiModel: 'claude-3-5-sonnet-latest',
  walletPrivateKey: 'your-wallet-private-key',
  rpcUrl: 'your-rpc-url',
});

// Execute commands in natural language
await agent.execute('transfer 0.1 ETH to 0x123...');
await agent.execute('What is my ETH balance?');
await agent.execute('Swap 5 USDC for ETH');

Using Individual Tools

All Langchain tools are available for direct import:

import { getBalance, transfer, swapTokens } from 'starknet-agent-kit';

// Use tools individually
const balance = await getBalance(address);

Running the Full Stack

Configuration

Create a .env file:

# Required for both package and server
PRIVATE_KEY=""
PUBLIC_ADDRESS=""
AI_PROVIDER_API_KEY=""
AI_MODEL=""  # e.g., "claude-3-5-sonnet-latest"
AI_PROVIDER=""  # "anthropic", "openai", "gemini", or "ollama"
RPC_URL=""

# Required only for server
API_KEY=""  # Security key for API endpoints
PORT=3001  # Optional, defaults to 3000

Development Mode

# Install dependencies first (if not done already)
pnpm install

# Start both frontend and backend
pnpm run dev

# Start only frontend
pnpm run dev --frontend-only

# Start only backend
pnpm run dev --backend-only

Production Mode

# Install dependencies first (if not done already)
pnpm install

# Start both frontend and backend
pnpm run start

# Start only frontend
pnpm run start --frontend-only

# Start only backend
pnpm run start --backend-only

Server API Endpoints

Make Agent Requests

curl --location 'localhost:3001/api/agent/request' \
--header 'x-api-key: your-api-key' \
--header 'Content-Type: application/json' \
--data '{
    "request": "What's my ETH balance?"
}'

Testing

# Run unit tests
pnpm test

# Run frontend tests
pnpm test:frontend

# Run end-to-end tests
pnpm test:e2e

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.