Documentation

Everything you need to integrate the Vala-Fi knowledge graph API.

Getting Started

Vala-Fi provides a REST API for querying financial company relationships extracted from SEC filings (10-K, 10-Q, 8-K). The graph currently covers 11,500+ companies and 25,000+ relationships across 12 sectors — with change detection that flags new, removed, and changed relationships between filings.

To get started:

Sign up for an API key (free, no credit card required)
Include your key in the X-API-Key header
Start querying the graph

Quick start

curl -H "X-API-Key: vfi_your_key_here" \
  https://api.valafi.dev/v1/company/AAPL

Authentication

All API requests require authentication via an API key passed in the X-API-Key request header.

Request Header

X-API-Key: vfi_your_key_here

API keys are prefixed with vfi_. If you don't have a key yet, sign up here.

Important: Keep your API key secure. Do not expose it in client-side code or public repositories. If compromised, contact us for a key rotation.

Core Endpoints

Base URL: https://api.valafi.dev

GET/v1/company/{ticker}

Get company profile by ticker symbol. Returns basic company information including sector, industry, and exchange.

Parameters

Name	Type	In	Required	Description
ticker	string	path	required	Stock ticker symbol (e.g., AAPL, MSFT)

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  https://api.valafi.dev/v1/company/AAPL

Example Response

json

{
  "ticker": "AAPL",
  "name": "Apple Inc.",
  "node_type": "full",
  "sector": "Technology",
  "industry": "Consumer Electronics",
  "country": "US",
  "exchange": "NASDAQ"
}

GET/v1/company/{ticker}/supply-chain

Get N-hop supply chain for a company. Traverse upstream (suppliers), downstream (customers), or both directions.

Parameters

Name	Type	In	Required	Description
ticker	string	path	required	Stock ticker symbol
hops	integer	query	optional	Number of hops to traverse (default: 1, max depends on tier)
direction	string	query	optional	Traversal direction: "upstream", "downstream", or "both" (default: "upstream")

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  "https://api.valafi.dev/v1/company/AAPL/supply-chain?hops=2&direction=both"

Example Response

json

{
  "company": {
    "ticker": "AAPL",
    "name": "Apple Inc.",
    "node_type": "full",
    "sector": "Technology"
  },
  "suppliers": [
    {
      "source": { "ticker": "AAPL", "name": "Apple Inc." },
      "target": { "ticker": "TSM", "name": "TSMC" },
      "relationship_type": "supplier",
      "strength": 0.95,
      "evidence": "TSMC is the primary manufacturer of Apple's custom silicon...",
      "hop": 1
    }
  ],
  "total_suppliers": 12,
  "hops_returned": 2,
  "max_hops_available": 3,
  "truncated": false
}

GET/v1/company/{ticker}/customers

Get all known customers of a company. Returns companies that have the queried company as a supplier.

Parameters

Name	Type	In	Required	Description
ticker	string	path	required	Stock ticker symbol

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  https://api.valafi.dev/v1/company/TSM/customers

Example Response

json

{
  "company": {
    "ticker": "TSM",
    "name": "TSMC",
    "node_type": "full",
    "sector": "Technology"
  },
  "relationships": [
    {
      "source": { "ticker": "TSM", "name": "TSMC" },
      "target": { "ticker": "AAPL", "name": "Apple Inc." },
      "relationship_type": "customer",
      "strength": 0.95,
      "evidence": "Apple is TSMC's largest customer..."
    }
  ],
  "total": 8,
  "truncated": false
}

GET/v1/company/{ticker}/competitors

Get all known competitors of a company extracted from SEC filings.

Parameters

Name	Type	In	Required	Description
ticker	string	path	required	Stock ticker symbol

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  https://api.valafi.dev/v1/company/AAPL/competitors

Example Response

json

{
  "company": {
    "ticker": "AAPL",
    "name": "Apple Inc.",
    "node_type": "full",
    "sector": "Technology"
  },
  "relationships": [
    {
      "source": { "ticker": "AAPL", "name": "Apple Inc." },
      "target": { "ticker": "MSFT", "name": "Microsoft Corp." },
      "relationship_type": "competitor",
      "strength": 0.88,
      "evidence": "Microsoft competes with Apple across personal computing..."
    }
  ],
  "total": 5,
  "truncated": false
}

GET/v1/path/{ticker_a}/{ticker_b}

Find the shortest path between two companies in the knowledge graph. Useful for discovering indirect relationships.

Parameters

Name	Type	In	Required	Description
ticker_a	string	path	required	Starting company ticker
ticker_b	string	path	required	Target company ticker

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  https://api.valafi.dev/v1/path/AAPL/NVDA

Example Response

json

{
  "source": { "ticker": "AAPL", "name": "Apple Inc." },
  "target": { "ticker": "NVDA", "name": "NVIDIA Corp." },
  "path": [
    { "ticker": "AAPL", "name": "Apple Inc." },
    { "ticker": "TSM", "name": "TSMC" },
    { "ticker": "NVDA", "name": "NVIDIA Corp." }
  ],
  "edges": [
    {
      "source": { "ticker": "AAPL" },
      "target": { "ticker": "TSM" },
      "relationship_type": "supplier"
    },
    {
      "source": { "ticker": "NVDA" },
      "target": { "ticker": "TSM" },
      "relationship_type": "supplier"
    }
  ],
  "path_length": 2
}

GET/v1/exposure/{ticker}

Get supply chain exposure and concentration risk analysis. Identifies shared suppliers/customers and single-source dependencies.

Parameters

Name	Type	In	Required	Description
ticker	string	path	required	Stock ticker symbol

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  https://api.valafi.dev/v1/exposure/AAPL

Example Response

json

{
  "company": { "ticker": "AAPL", "name": "Apple Inc." },
  "shared_suppliers": [
    {
      "company": { "ticker": "TSM", "name": "TSMC" },
      "relationship_to_source": "supplier",
      "relationship_to_peer": "supplier"
    }
  ],
  "shared_customers": [],
  "concentration_risks": [
    {
      "supplier": { "ticker": "TSM", "name": "TSMC" },
      "dependency_type": "sole_supplier",
      "alternatives_count": 1,
      "risk_level": "high"
    }
  ],
  "exposure_score": 0.72
}

GET/v1/sector/{sector}/graph

Get the relationship subgraph for an entire sector. Returns all companies and edges within the specified sector.

Parameters

Name	Type	In	Required	Description
sector	string	path	required	Sector name (e.g., "Technology", "Healthcare", "Energy")
relationship_types	string	query	optional	Comma-separated filter (e.g., "supplier,customer")

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  "https://api.valafi.dev/v1/sector/Technology/graph?relationship_types=supplier,customer"

Example Response

json

{
  "sector": "Technology",
  "companies": [
    { "ticker": "AAPL", "name": "Apple Inc.", "sector": "Technology" },
    { "ticker": "MSFT", "name": "Microsoft Corp.", "sector": "Technology" }
  ],
  "edges": [
    {
      "source": { "ticker": "AAPL" },
      "target": { "ticker": "TSM" },
      "relationship_type": "supplier",
      "strength": 0.95
    }
  ],
  "total_companies": 85,
  "total_edges": 142
}

Change Detection

Track relationship changes detected between SEC filing periods. These endpoints power the "what changed?" workflow.

GET/v1/company/{ticker}/changes

Relationship changes detected between filing periods for a specific company. Shows new, removed, and strength-changed relationships.

Parameters

Name	Type	In	Required	Description
ticker	string	path	required	Stock ticker symbol
since	string	query	optional	ISO date filter (e.g., 2024-01-01)
filing_type	string	query	optional	Filing type to compare (default: "10-K")

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  "https://api.valafi.dev/v1/company/AAPL/changes?since=2024-01-01"

Example Response

json

{
  "ticker": "AAPL",
  "filing_type": "10-K",
  "period": "2025-10-30 vs 2024-10-27",
  "new_relationships": [
    {
      "event_type": "new_relationship",
      "source_ticker": "AAPL",
      "target_ticker": "QRVO",
      "relationship_type": "supplier",
      "new_strength": 0.65,
      "filing_date": "2025-10-30",
      "severity": "high",
      "description": "New supplier relationship detected"
    }
  ],
  "removed_relationships": [],
  "strength_changes": [],
  "total_changes": 5
}

GET/v1/changes/feed

Change feed across ALL companies. The "what changed this week?" endpoint — returns newly detected relationship changes.

Parameters

Name	Type	In	Required	Description
since	string	query	required	ISO date (e.g., 2024-01-01)
tickers	string	query	optional	Comma-separated ticker filter
limit	integer	query	optional	Max results, 1-500 (default: 100)

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  "https://api.valafi.dev/v1/changes/feed?since=2024-01-01&limit=50"

Example Response

json

{
  "events": [
    {
      "event_type": "new_relationship",
      "source_ticker": "AAPL",
      "target_ticker": "QRVO",
      "relationship_type": "supplier",
      "filing_date": "2025-10-30",
      "severity": "high"
    }
  ],
  "since": "2024-01-01",
  "total": 47,
  "tickers_affected": 12
}

GET/v1/company/{ticker}/filings

Which SEC filings have been processed for a company and how many relationships were extracted from each.

Parameters

Name	Type	In	Required	Description
ticker	string	path	required	Stock ticker symbol

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  https://api.valafi.dev/v1/company/AAPL/filings

Example Response

json

{
  "ticker": "AAPL",
  "filings_processed": [
    {
      "filing_type": "10-K",
      "filing_date": "2025-10-30",
      "status": "completed",
      "relationships_extracted": 23
    }
  ],
  "total_filings": 3
}

Impact Simulation

Simulate supply chain disruptions and see cascade effects through the graph.

GET/v1/company/{ticker}/impact

Simulate a disruption at a company and see which downstream companies are affected, with impact scores and propagation paths.

Parameters

Name	Type	In	Required	Description
ticker	string	path	required	Company to disrupt
disruption_type	string	query	optional	Type of disruption (default: "supply_halt")
severity	float	query	optional	Severity 0.0-1.0 (default: 1.0)
max_hops	integer	query	optional	Propagation depth 1-5 (default: 3)

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  "https://api.valafi.dev/v1/company/TSM/impact?severity=1.0&max_hops=3"

Example Response

json

{
  "source": { "ticker": "TSM", "name": "TSMC" },
  "disruption_type": "supply_halt",
  "severity": 1.0,
  "impacted_companies": [
    {
      "company": { "ticker": "AAPL", "name": "Apple Inc." },
      "impact_score": 0.85,
      "hops_from_source": 1,
      "propagation_path": ["TSM", "AAPL"],
      "relationship_chain": ["supplier"]
    }
  ],
  "total_impacted": 23,
  "sectors_affected": ["Technology", "Consumer Electronics"],
  "critical_exposures": []
}

Portfolio Monitoring

Create a portfolio and monitor supply chain exposure, changes, and alerts across all holdings as a unit.

POST/v1/portfolio

Create a portfolio to monitor. Register holdings with optional weights.

Parameters

Name	Type	In	Required	Description
name	string	body	required	Portfolio name
holdings	array	body	required	Array of {ticker, weight} objects

Example Request

bash

curl -X POST -H "X-API-Key: vfi_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Main Book","holdings":[{"ticker":"AAPL","weight":0.15},{"ticker":"MSFT","weight":0.12},{"ticker":"NVDA","weight":0.10}]}' \
  https://api.valafi.dev/v1/portfolio

Example Response

json

{
  "portfolio_id": 1,
  "name": "Main Book",
  "holdings": [
    { "ticker": "AAPL", "weight": 0.15 },
    { "ticker": "MSFT", "weight": 0.12 },
    { "ticker": "NVDA", "weight": 0.10 }
  ],
  "created_at": "2025-03-28T12: 00: 00Z"
}

GET/v1/portfolio/{portfolio_id}/exposure

Aggregate supply chain exposure across all holdings. Shows shared suppliers, shared customers, and concentration risks at the portfolio level.

Parameters

Name	Type	In	Required	Description
portfolio_id	integer	path	required	Portfolio ID

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  https://api.valafi.dev/v1/portfolio/1/exposure

Example Response

json

{
  "portfolio_id": 1,
  "name": "Main Book",
  "shared_suppliers": [
    { "ticker": "TSM", "name": "TSMC", "shared_by": ["AAPL", "NVDA"] }
  ],
  "concentration_risks": [
    { "supplier": "TSM", "holdings_exposed": 2, "risk_level": "high" }
  ]
}

GET/v1/portfolio/{portfolio_id}/changes

Changes affecting any holding in the portfolio. One feed for the whole book.

Parameters

Name	Type	In	Required	Description
portfolio_id	integer	path	required	Portfolio ID
since	string	query	required	ISO date

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  "https://api.valafi.dev/v1/portfolio/1/changes?since=2024-01-01"

Example Response

json

{
  "portfolio_id": 1,
  "events": [
    {
      "event_type": "new_relationship",
      "holding_ticker": "AAPL",
      "target_ticker": "QRVO",
      "relationship_type": "supplier",
      "severity": "high"
    }
  ],
  "total": 12,
  "holdings_affected": 2
}

GET/v1/portfolio/{portfolio_id}/alerts

Proactive alerts when supply chain shifts are detected that affect portfolio holdings.

Parameters

Name	Type	In	Required	Description
portfolio_id	integer	path	required	Portfolio ID

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  https://api.valafi.dev/v1/portfolio/1/alerts

Example Response

json

{
  "portfolio_id": 1,
  "alerts": [
    {
      "type": "supplier_change",
      "holding": "AAPL",
      "description": "New supplier relationship detected: AAPL -> QRVO",
      "severity": "high",
      "detected_at": "2025-03-28T08: 00: 00Z"
    }
  ],
  "total": 3
}

POST/v1/portfolio/{portfolio_id}/simulate

Simulate a disruption scenario across the entire portfolio, not just one company.

Parameters

Name	Type	In	Required	Description
portfolio_id	integer	path	required	Portfolio ID
disrupted_ticker	string	body	required	Ticker of company to disrupt

Example Request

bash

curl -X POST -H "X-API-Key: vfi_your_key" \
  -H "Content-Type: application/json" \
  -d '{"disrupted_ticker":"TSM"}' \
  https://api.valafi.dev/v1/portfolio/1/simulate

Example Response

json

{
  "portfolio_id": 1,
  "disrupted": { "ticker": "TSM", "name": "TSMC" },
  "holdings_impacted": [
    { "ticker": "AAPL", "impact_score": 0.85 },
    { "ticker": "NVDA", "impact_score": 0.92 }
  ],
  "total_holdings_affected": 2,
  "portfolio_impact_score": 0.71
}

Developer Endpoints

Signup, key verification, and usage tracking.

POST/dev/signup

Parameters

Name	Type	In	Required	Description
email	string	body	required	Your email address
name	string	body	required	Your name
company	string	body	optional	Company or organization
use_case	string	body	optional	How you plan to use the API

Example Request

bash

curl -X POST -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"Your Name","use_case":"supply chain research"}' \
  https://api.valafi.dev/dev/signup

Example Response

json

{
  "email": "[email protected]",
  "name": "Your Name",
  "api_key": "vfi_dev_abc123...",
  "tier": "free",
  "message": "API key shown once. Save it now."
}

POST/dev/keys/verify

Check if an API key is valid and see remaining quota. No authentication required.

Parameters

Name	Type	In	Required	Description
api_key	string	body	required	The API key to verify

Example Request

bash

curl -X POST -H "Content-Type: application/json" \
  -d '{"api_key":"vfi_dev_abc123..."}' \
  https://api.valafi.dev/dev/keys/verify

Example Response

json

{
  "valid": true,
  "tier": "free",
  "remaining_requests_today": 42
}

GET/dev/usage

Get your current usage stats. Requires X-API-Key header.

Parameters

Name	Type	In	Required	Description

Example Request

bash

curl -H "X-API-Key: vfi_your_key" \
  https://api.valafi.dev/dev/usage

Example Response

json

{
  "requests_today": 8,
  "unique_tickers_today": 3,
  "tier": "free",
  "limits": {
    "requests_per_day": 50,
    "unique_tickers_per_day": 10
  }
}

Code Examples

cURL

terminal

curl -s -H "X-API-Key: vfi_your_key" \
  "https://api.valafi.dev/v1/company/AAPL/supply-chain?hops=2&direction=both" \
  | python -m json.tool

Python (httpx)

example.py

"token-keyword">import httpx

API_KEY = "vfi_your_key"
BASE_URL = "https://api.valafi.dev"

client = httpx.Client(
    base_url=BASE_URL,
    headers={"X-API-Key": API_KEY},
)

"token-comment"># Get Apple's supply chain
response = client.get("/v1/company/AAPL/supply-chain", params={
    "hops": 2,
    "direction": "both",
})
data = response.json()

"token-keyword">for edge "token-keyword">in data["suppliers"]:
    "token-keyword">print(f"{edge['source']['ticker']} -> {edge['target']['ticker']}")
    "token-keyword">print(f"  Type: {edge['relationship_type']}")
    "token-keyword">print(f"  Evidence: {edge.get('evidence', 'N/A')}")
    "token-keyword">print()

"token-comment"># Find path between two companies
path = client.get("/v1/path/AAPL/NVDA").json()
"token-keyword">print("Path:", " -> ".join(n["ticker"] "token-keyword">for n "token-keyword">in path["path"]))

JavaScript (fetch)

example.js

"token-keyword">const API_KEY = "vfi_your_key";
"token-keyword">const BASE_URL = "https:">//api.valafi.dev";

"token-keyword">async "token-keyword">function getSupplyChain(ticker, hops = 1) {
  "token-keyword">const res = "token-keyword">await fetch(
    `${BASE_URL}/v1/company/${ticker}/supply-chain?hops=${hops}&direction=both`,
    { headers: { "X-API-Key": API_KEY } }
  );

  "token-keyword">if (!res.ok) "token-keyword">throw "token-keyword">new Error(`API error: ${res.status}`);
  "token-keyword">return res.json();
}

"token-comment">// Usage
"token-keyword">const data = "token-keyword">await getSupplyChain("AAPL", 2);
console.log(`Found ${data.suppliers.length} relationships`);

"token-keyword">for ("token-keyword">const edge "token-keyword">of data.suppliers) {
  console.log(`${edge.source.ticker} -> ${edge.target.ticker} (${edge.relationship_type})`);
}

Rate Limits

Rate limits are enforced per API key. When you exceed your limit, the API returns a 429 Too Many Requests response with a Retry-After header.

Limit	Free Beta
Requests per day	50
Unique tickers per day	10
Results per query	5
Max hop depth	2
Strength scores	Hidden
Evidence text	First 2 results
Change feed	Included
Portfolio monitoring	Included
Sector graph	Paid only
Need higher limits?	Talk to us

When rate limited, the API returns a 429 status with a Retry-After header. We recommend implementing exponential backoff in your client.

MCP Integration

Vala-Fi works as a Model Context Protocol (MCP) server, enabling AI assistants like Claude Desktop, Cursor, and Windsurf to directly query the financial knowledge graph.

New to MCP? Follow the beginner-friendly setup guide with step-by-step instructions.

Claude Desktop

Claude Desktop uses a local MCP server. Requires uv (Python package runner). Use the full path to uvx (find it with which uvx in your terminal):

claude_desktop_config.json

{
  "mcpServers": {
    "vala-fi": {
      "command": "/full/path/to/uvx",
      "args": ["vala-fi-mcp"],
      "env": {
        "VALAFI_API_KEY": "vfi_your_key_here"
      }
    }
  }
}

Cursor / Windsurf / Claude Code

These tools support the remote MCP server — zero install, just paste and go.

Cursor / Windsurf / Claude Code

{
  "mcpServers": {
    "vala-fi": {
      "url": "https://mcp.valafi.dev/mcp",
      "headers": {
        "X-API-Key": "vfi_your_key_here"
      }
    }
  }
}

Same data, same limits: Both local and remote servers use the same API key and rate limits as the REST API.

Available MCP Tools

Once connected, your AI assistant can use these tools:

Tool	Description
get_company_profile	Company name, sector, industry, exchange
get_supply_chain	Upstream/downstream relationships (1-3 hops)
get_customers	All known customers with SEC citations
get_competitors	All known competitors with SEC citations
find_path	Shortest path between two companies
get_exposure	Supply chain concentration risk analysis
get_sector_graph	Full sector relationship subgraph

Try it:After configuring MCP, ask Claude: "What companies are in Apple's supply chain?" or "Find the path between Tesla and NVIDIA in the financial graph."