← back to docs

Getting Started with SAM Terminal

Introduction

SAM Terminal is a modular, plugin-based autonomous trading agent framework designed for EVM ecosystems. Built with TypeScript and powered by a Turborepo monorepo architecture, it combines the flexibility of microservices with the robustness of enterprise-grade infrastructure.

Who is SAM Terminal for?

SAM Terminal provides a plugin ecosystem that handles the complex parts (chain interactions, data providers, swap execution) so you can focus on your agent's business logic.

Prerequisites

Before installing SAM Terminal, ensure you have the following installed:

Required:

Optional but recommended:

Verify your installation:

node --version  # Should be v18.0.0 or higher
pnpm --version  # Should be 9.0.0 or higher
docker --version
git --version

Installation

1. Clone the Repository

git clone https://github.com/0xtinylabs/samterminal.git
cd samterminal

2. Install Dependencies

pnpm install

This installs all packages across the monorepo using pnpm workspaces.

3. Configure Environment Variables

Copy the example environment file:

cp .env.example .env

Edit .env and add your API keys (we'll cover this in detail later):

# Required for most plugins
ALCHEMY_API_KEY=your_alchemy_key
MORALIS_API_KEY=your_moralis_key

# Optional: For AI features
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key

# Optional: For Telegram notifications
MAIN_BOT_TOKEN=your_telegram_bot_token

# Optional: For swap functionality
MATCHA_API_KEY=your_0x_api_key

# Database (defaults work for local development)
DATABASE_URL=postgresql://user:password@localhost:5432/samterminal
REDIS_URL=redis://localhost:6379

4. Setup Development Environment

SAM Terminal provides a convenient command to setup everything:

pnpm sam setup

This command will:

Alternatively, you can run these steps manually:

pnpm install
pnpm build
docker compose up -d
pnpm db:migrate

Quick Start with CLI

SAM Terminal includes a powerful CLI that streamlines agent creation and management.

Creating Your First Agent

Clone the repository and configure your agent:

git clone https://github.com/0xtinylabs/samterminal.git my-trading-agent
cd my-trading-agent
cp .env.example .env
pnpm install && pnpm build

Then edit samterminal.config.json to select your plugins and chains. Available plugin profiles:

Supported chains:

Project Structure

After cloning, your project structure looks like this:

samterminal/
├── samterminal.config.json  # Main configuration file
├── .env                     # Environment variables
├── .env.example            # Template for required env vars
├── package.json            # Project dependencies
├── tsconfig.json           # TypeScript configuration
├── src/
│   ├── index.ts            # Main entry point
│   ├── agents/             # Your agent implementations
│   │   └── basic.ts        # Example agent
│   └── examples/           # Usage examples
│       ├── ai-chat.ts
│       ├── token-tracker.ts
│       └── onboarding.ts
└── node_modules/

Key files explained:

Configuration

The samterminal.config.json file is the heart of your agent configuration:

{
  "name": "my-trading-agent",
  "version": "1.0.0",
  "plugins": [
    "@samterminal/plugin-tokendata",
    "@samterminal/plugin-walletdata",
    "@samterminal/plugin-swap",
    "@samterminal/plugin-ai"
  ],
  "chains": {
    "default": "base",
    "enabled": ["base", "ethereum", "arbitrum"],
    "rpc": {
      "base": "https://base-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}",
      "ethereum": "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}",
      "arbitrum": "https://arb-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}"
    }
  },
  "agent": {
    "maxConcurrentTasks": 5,
    "retryAttempts": 3,
    "timeout": 30000
  }
}

Configuration sections:

Starting Services

SAM Terminal requires several backend services. Start them using Docker Compose:

docker compose up -d

This starts:

Databases:

Go Microservices:

NestJS Services:

docker compose ps

All services should show status "Up".

Useful Docker commands:

# View logs for all services
docker compose logs -f

# View logs for a specific service
docker compose logs -f tokendata

# Restart a service
docker compose restart swap

# Stop all services
docker compose down

# Stop and remove all data (careful!)
docker compose down -v

Running Your Agent

Development Mode (Recommended)

pnpm sam dev

This runs your agent with:

Production Mode

pnpm sam run

Advanced run options:

# Use a custom config file
pnpm sam run --config ./config/production.json

# Use a different environment file
pnpm sam run --env .env.production

# Enable watch mode manually
pnpm sam run --watch

# Run on a specific port
pnpm sam run --port 3001

Monitoring your agent:

Your agent will log to console. Look for:

Example output:

[SAM Terminal] Starting agent: my-trading-agent
[Plugins] Loading @samterminal/plugin-tokendata
[Plugins] Loading @samterminal/plugin-swap
[Chains] Connected to Base (chainId: 8453)
[Agent] Ready - listening for tasks

Installing Plugins

SAM Terminal's plugin system provides modular functionality.

Available Plugins

@samterminal/plugin-tokendata

@samterminal/plugin-walletdata

@samterminal/plugin-swap

@samterminal/plugin-ai

@samterminal/plugin-telegram

@samterminal/plugin-onboarding

Installing Plugins via CLI

# Install a single plugin
pnpm sam plugin install tokendata

# Install multiple plugins at once
pnpm sam plugin install tokendata walletdata swap

# List installed plugins
pnpm sam plugin list

# Remove a plugin
pnpm sam plugin remove ai

# Enable a disabled plugin
pnpm sam plugin enable telegram

# Disable a plugin without removing it
pnpm sam plugin disable telegram

Installing Plugins via Config

Edit samterminal.config.json:

{
  "plugins": [
    "@samterminal/plugin-tokendata",
    "@samterminal/plugin-walletdata",
    "@samterminal/plugin-swap"
  ]
}

Then reinstall dependencies:

pnpm install

API Keys Setup

Alchemy (Required for most plugins)

Alchemy provides RPC endpoints for blockchain interaction.

  1. Sign up at alchemy.com
  2. Create a new app
  3. Select your chains (Base, Ethereum, Arbitrum, etc.)
  4. Copy your API key
  5. Add to .env: ALCHEMY_API_KEY=your_key_here

Used by: tokendata, walletdata, swap

Moralis (Required for tokendata and walletdata)

Moralis provides enriched blockchain data APIs.

  1. Sign up at moralis.io
  2. Go to Account Settings > Keys
  3. Copy your Web3 API key
  4. Add to .env: MORALIS_API_KEY=your_key_here

Used by: tokendata, walletdata

0x API Key (Optional, for swap)

The 0x Protocol powers DEX aggregation.

  1. Sign up at 0x.org/docs
  2. Generate an API key
  3. Add to .env: ZEROX_API_KEY=your_key_here

Benefits: Higher rate limits, better pricing Used by: swap plugin

OpenAI (Optional, for AI features)

  1. Sign up at platform.openai.com
  2. Go to API Keys section
  3. Create a new secret key
  4. Add to .env: OPENAI_API_KEY=your_key_here

Used by: ai plugin

Anthropic (Alternative to OpenAI)

  1. Sign up at console.anthropic.com
  2. Generate an API key
  3. Add to .env: ANTHROPIC_API_KEY=your_key_here

Used by: ai plugin (alternative to OpenAI)

Telegram Bot Token (Optional, for notifications)

  1. Open Telegram and search for @BotFather
  2. Send /newbot and follow the instructions
  3. Copy the bot token
  4. Add to .env: MAIN_BOT_TOKEN=your_token_here

Used by: telegram plugin

Verifying Setup

SAM Terminal includes a diagnostic tool to verify your setup:

pnpm sam doctor

This command checks:

  1. Prerequisites:

    • Node.js version
    • pnpm installation
    • Docker availability

  2. Services:

    • PostgreSQL connection
    • Redis connection
    • Microservice health

  3. API Keys:

    • Validates each configured API key
    • Tests connectivity to external APIs
    • Reports which plugins are ready

  4. Configuration:

    • Validates samterminal.config.json syntax
    • Checks for missing required fields
    • Warns about deprecated options

Example output:

SAM Terminal Doctor

Prerequisites:
✓ Node.js v20.10.0
✓ pnpm 8.15.0
✓ Docker 24.0.6

Services:
✓ PostgreSQL (localhost:5432)
✓ Redis (localhost:6379)
✓ Tokendata service (healthy)
✓ Swap service (healthy)

API Keys:
✓ ALCHEMY_API_KEY (valid)
✓ MORALIS_API_KEY (valid)
⚠ ZEROX_API_KEY (not configured - optional)
✓ OPENAI_API_KEY (valid)
✗ MAIN_BOT_TOKEN (invalid or expired)

Configuration:
✓ samterminal.config.json (valid)
✓ 4 plugins configured
✓ 3 chains enabled

Status: Ready with warnings

Additional CLI Commands

Order Management

SAM Terminal supports creating and managing automated trading orders:

# Create a new order from a template
pnpm sam order create --template dca

# List all active orders
pnpm sam order list

# Get details for a specific order
pnpm sam order get <order-id>

# Cancel an order
pnpm sam order cancel <order-id>

# Pause an order temporarily
pnpm sam order pause <order-id>

# Resume a paused order
pnpm sam order resume <order-id>

Environment Information

# Display current environment configuration
pnpm sam info

This shows:

Next Steps

Congratulations! You now have SAM Terminal up and running.

Continue your journey:

Community:

Need help?

Happy building with SAM Terminal!