# Complete Broker Setup Guide

Detailed instructions for connecting every supported broker.

---

## Quick Start

1. **Enable MFA** on your account (Settings > Security)
2. **Go to** Settings > Brokers
3. **Click** Add Broker
4. **Follow** the steps for your broker below

---

## Alpaca (Recommended for Beginners)

**Best for**: US Stocks, ETFs, Fractional shares, Commission-free

### Why Alpaca?
- Free to sign up
- Excellent paper trading
- No minimum balance
- Commission-free trading
- Simple API setup

### Step-by-Step Setup

**1. Create Alpaca Account**
1. Go to Alpaca's website
2. Click "Sign Up"
3. Enter email and create password
4. Verify your email

**2. Complete Verification (for live trading)**
1. Log into Alpaca
2. Go to Account > Identity Verification
3. Enter personal information
4. Upload ID document
5. Wait for approval (usually same day)

**3. Get Paper Trading Keys**
1. Log into Alpaca
2. Switch to "Paper Trading" environment (toggle at top)
3. Go to "API Keys" in left sidebar
4. Click "Generate New Keys"
5. **Copy both**:
   - API Key ID (starts with `PK`)
   - Secret Key (only shown once!)

**4. Connect to Agencio**
1. Go to Settings > Brokers
2. Click "Add Broker"
3. Select "Alpaca"
4. Choose "Paper" mode
5. Paste API Key ID
6. Paste Secret Key
7. Click "Test Connection"
8. If successful, click "Save"

**5. Verify Connection**
- Check for green "Connected" status
- Click "Test" to verify again anytime
- View account balance in Trading dashboard

### Getting Live Keys (When Ready)
1. Complete identity verification
2. Fund your Alpaca account
3. Switch to "Live Trading" environment
4. Generate new API keys (will start with `AK`)
5. Add as new broker in Agencio with "Live" mode

### Alpaca Tips
- Paper and Live are separate environments
- Paper keys won't work for live (and vice versa)
- You can have both connected simultaneously
- Paper balance resets if you request it

---

## Interactive Brokers

**Best for**: Advanced traders, Options, Futures, Global markets

### Account Requirements
- IBKR Pro or IBKR Lite account
- API access enabled
- TWS or IB Gateway installed

### Step-by-Step Setup

**1. Enable API Access**
1. Log into IBKR Account Management
2. Go to Settings > User Settings
3. Find "API" section
4. Click "Change" next to API Settings
5. Enable "ActiveX and Socket Clients"
6. Note your Client ID (or create one)

**2. Configure TWS**
1. Open Trader Workstation
2. Go to Edit > Global Configuration
3. Navigate to API > Settings
4. Enable "Enable ActiveX and Socket Clients"
5. Note the "Socket port" (default: 7496 for live, 7497 for paper)
6. Add your IP to "Trusted IPs" if needed

**3. Connect to Agencio**
1. Go to Settings > Brokers
2. Click "Add Broker"
3. Select "Interactive Brokers"
4. Enter:
   - Host: localhost (or your TWS IP)
   - Port: 7496 (live) or 7497 (paper)
   - Client ID: Your client ID
5. Click "Test Connection"
6. If successful, click "Save"

### IBKR Requirements
- TWS or IB Gateway must be running
- Must be logged into TWS
- API permissions must be enabled

### IBKR Paper Trading
1. In TWS, go to File > Paper Trading Login
2. Use your paper trading credentials
3. Paper TWS uses port 7497 by default

---

## Binance

**Best for**: Cryptocurrency, Spot trading, Perpetual futures

### Account Requirements
- Binance account (not Binance.US for full features)
- Identity verification completed
- API trading enabled

### Step-by-Step Setup

**1. Create API Key**
1. Log into Binance
2. Go to Profile > API Management
3. Click "Create API"
4. Choose "System Generated"
5. Name your key (e.g., "Agencio Predict")
6. Complete 2FA verification
7. **Copy** the API Key and Secret Key

**2. Configure Permissions**
1. After creating, click "Edit"
2. Enable:
   - "Enable Reading" (required)
   - "Enable Spot & Margin Trading" (for spot)
   - "Enable Futures" (for perpetuals)
3. **Recommended**: Add IP restriction
   - Click "Restrict access to trusted IPs only"
   - Add your IP address

**3. Connect to Agencio**
1. Go to Settings > Brokers
2. Click "Add Broker"
3. Select "Binance"
4. Choose account type:
   - Spot
   - Futures (USDT-M)
5. Paste API Key
6. Paste Secret Key
7. Click "Test Connection"
8. Save if successful

### Binance Futures
- Separate balance from Spot
- Higher risk — leverage available
- Transfer funds to Futures wallet in Binance
- Select "Futures" when adding broker

### Security Best Practices
- Enable IP restriction
- Don't enable withdrawal permission
- Use a dedicated API key for Agencio
- Regularly review API key usage in Binance

---

## Pepperstone

**Best for**: Forex, CFDs, Commodities, Indices

### Account Requirements
- Pepperstone trading account
- Demo or Live account

### Step-by-Step Setup (OAuth)

**1. Initiate Connection**
1. Go to Settings > Brokers
2. Click "Add Broker"
3. Select "Pepperstone"
4. Click "Connect with Pepperstone"

**2. Authorize**
1. You're redirected to Pepperstone/cTrader login
2. Enter your credentials
3. Review permissions requested
4. Click "Allow" to authorize

**3. Complete**
1. Redirected back to Agencio
2. Connection automatically configured
3. Verify with "Test Connection"

### Pepperstone Features
- 70+ forex pairs
- Indices (US500, UK100, etc.)
- Commodities (Gold, Oil)
- Crypto CFDs
- No API key management needed

### Demo vs Live
- Select account type during OAuth
- Can connect both separately
- Demo for practice, Live for real trading

---

## Charles Schwab

**Best for**: US Stocks, ETFs, Options (US-based traders)

### Account Requirements
- Schwab brokerage account
- Trading permissions enabled

### Important: 7-Day Re-Authentication

⚠️ **Schwab tokens expire after 7 days**. You must re-authorize weekly.

Set a recurring calendar reminder!

### Step-by-Step Setup (OAuth)

**1. Initiate Connection**
1. Go to Settings > Brokers
2. Click "Add Broker"
3. Select "Charles Schwab"
4. Click "Connect with Schwab"

**2. Authorize**
1. Redirected to Schwab login
2. Enter Schwab credentials
3. Complete any 2FA
4. Review and approve permissions
5. Click "Allow"

**3. Complete**
1. Redirected back to Agencio
2. Connection configured
3. Test connection to verify

### Weekly Re-Authorization
1. You'll get a notification when token expires
2. Go to Settings > Brokers
3. Click "Re-authorize" on Schwab
4. Complete OAuth flow again

### Schwab Features
- US stocks and ETFs
- Options trading
- No API key to manage
- Integrated with Schwab's research

---

## Testing Your Connection

### After Connecting Any Broker

1. **Test Button**
   - Click "Test" next to the broker
   - Should show "Connection successful"
   - Displays account info

2. **Check Balance**
   - Go to Trading dashboard
   - Select the broker
   - Balance should display

3. **Place Test Order (Paper)**
   - Switch to Paper mode
   - Place a small test order
   - Verify it appears in your broker's interface

### Troubleshooting Failed Tests

| Error | Likely Cause | Solution |
|-------|--------------|----------|
| "Invalid credentials" | Wrong key/secret | Re-copy from broker |
| "Permission denied" | Missing API permission | Enable required permissions |
| "Connection refused" | TWS not running (IBKR) | Start TWS/IB Gateway |
| "IP blocked" | IP not whitelisted | Add IP to whitelist |
| "Token expired" | Schwab 7-day limit | Re-authorize |

---

## Managing Multiple Brokers

### Adding Multiple Brokers
- You can connect multiple brokers
- Each broker shows separately in Settings
- Choose which to use per trade/strategy

### Selecting Active Broker
1. In Trading view, look for broker selector
2. Choose which broker to use
3. Orders route to selected broker

### Per-Strategy Broker
- When creating strategies, select target broker
- Strategy uses that broker for execution

---

## Security Best Practices

### API Keys
- Never share your API keys
- Don't paste keys in chat/email
- Revoke compromised keys immediately
- Use unique keys for each platform

### IP Restrictions
Where supported (Binance):
- Enable IP restrictions
- Only allow known IPs
- Update when your IP changes

### Permissions
- Only enable required permissions
- Never enable withdrawal (not needed)
- Review permissions periodically

### In Agencio
- All keys encrypted with AES-256-GCM
- Keys never displayed after saving
- Only last 4 characters shown
- Secure delete on broker removal

---

## Switching Modes

### Mock to Paper
1. Connect a broker (paper or live)
2. Enable MFA
3. Go to Settings > Trading
4. Select "Paper Trading"
5. Confirm

### Paper to Live
Requirements:
- 30 days in paper mode
- 50+ trades completed
- Sharpe Ratio ≥ 1.0
- Max Drawdown ≤ 15%
- MFA enabled
- Live broker connected

Process:
1. Meet requirements above
2. Go to Settings > Trading
3. Request Live Access
4. Review and acknowledge risks
5. Get approved (usually automatic)

---

## Removing a Broker

1. Go to Settings > Brokers
2. Find the broker to remove
3. Click "Remove" or trash icon
4. Confirm removal
5. Credentials are securely deleted

Note: Remove broker connection in Agencio doesn't affect your broker account.

---

## Broker Comparison Summary

| Feature | Alpaca | IBKR | Binance | Pepperstone | Schwab |
|---------|--------|------|---------|-------------|--------|
| US Stocks | ✓ | ✓ | - | - | ✓ |
| Crypto | - | - | ✓ | CFDs | - |
| Forex | - | ✓ | - | ✓ | - |
| Options | - | ✓ | - | - | ✓ |
| Paper Trading | ✓ | ✓ | ✓ | ✓ | - |
| Setup | Easy | Medium | Easy | Easy | Easy |
| Auth Type | API Key | API | API Key | OAuth | OAuth |
| Re-auth | Never | Never | Never | Never | Weekly |
| Commission | Free | Low | Low | Low | Free |

---

## Getting Help

### Connection Issues
1. Check troubleshooting section above
2. Verify credentials at broker's site
3. Contact broker for API issues
4. Contact our support for platform issues

### Broker-Specific Help
- Each broker has documentation
- Check their API/developer docs
- Their support can help with credentials

---

*Broker availability may vary by region. Check broker websites for current offerings.*