---
title: "Puts an instrument on this portfolio's watchlist without recording any position. Pass `optionContract` with the OCC symbol to watch an option, or omit it to watch the stock. The instrument is verified against the live reference data before anything is stored, and the priced portfolio then lists it in `watching` with a mark and no economics. Watching an instrument the portfolio already watches answers 400; buying an instrument you watch folds the watch row into the held position rather than showing two rows."
method: POST
path: "/v1/portfolios/{id}/watches"
tags: ["Portfolios"]
---

# Puts an instrument on this portfolio's watchlist without recording any position. Pass \`optionContract\` with the OCC symbol to watch an option, or omit it to watch the stock. The instrument is verified against the live reference data before anything is stored, and the priced portfolio then lists it in \`watching\` with a mark and no economics. Watching an instrument the portfolio already watches answers 400; buying an instrument you watch folds the watch row into the held position rather than showing two rows.

`POST /v1/portfolios/{id}/watches`

## Request

- Base URL: `https://api.equibles.com`
- URL: `https://api.equibles.com/v1/portfolios/{id}/watches`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/equibles/apis/equibles-api/docs/v1/portfolios/:id/watches/post.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `id` string, uuid, required

## Request body

- AddWatchRequest
  - `ticker` string, required: Stock ticker, or MIC:TICKER for a listing on another exchange (e.g. XPAR:AIR). For an option, the ticker of the UNDERLYING, as MIC:TICKER for a Canadian contract (e.g. XTSE:RY).
  - `optionContract` string, nullable: Optional OCC option symbol, e.g. O:AAPL260116C00250000. When present the contract is verified against the live options data before anything is stored. Omit it to watch the stock.

## Response `201`

Created

- PortfolioWatchResponse: The answer to watching an instrument: which portfolio it landed in and the watch row itself. A write answers with identity only — the mark fields are filled by the priced GET.
  - `portfolioId` string, uuid
  - `portfolioName` string, nullable
  - `watch` PortfolioWatchDto: An instrument on the portfolio's watchlist that the account does NOT hold. A watch row carries a mark and nothing else — deliberately no quantity, cost or value fields, because there is no position to value and a zero would read as a total loss. It is never part of the portfolio's totals.
    - `id` string, uuid: The watch entry's id — what DELETE /v1/portfolios/{id}/watches/{watchId} takes.
    - `instrumentKind` string, nullable: "Stock" or "Option".
    - `ticker` string, nullable: The listed ticker: the stock itself, or the option's underlying.
    - `exchange` string, nullable: The exchange's market identifier code (MIC, e.g. XPAR) for a listing outside the U.S.; null for a U.S. listing. Together with ticker it names the listing, e.g. XPAR:AIR.
    - `name` string, nullable
    - `occTicker` string, nullable: The OCC contract symbol; null on a stock row.
    - `expirationDate` string, date, nullable
    - `strikePrice` number, double, nullable
    - `contractType` string, nullable: "Call" or "Put"; null on a stock row.
    - `sharesPerContract` integer, nullable
    - `currency` string, nullable: ISO 4217 code the mark is in: the listing's currency. Null when the listing states none, and on a row returned by a write, which carries no mark.
    - `markPerUnit` number, double, nullable: Price per share of the underlying. Null when this pass could not price it.
    - `markSource` string, nullable: Where the mark came from; null when unpriced.
    - `markAsOf` string, date, nullable: The trading session the mark belongs to. Null when the source did not date it.
    - `markUnavailableReason` string, nullable: Why there is no mark, when markSource is null.
    - `expired` boolean: True once a watched contract's expiration has passed.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found

---

[API](https://skmtc.dev/equibles/apis/equibles-api.md) - [All operations](https://skmtc.dev/equibles/apis/equibles-api/llms.txt) - [OpenAPI document](https://skmtc.dev/equibles/apis/equibles-api/revisions/666e06778588?raw)