# Real-Time Prices

Get real-time midpoint prices for one or more stocks. This endpoint returns real-time prices for stocks, using the [SmartMid](https://www.marketdata.app/smart-mid/) model.

## Endpoint
```
https://api.marketdata.app/v1/stocks/prices/{symbol}/
```
or
```
https://api.marketdata.app/v1/stocks/prices/?symbols={symbol1},{symbol2},...
```

### Method
```
GET
```
## Request Examples

### Single Symbol

### HTTP

**GET** [https://api.marketdata.app/v1/stocks/prices/AAPL/](https://api.marketdata.app/v1/stocks/prices/AAPL/)

### JavaScript

```js title="app.js"
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);
}
```

### TypeScript

```typescript title="app.ts"
import { MarketDataClient } from "@marketdata/sdk";
import type { StockPrice } from "@marketdata/sdk";

const client = new MarketDataClient();

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

### Python

```python title="app.py"
from marketdata import MarketDataClient

client = MarketDataClient()
prices = client.stocks.prices("AAPL")
print(prices)
```

### PHP

```php title="stockPrices.php"
use MarketDataApp\Client;

$client = new Client();
$prices = $client->stocks->prices("AAPL");

// Display formatted price
echo $prices;
```

### Java

```java title="StockPrices.java"
import com.marketdata.sdk.MarketDataClient;
import com.marketdata.sdk.stocks.StockPricesRequest;

try (MarketDataClient client = new MarketDataClient()) {
  client.stocks().prices(StockPricesRequest.of("AAPL")).values().forEach(System.out::println);
}
```

### Kotlin

```kotlin title="StockPrices.kt"
import com.marketdata.sdk.MarketDataClient
import com.marketdata.sdk.stocks.StockPricesRequest

MarketDataClient().use { client ->
    client.stocks().prices(StockPricesRequest.of("AAPL")).values().forEach(::println)
}
```

### C#

```csharp title="StockPrices.cs"
using MarketDataApp;

using var client = await MarketDataClient.CreateAsync();

foreach (var price in (await client.Stocks.GetPriceAsync("AAPL")).Values)
{
    Console.WriteLine(price);
}
```

### Multiple Symbols

### HTTP

**GET** [https://api.marketdata.app/v1/stocks/prices/?symbols=AAPL,META,MSFT](https://api.marketdata.app/v1/stocks/prices/?symbols=AAPL,META,MSFT)

### JavaScript

```js title="app.js"
import { MarketDataClient } from "@marketdata/sdk";

const client = new MarketDataClient();

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

### TypeScript

```typescript title="app.ts"
import { MarketDataClient } from "@marketdata/sdk";
import type { StockPrice } from "@marketdata/sdk";

const client = new MarketDataClient();

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

### Python

```python title="app.py"
from marketdata import MarketDataClient

client = MarketDataClient()
prices = client.stocks.prices(["AAPL", "META", "MSFT"])
print(prices)
```

### PHP

```php title="stockPrices.php"
use MarketDataApp\Client;

$client = new Client();
$prices = $client->stocks->prices(["AAPL", "META", "MSFT"]);

// Display formatted prices summary
echo $prices;
```

### Java

```java title="StockPrices.java"
import com.marketdata.sdk.MarketDataClient;
import com.marketdata.sdk.stocks.StockPricesRequest;

try (MarketDataClient client = new MarketDataClient()) {
  client.stocks().prices(StockPricesRequest.of("AAPL", "META", "MSFT")).values().forEach(System.out::println);
}
```

### Kotlin

```kotlin title="StockPrices.kt"
import com.marketdata.sdk.MarketDataClient
import com.marketdata.sdk.stocks.StockPricesRequest

MarketDataClient().use { client ->
    client.stocks().prices(StockPricesRequest.of("AAPL", "META", "MSFT")).values().forEach(::println)
}
```

### C#

```csharp title="StockPrices.cs"
using MarketDataApp;

using var client = await MarketDataClient.CreateAsync();

foreach (var price in (await client.Stocks.GetPricesAsync(["AAPL", "META", "MSFT"])).Values)
{
    Console.WriteLine(price);
}
```

## Response Example

```json
{
  "s": "ok",
  "symbol": ["AAPL", "META", "MSFT"],
  "mid": [149.07, 320.45, 380.12],
  "change": [-2.052, 1.23, -0.85],
  "changepct": [-0.0088, 0.0039, -0.0022],
  "updated": [1663958092, 1663958092, 1663958092]
}
```

## Request Parameters

### Required

You can provide the symbol(s) in one of two ways:

1. As part of the URL path:
   - **symbol** `string`
     The company's ticker symbol.

2. As a query parameter:
   - **symbols** `string`
     Comma-separated list of ticker symbols.

> [!TIP]
> **Batching multi-symbol requests**
>
> There is no application-level cap on the number of symbols, but the HTTP request line is limited to 4094 bytes. For typical 4-character tickers that's roughly 700–800 symbols per request. To stay clear of the limit, chunk into batches of **500 symbols or fewer**. See [400: Bad Request — URL Too Long](https://www.marketdata.app/docs/api/troubleshooting/bad-request#case-5-url-too-long-multi-symbol-requests) for details.

### Optional

- **extended** `boolean`

  Control the inclusion of extended hours data in the price output. Defaults to `true` if omitted. 

  - When set to `true`, the most recent price is always returned, without regard to whether the market is open for primary trading or extended hours trading.
  - When set to `false`, only prices from the primary trading session are returned. When the market is closed or in extended hours, a historical price from the last closing bell of the primary trading session is returned instead of an extended hours price. 

## Response Attributes

### Success

- **s** `string`

  Will always be `ok` when there is data for the symbols requested.

- **symbol** `array[string]`

  Array of ticker symbols that were requested.

- **mid** `array[number]`

  Array of midpoint prices, as calculated by the [SmartMid](https://www.marketdata.app/smart-mid/) model.

- **change** `array[number]`

  Array of price changes in currency units compared to the closing price of the previous primary trading session.

- **changepct** `array[number]`

  Array of price changes in percent, expressed as a decimal, compared to the closing price of the previous day. For example, a 3% change will be represented as 0.03.

> [!NOTE]
>   - When the market is open for primary trading, **change** and **changepct** are always calculated using the current midpoint price and the last primary session close. When the market is closed or in extended hours, this criteria is also used as long as `extended` is omitted or set to `true`.
>   - When `extended` is set to `false`, and the market is closed or in extended hours, prices from extended hours are not considered. The values for **change** and **changepct** will be calculated using the last two closing prices instead.

- **updated** `array[date]`

  Array of date/times for each stock price. All timestamps use US Eastern Time (America/New_York). See [Response Timezone](https://www.marketdata.app/docs/docs/api/dates-and-times#response-timezone) for details.

### No Data

- **s** `string`

  Status will only be `no_data` if no prices can be found for all of the symbols. If a price for any symbol can be returned, the request will be successful.

### Error

- **s** `string`

  Status will be `error` if the request produces an error response.

- **errmsg** `string`
  An error message.

## Usage Information

### Data Availability

This endpoint is available to all users and does not require any exchange entitlements. All users receive real-time prices regardless of their plan or access level. **Cached, delayed, and historical data are not available on this endpoint - only real-time prices are provided.**

| User Type | Exchange Entitlement | Price Type |
|-----------|----------------------|------------|
| All Users | Not Required         | Real-time  |

### Pricing

The cost of using the stock prices API endpoint is 1 credit per symbol.

| Data Type       | Cost Basis    | Credits Required per Unit |
|-----------------|---------------|---------------------------|
| Real-Time Data  | Per symbol    | 1 credit                  |
| Cached Data     | Not available | N/A                       |
| Delayed Data    | Not available | N/A                       |
| Historical Data | Not available | N/A                       |