@balchemyai/agent-sdk 0.1.1 → 0.1.2

package/docs/BEHAVIOR_RULES.md

@@ -0,0 +1,184 @@
+# Behavior Rules (BRL) — YAML Reference
+
+Behavior rules define how your agent trades. They are validated by the Balchemy
+backend before any trade is executed. The agent's LLM reads a compressed summary
+of your rules as context for every decision.
+
+---
+
+## Where to set rules
+
+**In `agent.config.yaml`** (inline):
+
+```yaml
+behavior_rules:
+  version: "1"
+  preset: custom
+  risk:
+    max_single_trade_usd: 50
+```
+
+**As a separate file** (referenced by path):
+
+```yaml
+behavior_rules_path: ./my-rules.yaml
+```
+
+---
+
+## Schema
+
+### Top-level fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `version` | string | Yes | Rule schema version. Always `"1"`. |
+| `preset` | string | No | Base preset to inherit (`memecoin-sniper`, `dca-accumulator`, `swing-trader`, `custom`). Inline fields override preset defaults. |
+
+---
+
+### `risk` — global safety limits
+
+```yaml
+risk:
+  max_single_trade_usd: 50       # Hard cap per trade. Default: 50
+  max_daily_loss_usd: 200        # Pause trading after this daily loss. Default: 500
+  max_open_positions: 5          # Max simultaneous positions. Default: 10
+  pause_on_drawdown_pct: 20      # Pause if portfolio drops this % from peak. Default: none
+  allowed_chains: [solana]       # Restrict to specific chains. Default: [solana, base]
+```
+
+---
+
+### `filters` — asset eligibility
+
+```yaml
+filters:
+  min_liquidity_usd: 10000       # Reject tokens below this liquidity. Default: 5000
+  max_market_cap_usd: 10000000   # Reject tokens above this market cap. Default: none
+  require_verified_contract: false  # Only trade verified contracts. Default: false
+  blocked_tokens:                # Token addresses to never trade
+    - "So11111111111111111111111111111111111111112"
+  allowed_tokens:                # Allowlist (if set, only these tokens trade)
+    - "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
+```
+
+---
+
+### `entry` — trade entry conditions
+
+```yaml
+entry:
+  trigger: launch_signal         # launch_signal | price_drop | rsi_signal | manual
+  max_position_usd: 100          # Max USD per position. Default: 50
+  slippage_bps: 200              # Max slippage in basis points. Default: 100
+  min_confidence: 0.7            # Min LLM confidence score to enter. Default: 0.5
+  indicators: [rsi, macd]        # Required indicators for entry. Default: []
+  rsi_oversold: 30               # Enter when RSI below this value. Default: 30
+```
+
+---
+
+### `exit` — trade exit conditions
+
+```yaml
+exit:
+  take_profit_pct: 50            # Close position when up this %. Default: none
+  stop_loss_pct: 25              # Close position when down this %. Default: none
+  trailing_stop_pct: 10          # Trailing stop loss. Default: none
+  max_hold_minutes: 120          # Force exit after this many minutes. Default: none
+  min_hold_hours: 1              # Do not exit before this time. Default: 0
+  max_hold_hours: 72             # Force exit after this time. Default: none
+```
+
+---
+
+### `dca` — dollar-cost averaging (DCA preset)
+
+```yaml
+dca:
+  target_token: SOL              # Token to accumulate
+  amount_usd: 10                 # USD per interval purchase
+  interval_hours: 24             # Purchase interval in hours
+  max_total_usd: 1000            # Stop after this total invested. Default: none
+```
+
+---
+
+## Preset defaults
+
+### memecoin-sniper
+
+```yaml
+behavior_rules:
+  version: "1"
+  preset: memecoin-sniper
+  filters:
+    min_liquidity_usd: 10000
+    max_market_cap_usd: 5000000
+    require_verified_contract: false
+  entry:
+    trigger: launch_signal
+    max_position_usd: 50
+    slippage_bps: 300
+  exit:
+    take_profit_pct: 100
+    stop_loss_pct: 50
+    max_hold_minutes: 60
+```
+
+### dca-accumulator
+
+```yaml
+behavior_rules:
+  version: "1"
+  preset: dca-accumulator
+  dca:
+    target_token: SOL
+    amount_usd: 10
+    interval_hours: 24
+    max_total_usd: 1000
+  risk:
+    max_single_trade_usd: 10
+    pause_on_drawdown_pct: 30
+```
+
+### swing-trader
+
+```yaml
+behavior_rules:
+  version: "1"
+  preset: swing-trader
+  entry:
+    indicators: [rsi, macd]
+    rsi_oversold: 30
+    max_position_usd: 200
+    slippage_bps: 100
+  exit:
+    take_profit_pct: 20
+    stop_loss_pct: 10
+    min_hold_hours: 2
+    max_hold_hours: 72
+```
+
+---
+
+## Enforcement
+
+Rules are enforced at three levels:
+
+1. **Pre-check** — asset filters applied before the LLM is called (no LLM cost)
+2. **LLM context** — compressed rule summary injected into every decision prompt
+3. **Post-check** — Balchemy backend validates trade parameters against rules before execution
+
+If a trade violates a rule at any level, it is rejected with an error logged via `onError`.
+
+---
+
+## Tips
+
+- Start with a preset and override only the fields you need
+- Keep `max_single_trade_usd` low (≤ $50) until you trust your strategy
+- Use `blocked_tokens` to exclude known scams
+- Use `min_confidence` to reduce false positives when LLM is uncertain
+- Monitor LLM cost with `onStatusChange` — `llmCostToday` / `maxDailyLlmCost`

package/docs/DEPLOYMENT.md

@@ -0,0 +1,195 @@
+# Deployment Guide
+
+Your agent runs as a long-lived Node.js process. The recommended deployment targets
+are a personal VPS ($4–7/mo) or a managed container platform (Railway, Render).
+
+---
+
+## Option A: Docker on a VPS (recommended)
+
+This is the most reliable option. The agent runs in a Docker container that restarts
+automatically on failure or reboot.
+
+### Requirements
+
+- Any Linux VPS with Docker installed (Ubuntu 22.04 LTS recommended)
+- At least 256 MB RAM, 1 vCPU
+- Providers: DigitalOcean, Hetzner, Vultr, Linode — all work fine
+
+### Steps
+
+**1. On your local machine:**
+
+```bash
+npx create-balchemy-agent           # Setup wizard
+npx balchemy-agent docker           # Generate Dockerfile + docker-compose.yml
+```
+
+This creates:
+```
+Dockerfile
+docker-compose.yml
+.env.example         ← copy to .env, fill in credentials
+agent.config.yaml    ← edit behavior_rules as needed
+```
+
+**2. Copy files to your VPS:**
+
+```bash
+scp Dockerfile docker-compose.yml agent.config.yaml .env user@your-vps:/home/user/agent/
+```
+
+**3. On your VPS:**
+
+```bash
+cd /home/user/agent
+docker compose up -d
+docker compose logs -f          # Watch logs
+```
+
+**4. Verify the agent is running:**
+
+```bash
+docker compose ps
+# balchemy-agent   Up (healthy)
+```
+
+### Managing the agent
+
+```bash
+docker compose stop              # Graceful stop
+docker compose start             # Start after stop
+docker compose restart           # Restart
+docker compose logs -f           # Tail logs
+docker compose pull && docker compose up -d   # Update
+```
+
+### Updating config without rebuilding
+
+The `agent.config.yaml` is mounted read-only into the container. Edit it on the
+VPS and restart:
+
+```bash
+nano agent.config.yaml
+docker compose restart
+```
+
+---
+
+## Option B: Railway
+
+Railway provides free-tier hosting for small containers.
+
+1. Push your agent directory to a GitHub repo (exclude `.env`)
+2. Create a new Railway project → Deploy from GitHub
+3. Set environment variables in Railway dashboard:
+   - `MCP_ENDPOINT`, `BALCHEMY_API_KEY`, `LLM_API_KEY`
+4. Railway auto-detects `Dockerfile` and builds the image
+5. Set restart policy to "Always"
+
+---
+
+## Option C: Render
+
+Similar to Railway. Use Render's "Background Worker" service type (not Web Service).
+
+1. Connect your GitHub repo
+2. Select "Background Worker" (no port required)
+3. Set environment variables in Render dashboard
+4. Set "Restart Policy" to "Always"
+
+---
+
+## Option D: systemd daemon (Linux without Docker)
+
+If you prefer to run the agent directly as a system service:
+
+**1. Install globally:**
+
+```bash
+npm install -g create-balchemy-agent @balchemy/agent-sdk
+```
+
+**2. Create a systemd unit file:**
+
+```ini
+# /etc/systemd/system/balchemy-agent.service
+[Unit]
+Description=Balchemy Trading Agent
+After=network.target
+
+[Service]
+Type=simple
+User=ubuntu
+WorkingDirectory=/home/ubuntu/agent
+ExecStart=/usr/bin/balchemy-agent start /home/ubuntu/agent/agent.config.yaml
+EnvironmentFile=/home/ubuntu/agent/.env
+Restart=always
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+```
+
+**3. Enable and start:**
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable balchemy-agent
+sudo systemctl start balchemy-agent
+sudo journalctl -u balchemy-agent -f
+```
+
+---
+
+## Security checklist
+
+- `.env` must have permissions `600`: `chmod 600 .env`
+- Never expose `agent.config.yaml` or `.env` via HTTP
+- Use a non-root user inside the container (default Dockerfile uses `node` user)
+- Rotate API keys regularly in Hub > Agents > API Keys
+- Set `max_single_trade_usd` and `max_daily_loss_usd` to safe values before deploying
+
+---
+
+## Monitoring
+
+The agent logs to stdout in this format:
+
+```
+[agent] status=running events=42 decisions=7 trades=2 llmCost=$0.0120/5.00
+[agent] decision action=buy token=SOL amount=10 confidence=0.87
+[agent] error: trade_command failed: insufficient balance
+```
+
+To forward logs to a log aggregator (e.g., Loki, Datadog):
+
+```yaml
+# In docker-compose.yml
+logging:
+  driver: loki
+  options:
+    loki-url: "http://your-loki-host:3100/loki/api/v1/push"
+    loki-labels: "service=balchemy-agent"
+```
+
+---
+
+## Troubleshooting
+
+**Agent exits immediately:**
+- Check `.env` — all required vars must be set
+- Check `agent.config.yaml` — `mcp_endpoint` and `api_key` are required
+- Run `docker compose logs` to see the error
+
+**Agent starts but makes no decisions:**
+- Verify your API key has `trade` scope (Hub > API Keys > Scopes)
+- Check that your agent has a funded wallet
+- Lower `min_confidence` in `behavior_rules`
+
+**Budget exhausted quickly:**
+- Reduce `max_daily_usd` in `llm` config
+- Switch to a cheaper model (`claude-haiku-4-5` or `gpt-4o-mini`)
+- Add more specific filters to avoid processing low-quality signals

package/docs/QUICKSTART.md

@@ -0,0 +1,123 @@
+# Balchemy Agent — Quickstart
+
+Get an autonomous trading agent running in under 5 minutes.
+
+---
+
+## Prerequisites
+
+- Node.js 18+ (or Docker)
+- A Balchemy account with at least one agent created in the Hub
+- An API key from Hub > Agents > your agent > API Keys
+- An LLM API key (Anthropic or OpenAI)
+
+---
+
+## Step 1: Create an agent in the Hub
+
+1. Go to [balchemy.ai](https://balchemy.ai) and sign in
+2. Open Hub > Agents > New Agent
+3. Complete the setup wizard (wallets, trading config, connect)
+4. Copy the MCP endpoint from the API tab: `https://api.balchemy.ai/mcp/YOUR_PUBLIC_ID`
+5. Generate an API key and copy it (shown once)
+
+---
+
+## Step 2: Run the setup wizard
+
+```bash
+npx create-balchemy-agent
+```
+
+The wizard asks:
+- MCP endpoint
+- Balchemy API key
+- LLM provider (Anthropic or OpenAI) + API key + model
+- Daily LLM budget (USD)
+- Strategy preset
+
+It writes `agent.config.yaml` and `.env` to the current directory.
+
+---
+
+## Step 3: Start the agent
+
+```bash
+npx balchemy-agent start
+```
+
+You should see:
+
+```
+Starting Balchemy agent from: /path/to/agent.config.yaml
+[agent] Running. Press Ctrl+C to stop.
+[agent] status=running events=0 decisions=0 trades=0 llmCost=$0.0000/5
+```
+
+The agent:
+1. Connects to the Balchemy SSE event stream
+2. Receives market signals and platform events
+3. Calls your LLM to decide whether to buy, sell, or hold
+4. Executes approved trades via MCP tool calls
+
+---
+
+## Step 4: Docker (production)
+
+```bash
+npx balchemy-agent docker
+docker compose up -d
+docker compose logs -f
+```
+
+The generated `docker-compose.yml` runs the agent with:
+- `restart: always` — survives crashes and reboots
+- Mounted `agent.config.yaml` — edit config without rebuilding
+- JSON log rotation (10 MB × 5 files)
+
+---
+
+## Programmatic usage (TypeScript)
+
+```typescript
+import { AgentLoop } from '@balchemy/agent-sdk';
+
+// From YAML config file
+const loop = AgentLoop.fromConfig('./agent.config.yaml');
+await loop.start();
+
+// Or inline config
+const loop2 = new AgentLoop({
+  mcpEndpoint: 'https://api.balchemy.ai/mcp/YOUR_PUBLIC_ID',
+  apiKey: process.env.BALCHEMY_API_KEY!,
+  llmProvider: 'anthropic',
+  llmApiKey: process.env.ANTHROPIC_API_KEY!,
+  llmModel: 'claude-haiku-4-5',
+  maxDailyLlmCost: 5,
+  onStatusChange: (s) => console.log('status', s.status),
+  onDecision: (d) => console.log('decision', d),
+  onError: (e) => console.error('error', e.message),
+});
+await loop2.start();
+```
+
+---
+
+## Strategy presets
+
+| Preset | Description | Recommended model |
+|--------|-------------|-------------------|
+| `dca-accumulator` | Buy fixed-USD at regular intervals | gpt-4o-mini |
+| `memecoin-sniper` | Buy on launch signals, sell on pump | claude-haiku-4-5 |
+| `swing-trader` | Hold positions 2–72h, exit on RSI/MACD | claude-haiku-4-5 |
+| `custom` | Define your own rules in `behavior_rules` | any |
+
+See [BEHAVIOR_RULES.md](./BEHAVIOR_RULES.md) for the full rule schema.
+
+---
+
+## Next steps
+
+- [BEHAVIOR_RULES.md](./BEHAVIOR_RULES.md) — customize your agent's trading logic
+- [DEPLOYMENT.md](./DEPLOYMENT.md) — deploy to a VPS, Railway, or Render
+- [examples/](./examples/) — ready-to-use strategy YAML files

package/docs/error-retry-strategy.md

@@ -0,0 +1,27 @@
+# Error Classification and Retry Strategy
+
+## Error Classes
+
+- `auth_error`: JWT/identity mismatch, unauthorized onboarding.
+- `policy_error`: guardrail rejection, invalid payload, unsupported mode/provider.
+- `rate_limit_error`: endpoint throttling.
+- `provider_auth_error`: upstream provider verify authorization failure.
+- `network_error`: timeout, DNS, transport errors.
+- `execution_error`: MCP call returned JSON-RPC error.
+- `invalid_response`: malformed payload.
+- `unknown_error`: fallback.
+
+## Recommended Retry Rules
+
+- `rate_limit_error`: exponential backoff with jitter (`2s`, `5s`, `10s`, `20s`).
+- `network_error`: bounded retries (`max=3`) with linear backoff (`1s`, `2s`, `3s`).
+- `execution_error`: retry only if tool is idempotent (`tools/list`, status calls).
+- `policy_error` / `auth_error` / `provider_auth_error`: do not blind-retry; require input or credential fix.
+
+## Safe Retry Gate
+
+Retry only when all conditions hold:
+
+1. Error class is retryable (`network_error` or `rate_limit_error`).
+2. Operation is idempotent or duplicate-safe.
+3. Retry budget for the request has remaining attempts.

package/docs/examples/custom-strategy.yaml

@@ -0,0 +1,73 @@
+# Custom Strategy — Annotated Example
+#
+# This file shows every supported behavior_rules field.
+# Use it as a reference when building your own strategy.
+# Delete or comment out fields you do not need.
+
+mcp_endpoint: "${MCP_ENDPOINT}"
+api_key: "${BALCHEMY_API_KEY}"
+
+llm:
+  provider: anthropic            # anthropic | openai
+  api_key: "${LLM_API_KEY}"
+  model: claude-haiku-4-5        # Use haiku/gpt-4o-mini for cost, sonnet/gpt-5 for quality
+  max_daily_usd: 5               # Hard LLM budget cap in USD per day
+  timeout_ms: 10000              # LLM call timeout in milliseconds
+
+# Optional: separate cheap/full models for model routing
+# cheapModel: claude-haiku-4-5  # Used for low-significance events (score < 60)
+# fullModel: claude-sonnet-4    # Used for high-significance events (score >= 60)
+
+strategy: custom
+
+# Optional webhook receiver — receives Balchemy push events directly
+# webhook:
+#   port: 4242
+#   secret: "${WEBHOOK_SECRET}"
+
+behavior_rules:
+  version: "1"
+  preset: custom                 # custom | memecoin-sniper | dca-accumulator | swing-trader
+
+  # ─── Risk limits (applied globally, cannot be overridden per trade) ──────────
+  risk:
+    max_single_trade_usd: 50     # Hard cap per trade
+    max_daily_loss_usd: 200      # Pause after this daily loss
+    max_open_positions: 5        # Max simultaneous open positions
+    pause_on_drawdown_pct: 20    # Pause if portfolio drops 20% from peak
+    allowed_chains: [solana]     # solana | base | ethereum | arbitrum
+
+  # ─── Asset filters (applied before LLM call — zero LLM cost) ────────────────
+  filters:
+    min_liquidity_usd: 20000
+    max_market_cap_usd: 50000000
+    require_verified_contract: false
+    blocked_tokens:              # Addresses to never trade
+      - "So11111111111111111111111111111111111111112"
+    # allowed_tokens:            # If set, only these tokens will be traded
+    #   - "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
+
+  # ─── Entry conditions ────────────────────────────────────────────────────────
+  entry:
+    # Trigger type: launch_signal | price_drop | rsi_signal | manual
+    trigger: price_drop
+    indicators: [rsi]
+    rsi_oversold: 35
+    max_position_usd: 100
+    slippage_bps: 150
+    min_confidence: 0.7          # LLM confidence threshold (0.0–1.0)
+
+  # ─── Exit conditions ─────────────────────────────────────────────────────────
+  exit:
+    take_profit_pct: 30
+    stop_loss_pct: 15
+    trailing_stop_pct: 10        # Activate once in profit; trail 10% below peak
+    min_hold_hours: 0            # Allow immediate exit if conditions are met
+    max_hold_hours: 48           # Force exit after 48 hours
+
+  # ─── DCA config (only for dca-accumulator preset) ───────────────────────────
+  # dca:
+  #   target_token: SOL
+  #   amount_usd: 10
+  #   interval_hours: 24
+  #   max_total_usd: 500

package/docs/examples/dca-accumulator.yaml

@@ -0,0 +1,41 @@
+# DCA Accumulator Strategy
+#
+# Dollar-cost averages into SOL on a fixed schedule.
+# Buys $10 of SOL every 24 hours regardless of price.
+# Pauses DCA if portfolio drops more than 30% from peak.
+#
+# Risk profile: LOW — patient accumulation, no active trading decisions.
+# Recommended LLM: gpt-4o-mini (sufficient for simple buy confirmations)
+
+mcp_endpoint: "${MCP_ENDPOINT}"
+api_key: "${BALCHEMY_API_KEY}"
+
+llm:
+  provider: openai
+  api_key: "${LLM_API_KEY}"
+  model: gpt-4o-mini
+  max_daily_usd: 1              # DCA fires once per day — very low LLM cost
+  timeout_ms: 15000
+
+strategy: dca-accumulator
+
+behavior_rules:
+  version: "1"
+  preset: dca-accumulator
+
+  dca:
+    target_token: SOL
+    amount_usd: 10              # Buy $10 per interval
+    interval_hours: 24          # Daily purchases
+    max_total_usd: 1000         # Stop after $1000 total invested
+
+  risk:
+    max_single_trade_usd: 10    # Each DCA buy is capped at $10
+    pause_on_drawdown_pct: 30   # Pause if portfolio value drops 30% from peak
+    max_open_positions: 1       # Only hold SOL — single-asset strategy
+    allowed_chains: [solana]
+
+  filters:
+    allowed_tokens:
+      # Wrapped SOL (wSOL) — the only token this strategy trades
+      - "So11111111111111111111111111111111111111112"

package/docs/examples/memecoin-sniper.yaml

@@ -0,0 +1,47 @@
+# Memecoin Sniper Strategy
+#
+# Buys newly launched memecoins on Solana within the first few minutes
+# of listing. Takes profit at 100% gain, cuts losses at 50% drop.
+# Positions are never held longer than 60 minutes.
+#
+# Risk profile: HIGH — many trades will lose, winners cover losers.
+# Recommended LLM: claude-haiku-4-5 (fast, cheap, sufficient for signal routing)
+
+mcp_endpoint: "${MCP_ENDPOINT}"
+api_key: "${BALCHEMY_API_KEY}"
+
+llm:
+  provider: anthropic
+  api_key: "${LLM_API_KEY}"
+  model: claude-haiku-4-5
+  max_daily_usd: 3              # Memecoin sniper fires frequently — keep budget low
+  timeout_ms: 5000              # Tight timeout — stale signals are worthless
+
+strategy: memecoin-sniper
+
+behavior_rules:
+  version: "1"
+  preset: memecoin-sniper
+
+  filters:
+    min_liquidity_usd: 10000      # Avoid rugpulls with thin liquidity
+    max_market_cap_usd: 5000000   # Only micro-caps — higher upside
+    require_verified_contract: false  # Most new launches are unverified
+    allowed_chains: [solana]
+
+  entry:
+    trigger: launch_signal         # React to new token launch events
+    max_position_usd: 25           # Small positions — many trades
+    slippage_bps: 400              # High slippage accepted for fast entry
+    min_confidence: 0.55           # Lower threshold — sniper takes more swings
+
+  exit:
+    take_profit_pct: 100           # Double or nothing
+    stop_loss_pct: 50              # Cut at -50%
+    max_hold_minutes: 60           # Force exit after 1 hour no matter what
+    trailing_stop_pct: 20          # Lock in gains if price reverses 20% from peak
+
+  risk:
+    max_single_trade_usd: 25
+    max_daily_loss_usd: 100        # Hard daily stop
+    max_open_positions: 3          # Never hold more than 3 memecoins at once