Clawback

ClawBack

Mirror congressional stock trades with automated broker execution

Agent Instructions

When the user invokes /clawback, execute the appropriate command based on the argument:

Commands

When the user invokes /clawback with any arguments, execute the corresponding command:

| Command | Action | |---------|--------| | /clawback setup | Run the setup wizard: Execute {baseDir}/bin/clawback.py setup | | /clawback status | Check system status: Execute {baseDir}/bin/clawback.py status | | /clawback run | Start trading bot: Execute {baseDir}/bin/clawback.py run | | /clawback daemon | Run as background service: Execute {baseDir}/bin/clawback.py daemon | | /clawback test | Test notifications: Execute {baseDir}/bin/clawback.py test | | /clawback (no args) | Show help: Execute {baseDir}/bin/clawback.py --help |

How to Execute Commands

Option 1: Using the wrapper script (recommended) When executing ClawBack commands, always: 1. Use the wrapper script at {baseDir}/bin/clawback.py 2. Pass the command as an argument (e.g., {baseDir}/bin/clawback.py status) 3. Capture and display the output to the user

Option 2: Direct Python execution (if wrapper doesn't work) If the wrapper script fails, you can run ClawBack directly: 1. Change to the skill directory: cd {baseDir} 2. Activate the virtual environment: source venv/bin/activate 3. Run the CLI: python -m clawback.cli [command] 4. Capture and display the output

Important: Always check if the virtual environment exists at {baseDir}/venv. If not, you may need to run the setup first.

/clawback setup - Interactive Setup Flow

When user runs /clawback setup, follow these steps:

Step 1: Install dependencies (if needed) Check if {baseDir}/venv exists. If not, run:

cd {baseDir} && python3 -m venv venv && source venv/bin/activate && pip install -e .

Step 2: Prompt for E*TRADE credentials Ask the user for each value:

1. Environment: Ask "Do you want to use sandbox (testing) or production (real money)?" - Default: sandbox

2. Consumer Key: Ask "Enter your E*TRADE Consumer Key (from developer.etrade.com):" - Required field

3. Consumer Secret: Ask "Enter your E*TRADE Consumer Secret:" - Required field

4. Account ID: Ask "Enter your E*TRADE Account ID (or leave blank to get it after OAuth):" - Optional - can be obtained later

Step 3: Save configuration Create/update ~/.clawback/config.json with the provided values:

{
  "broker": {
    "adapter": "etrade",
    "environment": "",
    "credentials": {
      "apiKey": "",
      "apiSecret": ""
    }
  },
  "trading": {
    "accountId": "",
    "initialCapital": 50000,
    "tradeScalePercentage": 0.01,
    "maxPositionPercentage": 0.05,
    "dailyLossLimit": 0.02
  },
  "notifications": {
    "telegram": {
      "enabled": true,
      "useOpenClaw": true
    }
  },
  "congress": {
    "dataSource": "official",
    "pollIntervalHours": 24,
    "minimumTradeSize": 10000
  }
}

Step 4: Confirm setup Tell the user: "Configuration saved to ~/.clawback/config.json. Run /clawback status to verify."

Getting E*TRADE API Credentials

Direct user to: https://developer.etrade.com 1. Create a developer account 2. Create a new app (sandbox first for testing) 3. Copy the Consumer Key and Consumer Secret

Configuration Location

Reading Saved Configuration

To check if the user has configured credentials, read ~/.clawback/config.json:

The CLI automatically reads from ~/.clawback/config.json for all operations.

Checking Setup Status

Before running /clawback status or /clawback run, verify: 1. {baseDir}/venv exists (dependencies installed) 2. ~/.clawback/config.json exists with non-empty broker.credentials.apiKey

If either is missing, suggest running /clawback setup first.

ClawBack tracks stock trades disclosed by members of Congress (House and Senate) and executes scaled positions in your E*TRADE brokerage account. Built on the premise that congressional leaders consistently outperform the market due to informational advantages.

Default Target Politicians

ClawBack monitors these politicians by default (configurable):

| Politician | Chamber | Priority | |------------|---------|----------| | Nancy Pelosi | House | 1 (highest) | | Dan Crenshaw | House | 2 | | Tommy Tuberville | Senate | 2 | | Marjorie Taylor Greene | House | 3 |

Trading Strategy Defaults

| Parameter | Default | Description | |-----------|---------|-------------| | Trade Delay | 3 days | Wait after disclosure before trading | | Holding Period | 30 days | Target hold time for positions | | Position Size | 5% | Max allocation per trade | | Stop-Loss | 8% | Per-position stop-loss | | Portfolio Drawdown | 15% | Max portfolio loss before halt | | Disclosure Checks | 10:00, 14:00, 18:00 ET | Daily check times |

Features

Performance (Backtest Results)

| Strategy | Win Rate | Return | Sharpe | |----------|----------|--------|--------| | 3-day delay, 30-day hold | 42.9% | +6.2% | 0.39 | | 9-day delay, 90-day hold | 57.1% | +4.7% | 0.22 |

Congressional leaders have outperformed the S&P 500 by 47% annually according to NBER research.

Installation via ClawHub

# Install from ClawHub registry
clawhub install clawback
Or install from local directory
clawhub install ./clawback

Troubleshooting

Common Issues

1. Skill not executing: If /clawback doesn't work in OpenClaw: - Check if the skill is in the correct location: {baseDir}/ - Verify the wrapper script is executable: chmod +x {baseDir}/bin/clawback.py - Check if virtual environment exists: {baseDir}/venv/

2. Authentication issues: If E*TRADE authentication fails: - Run the authentication utility: python {baseDir}/scripts/auth_utility.py --auth - Run {baseDir}/bin/clawback.py setup to reconfigure - Check credentials in ~/.clawback/config.json - Verify E*TRADE API keys are valid

3. Token expiration: If tokens expire (30-day lifespan): - Run: python {baseDir}/scripts/auth_utility.py --refresh - Or start new authentication: python {baseDir}/scripts/auth_utility.py --auth

4. Python import errors: If you see "ModuleNotFoundError": - Ensure virtual environment is activated - Run pip install -e . in {baseDir}/ - Check Python path includes {baseDir}/src

Debug Mode

To debug skill execution, add DEBUG=1 environment variable:

DEBUG=1 {baseDir}/bin/clawback.py status

This will show additional information about the execution context.

Post-Installation Setup

After installation via ClawHub, the install.sh script runs automatically:

1. Python Environment Setup - Creates virtual environment 2. Package Installation - Installs ClawBack via pip 3. Directory Structure - Creates logs/, data/, config/ directories 4. Setup Prompt - Asks if you want to run the setup wizard

If you skip setup during installation, run it manually:

cd ~/.openclaw/skills/clawback
./setup.sh          # Interactive setup wizard
or
clawback setup      # CLI-based setup

Improved Setup Features

Interactive Setup Wizard

The setup wizard guides you through configuration:

Step 1: Environment Selection

Step 2: E*TRADE API Credentials

Step 3: Authentication

Step 4: Account Selection

Step 5: Telegram Setup (Optional)

Environment Variables

After setup, credentials are stored in .env:

# E*TRADE API (required)
BROKER_API_KEY=your_consumer_key_here
BROKER_API_SECRET=your_consumer_secret_here
BROKER_ACCOUNT_ID=your_account_id_here
Telegram (optional)
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here
FMP API (optional)
FMP_API_KEY=your_fmp_api_key_here

Usage

# Use the installed CLI command
clawback run      # Start interactive trading mode
clawback daemon   # Run as background service
clawback status   # Check system status
clawback setup    # Re-run setup wizard
clawback test     # Test Telegram notifications

Automated Trading

The clawback daemon command runs continuously with:

Data Sources

Supported Brokers

ClawBack currently only supports E*TRADE. The adapter pattern allows for future broker support, but only E*TRADE is implemented and tested.

| Broker | Adapter | Status | |--------|---------|--------| | E*TRADE | etrade_adapter.py | Supported |

Risk Management

Authentication Helpers

For manual E*TRADE authentication outside the main CLI:

# Standalone OAuth authentication script
cd {baseDir}
source venv/bin/activate
python scripts/auth_script.py

This generates an authorization URL, prompts for the verification code, and completes authentication.

File Locations

| File | Purpose | |------|---------| | ~/.clawback/config.json | Main configuration | | ~/.clawback/.access_tokens.json | E*TRADE OAuth tokens | | ~/.clawback/data/trading.db | SQLite database |

Security

Support

Disclaimer

Trading involves substantial risk of loss. This software is for educational purposes only. Past congressional trading performance does not guarantee future results. Always test with E*TRADE sandbox accounts before live trading.

# Use the installed CLI command
clawback run      # Start interactive trading mode
clawback daemon   # Run as background service
clawback status   # Check system status
clawback setup    # Re-run setup wizard
clawback test     # Test Telegram notifications

Common Issues

1. Skill not executing: If /clawback doesn't work in OpenClaw: - Check if the skill is in the correct location: {baseDir}/ - Verify the wrapper script is executable: chmod +x {baseDir}/bin/clawback.py - Check if virtual environment exists: {baseDir}/venv/

2. Authentication issues: If E*TRADE authentication fails: - Run the authentication utility: python {baseDir}/scripts/auth_utility.py --auth - Run {baseDir}/bin/clawback.py setup to reconfigure - Check credentials in ~/.clawback/config.json - Verify E*TRADE API keys are valid

3. Token expiration: If tokens expire (30-day lifespan): - Run: python {baseDir}/scripts/auth_utility.py --refresh - Or start new authentication: python {baseDir}/scripts/auth_utility.py --auth

4. Python import errors: If you see "ModuleNotFoundError": - Ensure virtual environment is activated - Run pip install -e . in {baseDir}/ - Check Python path includes {baseDir}/src

Debug Mode

To debug skill execution, add DEBUG=1 environment variable:

DEBUG=1 {baseDir}/bin/clawback.py status

This will show additional information about the execution context.

Post-Installation Setup

After installation via ClawHub, the install.sh script runs automatically:

1. Python Environment Setup - Creates virtual environment 2. Package Installation - Installs ClawBack via pip 3. Directory Structure - Creates logs/, data/, config/ directories 4. Setup Prompt - Asks if you want to run the setup wizard

If you skip setup during installation, run it manually:

cd ~/.openclaw/skills/clawback
./setup.sh          # Interactive setup wizard
or
clawback setup      # CLI-based setup

Improved Setup Features