# Broker Setup Guide

Connect your brokerage account to enable paper trading and live execution.

---

## Overview

Agencio Predict supports multiple brokers for different asset classes:

| Broker | Asset Classes | Paper Trading | Live Trading |
|--------|---------------|---------------|--------------|
| **Alpaca** | US Stocks, ETFs | Yes | Yes |
| **Interactive Brokers** | Stocks, ETFs, Options, Futures | Yes | Yes |
| **Binance** | Crypto (Spot & Perpetuals) | Yes | Yes |
| **Pepperstone** | Forex, CFDs | Yes | Yes |
| **Charles Schwab** | US Stocks, ETFs, Options | No | Yes |

**Recommended for beginners**: Start with Alpaca — it's free to set up and has excellent paper trading.

---

## Execution Modes

Before connecting a broker, understand the three modes:

### Mock Mode (Default)
- Virtual $100,000 in simulated funds
- Instant "fills" at current market price
- No broker connection required
- Perfect for learning and testing ideas

### Paper Mode
- Real market data with simulated execution
- Realistic slippage and fill simulation
- Requires broker paper trading account
- Track real-world performance without risk

### Live Mode
- Real trades with real money
- Connected to your funded brokerage account
- Full platform safety features active
- Requires: MFA + broker connection + approval

---

## Setting Up Alpaca (Recommended)

### Step 1: Create an Alpaca Account
1. Visit Alpaca's website and sign up
2. Complete identity verification (for live trading)
3. You'll have access to both paper and live environments

### Step 2: Get Your API Keys

**For Paper Trading**:
1. Log into your Alpaca paper trading dashboard
2. Navigate to API Keys
3. Generate a new key pair
4. Copy both the **API Key ID** and **Secret Key**

**For Live Trading**:
1. Log into your Alpaca live (brokerage) dashboard
2. Navigate to API Keys
3. Generate a new key pair
4. Copy both keys

> **Important**: Paper and live keys are different. Paper keys start with `PK`, live keys start with `AK`.

### Step 3: Connect in Agencio

1. Go to **Settings > Brokers**
2. Click **Add Broker**
3. Select **Alpaca**
4. Choose mode: **Paper** or **Live**
5. Enter your API Key ID
6. Enter your Secret Key
7. Click **Test Connection**
8. If successful, click **Save**

### Step 4: Test Your Connection
After saving:
1. Click **Test** next to your broker
2. Verify account balance appears
3. Check that positions load correctly

---

## Setting Up Interactive Brokers

### Prerequisites
- IBKR Pro or IBKR Lite account
- API access enabled in account settings
- TWS (Trader Workstation) or IB Gateway running

### Get API Credentials
1. Log into IBKR Account Management
2. Go to **Settings > API**
3. Enable API access
4. Note your client ID and port settings

### Connect in Agencio
1. Go to **Settings > Brokers**
2. Click **Add Broker**
3. Select **Interactive Brokers**
4. Enter your credentials
5. Test and save

---

## Setting Up Binance

### For Spot Trading
1. Log into Binance
2. Go to **API Management**
3. Create a new API key
4. Enable **Spot Trading** permission
5. Add IP restrictions (recommended)
6. Copy API Key and Secret

### For Futures/Perpetuals
1. Enable **Futures Trading** in your Binance account
2. Create API key with futures permissions
3. Note: Higher risk, separate balance

### Connect in Agencio
1. Go to **Settings > Brokers**
2. Select **Binance**
3. Enter API Key and Secret
4. Select trading type (Spot or Futures)
5. Test and save

---

## Setting Up Pepperstone

Pepperstone uses OAuth for secure connection — no API keys to manage.

### Steps
1. Go to **Settings > Brokers**
2. Click **Add Broker**
3. Select **Pepperstone**
4. Click **Connect with Pepperstone**
5. Log into your Pepperstone account
6. Authorize Agencio Predict
7. You'll be redirected back automatically

### Supported Markets
- 70+ forex pairs
- Indices
- Commodities
- Crypto CFDs

---

## Setting Up Charles Schwab

Schwab also uses OAuth for connection.

### Important Note
Schwab tokens expire after **7 days**. You'll need to re-authorize weekly for continuous access.

### Steps
1. Go to **Settings > Brokers**
2. Select **Charles Schwab**
3. Click **Connect with Schwab**
4. Log into your Schwab account
5. Authorize the connection
6. Set a calendar reminder to re-authorize weekly

---

## Upgrading to Live Trading

### Requirements
Before going live, you must:

| Requirement | How to Complete |
|-------------|-----------------|
| Enable MFA | Settings > Security > Enable MFA |
| Connect broker (live) | Follow steps above with live credentials |
| Paper trading history | 30+ days and 50+ trades in paper mode |
| Strategy approval | Meet performance thresholds |

### Request Live Access
1. Go to **Settings > Trading**
2. Click **Request Live Access**
3. Review and acknowledge risk disclosures
4. Submit request
5. Approval is usually automatic if requirements are met

---

## Security

### How We Protect Your Keys
- All API keys are encrypted using AES-256-GCM
- Keys are never displayed after saving (only last 4 characters)
- Credentials are stored separately from other data
- We never have access to your brokerage password

### Best Practices
- **Use paper keys first** — Test everything before going live
- **Enable IP restrictions** — If your broker supports it
- **Use separate API keys** — Don't reuse keys across platforms
- **Rotate periodically** — Generate new keys every few months
- **Monitor activity** — Check your broker's API logs

### Platform Safeguards
| Safeguard | Description |
|-----------|-------------|
| Kill Switch | Instantly stop all trading platform-wide |
| Order Limits | Maximum order size enforced |
| Daily Loss Cap | Trading pauses if daily loss threshold hit |
| Position Limits | Maximum exposure per symbol |

---

## Troubleshooting

### Connection Failed
**Possible causes**:
- Incorrect API key or secret
- Key doesn't have required permissions
- IP not whitelisted (if using restrictions)
- Broker API is temporarily down

**Solutions**:
1. Double-check key and secret (copy-paste fresh)
2. Verify permissions in broker dashboard
3. Check your IP whitelist settings
4. Try again in a few minutes

### "Invalid Key Type" Error
- Paper keys won't work for live mode (and vice versa)
- Alpaca: Paper keys start with `PK`, live with `AK`
- Make sure you're using the right key for the right mode

### Orders Not Executing
- Check broker account has sufficient funds
- Verify market is open for that asset
- Check for any broker-side restrictions
- Review order in broker's dashboard

### Position Mismatch
- Positions may take a few seconds to sync
- Click **Refresh** to force update
- If persistent, disconnect and reconnect broker

---

## Broker Comparison

| Feature | Alpaca | IBKR | Binance | Pepperstone | Schwab |
|---------|--------|------|---------|-------------|--------|
| Setup difficulty | Easy | Medium | Easy | Easy | Easy |
| Paper trading | Yes | Yes | Yes | Yes | No |
| Stocks | Yes | Yes | No | No | Yes |
| Crypto | No | No | Yes | CFDs | No |
| Forex | No | Yes | No | Yes | No |
| Commission | Free | Low | Low | Low | Free |
| Auth method | API Key | API Key | API Key | OAuth | OAuth |

---

## Next Steps

1. **Start with paper trading** — Get comfortable with the system
2. **Run strategies in paper mode** — Validate performance
3. **When ready**, upgrade to live with a small allocation
4. **Scale gradually** — Increase size as confidence grows

---

*Broker availability and features may vary by region. Check with your broker for specific terms and conditions.*