# finlight

> finlight is a financial news API delivering real-time, AI-enriched news articles with sentiment analysis, company/ticker entity resolution, and full-text content. Data is available via REST API, WebSocket streams, push Webhooks, and an MCP server for AI assistants. Official client libraries are published for TypeScript/JavaScript, Python, Go, .NET, Java/Kotlin, PHP, Ruby, and Rust — see "Client Libraries" below.

Key facts for integrating with finlight:

- REST base URL: `https://api.finlight.me` (current version: v2, e.g. `POST https://api.finlight.me/v2/articles`)
- Authentication: API key in the `X-API-KEY` request header. Get a free API key at https://app.finlight.me
- WebSocket (Enhanced, full article model): `wss://wss.finlight.me`
- WebSocket (Raw, lightweight/low-latency): `wss://wss.finlight.me/raw`
- Webhooks: push delivery of matching articles to your endpoint, configured at https://app.finlight.me/news-webhooks — available as Enriched (AI-processed) or Raw (fast, unenriched)
- MCP server (Model Context Protocol, Streamable HTTP): `https://mcp.finlight.me` — connect Claude, ChatGPT, or your own agents; auth via OAuth or `x-api-key` header; tools: `search_articles`, `get_article_by_link`, `list_sources`
- Rate limits: monthly request quota, burst rate, WebSocket connection count, and webhook delivery quota depend on your plan; see https://finlight.me/pricing
- Errors: standard HTTP status codes (400, 401, 403, 404, 422, 429, 500) with JSON error bodies

## Client Libraries

Full page with install commands and requirements for every language:
https://docs.finlight.me/en/v2/client-libraries/
Usage examples for each language are shown inline on the endpoint pages below —
every request example carries one tab per client library.

Eight official client libraries are published. They cover the same surface: REST (search
articles, fetch an article by link, list sources), real-time WebSocket streaming (enhanced
and raw) with auto-reconnect and keepalive, retries with exponential backoff, and
HMAC-SHA256 webhook signature verification with replay protection. The one exception is
PHP, which deliberately omits WebSocket streaming (use webhooks for push delivery into a
PHP application). Every library authenticates the same way as the raw API — the
`X-API-KEY` header.

- **TypeScript / JavaScript** — `npm install finlight-client` (npm: `finlight-client`, JSR: `@finlight/client`). Source: https://github.com/jubeiargh/finlight-client
- **Python** — `pip install finlight-client` (PyPI: `finlight-client`). Source: https://github.com/jubeiargh/finlight-client-py
- **Go** — `go get github.com/callbk/finlight-client-go` (requires Go 1.23+; streams are exposed as range-over-func iterators). Source: https://github.com/callbk/finlight-client-go
- **.NET / C#** — `dotnet add package Finlight.Client` (requires .NET 8+; streams are `IAsyncEnumerable`). Source: https://github.com/callbk/finlight-client-dotnet
- **Java / Kotlin (JVM)** — Maven Central coordinate `me.finlight:finlight-client` (requires Java 17+; JSpecify null-marked API, immutable records and builders for Kotlin interop; also available via JitPack). Source: https://github.com/callbk/finlight-client-java
- **PHP** — `composer require finlight/client` (Packagist: `finlight/client`, requires PHP 8.1+ and any PSR-18 HTTP client; REST and webhook verification only, no WebSocket). Source: https://github.com/callbk/finlight-client-php
- **Ruby** — `gem install finlight-client` (RubyGems: `finlight-client`, requires Ruby 3.2+). Source: https://github.com/callbk/finlight-client-ruby
- **Rust** — `cargo add finlight-client` (crates.io: `finlight-client`, requires Rust 1.85+; async on tokio, streams are `Stream`s; docs at https://docs.rs/finlight-client). Source: https://github.com/callbk/finlight-client-rust

## Getting Started

- [Quickstart](https://docs.finlight.me/en/v2/): Sign up, get a free API key, choose a client (TypeScript, Python, or raw HTTP), and make your first API call
- [Client Libraries](https://docs.finlight.me/en/v2/client-libraries/): All eight official SDKs — installation commands, runtime requirements, and source repositories for TypeScript/JavaScript, Python, Go, .NET, Java/Kotlin, PHP, Ruby, and Rust
- [REST API Basics](https://docs.finlight.me/en/v2/rest-basics/): Endpoint structure, API versioning, and authentication with the X-API-KEY header
- [REST Endpoints](https://docs.finlight.me/en/v2/rest-endpoints/): Full reference for POST /v2/articles (search articles), GET /v2/articles/by-link (fetch a single article), and GET /v2/sources (list supported sources), including the Article and Company response models
- [Errors & Status Codes](https://docs.finlight.me/en/v2/errors/): HTTP status codes and error response bodies, including validation, authentication, permission, and rate-limit errors, plus error-handling best practices
- [Rate Limits & Quotas](https://docs.finlight.me/en/v2/rate-limits/): The four usage limits (monthly quota, burst rate, WebSocket connections, webhook deliveries), plan capabilities, and enforcement behavior

## Query Language

- [Advanced Query Building](https://docs.finlight.me/en/v2/advanced-query-building/): Query syntax with boolean operators (AND, OR, NOT), field-level filtering (title, content, tickers, sources), phrase matching, language and multilingual coverage, pagination, and Raw WebSocket query fields

## WebSocket API

- [WebSocket Quickstart](https://docs.finlight.me/en/v2/websocket-quickstart/): Connect and receive real-time articles in minutes using the TypeScript or Python SDK
- [WebSocket Basics](https://docs.finlight.me/en/v2/websocket-basics/): Connection setup to wss://wss.finlight.me, API-key authentication, and the ping/pong keep-alive mechanism
- [Enhanced WebSocket — Subscribe](https://docs.finlight.me/en/v2/websocket-subscribe/): Subscribe to real-time articles with the full enriched article model (sentiment, companies, content)
- [Raw WebSocket — Subscribe](https://docs.finlight.me/en/v2/raw-websocket-subscribe/): Lightweight low-latency stream at wss://wss.finlight.me/raw delivering core article data without AI enrichment
- [Browser WebSocket](https://docs.finlight.me/en/v2/browser-websocket/): Connect directly from a browser with the native WebSocket API — connection URLs, query parameters, subscribe message format, and server message types

## Webhooks

- [Webhooks Quickstart](https://docs.finlight.me/en/v2/webhooks/): What webhooks are, and a step-by-step tutorial for creating and testing your first webhook in the dashboard
- [Enriched Webhooks](https://docs.finlight.me/en/v2/webhooks/enriched/): Full AI-processed article delivery with company entity resolution, sentiment analysis, and comprehensive filtering options
- [Raw Webhooks](https://docs.finlight.me/en/v2/webhooks/raw/): Fast, lightweight article delivery without AI enrichment, with query field-level filtering — ideal for high-throughput pipelines
- [Webhook Authentication](https://docs.finlight.me/en/v2/webhooks/authentication/): Securing webhook endpoints — X-Finlight-Key header, basic auth, HMAC signature validation, and security best practices
- [Testing Webhooks](https://docs.finlight.me/en/v2/webhooks/testing/): Dashboard tools for manual test deliveries, call history, monitoring, and debugging, plus endpoint implementation requirements
- [Webhooks — Good to Know](https://docs.finlight.me/en/v2/webhooks/good-to-know/): Retry logic, auto-disable protection after repeated failures, recovery/re-enabling, and quota management

## MCP Server (AI Assistants)

- [Connect Claude & ChatGPT](https://docs.finlight.me/en/v2/ai-assistants/): Set up the finlight MCP server in Claude Desktop or ChatGPT to search financial news, analyze sentiment, and research companies conversationally
- [MCP Developer Integration](https://docs.finlight.me/en/v2/ai-assistants/developers/): Programmatic MCP access at https://mcp.finlight.me — authentication (OAuth flow or x-api-key header), JSON-RPC protocol methods, tool reference (search_articles, get_article_by_link, list_sources), TypeScript/Python/cURL examples, error handling, and rate limits

## Support

- [Support & Contact](https://docs.finlight.me/en/v2/support/): Support channels (Discord, email), troubleshooting help, feature requests, and feedback

## Optional

- [Full documentation as a single file](https://docs.finlight.me/llms-full.txt): The complete content of all documentation pages, concatenated as plain markdown (llms-full.txt)
- Any single page as plain markdown: append `.md` to its URL — e.g. https://docs.finlight.me/en/v2/rest-basics.md (section landing pages too: https://docs.finlight.me/en/v2/webhooks.md; the v2 quickstart is https://docs.finlight.me/en/v2/index.md). Available in every documented locale (en, zh, hi, es, ja, ko, pt, ar, ru)
- [finlight Homepage](https://finlight.me): Product overview
- [Pricing & Plans](https://finlight.me/pricing): Free and paid plan comparison with quotas and capabilities
- [Dashboard](https://app.finlight.me): Sign up, manage API keys, configure webhooks, and monitor usage
- [Legacy v1 API Docs](https://docs.finlight.me/en/v1/): Documentation for the deprecated v1 REST and WebSocket APIs (new integrations should use v2)