openapi: 3.2.0 info: title: 2s — the (most) everything Stocks API version: '1' summary: The (most) everything API. description: 'The (most) everything API for AI agents: 575+ pay-per-call endpoints on one origin.' contact: name: 2s url: https://2s.io email: alley@2s.io x-logo: url: https://2s.io/icon-512.png altText: 2s x-guidance: 'Pay-per-call REST API for AI agents — hundreds of endpoints returning ground-truth data (US public records, company & legal identifiers, finance/SEC, crypto/web3, security & CVEs, medical codes, weather & geocoding, agriculture, energy, maritime, music, and more). Every endpoint is paid per call in USDC via x402 (Base or Solana) — no API key, no signup. Call any endpoint with no auth to get a 402 PaymentRequirements envelope, sign it (EIP-3009 on Base, partial SPL transfer on Solana), and retry with the PAYMENT-SIGNATURE header. Add ?trial=1 for one free real call per endpoint per hour to test before paying. To discover the right endpoint: GET https://2s.io/api/directory for the full catalog, or GET https://2s.io/api/search/endpoints?q= for a ranked match. Per-call price is on each operation as x-payment-info (from $0.001). Batch up to 50 calls behind one payment via POST https://2s.io/api/batch/run.' servers: - url: https://2s.io tags: - name: Stocks paths: /api/stocks/company-news: get: tags: - Stocks summary: Recent news articles about a specific US-listed company description: Recent news articles about a specific US-listed company. Pass ticker and optionally a from/to date window (YYYY-MM-DD; defaults to the last 14 days); returns headlines with source, summary, URL, image, related symbol, category, and publish time (newest first). Use it to catch up on what is being written about a company. News aggregated by Finnhub. operationId: stocks_company-news deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized: items = company news articles, newest first.' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: datetime: type: string nullable: true description: Publish time (ISO 8601). headline: type: string nullable: true source: type: string nullable: true summary: type: string nullable: true url: type: string nullable: true image: type: string nullable: true category: type: string nullable: true related: type: string nullable: true id: type: number nullable: true required: - datetime - headline - source - summary - url - image - category - related - id additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' meta: type: object properties: symbol: type: string from: type: string to: type: string required: - symbol - from - to additionalProperties: false required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.company-news x-2s-version: null x-2s-price: usd: 0.0025 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.002500' protocols: - x402: {} parameters: - name: ticker in: query required: true description: US-listed ticker symbol. schema: type: string minLength: 1 maxLength: 12 pattern: ^[A-Za-z][A-Za-z0-9.\-]{0,11}$ - name: from in: query required: false description: 'Earliest article date YYYY-MM-DD (default: 14 days ago).' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: to in: query required: false description: 'Latest article date YYYY-MM-DD (default: today).' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: limit in: query required: false description: Max articles to return (default 100). schema: type: integer minimum: 1 maximum: 250 - $ref: '#/components/parameters/TrialMode' /api/stocks/earnings-surprises: get: tags: - Stocks summary: Historical quarterly earnings surprises for a US-listed description: Historical quarterly earnings surprises for a US-listed company — reported (actual) EPS vs the analyst consensus estimate, the absolute surprise, and the surprise percentage, for the most recent quarters (newest first). Pass ticker (optionally limit). Tells you whether a company has been beating or missing expectations. Data by Finnhub. operationId: stocks_earnings-surprises deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized: items = quarterly EPS actual-vs-estimate, newest first.' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: period: type: string description: Fiscal period end date (yyyy-mm-dd). actual: type: number nullable: true description: Reported EPS. estimate: type: number nullable: true description: Consensus estimated EPS. surprise: type: number nullable: true description: actual − estimate. surprisePercent: type: number nullable: true quarter: type: number nullable: true year: type: number nullable: true required: - period - actual - estimate - surprise - surprisePercent - quarter - year additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' meta: type: object properties: symbol: type: string required: - symbol additionalProperties: false required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.earnings-surprises x-2s-version: null x-2s-price: usd: 0.0025 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.002500' protocols: - x402: {} parameters: - name: ticker in: query required: true description: US-listed ticker symbol. schema: type: string minLength: 1 maxLength: 12 pattern: ^[A-Za-z][A-Za-z0-9.\-]{0,11}$ - name: limit in: query required: false description: Max quarters to return (default all available, usually 4). schema: type: integer minimum: 1 maximum: 40 - $ref: '#/components/parameters/TrialMode' /api/stocks/financials-reported: get: tags: - Stocks summary: As-reported financial statements for a US-listed company description: As-reported financial statements for a US-listed company, exactly as filed with the SEC — balance sheet, income statement, and cash-flow statement line items, parsed from each 10-K/10-Q. Pass ticker and optionally freq (annual or quarterly) and limit; returns the most recent filings (newest first) with filing metadata (form, period, filed date, accession) and the full report under `report`. Data by Finnhub. operationId: stocks_financials-reported deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized: items = as-reported filings (newest first), each with the full report.' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: symbol: type: string nullable: true cik: type: string nullable: true year: type: number nullable: true quarter: type: number nullable: true form: type: string nullable: true startDate: type: string nullable: true endDate: type: string nullable: true filedDate: type: string nullable: true accessNumber: type: string nullable: true report: type: object additionalProperties: {} description: 'As-reported statements: { bs, ic, cf } line-item arrays.' required: - symbol - cik - year - quarter - form - startDate - endDate - filedDate - accessNumber - report additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' meta: type: object properties: symbol: type: string freq: type: string required: - symbol - freq additionalProperties: false required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.financials-reported x-2s-version: null x-2s-price: usd: 0.0025 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.002500' protocols: - x402: {} parameters: - name: ticker in: query required: true description: US-listed ticker symbol. schema: type: string minLength: 1 maxLength: 12 pattern: ^[A-Za-z][A-Za-z0-9.\-]{0,11}$ - name: freq in: query required: false description: 'Statement frequency. Default: annual.' schema: type: string enum: - annual - quarterly - name: limit in: query required: false description: Max filings to return (default 4). schema: type: integer minimum: 1 maximum: 20 - $ref: '#/components/parameters/TrialMode' /api/stocks/gov-spending: get: tags: - Stocks summary: US federal government spending awarded to a public company description: US federal government spending awarded to a public company (sourced from USAspending). Pass ticker and optionally a from/to window (YYYY-MM-DD; defaults to ~2 years); returns each award with the recipient (and parent), awarding agency/sub-agency, obligated/outlayed/potential/total values in USD, action date, and period of performance. Use it to see how much federal money flows to a company. Data by Finnhub. operationId: stocks_gov-spending deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized: items = federal award records (newest first).' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: symbol: type: string nullable: true recipientName: type: string nullable: true recipientParentName: type: string nullable: true awardingAgencyName: type: string nullable: true awardingSubAgencyName: type: string nullable: true totalValue: type: number nullable: true obligatedAmount: type: number nullable: true outlayedAmount: type: number nullable: true potentialAmount: type: number nullable: true actionDate: type: string nullable: true performanceStartDate: type: string nullable: true performanceEndDate: type: string nullable: true required: - symbol - recipientName - recipientParentName - awardingAgencyName - awardingSubAgencyName - totalValue - obligatedAmount - outlayedAmount - potentialAmount - actionDate - performanceStartDate - performanceEndDate additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' meta: type: object properties: symbol: type: string from: type: string to: type: string required: - symbol - from - to additionalProperties: false required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.gov-spending x-2s-version: null x-2s-price: usd: 0.0025 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.002500' protocols: - x402: {} parameters: - name: ticker in: query required: true description: US-listed ticker symbol. schema: type: string minLength: 1 maxLength: 12 pattern: ^[A-Za-z][A-Za-z0-9.\-]{0,11}$ - name: from in: query required: false description: 'Earliest action date YYYY-MM-DD (default: ~2 years ago).' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: to in: query required: false description: 'Latest action date YYYY-MM-DD (default: today).' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: limit in: query required: false description: Max awards to return (default 100). schema: type: integer minimum: 1 maximum: 500 - $ref: '#/components/parameters/TrialMode' /api/stocks/h1b-visas: get: tags: - Stocks summary: US work-visa (H-1B and related) applications filed by a description: US work-visa (H-1B and related) applications filed by a public company, sourced from Department of Labor LCA disclosures. Pass ticker and optionally a from/to window (YYYY-MM-DD; defaults to ~2 years); returns each application with job title, SOC code, visa class, case status, wage range, worksite city/state, employment dates, and case number. Use it as a hiring/headcount signal. Data by Finnhub. operationId: stocks_h1b-visas deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized: items = work-visa applications (newest first).' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: symbol: type: string nullable: true year: type: number nullable: true quarter: type: number nullable: true caseNumber: type: string nullable: true caseStatus: type: string nullable: true visaClass: type: string nullable: true jobTitle: type: string nullable: true socCode: type: string nullable: true wageRangeFrom: type: number nullable: true wageRangeTo: type: number nullable: true employerName: type: string nullable: true worksiteCity: type: string nullable: true worksiteState: type: string nullable: true beginDate: type: string nullable: true endDate: type: string nullable: true required: - symbol - year - quarter - caseNumber - caseStatus - visaClass - jobTitle - socCode - wageRangeFrom - wageRangeTo - employerName - worksiteCity - worksiteState - beginDate - endDate additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' meta: type: object properties: symbol: type: string from: type: string to: type: string required: - symbol - from - to additionalProperties: false required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.h1b-visas x-2s-version: null x-2s-price: usd: 0.0025 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.002500' protocols: - x402: {} parameters: - name: ticker in: query required: true description: US-listed ticker symbol. schema: type: string minLength: 1 maxLength: 12 pattern: ^[A-Za-z][A-Za-z0-9.\-]{0,11}$ - name: from in: query required: false description: 'Earliest received date YYYY-MM-DD (default: ~2 years ago).' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: to in: query required: false description: 'Latest received date YYYY-MM-DD (default: today).' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: limit in: query required: false description: Max applications to return (default 100). schema: type: integer minimum: 1 maximum: 500 - $ref: '#/components/parameters/TrialMode' /api/stocks/insider-sentiment: get: tags: - Stocks summary: Aggregated insider sentiment for a US-listed company, by month description: Aggregated insider sentiment for a US-listed company, by month. For each month returns the net change in insider share holdings and Finnhub's MSPR (Monthly Share Purchase Ratio, −100 to +100 — higher means more net insider buying). Pass ticker and optionally a from/to window (YYYY-MM-DD; defaults to ~1 year). A distilled signal layered on top of raw insider filings. Data by Finnhub. operationId: stocks_insider-sentiment deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized: items = monthly insider sentiment rows.' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: symbol: type: string nullable: true year: type: number nullable: true month: type: number nullable: true change: type: number nullable: true description: Net change in insider share holdings for the month. mspr: type: number nullable: true description: Monthly Share Purchase Ratio, −100..+100. required: - symbol - year - month - change - mspr additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' meta: type: object properties: symbol: type: string from: type: string to: type: string required: - symbol - from - to additionalProperties: false required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.insider-sentiment x-2s-version: null x-2s-price: usd: 0.0025 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.002500' protocols: - x402: {} parameters: - name: ticker in: query required: true description: US-listed ticker symbol. schema: type: string minLength: 1 maxLength: 12 pattern: ^[A-Za-z][A-Za-z0-9.\-]{0,11}$ - name: from in: query required: false description: 'Earliest month date YYYY-MM-DD (default: ~1 year ago).' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: to in: query required: false description: 'Latest month date YYYY-MM-DD (default: today).' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - $ref: '#/components/parameters/TrialMode' /api/stocks/lobbying: get: tags: - Stocks summary: US federal lobbying disclosures for a public company description: US federal lobbying disclosures for a public company (sourced from US Senate LDA filings). Pass ticker and optionally a from/to window (YYYY-MM-DD; defaults to ~3 years); returns each filing with the registrant name, the period (year + quarter), reported lobbying income/expenses in USD, and a link to the official Senate filing. Use it to track a company’s lobbying spend over time. Data by Finnhub. operationId: stocks_lobbying deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized: items = lobbying filings (newest first).' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: symbol: type: string nullable: true name: type: string nullable: true description: type: string nullable: true year: type: number nullable: true period: type: string nullable: true income: type: number nullable: true description: Reported lobbying income (USD). expenses: type: number nullable: true description: Reported lobbying expenses (USD). documentUrl: type: string nullable: true required: - symbol - name - description - year - period - income - expenses - documentUrl additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' meta: type: object properties: symbol: type: string from: type: string to: type: string required: - symbol - from - to additionalProperties: false required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.lobbying x-2s-version: null x-2s-price: usd: 0.0025 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.002500' protocols: - x402: {} parameters: - name: ticker in: query required: true description: US-listed ticker symbol. schema: type: string minLength: 1 maxLength: 12 pattern: ^[A-Za-z][A-Za-z0-9.\-]{0,11}$ - name: from in: query required: false description: 'Earliest filing date YYYY-MM-DD (default: ~3 years ago).' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: to in: query required: false description: 'Latest filing date YYYY-MM-DD (default: today).' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: limit in: query required: false description: Max filings to return (default 100). schema: type: integer minimum: 1 maximum: 500 - $ref: '#/components/parameters/TrialMode' /api/stocks/metrics: get: tags: - Stocks summary: Key fundamental metrics and 52-week price statistics for a description: Key fundamental metrics and 52-week price statistics for a US-listed company. Pass ticker; returns headline valuation, margin, and per-share figures — P/E, P/B, P/S, PEG, EV/EBITDA, gross/operating/net margins, ROE, ROA, current ratio, debt/equity, dividend yield, beta, 52-week high/low, and YTD/52-week price returns — plus the full Finnhub metric map under `metric`. Computed ratios you would otherwise derive yourself from raw filings. Market & fundamental data by Finnhub. operationId: stocks_metrics deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized: items = [one company’s key metrics + the full metric map]; total = 1.' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: ticker: type: string peTTM: type: number nullable: true psTTM: type: number nullable: true pbAnnual: type: number nullable: true pegTTM: type: number nullable: true evEbitdaTTM: type: number nullable: true grossMarginTTM: type: number nullable: true operatingMarginTTM: type: number nullable: true netMarginTTM: type: number nullable: true roeTTM: type: number nullable: true roaTTM: type: number nullable: true currentRatioAnnual: type: number nullable: true debtToEquityAnnual: type: number nullable: true dividendYield: type: number nullable: true beta: type: number nullable: true week52High: type: number nullable: true week52Low: type: number nullable: true priceReturnYTD: type: number nullable: true priceReturn52Week: type: number nullable: true metric: type: object additionalProperties: {} description: Full Finnhub metric map (all computed ratios). required: - ticker - peTTM - psTTM - pbAnnual - pegTTM - evEbitdaTTM - grossMarginTTM - operatingMarginTTM - netMarginTTM - roeTTM - roaTTM - currentRatioAnnual - debtToEquityAnnual - dividendYield - beta - week52High - week52Low - priceReturnYTD - priceReturn52Week - metric additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.metrics x-2s-version: null x-2s-price: usd: 0.0025 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.002500' protocols: - x402: {} parameters: - name: ticker in: query required: true description: US-listed ticker symbol. schema: type: string minLength: 1 maxLength: 12 pattern: ^[A-Za-z][A-Za-z0-9.\-]{0,11}$ - $ref: '#/components/parameters/TrialMode' /api/stocks/patents: get: tags: - Stocks summary: USPTO patent activity associated with a public company description: USPTO patent activity associated with a public company. Pass ticker and optionally a from/to window (YYYY-MM-DD; defaults to ~2 years); returns each record with the application number, patent number (when granted), the filing company name(s), description/title, patent type, filing status, filing and publication dates, and a document URL. A company-level innovation/R&D signal (distinct from our keyword patent search). Data by Finnhub. operationId: stocks_patents deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized: items = patent records (newest first).' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: symbol: type: string nullable: true applicationNumber: type: string nullable: true patentNumber: type: string nullable: true companyFilingName: type: array items: type: string description: Filing company name(s). description: type: string nullable: true patentType: type: string nullable: true filingStatus: type: string nullable: true filingDate: type: string nullable: true publicationDate: type: string nullable: true url: type: string nullable: true required: - symbol - applicationNumber - patentNumber - companyFilingName - description - patentType - filingStatus - filingDate - publicationDate - url additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' meta: type: object properties: symbol: type: string from: type: string to: type: string required: - symbol - from - to additionalProperties: false required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.patents x-2s-version: null x-2s-price: usd: 0.0025 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.002500' protocols: - x402: {} parameters: - name: ticker in: query required: true description: US-listed ticker symbol. schema: type: string minLength: 1 maxLength: 12 pattern: ^[A-Za-z][A-Za-z0-9.\-]{0,11}$ - name: from in: query required: false description: 'Earliest filing date YYYY-MM-DD (default: ~2 years ago).' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: to in: query required: false description: 'Latest filing date YYYY-MM-DD (default: today).' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ - name: limit in: query required: false description: Max records to return (default 100). schema: type: integer minimum: 1 maximum: 500 - $ref: '#/components/parameters/TrialMode' /api/stocks/peers: get: tags: - Stocks summary: Peer companies for a US-listed ticker - other companies in description: Peer companies for a US-listed ticker — other companies in the same sector and sub-industry, useful for comparables, relative valuation, and screening. Pass ticker (optionally grouping to control how peers are grouped); returns a ranked list of peer ticker symbols (the input symbol is usually first). Data by Finnhub. operationId: stocks_peers deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized: items = [{ ticker }] peer companies; meta.symbol echoes the input.' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: ticker: type: string required: - ticker additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' meta: type: object properties: symbol: type: string required: - symbol additionalProperties: false required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.peers x-2s-version: null x-2s-price: usd: 0.0025 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.002500' protocols: - x402: {} parameters: - name: ticker in: query required: true description: US-listed ticker symbol. schema: type: string minLength: 1 maxLength: 12 pattern: ^[A-Za-z][A-Za-z0-9.\-]{0,11}$ - name: grouping in: query required: false description: 'How to group peers. Default: sub-industry.' schema: type: string enum: - sector - industry - subIndustry - $ref: '#/components/parameters/TrialMode' /api/stocks/quote: get: tags: - Stocks summary: Latest daily stock quote for a US-listed ticker description: 'Latest daily stock quote for a US-listed ticker. Returns the most recent completed trading session: open, high, low, close, volume, VWAP, and trade count, plus the change and percent change versus the prior session, and company reference data (name, primary exchange, security type, currency, market cap). NOTE: this plan tier serves end-of-day / delayed data (the response flags delayed=true), suitable for daily snapshots, fundamentals context, and post-close analysis rather than real-time trading. Pass ticker as a US symbol (e.g. AAPL, MSFT, BRK.B). Market data by Massive (formerly Polygon.io).' operationId: stocks_quote deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized envelope: items = [one ticker’s latest daily quote with change vs prior session + company metadata]; total = 1.' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: ticker: type: string name: type: string nullable: true exchange: type: string nullable: true description: Primary listing exchange MIC, e.g. XNAS, XNYS. type: type: string nullable: true description: Security type, e.g. CS (common stock), ETF. currency: type: string nullable: true marketCapUSD: type: number nullable: true date: type: string description: Date of the latest completed daily bar (yyyy-mm-dd). open: type: number nullable: true high: type: number nullable: true low: type: number nullable: true close: type: number nullable: true volume: type: number nullable: true vwap: type: number nullable: true description: Volume-weighted average price for the bar. transactions: type: number nullable: true previousClose: type: number nullable: true change: type: number nullable: true description: close − previousClose. changePercent: type: number nullable: true delayed: type: boolean description: True — this tier serves end-of-day / delayed data, not real-time. required: - ticker - name - exchange - type - currency - marketCapUSD - date - open - high - low - close - volume - vwap - transactions - previousClose - change - changePercent - delayed additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.quote x-2s-version: null x-2s-price: usd: 0.0045 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.004500' protocols: - x402: {} parameters: - name: ticker in: query required: true description: US-listed ticker symbol. schema: type: string minLength: 1 maxLength: 12 pattern: ^[A-Za-z][A-Za-z0-9.\-]{0,11}$ - $ref: '#/components/parameters/TrialMode' /api/stocks/recommendations: get: tags: - Stocks summary: Analyst recommendation trend for a US-listed company - the description: Analyst recommendation trend for a US-listed company — the number of analysts rating it strong buy, buy, hold, sell, and strong sell, snapshotted per month (newest first). Pass ticker. Use it to see the consensus and how sentiment is shifting over time. Data by Finnhub. operationId: stocks_recommendations deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized: items = monthly analyst-rating counts, newest first.' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: period: type: string description: Month of the snapshot (yyyy-mm-dd). strongBuy: type: number nullable: true buy: type: number nullable: true hold: type: number nullable: true sell: type: number nullable: true strongSell: type: number nullable: true required: - period - strongBuy - buy - hold - sell - strongSell additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' meta: type: object properties: symbol: type: string required: - symbol additionalProperties: false required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.recommendations x-2s-version: null x-2s-price: usd: 0.0025 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.002500' protocols: - x402: {} parameters: - name: ticker in: query required: true description: US-listed ticker symbol. schema: type: string minLength: 1 maxLength: 12 pattern: ^[A-Za-z][A-Za-z0-9.\-]{0,11}$ - $ref: '#/components/parameters/TrialMode' /api/stocks/screener: get: tags: - Stocks summary: Fundamental stock screener built on SEC EDGAR XBRL Frames description: 'Fundamental stock screener built on SEC EDGAR XBRL Frames — screen every public filer on a reported financial concept for one period, in a single call. Absolute mode: give a concept (e.g. Revenues, NetIncomeLoss, Assets), a period (CY2023 annual, CY2024Q1 quarter, CY2024Q1I instant), and an optional op/value to filter (e.g. Revenues gte 10000000000 → companies with >= $10B FY2023 revenue). Ratio mode: add ratioConcept to compute concept / ratioConcept per company joined by CIK, then op/value filter the ratio (e.g. concept=GrossProfit, ratioConcept=Revenues, op=gte, value=0.7 → gross margin >= 70%). Returns matching companies with CIK, entity name, value (and ratio), sorted, plus meta with the total matched and the screenable universe size. Free, public-domain (SEC EDGAR).' operationId: stocks_screener deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized envelope: items = matching companies (sorted by value/ratio, sliced to limit); total = total matched; meta carries concept/ratioConcept/period/unit/totalMatched/totalUniverse.' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: cik: type: number entityName: type: string nullable: true value: type: number ratio: type: number required: - cik - entityName - value additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.screener x-2s-version: null x-2s-price: usd: 0.012 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.012000' protocols: - x402: {} parameters: - name: concept in: query required: true description: XBRL us-gaap concept, e.g. Revenues, GrossProfit, NetIncomeLoss, Assets. schema: type: string pattern: ^[A-Za-z0-9]+$ minLength: 2 maxLength: 80 - name: period in: query required: true description: CY2023 (annual), CY2024Q1 (quarter), CY2024Q1I (instant, for balance-sheet items). schema: type: string pattern: ^CY\d{4}(Q[1-4]I?)?$ - name: unit in: query required: false description: Unit (default USD). schema: type: string minLength: 1 maxLength: 20 - name: op in: query required: false description: Comparison operator (with value). Filters the concept value, or the ratio when ratioConcept is set. schema: type: string enum: - gt - gte - lt - lte - name: value in: query required: false description: Comparison threshold (with op). For ratios use a fraction, e.g. 0.7 for 70%. schema: type: number - name: ratioConcept in: query required: false description: Optional second XBRL concept; computes ratio = concept / ratioConcept per company (joined by CIK), and op/value then filter the ratio. schema: type: string pattern: ^[A-Za-z0-9]+$ minLength: 2 maxLength: 80 - name: sort in: query required: false description: Sort by value/ratio (default desc). schema: type: string enum: - asc - desc - name: limit in: query required: false description: Max companies (1-100, default 25). schema: type: integer minimum: 1 maximum: 100 - $ref: '#/components/parameters/TrialMode' /api/stocks/symbols: get: tags: - Stocks summary: Search or list the tradable equity symbol universe for an description: Search or list the tradable equity symbol universe for an exchange. Pass q to substring-match on symbol or company name (case-insensitive), and/or exchange (default US) and limit. Returns matching listings with symbol, display symbol, description (company name), security type (e.g. Common Stock, ETF), currency, MIC, and FIGI. Use it to resolve a name to a ticker or enumerate a market. Data by Finnhub. operationId: stocks_symbols deprecated: false security: - x402Payment: [] responses: '200': description: 'Normalized: items = matching symbols; total = matched count (capped to limit in items).' content: application/json: schema: type: object required: - data - meta properties: data: type: object properties: ok: type: boolean enum: - true items: type: array items: type: object properties: symbol: type: string nullable: true displaySymbol: type: string nullable: true description: type: string nullable: true type: type: string nullable: true currency: type: string nullable: true mic: type: string nullable: true figi: type: string nullable: true required: - symbol - displaySymbol - description - type - currency - mic - figi additionalProperties: false total: type: integer nullable: true description: Total matching rows upstream; null when unknown. source: $ref: '#/components/schemas/Source' meta: type: object properties: exchange: type: string q: type: string nullable: true matched: type: integer required: - exchange - q - matched additionalProperties: false required: - ok - items - total - source additionalProperties: false meta: $ref: '#/components/schemas/CallMeta' '400': $ref: '#/components/responses/BadRequest' '402': $ref: '#/components/responses/PaymentRequired' '405': $ref: '#/components/responses/MethodNotAllowed' '500': $ref: '#/components/responses/ServerError' '502': $ref: '#/components/responses/UpstreamError' x-2s-id: stocks.symbols x-2s-version: null x-2s-price: usd: 0.0025 x-2s-accepts: - x402 x-2s-response-shape: normalized x-payment-info: price: mode: fixed currency: USD amount: '0.002500' protocols: - x402: {} parameters: - name: q in: query required: false description: Substring match on symbol or company name (case-insensitive). schema: type: string minLength: 1 maxLength: 64 - name: exchange in: query required: false description: Exchange code (default US). schema: type: string minLength: 1 maxLength: 8 pattern: ^[A-Za-z]+$ - name: limit in: query required: false description: Max rows to return (default 50). schema: type: integer minimum: 1 maximum: 500 - $ref: '#/components/parameters/TrialMode' components: schemas: Source: type: object description: 'Provenance of the data: upstream provider, source URL, and license.' properties: provider: type: string description: Upstream data provider. url: type: string description: Source URL or documentation link. license: type: string description: License / usage terms for the data. CallMeta: type: object description: Per-call meta envelope — endpoint id, cost, caller kind, settlement details. X402PaymentRequiredV2: type: object description: x402 v2 PaymentRequired envelope. Pick any entry from accepts[], sign for that rail, retry with the PAYMENT-SIGNATURE header. required: - x402Version - accepts properties: x402Version: type: integer const: 2 error: type: string description: Human-readable reason payment is required. resource: type: string description: The resource URL being purchased. accepts: type: array description: Payment requirement options, one per supported network (Base USDC, Solana USDC). items: type: object required: - scheme - network - amount - asset - payTo - maxTimeoutSeconds properties: scheme: type: string enum: - exact network: type: string description: CAIP-2 network id, e.g. "eip155:8453" (Base) or "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp". amount: type: string description: Price in atomic asset units (USDC has 6 decimals). asset: type: string description: Asset contract address / mint. payTo: type: string description: Treasury address to pay. maxTimeoutSeconds: type: integer extra: type: object description: 'Rail-specific extras (EVM: EIP-712 domain name/version; Solana: feePayer).' additionalProperties: true extensions: type: object description: Optional discovery metadata (e.g. bazaar input/output schemas). additionalProperties: true responses: PaymentRequired: description: Payment required. Body contains the x402 PaymentRequirements envelope with a multi-network accepts array; the per-call price is in accepts[].amount (and on the operation as x-2s-price). Sign for whichever rail you hold USDC on (EIP-3009 for Base, partial SPL transfer for Solana) and retry with the PAYMENT-SIGNATURE header (X-PAYMENT also accepted for v1 clients). content: application/json: schema: $ref: '#/components/schemas/X402PaymentRequiredV2' UpstreamError: description: Upstream provider error. MethodNotAllowed: description: Method not allowed — see `Allow` header for the supported method. ServerError: description: Internal server error. BadRequest: description: Bad request — invalid parameters. parameters: TrialMode: name: trial in: query required: false description: 'Try before you buy. Set to 1 for one free real call per endpoint per hour — no wallet or payment needed — to verify the endpoint before paying. Equivalent to sending the "X-2s-Trial: 1" request header. Works on every endpoint.' schema: type: integer enum: - 1 securitySchemes: x402Payment: type: apiKey in: header name: PAYMENT-SIGNATURE description: 'x402 protocol v2: base64-encoded PaymentPayload. Call any paid endpoint without auth to receive a 402 with a multi-network PaymentRequirements envelope. Sign for either rail: EIP-3009 transferWithAuthorization (Base USDC) OR a partial SPL token transfer (Solana USDC). Retry with PAYMENT-SIGNATURE header. X-PAYMENT is also accepted for v1 buyer clients. See https://x402.org.'