Clawback

SKILL.md

---
name: clawback
description: Mirror congressional stock trades with automated broker execution and risk management. Use when you want to track and automatically trade based on congressional disclosures from House Clerk and Senate eFD sources.
version: 1.1.0
author: mainfraame
homepage: https://github.com/mainfraame/clawback
user-invocable: true
metadata: {"openclaw": {"emoji": "🦀", "requires": {"bins": ["python3", "pip"]}, "install": {"pip": "{baseDir}"}, "primaryEnv": "BROKER_API_KEY"}}
---

# 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:
```bash
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:
```json
{
  "broker": {
    "adapter": "etrade",
    "environment": "<sandbox or production>",
    "credentials": {
      "apiKey": "<consumer_key>",
      "apiSecret": "<consumer_secret>"
    }
  },
  "trading": {
    "accountId": "<account_id>",
    "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

- Config file: `~/.clawback/config.json`
- Skill directory: `{baseDir}`

### Reading Saved Configuration

To check if the user has configured credentials, read `~/.clawback/config.json`:
- If file doesn't exist or credentials are empty → prompt for setup
- If credentials exist → can proceed with status/run commands

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

- **Real-time disclosure tracking** from official House Clerk and Senate eFD sources
- **Automated trade execution** via E*TRADE API (only supported broker)
- **Smart position sizing** - scales trades to your account size
- **Trailing stop-losses** - lock in profits, limit losses
- **Risk management** - drawdown limits, consecutive loss protection
- **Telegram notifications** - get alerts for new trades and stop-losses
- **Backtesting engine** - test strategies on historical data

## 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

```bash
# 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:
```bash
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:
```bash
cd ~/.openclaw/skills/clawback
./setup.sh          # Interactive setup wizard
# or
clawback setup      # CLI-based setup
```

### Improved Setup Features

- **Better input handling** - Works in both interactive and non-interactive modes
- **Input validation** - Validates E*TRADE API key formats
- **Timeout handling** - Automatically uses defaults if no input
- **Error recovery** - Fallback to manual setup if CLI fails
- **Configuration check** - Detects existing config and offers options

## Interactive Setup Wizard

The setup wizard guides you through configuration:

### Step 1: Environment Selection
- **Sandbox** (recommended for testing): No real trades, uses E*TRADE developer sandbox
- **Production**: Real trading with real money

### Step 2: E*TRADE API Credentials
- **Consumer Key**: From E*TRADE developer portal
- **Consumer Secret**: From E*TRADE developer portal

### Step 3: Authentication
- Automatic OAuth flow with E*TRADE
- Opens browser for authorization
- Returns verification code

### Step 4: Account Selection
- Lists all available E*TRADE accounts
- Choose which account to trade with

### Step 5: Telegram Setup (Optional)
- Configure notifications via Telegram bot
- Uses OpenClaw's built-in Telegram channel if available

## Environment Variables

After setup, credentials are stored in `.env`:

```bash
# 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

```bash
# 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:
- **Disclosure checks** at 10:00, 14:00, 18:00 ET (when filings are typically released)
- **Trade execution** at 9:35 AM ET (5 min after market open)
- **Token refresh** every 90 minutes (keeps E*TRADE session alive)
- **Market hours enforcement** (9:30 AM - 4:00 PM ET)

## Data Sources

- **House Clerk**: https://disclosures-clerk.house.gov (PDF parsing)
- **Senate eFD**: https://efdsearch.senate.gov (web scraping)
- **Financial Modeling Prep**: Enhanced financial data (optional)

## 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

- **Position limits**: 5% max per symbol, 20 positions max
- **Stop-losses**: 8% per position, 15% portfolio drawdown
- **Daily limits**: 3% max daily loss
- **PDT compliance**: Conservative 2 trades/day limit

## Authentication Helpers

For manual E*TRADE authentication outside the main CLI:

```bash
# 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

- No hardcoded credentials in source code
- Environment variable based configuration
- Encrypted token storage for E*TRADE
- Git-ignored `.env` file
- Optional production encryption

## Support

- **Documentation**: See README.md for detailed setup
- **Issues**: https://github.com/mainfraame/clawback/issues
- **Community**: https://discord.com/invite/clawd

## 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.