npm package: @openpets/trading-212
Description: Trading 212 API integration for managing equity orders, positions, dividends, and account information. Supports both paper trading (demo) and live trading environments.
Latest version: 1.0.3

# Trading 212 Plugin

Commission-free stock and ETF trading API integration for OpenPets.

## Features

- **Account Management** - View account summary, cash balances, and investment metrics
- **Portfolio Tracking** - Monitor all open positions with P/L information
- **Order Management** - Place Market, Limit, Stop, and Stop-Limit orders
- **Instrument Discovery** - Browse available stocks, ETFs, and other instruments
- **History & Reporting** - Access dividends, transactions, and generate CSV reports

## Quick Start

### 1. Get Your API Credentials

Generate your API keys from within the Trading 212 app:
- Open Trading 212 app → Settings → API
- Create a new API key pair
- [Detailed instructions](https://helpcentre.trading212.com/hc/en-us/articles/14584770928157-Trading-212-API-key)

### 2. Configure Environment Variables

```bash
cp .env.example .env
```

Edit `.env` and add your credentials:

```bash
TRADING_212_API_KEY=your_api_key_here
TRADING_212_API_SECRET=your_api_secret_here

# Optional: Use 'live' for real money (default: 'demo')
TRADING_212_ENVIRONMENT=demo
```

### 3. Test Connection

```bash
opencode run "test trading 212 connection"
```

## Available Tools

### Core Tools (Always Loaded)

| Tool | Description |
|------|-------------|
| `trading-212-test-connection` | Test API connection and configuration |
| `trading-212-get-account-summary` | Get account cash and investment summary |
| `trading-212-get-positions` | Fetch all open positions |
| `trading-212-get-pending-orders` | List all pending orders |
| `trading-212-get-order-by-id` | Get a specific order by ID |
| `trading-212-cancel-order` | Cancel a pending order |
| `trading-212-place-market-order` | Place a market order |
| `trading-212-place-limit-order` | Place a limit order (demo only) |
| `trading-212-place-stop-order` | Place a stop order (demo only) |
| `trading-212-place-stop-limit-order` | Place a stop-limit order (demo only) |
| `trading-212-get-instruments` | Get all available instruments |
| `trading-212-get-exchanges` | Get exchange metadata and schedules |

### Historical Events Tools (Enable with env var)

Enable with: `TRADING_212_LOAD_HISTORICAL_EVENTS_TOOLS=true`

| Tool | Description |
|------|-------------|
| `trading-212-get-dividends` | Get dividend payment history |
| `trading-212-get-historical-orders` | Get historical order data |
| `trading-212-get-transactions` | Get account transactions |
| `trading-212-get-reports` | List generated CSV reports |
| `trading-212-request-report` | Request a new CSV report |

## Example Usage

### Check Account Status

```bash
opencode run "get my trading 212 account summary"
```

### View Portfolio

```bash
opencode run "show all my open positions"
```

### Place an Order

```bash
# Buy 10 shares of Apple
opencode run "buy 10 shares of AAPL_US_EQ using market order"

# Sell 5 shares
opencode run "sell 5 shares of MSFT_US_EQ using market order"
```

**Note:** Use positive quantity for buy, negative for sell.

### Find Instruments

```bash
opencode run "get all available trading instruments"
```

## API Environments

| Environment | Base URL | Description |
|-------------|----------|-------------|
| `demo` | https://demo.trading212.com | Paper trading (safe testing) |
| `live` | https://live.trading212.com | Real money trading |

**Important:** Start with `demo` environment to test your integration before using real money.

## Limitations

- **Account Types:** Only Invest and Stocks ISA accounts are supported (no CFD)
- **Live Order Types:** Only Market orders are supported in live environment
- **Currency:** Orders execute in the primary account currency only
- **Multi-currency:** Not supported via API

## Rate Limits

| Endpoint | Limit |
|----------|-------|
| Account Summary | 1 req / 5s |
| Positions | 1 req / 1s |
| Orders (list) | 1 req / 5s |
| Orders (place) | 50 req / 1min |
| Orders (cancel) | 50 req / 1min |
| Instruments | 1 req / 50s |
| Exchanges | 1 req / 30s |
| History endpoints | 6 req / 1min |

## Read-Only Mode

Enable read-only mode to prevent accidental trades:

```bash
pets read-only trading-212 on
```

This disables all write operations (place order, cancel order, request report).

## Troubleshooting

### "Authentication failed"

- Verify your API key and secret are correct
- Check that your API key has the required scopes
- Ensure you're using the correct environment (demo vs live)

### "Rate limited"

- Check response headers for `x-ratelimit-reset`
- Wait until the reset time before retrying
- Consider caching instrument data (refreshes every 10 minutes)

### "Order not supported"

- In live environment, only Market orders are supported
- Limit, Stop, and Stop-Limit orders only work in demo

## Links

- [Trading 212 API Documentation](https://docs.trading212.com/)
- [API Terms](https://www.trading212.com/legal-documentation/API-Terms_EN.pdf)
- [Community Forum](https://community.trading212.com/)