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 10-K filings. The graph currently covers 5,200+ companies and 8,000+ relationships across 11 sectors.

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.

API 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
}

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	Paid (coming soon)
Requests per day	50	Contact us
Unique tickers per day	10	Contact us
Results per query	5	Contact us
Max hop depth	2	Contact us
Strength scores	Included	Contact us
SEC citations	All results	Contact us
Sector graph endpoint	Paid only	Contact 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 7 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."