mkts Market Data

Real-time market data, portfolio tracking, trade journaling, screening, and news for stocks, crypto, ETFs, commodities, and forex — no API key required to start

# mkts Market Data Skill

A complete financial toolkit for AI agents. Get market overviews, live quotes, historical OHLCV data, earnings calendars, and news from 8+ sources. Screen assets by price, volume, and market cap. Compare tickers side-by-side. Track portfolios with P&L, allocation, and benchmark performance. Log trade rationale in a journal. Manage watchlists. No API key needed for market data — register programmatically for higher limits.

**Base URL**: `https://mkts.io/api/v1`

**Auth**: No API key required for basic access (20 req/hour per IP). For higher limits, register for a free key and pass it via header: `-H "X-API-Key: $MKTS_API_KEY"`

### Register for an API Key (Optional)
Get a free API key programmatically for higher rate limits (100 req/hour):
```bash
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","name":"my-agent"}' \
  https://mkts.io/api/v1/register
```
Returns `{ "success": true, "data": { "apiKey": "mk_live_...", ... } }`. Save the key — it is shown only once. Max 3 keys per email.

## Endpoints

### Market Overview
Get global market stats (total market cap, BTC dominance, etc.):
```bash
curl -s -H "X-API-Key: $MKTS_API_KEY" https://mkts.io/api/v1/market
```

### List Assets
Get a filtered, paginated list of assets:
```bash
# All assets (default: top 50 by market cap)
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/assets"

# Filter by type
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/assets?type=stock&limit=20"

# Filter by sector
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/assets?type=stock&sector=technology"

# Search by name or symbol
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/assets?search=apple"

# Pagination and sorting
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/assets?sort=change24h&dir=desc&limit=10&offset=0"
```

Query params: `type` (crypto|stock|etf|commodity|forex), `sector`, `platform`, `marketType`, `search`, `limit` (1-500), `offset`, `sort` (price|change24h|volume24h|marketCap), `dir` (asc|desc)

### Single Asset
Get details for a specific asset by symbol:
```bash
curl -s -H "X-API-Key: $MKTS_API_KEY" https://mkts.io/api/v1/asset/AAPL
curl -s -H "X-API-Key: $MKTS_API_KEY" https://mkts.io/api/v1/asset/BTC
```

### Live Quote (Real-time)
Get a fresh quote directly from Yahoo Finance or CoinGecko (shared 60s cache, stricter rate limits):
```bash
# Auto-detect source
curl -s -H "X-API-Key: $MKTS_API_KEY" https://mkts.io/api/v1/asset/AAPL/live

# Force crypto source
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/asset/bitcoin/live?type=crypto"
```

For stocks/ETFs, the response includes extended-hours fields when available: `marketState` (PRE, REGULAR, POST, CLOSED), `preMarketPrice`, `preMarketChange`, `preMarketChangePercent`, `preMarketTime`, `postMarketPrice`, `postMarketChange`, `postMarketChangePercent`, `postMarketTime`. Times are Unix timestamps in milliseconds. Fields are `null` when the market is not in that session or for asset types that trade 24/7 (crypto).

### Top Movers
Get top gainers and losers:
```bash
# Both gainers and losers
curl -s -H "X-API-Key: $MKTS_API_KEY" https://mkts.io/api/v1/movers

# Just gainers, limited to crypto
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/movers?direction=gainers&type=crypto&limit=5"
```

### Screener
Filter assets with range conditions:
```bash
# Stocks down more than 3%, market cap > $10B
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/screen?type=stock&maxChange=-3&minMarketCap=10000000000"

# Crypto under $1 with high volume
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/screen?type=crypto&maxPrice=1&minVolume=1000000"
```

Query params: `type`, `sector`, `minPrice`, `maxPrice`, `minChange`, `maxChange`, `minVolume`, `maxVolume`, `minMarketCap`, `maxMarketCap`, `limit`, `offset`, `sort`, `dir`

### Sector Performance
Get aggregate performance by sector:
```bash
curl -s -H "X-API-Key: $MKTS_API_KEY" https://mkts.io/api/v1/sectors
```

### Compare Assets
Compare multiple assets side-by-side:
```bash
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/compare?symbols=AAPL,MSFT,GOOGL"
```

### Market Brief
Get a curated summary ideal for morning briefings or agent digests:
```bash
curl -s -H "X-API-Key: $MKTS_API_KEY" https://mkts.io/api/v1/brief
```

Returns: global market stats, top 5 gainers/losers, sector summary, and natural-language highlights.

### Macro Snapshot
Get key macro indicators in one call (BTC, ETH, S&P 500, Nasdaq, Gold, Oil, DXY, VIX, 10Y):
```bash
curl -s -H "X-API-Key: $MKTS_API_KEY" https://mkts.io/api/v1/macro
```

Returns `{ indicators, generatedAt }`. Each indicator has `name`, `symbol`, `price`, and `change24h`. Snapshot assets (BTC, ETH, SPY, QQQ, GC=F, CL=F) update on data refresh; live indicators (DX-Y.NYB, ^VIX, ^TNX) are fetched in real-time with 60s caching.

### News
Get latest financial news from RSS feeds (free, no extra API cost):
```bash
# All news
curl -s -H "X-API-Key: $MKTS_API_KEY" https://mkts.io/api/v1/news

# Filter by category
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/news?category=crypto&limit=10"

# News for a specific symbol (searches all feeds by symbol + company name)
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/news?symbol=HOOD"
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/news?symbol=AAPL&limit=5"
```

Query params: `category` (crypto|markets|commodities|forex), `symbol` (filter by asset symbol — overrides category), `limit` (1-50, default 20).

Returns `{ count, news, sources }` (plus `symbol` when filtering by symbol). Each news item has `title`, `link`, `pubDate`, `source`, and `category`. Sources include CoinDesk, Cointelegraph, Decrypt, MarketWatch, CNBC, Investing.com, OilPrice, and FXStreet.

### Historical Prices (OHLCV)
Get daily historical candles for any asset:
```bash
# Stock — full OHLCV from Yahoo Finance
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/asset/AAPL/history?range=3M"

# Crypto — close + volume from CoinGecko (max 365 days)
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/asset/BTC/history?range=1Y"
```

Query params: `range` (1M|3M|6M|YTD|1Y, default 3M).

Returns `{ symbol, range, candles, source }`. Each candle has `date`, `close`, and optionally `open`, `high`, `low`, `volume`. Stocks/ETFs/commodities include full OHLCV; crypto includes close + volume only.

### Earnings Calendar
Get earnings dates, EPS estimates, and recent quarter history:
```bash
# Real-time lookup for specific symbols (max 20)
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/earnings?symbols=AAPL,TSLA,MSFT"

# Pre-cached weekly view (no real-time Yahoo calls)
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/earnings?week=current"
curl -s -H "X-API-Key: $MKTS_API_KEY" "https://mkts.io/api/v1/earnings?week=next"
```

Query params: `symbols` (comma-separated, max 20) OR `week` (current|next). Only stocks and ETFs — crypto/commodities are not supported.

Returns `{ earnings }` array. Each record has `symbol`, `name`, `earningsDate`, `earningsDates`, `epsEstimate`, `epsActual`, `revenueEstimate`, `surprisePercent`, and `recentQuarters` (array of `{ date, actual, estimate }`).

### Stock/ETF Details (Fundamentals)
Get comprehensive company data: profile, financials, earnings, analyst consensus, ownership, insider activity, SEC filings, and ETF holdings:
```bash
# Stock fundamentals
curl -s -H "X-API-Key: $MKTS_API_KEY" https://mkts.io/api/v1/asset/AAPL/details

# ETF details (includes top holdings and sector weightings)
curl -s -H "X-API-Key: $MKTS_API_KEY" https://mkts.io/api/v1/asset/SPY/details
```

Stocks and ETFs only — crypto, commodities, and forex are not supported. Real-time Yahoo Finance call with a shared 60s DynamoDB-backed cache (counts against live rate limits).

Returns a rich object with: `symbo