# Agents.md

This page provides a condensed, easily copyable reference of our API endpoints for AI agents and LLMs. Copy all the text below and paste it directly into your AI assistant or agent framework to give it full context of the CuteMarkets API!

## Global Context
- **Base URL:** `https://api.cutemarkets.com/v1/`
- **Authentication:** Pass the API key in the generic Authorization header.
  - *Example:* `Authorization: Bearer YOUR_API_KEY`
- **Response Format:** JSON
- **OpenAPI:** `https://cutemarkets.com/openapi.json`

## Endpoints

### 1. Options Market Data
Our core options data allows you to pull entire chains or query specific contracts.

- **Option Chain** (`GET https://api.cutemarkets.com/v1/options/chain/{ticker}/`)
  - **Purpose:** Get the full options chain for a given underlying asset.
  - **Example:** `GET https://api.cutemarkets.com/v1/options/chain/NFLX/?limit=10`
  - [Read More](https://cutemarkets.com/docs/option-chain)

- **Contract Snapshot** (`GET https://api.cutemarkets.com/v1/options/snapshot/{contract_symbol}/`)
  - **Purpose:** Real-time snapshot of an options contract (prices, greeks, implied volatility).
  - [Read More](https://cutemarkets.com/docs/option-contract-snapshot)

- **Contracts List** (`GET https://api.cutemarkets.com/v1/options/contracts/`)
  - **Purpose:** Search and filter active options contracts. Use query params like `underlying_ticker`.
  - [Read More](https://cutemarkets.com/docs/contracts)

- **Trades** (`GET https://api.cutemarkets.com/v1/options/trades/{contract_symbol}/`)
  - **Purpose:** Fetch historical or real-time trades.
  - [Read More](https://cutemarkets.com/docs/trades)

- **Quotes** (`GET https://api.cutemarkets.com/v1/options/quotes/{contract_symbol}/`)
  - **Purpose:** Fetch historical or real-time NBBO quotes.
  - [Read More](https://cutemarkets.com/docs/quotes)

- **Aggregates (OHLC)** (`GET https://api.cutemarkets.com/v1/options/aggs/{ticker}/`)
  - **Purpose:** Get minute, hour, or daily bars for options or the underlying ticker.
  - [Read More](https://cutemarkets.com/docs/aggregates)

### 2. Technical Indicators
Fetch calculated technical indicators for any underlying asset.

- **SMA:** `GET https://api.cutemarkets.com/v1/indicators/sma/{ticker}/`
  - [Read More](https://cutemarkets.com/docs/indicators-sma)
- **EMA:** `GET https://api.cutemarkets.com/v1/indicators/ema/{ticker}/`
  - [Read More](https://cutemarkets.com/docs/indicators-ema)
- **MACD:** `GET https://api.cutemarkets.com/v1/indicators/macd/{ticker}/`
  - [Read More](https://cutemarkets.com/docs/indicators-macd)
- **RSI:** `GET https://api.cutemarkets.com/v1/indicators/rsi/{ticker}/`
  - [Read More](https://cutemarkets.com/docs/indicators-rsi)

### 3. Reference Data
Helper endpoints for lookup tasks.

- **Ticker Search** (`GET https://api.cutemarkets.com/v1/reference/tickers/`)
  - **Purpose:** General ticker lookup for equities and indices.
  - [Read More](https://cutemarkets.com/docs/ticker-search)
- **Expirations** (`GET https://api.cutemarkets.com/v1/reference/expirations/{ticker}/`)
  - **Purpose:** Available expiration dates for an underlying ticker.
  - [Read More](https://cutemarkets.com/docs/expirations)

### 4. Paper Trading Quick Start
Use a Paper Trading API key. Paper trading is local to CuteMarkets; orders are Alpaca-shaped but are not routed to Alpaca.

1. List or create an account:

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

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

2. Submit a stock order:

```bash
curl https://api.cutemarkets.com/v1/paper/accounts/{account_id}/orders/ \
  -X POST \
  -H "Authorization: Bearer YOUR_PAPER_API_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"
  }'
```

3. Submit a single-leg option order:

```bash
curl https://api.cutemarkets.com/v1/paper/accounts/{account_id}/orders/ \
  -X POST \
  -H "Authorization: Bearer YOUR_PAPER_API_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",
    "client_order_id": "agent-spy-call-001"
  }'
```

4. Poll state after each decision:

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

curl https://api.cutemarkets.com/v1/paper/accounts/{account_id}/positions/ \
  -H "Authorization: Bearer YOUR_PAPER_API_KEY"

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

5. Cancel an open order:

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

Agent rules: use stable `client_order_id` values, do not reuse them within an account generation, inspect positions before sells, cancel open `new`, `accepted`, or `partially_filled` orders with `DELETE`, and reset only when intentionally starting a new run. Closed-market orders stay `accepted` until the next regular market session unless canceled first.

> **General Agent Tip:** When paginating through requests, always look out for a `next` URL in the JSON response payload. See [Error Handling](https://cutemarkets.com/docs/errors) for information on 4XX errors.