# Prices

Retrieve stock prices for any supported stock symbol.

## Making Requests

Use the `prices()` method on the `stocks` resource to fetch stock prices. The method returns a [`MarketDataPromise`](https://www.marketdata.app/docs/sdk/js/client#MarketDataPromise) that resolves to decoded records by default, or rejects with a `MarketDataClientError` subclass on failure. The output format is controlled by the `outputFormat` parameter (or `MARKETDATA_OUTPUT_FORMAT` env var):

| Output Format          | Result Payload                        | Description                                                           |
|------------------------|---------------------------------------|-----------------------------------------------------------------------|
| **internal** (default) | `StockPrice[]` or `StockPriceHuman[]` | Array of decoded price records, one per symbol.                       |
| **json**               | Raw JSON object                       | The compressed, array-keyed response object as returned by the API.   |
| **csv**                | `Blob`                                | CSV payload. Use `.save(filename)` on the result to write it to disk. |

<a name="prices"></a>
## prices

```typescript
// Positional form
prices<P>(
  symbols: string | string[],
  params?: P,
): MarketDataPromise<StockPrice[] | StockPriceHuman[]>

// Object form
prices<P>(
  params: P & { symbols: string | string[] },
): MarketDataPromise<StockPrice[] | StockPriceHuman[]>
```

Fetches stock prices for one or more symbols. The return type is narrowed automatically:

- If `human: true` (or `useHumanReadable: true`) → payload is `StockPriceHuman[]`
- If `outputFormat: "csv"` → payload is `Blob`
- Otherwise → payload is `StockPrice[]`

#### Parameters

- `symbols` (string | string[])

  A single symbol string or an array of symbol strings for which to fetch prices.

- [`outputFormat`](https://www.marketdata.app/docs/sdk/js/settings#output-format) (optional)

  The format of the returned data. See [Settings](https://www.marketdata.app/docs/sdk/js/settings#output-format) for details. Also accepts the alias `format`.

- [`dateFormat`](https://www.marketdata.app/docs/sdk/js/settings#date-format) (optional)

  The date format to use in the response. Also accepts the alias `dateformat`. See [Settings](https://www.marketdata.app/docs/sdk/js/settings#date-format) for details.

- [`columns`](https://www.marketdata.app/docs/sdk/js/settings#columns) (optional)

  Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/js/settings#columns) for details.

- [`addHeaders`](https://www.marketdata.app/docs/sdk/js/settings#headers) (optional)

  Whether to include headers in CSV output. Also accepts the alias `headers`. See [Settings](https://www.marketdata.app/docs/sdk/js/settings#headers) for details.

- [`useHumanReadable`](https://www.marketdata.app/docs/sdk/js/settings#human-readable) (optional)

  Whether to use human-readable field names. Also accepts the alias `human`. See [Settings](https://www.marketdata.app/docs/sdk/js/settings#human-readable) for details.

- [`mode`](https://www.marketdata.app/docs/sdk/js/settings#data-mode) (optional)

  The data mode to use (`"live"`, `"cached"`, `"delayed"`). See [Settings](https://www.marketdata.app/docs/sdk/js/settings#data-mode) for details.

#### Returns

- [`MarketDataPromise<StockPrice[] | StockPriceHuman[] | Blob>`](https://www.marketdata.app/docs/sdk/js/client#MarketDataPromise)

  A Promise that resolves to the prices data in the requested format, or rejects with a `MarketDataClientError` subclass on failure. Handle with `await` + `try/catch`.

### Single Symbol

```typescript
import { MarketDataClient } from "@marketdata/sdk";

const client = new MarketDataClient();

try {
  const prices = await client.stocks.prices("AAPL");
  console.log(prices[0].mid);
} catch (error) {
  console.error(error);
}
```

### Multiple Symbols

```typescript
import { MarketDataClient } from "@marketdata/sdk";

const client = new MarketDataClient();

try {
  const prices = await client.stocks.prices(["AAPL", "MSFT", "GOOGL"]);
  for (const p of prices) {
    console.log(`${p.symbol}: ${p.mid}`);
  }
} catch (error) {
  console.error(error);
}
```

### Human Readable

```typescript
import { MarketDataClient } from "@marketdata/sdk";

const client = new MarketDataClient();

try {
  const prices = await client.stocks.prices("AAPL", { human: true });
  for (const p of prices) {
    console.log(`${p.Symbol}: mid=${p.Mid}, change=${p.Change_Percent}`);
  }
} catch (error) {
  console.error(error);
}
```

### Raw JSON

```typescript
import { MarketDataClient, OutputFormat } from "@marketdata/sdk";

const client = new MarketDataClient();

try {
  const json = await client.stocks.prices(["AAPL", "MSFT"], {
    outputFormat: OutputFormat.JSON,
  });
  console.log(json);
} catch (error) {
  console.error(error);
}
```

### CSV

```typescript
import { MarketDataClient, OutputFormat } from "@marketdata/sdk";

const client = new MarketDataClient();

const csv = await client.stocks.prices(["AAPL", "MSFT"], {
  outputFormat: OutputFormat.CSV,
});

// Save the Blob to disk (Node.js)
const filename = await csv.save("prices.csv");
console.log(`CSV saved to: ${filename}`);
```

<a name="StockPrice"></a>
## StockPrice

```typescript
interface StockPrice {
  s?: string;
  symbol: string;
  mid: number;
  change: number;
  changepct: number;
  updated: number;
}
```

`StockPrice` represents a single stock price, with short machine-readable field names.

#### Properties

- `s` (string, optional): Status indicator (`"ok"` for successful responses).
- `symbol` (string): The stock symbol.
- `mid` (number): The mid price calculated between the ask and bid.
- `change` (number): The price change.
- `changepct` (number): The fractional price change (e.g. `0.0124` for +1.24%).
- `updated` (number): Unix timestamp when the price was last updated.

<a name="StockPriceHuman"></a>
## StockPriceHuman

```typescript
interface StockPriceHuman {
  s?: string;
  Symbol: string;
  Mid: number;
  Change_Price: number;
  Change_Percent: number;
  Date: number;
}
```

`StockPriceHuman` represents a stock price in human-readable format with capitalized, snake-case field names. Returned when `human: true` (or `useHumanReadable: true`) is set.

#### Properties

- `Symbol` (string): The stock symbol.
- `Mid` (number): The mid price.
- `Change_Price` (number): The price change.
- `Change_Percent` (number): The percent change.
- `Date` (number): Unix timestamp of the update.