{
  "schemaVersion": "1.0",
  "item": {
    "slug": "mkts-market-data",
    "name": "mkts Market Data",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/sdliriano/mkts-market-data",
    "canonicalUrl": "https://clawhub.ai/sdliriano/mkts-market-data",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/mkts-market-data",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=mkts-market-data",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-07T17:22:31.273Z",
      "expiresAt": "2026-05-14T17:22:31.273Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=afrexai-annual-report",
        "contentDisposition": "attachment; filename=\"afrexai-annual-report-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/mkts-market-data"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/mkts-market-data",
    "agentPageUrl": "https://openagent3.xyz/skills/mkts-market-data/agent",
    "manifestUrl": "https://openagent3.xyz/skills/mkts-market-data/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/mkts-market-data/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "mkts Market Data Skill",
        "body": "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.\n\nBase URL: https://mkts.io/api/v1\n\nAuth: 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\""
      },
      {
        "title": "Register for an API Key (Optional)",
        "body": "Get a free API key programmatically for higher rate limits (100 req/hour):\n\ncurl -s -X POST -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"you@example.com\",\"name\":\"my-agent\"}' \\\n  https://mkts.io/api/v1/register\n\nReturns { \"success\": true, \"data\": { \"apiKey\": \"mk_live_...\", ... } }. Save the key — it is shown only once. Max 3 keys per email."
      },
      {
        "title": "Market Overview",
        "body": "Get global market stats (total market cap, BTC dominance, etc.):\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/market"
      },
      {
        "title": "List Assets",
        "body": "Get a filtered, paginated list of assets:\n\n# All assets (default: top 50 by market cap)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/assets\"\n\n# Filter by type\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/assets?type=stock&limit=20\"\n\n# Filter by sector\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/assets?type=stock&sector=technology\"\n\n# Search by name or symbol\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/assets?search=apple\"\n\n# Pagination and sorting\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/assets?sort=change24h&dir=desc&limit=10&offset=0\"\n\nQuery params: type (crypto|stock|etf|commodity|forex), sector, platform, marketType, search, limit (1-500), offset, sort (price|change24h|volume24h|marketCap), dir (asc|desc)"
      },
      {
        "title": "Single Asset",
        "body": "Get details for a specific asset by symbol:\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/AAPL\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/BTC"
      },
      {
        "title": "Live Quote (Real-time)",
        "body": "Get a fresh quote directly from Yahoo Finance or CoinGecko (shared 60s cache, stricter rate limits):\n\n# Auto-detect source\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/AAPL/live\n\n# Force crypto source\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/asset/bitcoin/live?type=crypto\"\n\nFor 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)."
      },
      {
        "title": "Top Movers",
        "body": "Get top gainers and losers:\n\n# Both gainers and losers\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/movers\n\n# Just gainers, limited to crypto\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/movers?direction=gainers&type=crypto&limit=5\""
      },
      {
        "title": "Screener",
        "body": "Filter assets with range conditions:\n\n# Stocks down more than 3%, market cap > $10B\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/screen?type=stock&maxChange=-3&minMarketCap=10000000000\"\n\n# Crypto under $1 with high volume\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/screen?type=crypto&maxPrice=1&minVolume=1000000\"\n\nQuery params: type, sector, minPrice, maxPrice, minChange, maxChange, minVolume, maxVolume, minMarketCap, maxMarketCap, limit, offset, sort, dir"
      },
      {
        "title": "Sector Performance",
        "body": "Get aggregate performance by sector:\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/sectors"
      },
      {
        "title": "Compare Assets",
        "body": "Compare multiple assets side-by-side:\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/compare?symbols=AAPL,MSFT,GOOGL\""
      },
      {
        "title": "Market Brief",
        "body": "Get a curated summary ideal for morning briefings or agent digests:\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/brief\n\nReturns: global market stats, top 5 gainers/losers, sector summary, and natural-language highlights."
      },
      {
        "title": "Macro Snapshot",
        "body": "Get key macro indicators in one call (BTC, ETH, S&P 500, Nasdaq, Gold, Oil, DXY, VIX, 10Y):\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/macro\n\nReturns { 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."
      },
      {
        "title": "News",
        "body": "Get latest financial news from RSS feeds (free, no extra API cost):\n\n# All news\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/news\n\n# Filter by category\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/news?category=crypto&limit=10\"\n\n# News for a specific symbol (searches all feeds by symbol + company name)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/news?symbol=HOOD\"\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/news?symbol=AAPL&limit=5\"\n\nQuery params: category (crypto|markets|commodities|forex), symbol (filter by asset symbol — overrides category), limit (1-50, default 20).\n\nReturns { 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."
      },
      {
        "title": "Historical Prices (OHLCV)",
        "body": "Get daily historical candles for any asset:\n\n# Stock — full OHLCV from Yahoo Finance\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/asset/AAPL/history?range=3M\"\n\n# Crypto — close + volume from CoinGecko (max 365 days)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/asset/BTC/history?range=1Y\"\n\nQuery params: range (1M|3M|6M|YTD|1Y, default 3M).\n\nReturns { 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."
      },
      {
        "title": "Earnings Calendar",
        "body": "Get earnings dates, EPS estimates, and recent quarter history:\n\n# Real-time lookup for specific symbols (max 20)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/earnings?symbols=AAPL,TSLA,MSFT\"\n\n# Pre-cached weekly view (no real-time Yahoo calls)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/earnings?week=current\"\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/earnings?week=next\"\n\nQuery params: symbols (comma-separated, max 20) OR week (current|next). Only stocks and ETFs — crypto/commodities are not supported.\n\nReturns { earnings } array. Each record has symbol, name, earningsDate, earningsDates, epsEstimate, epsActual, revenueEstimate, surprisePercent, and recentQuarters (array of { date, actual, estimate })."
      },
      {
        "title": "Stock/ETF Details (Fundamentals)",
        "body": "Get comprehensive company data: profile, financials, earnings, analyst consensus, ownership, insider activity, SEC filings, and ETF holdings:\n\n# Stock fundamentals\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/AAPL/details\n\n# ETF details (includes top holdings and sector weightings)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/SPY/details\n\nStocks 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).\n\nReturns a rich object with: symbol, name, description, website, industry, sector, employees, headquarters, executives, trailingPE, forwardPE, dividendYield, beta, fiftyTwoWeekHigh, fiftyTwoWeekLow, targetPrice, recommendationKey, numberOfAnalysts, totalRevenue, revenueGrowth, grossMargins, operatingMargins, profitMargins, ebitda, returnOnAssets, returnOnEquity, totalCash, totalDebt, debtToEquity, freeCashflow, operatingCashflow, currentRatio, earningsGrowth, revenuePerShare, earningsQuarterly, earningsYearly, forwardEstimates, insidersPercentHeld, institutionsPercentHeld, topInstitutionalHolders, insiderTransactions, netSharePurchaseActivity, recommendationTrend, upgradeDowngradeHistory, calendarEvents, secFilings. ETFs additionally include fundFamily, category, and topHoldings (holdings array, sector weightings, equity holdings ratios)."
      },
      {
        "title": "SEC Filings",
        "body": "Get filings directly without pulling the full company details payload:\n\n# Latest filings\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/AAPL/filings\n\n# Filter by form type\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/asset/AAPL/filings?type=10-K&limit=5\"\n\nQuery params: type (optional SEC form type, e.g. 10-K, 10-Q, 8-K), limit (1-50, default 20). Backed by a shared 5-minute DynamoDB cache per symbol.\n\nReturns { symbol, count, filings, fetchedAt }. Each filing has date, type, title, and edgarUrl."
      },
      {
        "title": "Filings Search",
        "body": "Search filings across a bounded stock or ETF universe:\n\n# Latest large-cap 8-Ks\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \\\n  \"https://mkts.io/api/v1/filings/search?filingType=8-K&minMarketCap=10000000000&limit=20\"\n\n# Tech 10-Qs with title keyword filtering\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \\\n  \"https://mkts.io/api/v1/filings/search?sector=technology&filingType=10-Q&title=earnings&dateFrom=2026-01-01\"\n\nQuery params: type (stock or etf, default stock), sector, search, symbols, filingType, title, minMarketCap, maxMarketCap, dateFrom, dateTo, limit, universe.\n\nsymbols is capped at 25 tickers. universe is bounded by tier: keyless 10, free key 40, premium 150. dateFrom and dateTo use YYYY-MM-DD. The endpoint uses your snapshot to define the candidate universe, then fetches filings live from Yahoo Finance with a shared per-symbol cache and a shared short-lived result cache.\n\nReturns { results, total, limit, scanned, universe, source }. Each result includes symbol, name, sector, marketCap, and a nested filing object with date, type, title, and edgarUrl. Response headers include X-Query-Cache (hit or miss) and X-Query-Universe (effective capped universe)."
      },
      {
        "title": "Trending / Market Highlights",
        "body": "Get the most active stocks, top gainers, and top losers from Yahoo Finance screener (pre-cached, updated every 30 minutes):\n\n# All sections\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/trending\n\n# Just gainers\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/trending?section=gainers\"\n\n# Limit to top 5 per section\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/trending?count=5\"\n\nQuery params: section (trending|gainers|losers — omit for all), count (1-50, limits results per section).\n\nReturns { trending, gainers, losers, fetchedAt }. Each item has symbol, shortName, price, change, changePct, volume, marketCap. US equities only. Snapshot endpoint (not live), no extra Yahoo calls."
      },
      {
        "title": "Fundamentals Time Series",
        "body": "Get historical financial statements (income statement, balance sheet, cash flow) with computed margins:\n\n# Annual fundamentals (default: last 5 years, all statements)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/AAPL/fundamentals\n\n# Quarterly income statement\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/asset/MSFT/fundamentals?type=quarterly&module=financials\"\n\nQuery params: type (annual|quarterly, default annual), module (all|financials|balance-sheet|cash-flow, default all).\n\nStocks 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).\n\nReturns { symbol, type, module, periods, fetchedAt }. Each period has: date, periodLabel, revenue, costOfRevenue, grossProfit, operatingIncome, netIncome, ebitda, eps, grossMargin, operatingMargin, netMargin, totalAssets, totalLiabilities, stockholdersEquity, totalDebt, cashAndEquivalents, workingCapital, operatingCashFlow, capitalExpenditure, freeCashFlow. Margins are decimals (0.35 = 35%). Periods are sorted chronologically (oldest first)."
      },
      {
        "title": "Fundamentals Screener",
        "body": "Screen stocks or ETFs using valuation, profitability, growth, leverage, liquidity, and cash-flow metrics:\n\n# Profitable large-cap tech with strong margins\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \\\n  \"https://mkts.io/api/v1/fundamentals/screen?sector=technology&minMarketCap=10000000000&minGrossMargin=0.50&minOperatingMargin=0.20&sort=revenueGrowth\"\n\n# ETFs with positive analyst upside\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \\\n  \"https://mkts.io/api/v1/fundamentals/screen?type=etf&minTargetPriceUpside=0.05&sort=targetPriceUpside\"\n\nQuery params: type (stock or etf, default stock), sector, search, symbols, limit, universe, sort, dir, minMarketCap, maxMarketCap, minTrailingPE, maxTrailingPE, minForwardPE, maxForwardPE, minRevenueGrowth, maxRevenueGrowth, minGrossMargin, maxGrossMargin, minOperatingMargin, maxOperatingMargin, minProfitMargin, maxProfitMargin, minReturnOnEquity, maxReturnOnEquity, minReturnOnAssets, maxReturnOnAssets, minDebtToEquity, maxDebtToEquity, minCurrentRatio, maxCurrentRatio, minDividendYield, maxDividendYield, minFreeCashflow, maxFreeCashflow, minTotalRevenue, maxTotalRevenue, minEarningsGrowth, maxEarningsGrowth, minTargetPriceUpside, maxTargetPriceUpside.\n\nsymbols is capped at 25 tickers. universe is bounded by tier: keyless 10, free key 40, premium 150. Margin, yield, growth, and upside fields are decimals (0.20 = 20%). The screener enriches a capped snapshot universe with shared-cache company details, then filters and sorts the enriched set. Query results also use a shared short-lived result cache.\n\nReturns { results, total, limit, scanned, universe, source }. Each result includes snapshot fields plus valuation, growth, profitability, leverage, and analyst fields. Response headers include X-Query-Cache (hit or miss) and X-Query-Universe (effective capped universe)."
      },
      {
        "title": "Options Chain",
        "body": "Get the options chain for a stock or ETF (calls, puts, open interest, implied volatility, expirations):\n\n# Default (nearest expiration)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/AAPL/options\n\n# Specific expiration\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/asset/AAPL/options?expiration=2026-03-21\"\n\nStocks 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).\n\nReturns symbol, expirations (array of available dates), selectedExpiration, lastPrice, calls, puts, and summary (totalCallOI, totalPutOI, putCallRatio, totalCallVolume, totalPutVolume). Each contract has strike, lastPrice, bid, ask, change, percentChange, volume, openInterest, impliedVolatility, inTheMoney, expiration, contractSymbol."
      },
      {
        "title": "Portfolio Card Image",
        "body": "Generate a shareable 1200×630 PNG card showing portfolio summary:\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/portfolio/card?range=YTD\" -o card.png\n\nQuery params: range (1M|3M|6M|YTD|1Y, default YTD). Requires API key. Returns image/png.\n\nThe card shows total portfolio value, gain/loss with color coding, a sparkline chart, and top holdings by allocation."
      },
      {
        "title": "Portfolio (Read)",
        "body": "Get the authenticated user's portfolio holdings with current prices, P&L, and allocation:\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/portfolio\n\nReturns totalValue, totalCost, totalGainLoss, totalGainLossPercent, dayChange, dayChangePercent, and a holdings array. Each holding includes symbol, name, type, quantity, avgCostBasis, currentPrice, currentValue, costBasis, gainLoss, gainLossPercent, dayChange, dayChangePercent, and allocation (percentage of portfolio). An empty portfolio returns zero totals and an empty holdings array."
      },
      {
        "title": "Portfolio (Write)",
        "body": "Add, remove, or clear holdings:\n\n# Add a holding\ncurl -s -X POST -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"symbol\":\"AAPL\",\"name\":\"Apple Inc.\",\"assetType\":\"stock\",\"quantity\":10,\"avgCostBasis\":150.00}' \\\n  https://mkts.io/api/v1/portfolio\n\n# Delete a single holding by ID\ncurl -s -X DELETE -H \"X-API-Key: $MKTS_API_KEY\" \\\n  https://mkts.io/api/v1/portfolio/HOLDING_ID\n\n# Clear all holdings\ncurl -s -X DELETE -H \"X-API-Key: $MKTS_API_KEY\" \\\n  https://mkts.io/api/v1/portfolio\n\nPOST body fields: symbol (required, uppercase), name (required), assetType (crypto|stock|etf|commodity|forex), quantity (> 0), avgCostBasis (>= 0). Optional: purchaseDate (ISO string, max 20 chars), notes (max 1000 chars).\nReturns the created holding with a server-generated id."
      },
      {
        "title": "Portfolio Performance with Benchmarks",
        "body": "Compare your portfolio's historical performance against market benchmarks:\n\n# YTD performance vs S&P 500\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \\\n  \"https://mkts.io/api/v1/portfolio/performance?range=YTD&benchmarks=SPY\"\n\n# 3-month performance vs S&P 500 and Bitcoin\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \\\n  \"https://mkts.io/api/v1/portfolio/performance?range=3M&benchmarks=SPY,BTC-USD\"\n\nQuery params: range (1M|3M|6M|YTD|1Y|ALL), benchmarks (comma-separated, max 4 from: SPY, QQQ, DIA, IWM, BTC-USD, GLD, AGG).\n\nReturns portfolio.percentChange, portfolio.startValue, portfolio.endValue, per-benchmark percentChange, and a unified chartData array with daily percentage changes. Empty portfolio returns zero values."
      },
      {
        "title": "Journal",
        "body": "Log trade rationale, notes, and observations:\n\n# List all journal entries\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/journal\n\n# Create a journal entry\ncurl -s -X POST -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"title\":\"AAPL thesis\",\"content\":\"Strong services growth...\",\"symbol\":\"AAPL\",\"tags\":[\"thesis\",\"buy\"]}' \\\n  https://mkts.io/api/v1/journal\n\n# Delete a journal entry\ncurl -s -X DELETE -H \"X-API-Key: $MKTS_API_KEY\" \\\n  https://mkts.io/api/v1/journal/ENTRY_ID\n\nPOST body fields: title (required, max 200), content (required, max 10000). Optional: symbol, tags (array from: thesis, lesson, mistake, observation, buy, sell, watchlist).\nGET returns { count, entries } sorted by most recent first."
      },
      {
        "title": "Watchlist",
        "body": "Create and manage watchlists of symbols:\n\n# List all watchlists\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/watchlist\n\n# Create a watchlist (optionally with symbols)\ncurl -s -X POST -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"Tech\",\"symbols\":[\"AAPL\",\"MSFT\",\"GOOGL\"]}' \\\n  https://mkts.io/api/v1/watchlist\n\n# Get a single watchlist\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/watchlist/WATCHLIST_ID\n\n# Update a watchlist (rename, add/remove symbols)\ncurl -s -X PATCH -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"Big Tech\",\"addSymbols\":[\"AMZN\"],\"removeSymbols\":[\"GOOGL\"]}' \\\n  https://mkts.io/api/v1/watchlist/WATCHLIST_ID\n\n# Delete a single watchlist\ncurl -s -X DELETE -H \"X-API-Key: $MKTS_API_KEY\" \\\n  https://mkts.io/api/v1/watchlist/WATCHLIST_ID\n\n# Delete all watchlists\ncurl -s -X DELETE -H \"X-API-Key: $MKTS_API_KEY\" \\\n  https://mkts.io/api/v1/watchlist\n\nPOST body fields: name (required, max 100 chars). Optional: symbols (array of uppercase symbols).\nPATCH body fields (all optional): name, addSymbols (array), removeSymbols (array).\nGET returns { count, watchlists } sorted by most recent first. Each watchlist has id, userId, name, symbols, createdAt, updatedAt."
      },
      {
        "title": "Response Format",
        "body": "All responses follow this structure:\n\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"meta\": {\n    \"lastUpdated\": 1708721400000,\n    \"requestsRemaining\": 94,\n    \"resetTime\": 1708725000000\n  }\n}\n\nErrors:\n\n{\n  \"success\": false,\n  \"error\": \"Rate limit exceeded\",\n  \"meta\": { \"requestsRemaining\": 0, \"resetTime\": 1708725000000 }\n}"
      },
      {
        "title": "Rate Limits",
        "body": "TierSnapshot endpointsLive endpointsKeyless (no API key)20 req/hour per IP20 req/hour per IPFree (with API key)100 req/hour10 req/hourPremium1,000 req/hour100 req/hour\n\nWhen rate limited, you'll receive a 429 response with a Retry-After header (in seconds). Register at POST /register for higher limits."
      },
      {
        "title": "Error Handling",
        "body": "401: Invalid API key, or API key required (portfolio/journal/watchlist endpoints)\n404: Asset not found\n429: Rate limit exceeded — wait and retry after Retry-After seconds\n500/502/503: Server error — retry with backoff"
      },
      {
        "title": "Ask (Natural Language)",
        "body": "Query market data using natural language. Requires API key. Counts against daily AI usage limit (5/day free, unlimited premium).\n\n# Screen for assets\ncurl -s -X POST -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"q\":\"tech stocks down more than 5%\"}' \\\n  https://mkts.io/api/v1/ask\n\n# Look up a single asset\ncurl -s -X POST -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"q\":\"what is bitcoin at?\"}' \\\n  https://mkts.io/api/v1/ask\n\n# Top movers\ncurl -s -X POST -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"q\":\"top crypto gainers today\"}' \\\n  https://mkts.io/api/v1/ask\n\nPOST body: { \"q\": \"your question\" } (max 500 chars). Returns { query, action, summary, results, timestamp }. Supported actions: screen, lookup, compare, movers, macro, brief. Results are cached for 5 minutes."
      },
      {
        "title": "Tips for Agents",
        "body": "No API key needed to start — market data endpoints work without auth (20 req/hour). Register at POST /register when you need higher limits\nPortfolio, journal, and watchlist endpoints require an API key — register first if you need these\nUse /v1/brief for morning market summaries — it combines everything in one call\nUse /v1/screen for building watchlists or alert conditions\nUse /v1/compare when the user asks to compare specific tickers\nUse /v1/asset/{symbol}/live only when the user needs a fresh quote — it has stricter rate limits\nParse the meta.requestsRemaining field to manage your rate limit budget\nThe highlights array in /v1/brief contains pre-formatted natural-language summaries\nUse /v1/portfolio when the user asks about their holdings, P&L, allocation, or portfolio performance\nUse POST /v1/portfolio to add holdings — the id is generated server-side, use it for subsequent deletes\nUse /v1/portfolio/performance?range=YTD&benchmarks=SPY to answer \"how am I doing vs the S&P?\"\nUse /v1/journal to log trade rationale — attach a symbol and tags for better organization\nPortfolio, journal, and watchlist endpoints return Cache-Control: private, no-store — do not cache these\nUse /v1/watchlist to manage symbol watchlists — create a list, then use /v1/compare or /v1/screen with those symbols\nUse PATCH /v1/watchlist/{id} with addSymbols/removeSymbols to manage symbols without replacing the whole list\nUse /v1/news?category=crypto to get relevant headlines before making trade decisions\nUse /v1/asset/{symbol}/history for technical analysis — stocks get full OHLCV, crypto gets close + volume\nUse /v1/earnings?symbols=AAPL before earnings season — check EPS estimates and recent quarter surprises\nUse /v1/earnings?week=current for a quick weekly earnings calendar (zero real-time API calls)\nUse /v1/portfolio/card to generate a shareable portfolio image — pipe to a file with -o card.png\nUse /v1/news?symbol=AAPL to get news specifically about an asset — searches all feeds by symbol and company name\nUse /v1/macro for a quick macro dashboard — BTC, ETH, S&P 500, Nasdaq, Gold, Oil, DXY, VIX, and 10Y in one call\nUse /v1/asset/{symbol}/details for deep fundamental analysis — earnings, analyst targets, insider activity, SEC filings, and ETF holdings in one call\nUse /v1/asset/{symbol}/options for derivatives analysis — get the full options chain with calls, puts, OI, IV, and all available expirations. Combine with /v1/asset/{symbol}/live for delta-neutral strategies\nUse /v1/trending for live market movers — most active, top gainers, top losers. Pre-cached from Yahoo screener, no live rate limit cost. Filter by ?section=gainers or limit with ?count=5\nUse /v1/asset/{symbol}/fundamentals for historical financial analysis — revenue trends, margin evolution, balance sheet health over 5 years. Use ?type=quarterly for recent quarter-by-quarter trends\nUse POST /v1/ask for complex natural language queries — it parses intent and routes to the right data. Requires API key, counts against AI daily limit"
      }
    ],
    "body": "mkts Market Data Skill\n\nA 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.\n\nBase URL: https://mkts.io/api/v1\n\nAuth: 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\"\n\nRegister for an API Key (Optional)\n\nGet a free API key programmatically for higher rate limits (100 req/hour):\n\ncurl -s -X POST -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"you@example.com\",\"name\":\"my-agent\"}' \\\n  https://mkts.io/api/v1/register\n\n\nReturns { \"success\": true, \"data\": { \"apiKey\": \"mk_live_...\", ... } }. Save the key — it is shown only once. Max 3 keys per email.\n\nEndpoints\nMarket Overview\n\nGet global market stats (total market cap, BTC dominance, etc.):\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/market\n\nList Assets\n\nGet a filtered, paginated list of assets:\n\n# All assets (default: top 50 by market cap)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/assets\"\n\n# Filter by type\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/assets?type=stock&limit=20\"\n\n# Filter by sector\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/assets?type=stock&sector=technology\"\n\n# Search by name or symbol\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/assets?search=apple\"\n\n# Pagination and sorting\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/assets?sort=change24h&dir=desc&limit=10&offset=0\"\n\n\nQuery params: type (crypto|stock|etf|commodity|forex), sector, platform, marketType, search, limit (1-500), offset, sort (price|change24h|volume24h|marketCap), dir (asc|desc)\n\nSingle Asset\n\nGet details for a specific asset by symbol:\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/AAPL\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/BTC\n\nLive Quote (Real-time)\n\nGet a fresh quote directly from Yahoo Finance or CoinGecko (shared 60s cache, stricter rate limits):\n\n# Auto-detect source\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/AAPL/live\n\n# Force crypto source\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/asset/bitcoin/live?type=crypto\"\n\n\nFor 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).\n\nTop Movers\n\nGet top gainers and losers:\n\n# Both gainers and losers\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/movers\n\n# Just gainers, limited to crypto\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/movers?direction=gainers&type=crypto&limit=5\"\n\nScreener\n\nFilter assets with range conditions:\n\n# Stocks down more than 3%, market cap > $10B\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/screen?type=stock&maxChange=-3&minMarketCap=10000000000\"\n\n# Crypto under $1 with high volume\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/screen?type=crypto&maxPrice=1&minVolume=1000000\"\n\n\nQuery params: type, sector, minPrice, maxPrice, minChange, maxChange, minVolume, maxVolume, minMarketCap, maxMarketCap, limit, offset, sort, dir\n\nSector Performance\n\nGet aggregate performance by sector:\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/sectors\n\nCompare Assets\n\nCompare multiple assets side-by-side:\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/compare?symbols=AAPL,MSFT,GOOGL\"\n\nMarket Brief\n\nGet a curated summary ideal for morning briefings or agent digests:\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/brief\n\n\nReturns: global market stats, top 5 gainers/losers, sector summary, and natural-language highlights.\n\nMacro Snapshot\n\nGet key macro indicators in one call (BTC, ETH, S&P 500, Nasdaq, Gold, Oil, DXY, VIX, 10Y):\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/macro\n\n\nReturns { 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.\n\nNews\n\nGet latest financial news from RSS feeds (free, no extra API cost):\n\n# All news\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/news\n\n# Filter by category\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/news?category=crypto&limit=10\"\n\n# News for a specific symbol (searches all feeds by symbol + company name)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/news?symbol=HOOD\"\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/news?symbol=AAPL&limit=5\"\n\n\nQuery params: category (crypto|markets|commodities|forex), symbol (filter by asset symbol — overrides category), limit (1-50, default 20).\n\nReturns { 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.\n\nHistorical Prices (OHLCV)\n\nGet daily historical candles for any asset:\n\n# Stock — full OHLCV from Yahoo Finance\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/asset/AAPL/history?range=3M\"\n\n# Crypto — close + volume from CoinGecko (max 365 days)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/asset/BTC/history?range=1Y\"\n\n\nQuery params: range (1M|3M|6M|YTD|1Y, default 3M).\n\nReturns { 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.\n\nEarnings Calendar\n\nGet earnings dates, EPS estimates, and recent quarter history:\n\n# Real-time lookup for specific symbols (max 20)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/earnings?symbols=AAPL,TSLA,MSFT\"\n\n# Pre-cached weekly view (no real-time Yahoo calls)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/earnings?week=current\"\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/earnings?week=next\"\n\n\nQuery params: symbols (comma-separated, max 20) OR week (current|next). Only stocks and ETFs — crypto/commodities are not supported.\n\nReturns { earnings } array. Each record has symbol, name, earningsDate, earningsDates, epsEstimate, epsActual, revenueEstimate, surprisePercent, and recentQuarters (array of { date, actual, estimate }).\n\nStock/ETF Details (Fundamentals)\n\nGet comprehensive company data: profile, financials, earnings, analyst consensus, ownership, insider activity, SEC filings, and ETF holdings:\n\n# Stock fundamentals\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/AAPL/details\n\n# ETF details (includes top holdings and sector weightings)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/SPY/details\n\n\nStocks 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).\n\nReturns a rich object with: symbol, name, description, website, industry, sector, employees, headquarters, executives, trailingPE, forwardPE, dividendYield, beta, fiftyTwoWeekHigh, fiftyTwoWeekLow, targetPrice, recommendationKey, numberOfAnalysts, totalRevenue, revenueGrowth, grossMargins, operatingMargins, profitMargins, ebitda, returnOnAssets, returnOnEquity, totalCash, totalDebt, debtToEquity, freeCashflow, operatingCashflow, currentRatio, earningsGrowth, revenuePerShare, earningsQuarterly, earningsYearly, forwardEstimates, insidersPercentHeld, institutionsPercentHeld, topInstitutionalHolders, insiderTransactions, netSharePurchaseActivity, recommendationTrend, upgradeDowngradeHistory, calendarEvents, secFilings. ETFs additionally include fundFamily, category, and topHoldings (holdings array, sector weightings, equity holdings ratios).\n\nSEC Filings\n\nGet filings directly without pulling the full company details payload:\n\n# Latest filings\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/AAPL/filings\n\n# Filter by form type\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/asset/AAPL/filings?type=10-K&limit=5\"\n\n\nQuery params: type (optional SEC form type, e.g. 10-K, 10-Q, 8-K), limit (1-50, default 20). Backed by a shared 5-minute DynamoDB cache per symbol.\n\nReturns { symbol, count, filings, fetchedAt }. Each filing has date, type, title, and edgarUrl.\n\nFilings Search\n\nSearch filings across a bounded stock or ETF universe:\n\n# Latest large-cap 8-Ks\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \\\n  \"https://mkts.io/api/v1/filings/search?filingType=8-K&minMarketCap=10000000000&limit=20\"\n\n# Tech 10-Qs with title keyword filtering\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \\\n  \"https://mkts.io/api/v1/filings/search?sector=technology&filingType=10-Q&title=earnings&dateFrom=2026-01-01\"\n\n\nQuery params: type (stock or etf, default stock), sector, search, symbols, filingType, title, minMarketCap, maxMarketCap, dateFrom, dateTo, limit, universe.\n\nsymbols is capped at 25 tickers. universe is bounded by tier: keyless 10, free key 40, premium 150. dateFrom and dateTo use YYYY-MM-DD. The endpoint uses your snapshot to define the candidate universe, then fetches filings live from Yahoo Finance with a shared per-symbol cache and a shared short-lived result cache.\n\nReturns { results, total, limit, scanned, universe, source }. Each result includes symbol, name, sector, marketCap, and a nested filing object with date, type, title, and edgarUrl. Response headers include X-Query-Cache (hit or miss) and X-Query-Universe (effective capped universe).\n\nTrending / Market Highlights\n\nGet the most active stocks, top gainers, and top losers from Yahoo Finance screener (pre-cached, updated every 30 minutes):\n\n# All sections\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/trending\n\n# Just gainers\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/trending?section=gainers\"\n\n# Limit to top 5 per section\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/trending?count=5\"\n\n\nQuery params: section (trending|gainers|losers — omit for all), count (1-50, limits results per section).\n\nReturns { trending, gainers, losers, fetchedAt }. Each item has symbol, shortName, price, change, changePct, volume, marketCap. US equities only. Snapshot endpoint (not live), no extra Yahoo calls.\n\nFundamentals Time Series\n\nGet historical financial statements (income statement, balance sheet, cash flow) with computed margins:\n\n# Annual fundamentals (default: last 5 years, all statements)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/AAPL/fundamentals\n\n# Quarterly income statement\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/asset/MSFT/fundamentals?type=quarterly&module=financials\"\n\n\nQuery params: type (annual|quarterly, default annual), module (all|financials|balance-sheet|cash-flow, default all).\n\nStocks 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).\n\nReturns { symbol, type, module, periods, fetchedAt }. Each period has: date, periodLabel, revenue, costOfRevenue, grossProfit, operatingIncome, netIncome, ebitda, eps, grossMargin, operatingMargin, netMargin, totalAssets, totalLiabilities, stockholdersEquity, totalDebt, cashAndEquivalents, workingCapital, operatingCashFlow, capitalExpenditure, freeCashFlow. Margins are decimals (0.35 = 35%). Periods are sorted chronologically (oldest first).\n\nFundamentals Screener\n\nScreen stocks or ETFs using valuation, profitability, growth, leverage, liquidity, and cash-flow metrics:\n\n# Profitable large-cap tech with strong margins\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \\\n  \"https://mkts.io/api/v1/fundamentals/screen?sector=technology&minMarketCap=10000000000&minGrossMargin=0.50&minOperatingMargin=0.20&sort=revenueGrowth\"\n\n# ETFs with positive analyst upside\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \\\n  \"https://mkts.io/api/v1/fundamentals/screen?type=etf&minTargetPriceUpside=0.05&sort=targetPriceUpside\"\n\n\nQuery params: type (stock or etf, default stock), sector, search, symbols, limit, universe, sort, dir, minMarketCap, maxMarketCap, minTrailingPE, maxTrailingPE, minForwardPE, maxForwardPE, minRevenueGrowth, maxRevenueGrowth, minGrossMargin, maxGrossMargin, minOperatingMargin, maxOperatingMargin, minProfitMargin, maxProfitMargin, minReturnOnEquity, maxReturnOnEquity, minReturnOnAssets, maxReturnOnAssets, minDebtToEquity, maxDebtToEquity, minCurrentRatio, maxCurrentRatio, minDividendYield, maxDividendYield, minFreeCashflow, maxFreeCashflow, minTotalRevenue, maxTotalRevenue, minEarningsGrowth, maxEarningsGrowth, minTargetPriceUpside, maxTargetPriceUpside.\n\nsymbols is capped at 25 tickers. universe is bounded by tier: keyless 10, free key 40, premium 150. Margin, yield, growth, and upside fields are decimals (0.20 = 20%). The screener enriches a capped snapshot universe with shared-cache company details, then filters and sorts the enriched set. Query results also use a shared short-lived result cache.\n\nReturns { results, total, limit, scanned, universe, source }. Each result includes snapshot fields plus valuation, growth, profitability, leverage, and analyst fields. Response headers include X-Query-Cache (hit or miss) and X-Query-Universe (effective capped universe).\n\nOptions Chain\n\nGet the options chain for a stock or ETF (calls, puts, open interest, implied volatility, expirations):\n\n# Default (nearest expiration)\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/asset/AAPL/options\n\n# Specific expiration\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/asset/AAPL/options?expiration=2026-03-21\"\n\n\nStocks 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).\n\nReturns symbol, expirations (array of available dates), selectedExpiration, lastPrice, calls, puts, and summary (totalCallOI, totalPutOI, putCallRatio, totalCallVolume, totalPutVolume). Each contract has strike, lastPrice, bid, ask, change, percentChange, volume, openInterest, impliedVolatility, inTheMoney, expiration, contractSymbol.\n\nPortfolio Card Image\n\nGenerate a shareable 1200×630 PNG card showing portfolio summary:\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \"https://mkts.io/api/v1/portfolio/card?range=YTD\" -o card.png\n\n\nQuery params: range (1M|3M|6M|YTD|1Y, default YTD). Requires API key. Returns image/png.\n\nThe card shows total portfolio value, gain/loss with color coding, a sparkline chart, and top holdings by allocation.\n\nPortfolio (Read)\n\nGet the authenticated user's portfolio holdings with current prices, P&L, and allocation:\n\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/portfolio\n\n\nReturns totalValue, totalCost, totalGainLoss, totalGainLossPercent, dayChange, dayChangePercent, and a holdings array. Each holding includes symbol, name, type, quantity, avgCostBasis, currentPrice, currentValue, costBasis, gainLoss, gainLossPercent, dayChange, dayChangePercent, and allocation (percentage of portfolio). An empty portfolio returns zero totals and an empty holdings array.\n\nPortfolio (Write)\n\nAdd, remove, or clear holdings:\n\n# Add a holding\ncurl -s -X POST -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"symbol\":\"AAPL\",\"name\":\"Apple Inc.\",\"assetType\":\"stock\",\"quantity\":10,\"avgCostBasis\":150.00}' \\\n  https://mkts.io/api/v1/portfolio\n\n# Delete a single holding by ID\ncurl -s -X DELETE -H \"X-API-Key: $MKTS_API_KEY\" \\\n  https://mkts.io/api/v1/portfolio/HOLDING_ID\n\n# Clear all holdings\ncurl -s -X DELETE -H \"X-API-Key: $MKTS_API_KEY\" \\\n  https://mkts.io/api/v1/portfolio\n\n\nPOST body fields: symbol (required, uppercase), name (required), assetType (crypto|stock|etf|commodity|forex), quantity (> 0), avgCostBasis (>= 0). Optional: purchaseDate (ISO string, max 20 chars), notes (max 1000 chars). Returns the created holding with a server-generated id.\n\nPortfolio Performance with Benchmarks\n\nCompare your portfolio's historical performance against market benchmarks:\n\n# YTD performance vs S&P 500\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \\\n  \"https://mkts.io/api/v1/portfolio/performance?range=YTD&benchmarks=SPY\"\n\n# 3-month performance vs S&P 500 and Bitcoin\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" \\\n  \"https://mkts.io/api/v1/portfolio/performance?range=3M&benchmarks=SPY,BTC-USD\"\n\n\nQuery params: range (1M|3M|6M|YTD|1Y|ALL), benchmarks (comma-separated, max 4 from: SPY, QQQ, DIA, IWM, BTC-USD, GLD, AGG).\n\nReturns portfolio.percentChange, portfolio.startValue, portfolio.endValue, per-benchmark percentChange, and a unified chartData array with daily percentage changes. Empty portfolio returns zero values.\n\nJournal\n\nLog trade rationale, notes, and observations:\n\n# List all journal entries\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/journal\n\n# Create a journal entry\ncurl -s -X POST -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"title\":\"AAPL thesis\",\"content\":\"Strong services growth...\",\"symbol\":\"AAPL\",\"tags\":[\"thesis\",\"buy\"]}' \\\n  https://mkts.io/api/v1/journal\n\n# Delete a journal entry\ncurl -s -X DELETE -H \"X-API-Key: $MKTS_API_KEY\" \\\n  https://mkts.io/api/v1/journal/ENTRY_ID\n\n\nPOST body fields: title (required, max 200), content (required, max 10000). Optional: symbol, tags (array from: thesis, lesson, mistake, observation, buy, sell, watchlist). GET returns { count, entries } sorted by most recent first.\n\nWatchlist\n\nCreate and manage watchlists of symbols:\n\n# List all watchlists\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/watchlist\n\n# Create a watchlist (optionally with symbols)\ncurl -s -X POST -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"Tech\",\"symbols\":[\"AAPL\",\"MSFT\",\"GOOGL\"]}' \\\n  https://mkts.io/api/v1/watchlist\n\n# Get a single watchlist\ncurl -s -H \"X-API-Key: $MKTS_API_KEY\" https://mkts.io/api/v1/watchlist/WATCHLIST_ID\n\n# Update a watchlist (rename, add/remove symbols)\ncurl -s -X PATCH -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"name\":\"Big Tech\",\"addSymbols\":[\"AMZN\"],\"removeSymbols\":[\"GOOGL\"]}' \\\n  https://mkts.io/api/v1/watchlist/WATCHLIST_ID\n\n# Delete a single watchlist\ncurl -s -X DELETE -H \"X-API-Key: $MKTS_API_KEY\" \\\n  https://mkts.io/api/v1/watchlist/WATCHLIST_ID\n\n# Delete all watchlists\ncurl -s -X DELETE -H \"X-API-Key: $MKTS_API_KEY\" \\\n  https://mkts.io/api/v1/watchlist\n\n\nPOST body fields: name (required, max 100 chars). Optional: symbols (array of uppercase symbols). PATCH body fields (all optional): name, addSymbols (array), removeSymbols (array). GET returns { count, watchlists } sorted by most recent first. Each watchlist has id, userId, name, symbols, createdAt, updatedAt.\n\nResponse Format\n\nAll responses follow this structure:\n\n{\n  \"success\": true,\n  \"data\": { ... },\n  \"meta\": {\n    \"lastUpdated\": 1708721400000,\n    \"requestsRemaining\": 94,\n    \"resetTime\": 1708725000000\n  }\n}\n\n\nErrors:\n\n{\n  \"success\": false,\n  \"error\": \"Rate limit exceeded\",\n  \"meta\": { \"requestsRemaining\": 0, \"resetTime\": 1708725000000 }\n}\n\nRate Limits\nTier\tSnapshot endpoints\tLive endpoints\nKeyless (no API key)\t20 req/hour per IP\t20 req/hour per IP\nFree (with API key)\t100 req/hour\t10 req/hour\nPremium\t1,000 req/hour\t100 req/hour\n\nWhen rate limited, you'll receive a 429 response with a Retry-After header (in seconds). Register at POST /register for higher limits.\n\nError Handling\n401: Invalid API key, or API key required (portfolio/journal/watchlist endpoints)\n404: Asset not found\n429: Rate limit exceeded — wait and retry after Retry-After seconds\n500/502/503: Server error — retry with backoff\nAsk (Natural Language)\n\nQuery market data using natural language. Requires API key. Counts against daily AI usage limit (5/day free, unlimited premium).\n\n# Screen for assets\ncurl -s -X POST -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"q\":\"tech stocks down more than 5%\"}' \\\n  https://mkts.io/api/v1/ask\n\n# Look up a single asset\ncurl -s -X POST -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"q\":\"what is bitcoin at?\"}' \\\n  https://mkts.io/api/v1/ask\n\n# Top movers\ncurl -s -X POST -H \"X-API-Key: $MKTS_API_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"q\":\"top crypto gainers today\"}' \\\n  https://mkts.io/api/v1/ask\n\n\nPOST body: { \"q\": \"your question\" } (max 500 chars). Returns { query, action, summary, results, timestamp }. Supported actions: screen, lookup, compare, movers, macro, brief. Results are cached for 5 minutes.\n\nTips for Agents\nNo API key needed to start — market data endpoints work without auth (20 req/hour). Register at POST /register when you need higher limits\nPortfolio, journal, and watchlist endpoints require an API key — register first if you need these\nUse /v1/brief for morning market summaries — it combines everything in one call\nUse /v1/screen for building watchlists or alert conditions\nUse /v1/compare when the user asks to compare specific tickers\nUse /v1/asset/{symbol}/live only when the user needs a fresh quote — it has stricter rate limits\nParse the meta.requestsRemaining field to manage your rate limit budget\nThe highlights array in /v1/brief contains pre-formatted natural-language summaries\nUse /v1/portfolio when the user asks about their holdings, P&L, allocation, or portfolio performance\nUse POST /v1/portfolio to add holdings — the id is generated server-side, use it for subsequent deletes\nUse /v1/portfolio/performance?range=YTD&benchmarks=SPY to answer \"how am I doing vs the S&P?\"\nUse /v1/journal to log trade rationale — attach a symbol and tags for better organization\nPortfolio, journal, and watchlist endpoints return Cache-Control: private, no-store — do not cache these\nUse /v1/watchlist to manage symbol watchlists — create a list, then use /v1/compare or /v1/screen with those symbols\nUse PATCH /v1/watchlist/{id} with addSymbols/removeSymbols to manage symbols without replacing the whole list\nUse /v1/news?category=crypto to get relevant headlines before making trade decisions\nUse /v1/asset/{symbol}/history for technical analysis — stocks get full OHLCV, crypto gets close + volume\nUse /v1/earnings?symbols=AAPL before earnings season — check EPS estimates and recent quarter surprises\nUse /v1/earnings?week=current for a quick weekly earnings calendar (zero real-time API calls)\nUse /v1/portfolio/card to generate a shareable portfolio image — pipe to a file with -o card.png\nUse /v1/news?symbol=AAPL to get news specifically about an asset — searches all feeds by symbol and company name\nUse /v1/macro for a quick macro dashboard — BTC, ETH, S&P 500, Nasdaq, Gold, Oil, DXY, VIX, and 10Y in one call\nUse /v1/asset/{symbol}/details for deep fundamental analysis — earnings, analyst targets, insider activity, SEC filings, and ETF holdings in one call\nUse /v1/asset/{symbol}/options for derivatives analysis — get the full options chain with calls, puts, OI, IV, and all available expirations. Combine with /v1/asset/{symbol}/live for delta-neutral strategies\nUse /v1/trending for live market movers — most active, top gainers, top losers. Pre-cached from Yahoo screener, no live rate limit cost. Filter by ?section=gainers or limit with ?count=5\nUse /v1/asset/{symbol}/fundamentals for historical financial analysis — revenue trends, margin evolution, balance sheet health over 5 years. Use ?type=quarterly for recent quarter-by-quarter trends\nUse POST /v1/ask for complex natural language queries — it parses intent and routes to the right data. Requires API key, counts against AI daily limit"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/sdliriano/mkts-market-data",
    "publisherUrl": "https://clawhub.ai/sdliriano/mkts-market-data",
    "owner": "sdliriano",
    "version": "1.0.11",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/mkts-market-data",
    "downloadUrl": "https://openagent3.xyz/downloads/mkts-market-data",
    "agentUrl": "https://openagent3.xyz/skills/mkts-market-data/agent",
    "manifestUrl": "https://openagent3.xyz/skills/mkts-market-data/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/mkts-market-data/agent.md"
  }
}