npm package: @hypeagent0/hypeagent
Description: AI-driven blockchain agent for HyperEVM - both CLI tool and SDK
Author: HypeAgent0
Latest version: 1.4.4

# HypeAgent

An AI-driven tool for blockchain interactions on HyperEVM. HypeAgent helps you interact with blockchain networks using natural language commands, powered by AI. Available both as a CLI tool and a JavaScript/TypeScript SDK.

🌐 **Website**: [hypeagent.app](https://hypeagent.app)

## Features

- 🤖 Natural Language Interaction - Talk to your blockchain in plain English
- 🔄 Smart Contract Interactions - Seamlessly interact with smart contracts
- 💼 Wallet Management - Create, import, and manage wallets easily
- 💰 Token Operations - Check balances, transfer tokens, and more
- 🌊 Liquidity Pool Management - Find and interact with liquidity pools
- 🔌 Flexible Integration - Use as CLI tool or integrate via TypeScript/JavaScript SDK
- 🛡️ Security First - Private keys never leave your machine
- 🎯 Custom AI Integration - Use your own AI provider or API endpoint

## Installation

```bash
npm install -g @hypeagent0/hypeagent  # For CLI usage
npm install @hypeagent0/hypeagent     # For SDK usage
```

## Configuration

HypeAgent can be configured using environment variables or programmatically. For CLI usage, create a `.env` file in your working directory or set the following environment variables:

```env
# AI Provider Configuration (Required)
AI_PROVIDER=openai  # or 'gemini'
AI_API_KEY=your_api_key_here
AI_MODEL=gpt-4  # or 'gpt-3.5-turbo' for OpenAI

# Blockchain Configuration (Optional)
ETH_PRIVATE_KEY=your_ethereum_private_key  # Optional: can also be managed during session
```

## Quick Start

### CLI Quick Start
```bash
# Start the interactive agent
hypeagent start

# Create a new wallet
> create wallet

# Check your balance
> what's my balance

# Find pools for a token
> find pools for USDC
```

### SDK Quick Start

#### Using Built-in AI Providers
```typescript
import { HypeAgent } from '@hypeagent0/hypeagent';

// Initialize with OpenAI
const agent = new HypeAgent({
  ai: {
    type: 'openai',
    apiKey: process.env.OPENAI_API_KEY,
    model: 'gpt-4'  // optional
  }
});

// Or initialize with Gemini
const agent = new HypeAgent({
  ai: {
    type: 'gemini',
    apiKey: process.env.GEMINI_API_KEY
  }
});

// Create a wallet and check balance
const wallet = await agent.createWallet();
const balance = await agent.getBalance();
```

#### Using Custom AI Provider
```typescript
import { HypeAgent } from '@hypeagent0/hypeagent';

// Example with Next.js API route
const agent = new HypeAgent({
  ai: {
    type: 'custom',
    provider: {
      async query(prompt: string) {
        const response = await fetch('/api/ai', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ prompt })
        });
        const data = await response.json();
        return data.response;
      }
    }
  }
});

// Use natural language commands
const result = await agent.executeCommand('find pools for USDC');
```

Example Next.js API Route (`pages/api/ai.ts`):
```typescript
import { OpenAI } from 'openai';
import { NextResponse } from 'next/server';

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

export async function POST(req: Request) {
  try {
    const { prompt } = await req.json();
    const response = await openai.chat.completions.create({
      model: 'gpt-4',
      messages: [{ role: 'user', content: prompt }]
    });
    
    return NextResponse.json({ 
      response: response.choices[0].message.content 
    });
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to process request' }, 
      { status: 500 }
    );
  }
}
```

## CLI Usage

Start an interactive session:

```bash
hypeagent start
```

### Command Line Options

All configuration can be provided via command-line arguments:

```bash
hypeagent start \
  --ai-provider openai \
  --ai-key your_api_key_here \
  --ai-model gpt-4 \
  --eth-key your_ethereum_private_key  # Optional: can also be managed during session
```

| Option | Description | Default |
|--------|-------------|---------|
| `--ai-provider` | AI provider to use (`openai` or `gemini`) | `openai` |
| `--ai-key` | AI provider API key | From environment |
| `--ai-model` | AI model to use | `gpt-4` |
| `--eth-key` | Ethereum private key for transactions | From environment |

## SDK Usage

The SDK provides a programmatic way to interact with HypeAgent. Here's how to use it:

```typescript
import { HypeAgent } from '@hypeagent0/hypeagent';

// Initialize with built-in provider
const agent = new HypeAgent({
  ai: {
    type: 'openai',
    apiKey: 'your_api_key_here',
    model: 'gpt-4'  // optional
  },
  ethPrivateKey: '0x...'  // optional
});

// Create a new wallet
const wallet = agent.createWallet();
console.log('New wallet:', wallet.address);

// Check balance using session wallet
const balance = await agent.getBalance();

// Check balance of a different wallet without changing session
const otherBalance = await agent.getBalance('0x123...');

// Transfer tokens using session wallet
await agent.transferHype('0xdest...', '1.0');

// Transfer tokens from a different wallet
await agent.transferHype('0xdest...', '1.0', '0x123...');

// Wrap HYPE using session wallet
await agent.wrapHype('1.0');

// Wrap HYPE using a different wallet
await agent.wrapHype('1.0', '0x123...');

// Get token balances with limit
const balances = await agent.getTokenBalances(10);

// Get token balances for a different wallet
const otherBalances = await agent.getTokenBalances(10, '0x123...');
```

### Using External Private Keys

All SDK methods that require wallet authentication now support an optional private key parameter. This allows you to:

1. Use a session wallet for repeated operations
2. Perform one-off operations with different wallets
3. Switch between wallets without changing the session

Methods that support external private keys:
- `getBalance(privateKey?: string)`
- `getTokenBalances(limit?: number, privateKey?: string)`
- `transferHype(toAddress: string, amount: string, privateKey?: string)`
- `wrapHype(amount: string, privateKey?: string)`
- `unwrapHype(amount: string, privateKey?: string)`

### Available SDK Methods

| Method | Description |
|--------|-------------|
| `createWallet()` | Creates a new wallet |
| `importWallet(privateKey)` | Imports an existing wallet |
| `getCurrentWallet()` | Gets current wallet info |
| `getBalance()` | Gets native HYPE balance |
| `getTokenBalances(limit?)` | Gets token balances |
| `transferHype(to, amount)` | Transfers HYPE tokens |
| `findPools(tokenA, tokenB?)` | Finds liquidity pools |
| `wrapHype(amount)` | Wraps HYPE to WHYPE |
| `unwrapHype(amount)` | Unwraps WHYPE to HYPE |
| `executeCommand(command)` | Executes natural language commands |

## Security Notes

- Private keys are only stored in memory during your session
- Keys are automatically cleared when you exit the CLI
- Never share your private keys or store them in plain text
- Back up any generated wallet private keys in a secure location
- When using custom AI providers, ensure your API endpoints are secure

## Support

For issues and feature requests, please visit our GitHub repository.

## License

MIT License - see LICENSE file for details.