Tutorial: ETF Data - Gnist Context

Finance

Data source: SEC EDGAR (N-PORT-P)

Overview

ETF Data wraps SEC EDGAR (N-PORT-P), handling authentication, pagination, and rate limits for you. This tutorial covers all 3 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-etf": {
      "url": "https://context.gnist.ai/mcp/etf/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (3)

`get_etf_holdings`

Get top portfolio holdings for an ETF or mutual fund. Returns the largest holdings by market value from the fund's most recent N-PORT-P filing (quarterly portfolio disclosure filed with SEC). Each holding includes name, CUSIP, market value, percentage of NAV, share count, asset category, and country of domicile. Examples: get_etf_holdings("SPY") → Top 25 holdings of SPDR S&P 500 ETF get_etf_holdings("QQQ", limit=10) → Top 10 Invesco QQQ holdings get_etf_holdings("VTI", limit=50) → Top 50 Vanguard Total Stock Market Returns: Fund name, report date, net assets, total holding count, and a list of holdings with value, weight, and classification.

Parameter	Type	Required	Description
`ticker_or_cik`	string	required	ETF or mutual fund ticker (e.g. "SPY", "QQQ", "VTI") or numeric CIK.
`limit`	integer	optional	Maximum holdings to return, sorted by market value (default 25). (default: `25`)

curl -X POST "https://context.gnist.ai/mcp/etf/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_etf_holdings", "arguments": {"ticker_or_cik": "SPY"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/etf/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'ticker_or_cik': 'SPY'}, 'name': 'get_etf_holdings'}},
)
print(resp.json())

`get_etf_allocation`

Get asset allocation breakdown for an ETF or mutual fund. Returns portfolio composition grouped by asset category (equity, debt, derivatives, etc.) and by country — from the most recent N-PORT-P filing. Useful for understanding an ETF's diversification, geographic exposure, and asset mix without reading the full holdings list. Examples: get_etf_allocation("SPY") → S&P 500 ETF allocation (mostly US equity) get_etf_allocation("BND") → Vanguard Bond ETF allocation (debt categories) get_etf_allocation("VT") → Vanguard Total World — global country breakdown Returns: Fund info, asset category breakdown with NAV percentages, and country breakdown with NAV percentages.

Parameter	Type	Required	Description
`ticker_or_cik`	string	required	ETF or mutual fund ticker (e.g. "SPY", "QQQ", "BND") or numeric CIK.

curl -X POST "https://context.gnist.ai/mcp/etf/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_etf_allocation", "arguments": {"ticker_or_cik": "SPY"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/etf/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'ticker_or_cik': 'SPY'},
            'name': 'get_etf_allocation'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/etf/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/etf/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does ETF Data provide?

ETF and mutual fund portfolio data — top holdings, asset allocation, and country exposure from SEC N-PORT filings. It exposes 3 tools: get_etf_holdings, get_etf_allocation, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the ETF Data API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.