# Paper Trading API

The CuteMarkets Paper Trading API is a local simulator similar to the one Alpaca has. It accepts Alpaca-shaped order payloads, but it does not route orders to Alpaca and it does not require Alpaca credentials.

Use a Paper Trading API key for these endpoints:

```bash
Authorization: Bearer cm_your_paper_key
```

## AI Agent Quick Start

Use this flow when an agent needs to start paper trading from zero:

1. List accounts and pick one if it exists.
2. Create one if the list is empty.
3. Submit orders with a stable `client_order_id`.
4. Poll orders, positions, and portfolio history after every decision.

```bash
BASE_URL="https://api.cutemarkets.com/v1"
PAPER_KEY="cm_your_paper_key"

ACCOUNT_ID=$(
  curl -s "$BASE_URL/paper/accounts/" \
    -H "Authorization: Bearer $PAPER_KEY" |
  python -c 'import json,sys; rows=json.load(sys.stdin)["results"]; print(rows[0]["id"] if rows else "")'
)

if [ -z "$ACCOUNT_ID" ]; then
  ACCOUNT_ID=$(
    curl -s "$BASE_URL/paper/accounts/" \
      -X POST \
      -H "Authorization: Bearer $PAPER_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name":"agent-sandbox","initial_cash":"100000"}' |
    python -c 'import json,sys; print(json.load(sys.stdin)["account"]["id"])'
  )
fi

curl "$BASE_URL/paper/accounts/$ACCOUNT_ID/orders/" \
  -X POST \
  -H "Authorization: Bearer $PAPER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "AAPL",
    "qty": "1",
    "side": "buy",
    "type": "market",
    "time_in_force": "day",
    "client_order_id": "agent-aapl-001"
  }'
```

Recommended agent loop:

- Use one account per strategy or experiment.
- Never reuse a `client_order_id` inside the same account generation.
- Read `/orders/`, `/positions/`, and `/portfolio/history/` before making the next decision.
- Use `DELETE /orders/{order_id}/` to cancel any open `new`, `accepted`, or `partially_filled` order.
- Orders submitted while the regular market is closed stay `accepted` until the next regular session, so agents can cancel them before they are evaluated.
- Use `POST /reset/` only when intentionally starting a new run.

## Accounts

Users can keep up to 20 active paper accounts. Archived accounts do not count toward that limit.

```bash
curl https://api.cutemarkets.com/v1/paper/accounts/ \
  -H "Authorization: Bearer cm_your_paper_key"
```

Create an account:

```bash
curl https://api.cutemarkets.com/v1/paper/accounts/ \
  -X POST \
  -H "Authorization: Bearer cm_your_paper_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ORB Sandbox",
    "initial_cash": "100000"
  }'
```

Reset an account:

```bash
curl https://api.cutemarkets.com/v1/paper/accounts/{account_id}/reset/ \
  -X POST \
  -H "Authorization: Bearer cm_your_paper_key" \
  -H "Content-Type: application/json" \
  -d '{
    "confirm": true,
    "initial_cash": "100000",
    "reason": "new strategy run"
  }'
```

Resetting cancels open orders, clears current positions, starts a new account generation, and preserves prior orders, fills, ledger entries, and equity history for audit.

Rename an account:

```bash
curl https://api.cutemarkets.com/v1/paper/accounts/{account_id}/ \
  -X PATCH \
  -H "Authorization: Bearer cm_your_paper_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "agent-run-2026-05-16"}'
```

Delete an account from the active list:

```bash
curl https://api.cutemarkets.com/v1/paper/accounts/{account_id}/ \
  -X DELETE \
  -H "Authorization: Bearer cm_your_paper_key"
```

Delete archives the account. It is hidden from the default account list, but remains available in audit history through `?include_archived=true`.

## Orders

Submit an order:

```bash
curl https://api.cutemarkets.com/v1/paper/accounts/{account_id}/orders/ \
  -X POST \
  -H "Authorization: Bearer cm_your_paper_key" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "AAPL",
    "qty": "10",
    "side": "buy",
    "type": "market",
    "time_in_force": "day",
    "client_order_id": "strategy-aapl-001"
  }'
```

Submit a single-leg option order:

```bash
curl https://api.cutemarkets.com/v1/paper/accounts/{account_id}/orders/ \
  -X POST \
  -H "Authorization: Bearer cm_your_paper_key" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "O:SPY260620C00500000",
    "qty": "1",
    "side": "buy",
    "type": "limit",
    "limit_price": "4.25",
    "time_in_force": "day",
    "position_intent": "buy_to_open"
  }'
```

Look up an order by client id:

```bash
curl "https://api.cutemarkets.com/v1/paper/accounts/{account_id}/orders:by_client_order_id?client_order_id=strategy-aapl-001" \
  -H "Authorization: Bearer cm_your_paper_key"
```

Cancel an open order:

```bash
curl https://api.cutemarkets.com/v1/paper/accounts/{account_id}/orders/{order_id}/ \
  -X DELETE \
  -H "Authorization: Bearer cm_your_paper_key"
```

The dashboard uses the same endpoint. Open orders show a `Cancel` action in the Paper Trading orders table.

Supported v1 order behavior:

| Field | Supported |
|---|---|
| `symbol` | Stock tickers and `O:` option contract tickers |
| `qty` | Decimal stock quantities; whole option contract quantities |
| `side` | `buy`, `sell` |
| `type` | `market`, `limit` |
| `time_in_force` | Stocks: `day`, `gtc`; options: `day` |
| `position_intent` | Options: `buy_to_open`, `sell_to_close` |
| `client_order_id` | Optional, unique per account generation |

Rejected in v1: stock short openings, naked option sells, multileg orders, option fractional quantities, notional orders, stop orders, trailing-stop orders, and extended-hours option orders.

## Realism Model

The simulator uses conservative quote-aware fills:

- Stock buys fill at ask and sells fill at bid.
- Option buys fill at ask and sells fill at bid, with a 100 multiplier.
- Limit orders fill only when marketable against the latest quote.
- Missing, crossed, stale, or invalid quotes prevent fills.
- Wide option spreads are rejected.
- Opening trades must fit available paper cash.
- Regular market hours are required for v1 fills. Orders submitted while the market is closed remain accepted and are evaluated during the next regular session unless canceled first.

## Performance

Portfolio history is available as an equity time series:

```bash
curl https://api.cutemarkets.com/v1/paper/accounts/{account_id}/portfolio/history/ \
  -H "Authorization: Bearer cm_your_paper_key"
```

The dashboard uses the same data for equity, cash, market value, realized P&L, unrealized P&L, drawdown, and recent fill charts.