Clawback

Mirror congressional stock trades with automated broker execution and risk management. Use when you want to track and automatically trade based on congressio...

Security Scan

The skill appears to implement a congressional-trade mirroring bot that needs E*TRADE credentials and will install/run locally, but there are packaging/metadata inconsistencies and persistent-install behaviors (cron/daemon, venv, config writes) that merit careful review before installing or giving credentials.

Purpose & Capability

The declared purpose (mirror congressional disclosures and trade via E*TRADE) aligns with the code and instructions: the repo contains an E*TRADE adapter, trade engine, CLI, setup/auth helpers, cron/daemon scripts and config handling. Requiring broker credentials is appropriate. However the registry metadata is inconsistent: it lists no required env vars but provides primaryEnv=BROKER_API_KEY and the README/SKILL.md also expect BROKER_API_SECRET, account id, and optional TELEGRAM tokens. That mismatch between declared requirements and actual needs is a packaging/information coherence issue.

Instruction Scope

SKILL.md instructs the agent to run local installation (create a venv, pip install -e .), execute the bundled wrapper {baseDir}/bin/clawback.py and other scripts, prompt the user for E*TRADE Consumer Key/Secret, and read/write ~/.clawback/config.json. Those actions are required for a trading bot but also mean the skill will create files in the user's home, may store long-lived credentials in disk JSON, and run background tasks. The instructions grant broad discretion to execute many local scripts (setup, cron setup, daemon), so a user should review the scripts before running them.

Install Mechanism

There is no remote download from an untrusted URL; installation is local via pip install -e . and the package ships setup and install scripts. That is lower risk than arbitrary URL downloads, but local install/run of Python package code means arbitrary code bundled in the repo will be executed on install/run. The SKILL.md metadata references pip "{baseDir}" which is logical but the registry-level install spec was marked as absent — another metadata inconsistency to be aware of.

Credentials

The skill's primary credential is BROKER_API_KEY which is expected. But the code and docs require additional secrets (E*TRADE Consumer Secret, Account ID, optional TELEGRAM_BOT_TOKEN/CHAT_ID) that are not fully declared in the registry's required-env listing. The skill saves credentials into ~/.clawback/config.json and uses persistent token files; storing sensitive keys on disk without explicit encryption is a data-security consideration. There are no unrelated credentials requested, but the mismatch between declared and used env/config items is noteworthy.

Persistence & Privilege

The project includes scripts to run as a daemon and to install cron jobs (scripts/setup_cron.sh, cron_manager, run_cron.sh). Running setup can create a venv, scheduled tasks, and long-running background processes that will continue operating and can execute trades autonomously. The skill is not force-included (always:false) but the package explicitly provides mechanisms for persistent background execution — the user must explicitly consent and inspect the cron/daemon scripts before enabling them.

What to consider before installing

This repo appears to implement exactly what it claims (an automated E*TRADE trading bot that mirrors congressional disclosures), but there are several red flags you should address before installing: - Review code and scripts first: inspect setup.sh, install.sh, scripts/setup_cron.sh, bin/clawback.py, and any auth helpers (complete_auth.py, scripts/auth_script.py) to understand exactly what will be run and what will be written to your system. - Use a sandbox account: test only with E*TRADE sandbox credentials and a sandbox brokerage account before giving any production API keys or enabling real trades. - Check where credentials are stored: the setup writes ~/.clawback/config.json and token files. If you must store secrets, consider encrypting them or storing them in a secure vault rather than plaintext files. - Watch for cron/daemon installation: the skill can add scheduled jobs or run background services—only enable those if you trust the code and understand the scheduled behavior and failure modes. - Prefer manual run until comfortable: run commands manually (inside an isolated virtualenv) and observe behavior before allowing automated/daemon operation. - Ask for metadata fixes: the packaging/registry metadata is inconsistent (declared envs vs README/SKILL.md and presence of many code files). Consider requesting the maintainer clarify required env vars, install steps, and whether credentials are persisted/encrypted. Given these inconsistencies and the power to execute trades and install persistent jobs, treat the skill as potentially risky until you (or someone you trust) have audited the code and tested it in a sandbox environment.

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": "<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

# 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

• 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:

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

• 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 ETRADE. The adapter pattern allows for future broker support, but only ETRADE 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:

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