trading212-api

What this skill does

# Trading 212 API

> **Note:** The Trading 212 API is currently in **beta** and under active development. Some endpoints or behaviors may change.

## Quick Reference

### Environments

| Environment | Base URL                             | Purpose                                 |
| ----------- | ------------------------------------ | --------------------------------------- |
| Demo        | `https://demo.trading212.com/api/v0` | Paper trading - test without real funds |
| Live        | `https://live.trading212.com/api/v0` | Real money trading                      |

### Order Quantity Convention

- **Positive quantity = BUY** (e.g., `10` buys 10 shares)
- **Negative quantity = SELL** (e.g., `-10` sells 10 shares)

### Account Types

Only **Invest** and **Stocks ISA** accounts are supported.

### Instrument Identifiers

Trading 212 uses custom tickers as unique identifiers for instruments.
Always search for the Trading 212 ticker before making instrument requests.

---

## Authentication

HTTP Basic Auth with API Key (username) and API Secret (password).

### Check Existing Setup First

Before guiding the user through authentication setup, check if credentials are already configured:

**Semantic rule:** Credentials are configured when **at least one complete set** is present: a complete set is key + secret for the same account (e.g. `T212_API_KEY` + `T212_API_SECRET`, or `T212_API_KEY_INVEST` + `T212_API_SECRET_INVEST`, or `T212_API_KEY_STOCKS_ISA` + `T212_API_SECRET_STOCKS_ISA`). You do not need all four account-specific vars; having only the Invest pair or only the Stocks ISA pair is enough. Check for any combination that gives at least one usable key+secret pair.

```bash
# Example: configured if any complete credential set exists
if [ -n "$T212_AUTH_HEADER" ] && [ -n "$T212_BASE_URL" ]; then
  echo "Configured (derived vars)"
elif [ -n "$T212_API_KEY" ] && [ -n "$T212_API_SECRET" ]; then
  echo "Configured (single account)"
elif [ -n "$T212_API_KEY_INVEST" ] && [ -n "$T212_API_SECRET_INVEST" ]; then
  echo "Configured (Invest); Stocks ISA also if T212_API_KEY_STOCKS_ISA and T212_API_SECRET_STOCKS_ISA are set"
elif [ -n "$T212_API_KEY_STOCKS_ISA" ] && [ -n "$T212_API_SECRET_STOCKS_ISA" ]; then
  echo "Configured (Stocks ISA); Invest also if T212_API_KEY_INVEST and T212_API_SECRET_INVEST are set"
else
  echo "No complete credential set found"
fi
```

If any complete set is present, skip the full setup and proceed with API calls; when making requests, use the resolution order in "Making Requests" below (pick the pair that matches the user's account context when multiple sets exist). Do not ask the user to run derivation one-liners or merge keys into a header. Only guide users through the full setup process below when no complete credential set exists.

> **Important:** Before making any API calls, always ask the user which environment they want to use: **LIVE** (real money) or **DEMO** (paper trading). Do not assume the environment.

### API Keys Are Environment-Specific

**API keys are tied to a specific environment and cannot be used across environments.**

| API Key Created In | Works With            | Does NOT Work With    |
| ------------------ | --------------------- | --------------------- |
| LIVE account       | `live.trading212.com` | `demo.trading212.com` |
| DEMO account       | `demo.trading212.com` | `live.trading212.com` |

If you get a 401 error, verify that:

1. You're using the correct API key for the target environment
2. The API key was generated in the same environment (LIVE or DEMO) you're trying to access

### Get Credentials

1. **Decide which environment to use** - LIVE (real money) or DEMO (paper trading)
2. Open Trading 212 app (mobile or web)
3. **Switch to the correct account** - Make sure you're in LIVE or DEMO mode matching your target environment
4. Navigate to **Settings** > **API**
5. Generate a new API key pair - you'll receive:
   - **API Key (ID)** (e.g., `35839398ZFVKUxpHzPiVsxKdOtZdaDJSrvyPF`)
   - **API Secret** (e.g., `7MOzYJlVJgxoPjdZJCEH3fO9ee7A0NzLylFFD4-3tlo`)
6. **Store the credentials separately** for each environment if you use both

### Building the Auth Header

Combine your API Key (ID) and Secret with a colon, base64 encode, and prefix with `Basic ` for the Authorization header.

**Optional:** To precompute the header from key/secret, you can set:

```bash
export T212_AUTH_HEADER="Basic $(echo -n "$T212_API_KEY:$T212_API_SECRET" | base64)"
```

Otherwise, the agent builds the header from `T212_API_KEY` and `T212_API_SECRET` when making requests.

**Manual (placeholders):**

```bash
# Format: T212_AUTH_HEADER = "Basic " + base64(API_KEY_ID:API_SECRET)
export T212_AUTH_HEADER="Basic $(echo -n "<YOUR_API_KEY_ID>:<YOUR_API_SECRET>" | base64)"

# Example with sample credentials:
export T212_AUTH_HEADER="Basic $(echo -n "35839398ZFVKUxpHzPiVsxKdOtZdaDJSrvyPF:7MOzYJlVJgxoPjdZJCEH3fO9ee7A0NzLylFFD4-3tlo" | base64)"
```

### Making Requests

When making API calls, use the first option that applies (semantically: pick the credential set that matches the user's account, or the only set present):

- **If `T212_AUTH_HEADER` and `T212_BASE_URL` are set:** use them in requests.
- **Else if `T212_API_KEY` and `T212_API_SECRET` are set:** use this pair (single account). Build header as `Basic $(echo -n "$T212_API_KEY:$T212_API_SECRET" | base64)` and base URL as `https://${T212_ENV:-live}.trading212.com`. Do not guide the user to derive or merge; you do it.
- **Else if both account-specific pairs are set** (`T212_API_KEY_INVEST`/`T212_API_SECRET_INVEST` and `T212_API_KEY_STOCKS_ISA`/`T212_API_SECRET_STOCKS_ISA`): the user must clearly specify which account to target (Invest or Stocks ISA), unless they ask for information for **all accounts**. Use the Invest pair when the user refers to Invest, and the Stocks ISA pair when the user refers to ISA/Stocks ISA. **If the user wants information for all accounts, make multiple API calls—one per account** (Invest and Stocks ISA)—and present or aggregate the results for both. **If it is not clear from context which account to use (and they did not ask for all accounts), ask for confirmation before making API calls** (e.g. "Which account should I use — Invest or Stocks ISA?"). Do not assume. Build the header from the chosen key/secret and base URL as `https://${T212_ENV:-live}.trading212.com`.
- **Else if only the Invest pair is set** (`T212_API_KEY_INVEST` and `T212_API_SECRET_INVEST`): use this pair for requests; if the user asks about Stocks ISA, only the Invest account is configured.
- **Else if only the Stocks ISA pair is set** (`T212_API_KEY_STOCKS_ISA` and `T212_API_SECRET_STOCKS_ISA`): use this pair for requests; if the user asks about Invest, only the Stocks ISA account is configured.

Use the `T212_AUTH_HEADER` value in the Authorization header when it is set:

```bash
# When T212_AUTH_HEADER and T212_BASE_URL are set:
curl -H "Authorization: $T212_AUTH_HEADER" \
  "${T212_BASE_URL}/api/v0/equity/account/summary"
```

When only primary vars are set, use the inline form in the curl:

```bash
# When only T212_API_KEY, T212_API_SECRET, T212_ENV are set:
curl -H "Authorization: Basic $(echo -n "$T212_API_KEY:$T212_API_SECRET" | base64)" \
  "https://${T212_ENV:-live}.trading212.com/api/v0/equity/account/summary"
```

> **Warning:** `T212_AUTH_HEADER` must be the full header value including the `Basic ` prefix.
>
> ```bash
> # WRONG - raw base64 without "Basic " prefix
> curl -H "Authorization: <base64-only>" ...  # This will NOT work!
>
> # CORRECT - use T212_AUTH_HEADER (contains "Basic <base64>")
> curl -H "Authorization: $T212_AUTH_HEADER" ...  # This works
> ```

### Environment Variables

**Single account vs all accounts:** API keys are for a **single account**. One key/secret pair (`T212_API_KEY` + `T212_API_SECRET`) = one account (Invest or Stocks ISA). To use **all accounts** (Invest and Stocks ISA), the user must set **two sets** of key/secret: `T212_API_KEY_I