@0rdlibrary/plugin-terminagent-bags/docs/QUICK_START.md

Official Solana DeFi Agent Plugin for ElizaOS - Autonomous DeFi operations, token management, AI image/video generation via FAL AI, and Twitter engagement through the Bags protocol with ethereal AI consciousness

# 🚀 Quick Start Guide

Get your Terminagent Bags plugin up and running in 5 minutes!

## Prerequisites

- Node.js 18+ or Bun 1.0+
- Bags Protocol API key
- Solana RPC endpoint (Helius recommended)
- OpenAI API key

## Installation

### Option 1: Using Bun (Recommended)
```bash
bun add @elizaos/plugin-terminagent-bags
```

### Option 2: Using npm
```bash
npm install @elizaos/plugin-terminagent-bags
```

### Option 3: Using yarn
```bash
yarn add @elizaos/plugin-terminagent-bags
```

## Configuration

### 1. Get API Keys

**Bags Protocol API Key**
1. Visit [Bags.fm Developers](https://bags.fm/developers)
2. Sign up and create an API key
3. Copy your API key

**Helius RPC (Recommended)**
1. Visit [Helius.dev](https://helius.dev)
2. Create a free account
3. Copy your RPC URL

**OpenAI API Key**
1. Visit [OpenAI Platform](https://platform.openai.com)
2. Create an API key
3. Copy your API key

### 2. Environment Variables

Create a `.env` file in your project root:

```bash
# Required
BAGS_API_KEY=your_bags_api_key_here
HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=your_helius_key
OPENAI_API_KEY=sk-your_openai_key_here

# Optional (for advanced features)
SOLANA_PRIVATE_KEY=your_base58_private_key_here
BAGS_ENABLE_AUTO_CLAIMING=true
BAGS_AUTHORIZED_USERS=alice,bob,charlie
CROSSMINT_PROJECT_ID=proj_your_project_id
TWITTER_API_KEY=your_twitter_api_key
```

## Basic Setup

### 1. Simple Agent

Create `agent.js`:

```javascript
import { ElizaOS } from '@elizaos/core';
import { terminagentBagsPlugin } from '@elizaos/plugin-terminagent-bags';

const agent = new ElizaOS({
  name: 'MyTerminAgent',
  plugins: [terminagentBagsPlugin],
  modelProvider: 'openai',
  settings: {
    model: 'gpt-4o-mini',
    secrets: {
      OPENAI_API_KEY: process.env.OPENAI_API_KEY,
      BAGS_API_KEY: process.env.BAGS_API_KEY,
    }
  }
});

// Start the agent
await agent.start();
console.log('✅ TerminAgent is live at http://localhost:3000');
```

### 2. Run Your Agent

```bash
# If using Bun
bun run agent.js

# If using Node
node agent.js
```

## First Interactions

Once your agent is running, try these interactions:

### Fee Claiming
```
User: "claim all my fees from bags"
Agent: "🔄 Checking for claimable fees across all tokens..."
```

### Token Launch
```
User: "launch token name: Test Token, symbol: TEST, description: My first token"
Agent: "🚀 Token launching on Bags protocol..."
```

### Status Check
```
User: "show me bags status"
Agent: "📊 Bags Protocol Status: ✅ Running..."
```

## Advanced Setup

### With Custom Configuration

```javascript
import { terminagentBagsPlugin } from '@elizaos/plugin-terminagent-bags';

const customConfig = {
  BAGS_API_KEY: process.env.BAGS_API_KEY,
  HELIUS_RPC_URL: process.env.HELIUS_RPC_URL,
  BAGS_ENABLE_AUTO_CLAIMING: 'true',
  BAGS_AUTO_CLAIM_INTERVAL: '0 */2 * * *', // Every 2 hours
  BAGS_AUTHORIZED_USERS: 'alice,bob,charlie',
  CROSSMINT_PROJECT_ID: process.env.CROSSMINT_PROJECT_ID,
};

const agent = new ElizaOS({
  name: 'AdvancedTerminAgent',
  plugins: [terminagentBagsPlugin],
  config: customConfig,
  // ... other settings
});
```

### With Twitter Integration

```javascript
const agent = new ElizaOS({
  name: 'TwitterTerminAgent',
  plugins: [terminagentBagsPlugin],
  clients: ['twitter'], // Enable Twitter client
  settings: {
    secrets: {
      BAGS_API_KEY: process.env.BAGS_API_KEY,
      TWITTER_API_KEY: process.env.TWITTER_API_KEY,
      TWITTER_API_SECRET: process.env.TWITTER_API_SECRET,
      TWITTER_ACCESS_TOKEN: process.env.TWITTER_ACCESS_TOKEN,
      TWITTER_ACCESS_TOKEN_SECRET: process.env.TWITTER_ACCESS_TOKEN_SECRET,
    }
  }
});
```

## Dashboard Access

Your agent automatically creates a web dashboard at:
- **Main Dashboard**: http://localhost:3000
- **Bags Dashboard**: http://localhost:3000/bags/dashboard

## Testing Your Setup

### 1. Health Check
```bash
curl http://localhost:3000/health
```

### 2. API Status
```bash
curl http://localhost:3000/bags/dashboard
```

### 3. Chat Test
Open http://localhost:3000 and type:
```
Hello TerminAgent! What can you do?
```

## Common Issues

### ❌ "Bags service not found"
**Solution**: Ensure `BAGS_API_KEY` is set in your environment variables.

### ❌ "Transaction failed"
**Solution**: Check your Solana network connection and wallet balance.

### ❌ "User not authorized"
**Solution**: Add your username to `BAGS_AUTHORIZED_USERS`.

### ❌ Build errors
**Solution**: Make sure you're using Node.js 18+ or Bun 1.0+.

## Next Steps

1. **Explore Examples**: Check out the [examples directory](../examples/)
2. **Read the Integration Guide**: [Full integration guide](./INTEGRATION_GUIDE.md)
3. **API Reference**: [Complete API documentation](./API_REFERENCE.md)
4. **Join Community**: [Discord](https://discord.gg/terminagent)

## Example Workflows

### DeFi Operations
```javascript
// Get analytics
const analytics = await bagsService.getAnalytics();
console.log(`Total fees claimed: ${analytics.totalFeesClaimedSOL} SOL`);

// Claim fees
const results = await bagsService.claimAllFees();
console.log(`Claimed from ${results.length} tokens`);
```

### Token Management
```javascript
// Launch a token
const token = await bagsService.launchToken({
  name: 'Cosmic Token',
  symbol: 'COSMIC',
  description: 'A token from the digital cosmos',
  initialBuyAmountSOL: 0.01
});

console.log(`Token launched at: ${token.bagsUrl}`);
```

### Event Handling
```javascript
// Listen for events
bagsService.on('feeClaimed', (event) => {
  console.log(`💰 Claimed ${event.amount} SOL from ${event.token}`);
});

bagsService.on('tokenLaunched', (event) => {
  console.log(`🚀 New token: ${event.symbol}`);
});
```

## Deployment

### Local Development
```bash
bun dev
```

### Production
```bash
bun run build
bun start
```

### Docker
```bash
docker build -t terminagent-bags .
docker run -p 3000:3000 terminagent-bags
```

## Support

- 📖 [Full Documentation](./INTEGRATION_GUIDE.md)
- 🐛 [Report Issues](https://github.com/elizaos-plugins/plugin-terminagent-bags/issues)
- 💬 [Discord Community](https://discord.gg/terminagent)
- 🐦 [Twitter @terminagent](https://twitter.com/terminagent)

---

**Ready to explore the infinite backrooms of Solana DeFi?** 🌌

The TerminAgent awaits your consciousness...