Free Top Gainers API
Stock Movers & PythonTop Gainers API
Movers & Python
Compare sessions, closes, movers, fields, limits, and JSON before using top gainers in Python.
What a free top gainers API should accomplish
This page targets positive-momentum discovery. The useful output is not merely a descending percentage list: it is a session-aware candidate set that explains the comparison price, validates liquidity, detects split distortions, and can be joined to catalysts such as earnings, guidance, approvals, analyst actions, or M&A. It supports breakout scanners and research queues, not an automatic buy recommendation.
For most products, the safest default is a regular-session U.S. equity leaderboard ranked by an independently recalculated return from the adjusted prior close. Premarket and after-hours lists should be separate views because thin trading, wider spreads, and different reference times can otherwise make the same symbol appear to have conflicting gains.
Ranking definition: preserve current price, prior regular-session close, session, adjustment state, volume, and eligibility rule. A large premarket move, an unadjusted split, and a liquid regular-session breakout are three different events even if the percentage field is identical.
What a stock market top gainers API should return
Use the correct positive-return denominator
Require current price, prior regular close, absolute change, percentage change, adjustment flag, and session. Recalculate the percentage instead of trusting a preformatted string.
Filter for actionable liquidity
Store volume, relative volume, price, market cap, exchange, security type, and spread when available. A 300% move on one trade is not equivalent to broad participation.
Detect splits, IPO baselines, and stale closes
Check corporate actions and listing dates before ranking. New listings may lack a valid prior close, while split-adjustment timing can manufacture an apparent gain.
Attach catalyst and continuation context
Join earnings, filings, news, gaps, intraday high, and distance from the opening price. This distinguishes a current breakout from a stock that spiked early and already faded.
Separate sessions and quote states
Label premarket, regular, and after-hours observations explicitly. Preserve last trade, bid, ask, quote time, market status, and halt state so an old print is not presented as a current executable move.
Control low-price and one-tick distortion
Use a configurable price floor, minimum dollar volume, trade-count threshold, and maximum spread. A few cents of movement can create a spectacular percentage on a very low-priced security without producing a durable or tradable signal.
Free stock market gainers API sources to evaluate
The providers below document market-mover or gainers endpoints, but their lists are not interchangeable. Treat the table as a starting point for verification rather than an endorsement because access and terms can change. Do not compare providers by row count alone. First write down the market, eligible security types, session, baseline price, minimum liquidity, refresh interval, and licensing required by your application, then test the same event-day sample against every candidate.
| Source | Useful signal | Verify before use |
|---|---|---|
| Alpha Vantage | Official documentation lists TOP_GAINERS_LOSERS, returning 20 U.S. gainers, losers, and most-active tickers. | Free-key quota, default data freshness, exchange entitlements, and production terms. |
| Massive | Its Top Market Movers endpoint documents the top 20 U.S. gainers or losers and a minimum-volume filter. | Current plan access, snapshot timing, market delay, and redistribution rights. |
| Financial Modeling Prep | Its Market Top Gainers page exposes a gainers endpoint and fields such as symbol, name, price, and change. | Current endpoint path, free-plan availability, quota, freshness, and security types included. |
| Webull | Official docs support gainers/losers ranking by period, category, sort field, and sort direction. | App credentials, sandbox versus production, supported market, signature flow, and access approval. |
Top gainers API Python example and validation
Rebuild the leaderboard from normalized source rows instead of accepting a provider’s formatted percentage. The example below creates a regular-session gainers list with explicit price, dollar-volume, baseline, and adjustment rules.
from decimal import Decimal, InvalidOperation
def build_top_gainers(
rows: list[dict],
minimum_price: Decimal = Decimal("1"),
minimum_dollar_volume: Decimal = Decimal("1000000"),
limit: int = 20,
) -> list[dict]:
eligible = []
for row in rows:
if row.get("session") != "regular" or row.get("market_status") != "open":
continue
if row.get("security_type") != "common_stock":
continue
if row.get("prior_close_adjusted") is not True:
continue
if row.get("corporate_action_status") not in {None, "resolved"}:
continue
try:
current = Decimal(str(row["current_price"]))
prior_close = Decimal(str(row["prior_regular_close"]))
volume = Decimal(str(row["volume"]))
except (KeyError, InvalidOperation):
continue
if current < minimum_price or prior_close <= 0 or volume < 0:
continue
dollar_volume = current * volume
if dollar_volume < minimum_dollar_volume:
continue
change_pct = ((current / prior_close) - Decimal("1")) * Decimal("100")
if change_pct <= 0:
continue
eligible.append({
"symbol": row["symbol"],
"exchange": row["exchange"],
"current_price": current,
"prior_regular_close": prior_close,
"change_pct": change_pct,
"dollar_volume": dollar_volume,
"source_timestamp": row["source_timestamp"],
"rule_version": "regular-gainers-v1",
})
eligible.sort(key=lambda item: (-item["change_pct"], item["symbol"]))
for rank, item in enumerate(eligible[:limit], start=1):
item["rank"] = rank
return eligible[:limit]Filtering is part of the ranking definition. Changing the minimum price, dollar-volume floor, security types, session, or adjustment policy changes the candidate universe and therefore every rank. Store the rule version and the excluded-row reasons with each snapshot so the list can be reproduced later.
1. Rebuild the positive return
Parse current price and prior regular close as decimals, apply the provider’s split-adjustment convention, and calculate (current / prior_close - 1) × 100. Reject rows without a valid denominator.
2. Apply momentum eligibility rules
Filter by exchange, security type, minimum price, market cap, dollar volume, relative volume, and spread before sorting. Save the rule version with the resulting list.
3. Add breakout and catalyst fields
Enrich each candidate with opening gap, intraday high, distance from high, volume versus average, earnings or filing event, and relevant news. The percentage rank becomes a research queue rather than a blind signal.
4. Track list entry, persistence, and exit
Store the first time a symbol entered the gainers set, peak rank, consecutive observations, and time of exit. This reveals whether momentum persisted or resulted from one early print.
5. Reconcile the ranking against raw bars
For a sample of ordinary days, earnings gaps, splits, IPOs, halts, and resumed trading, fetch the underlying close and intraday bars. Recompute the move, inspect excluded symbols, and record whether differences come from timing, adjustment, universe, or stale data.
6. Store point-in-time snapshots
Persist provider timestamp, retrieval time, rank, raw values, normalized values, and filter version. Backtests must use the list visible at that moment rather than the final end-of-day leaderboard, which contains information unavailable earlier.
How QVeris helps connect market movers APIs
QVeris does not publish stock rankings, grant exchange licenses, or guarantee a provider’s feed. It helps developers and agents discover available financial-data capabilities, inspect interfaces, and connect a selected external tool through a consistent workflow.
- Open the Alpha Vantage Top Gainers & Losers tool details to inspect the exact market-movers capability.
- Inspect inputs, outputs, authentication, supported markets, provider documentation, timestamps, session definitions, and adjustment conventions before connecting.
- Pass market, session, eligible universe, liquidity thresholds, freshness tolerance, and desired output schema as explicit tool requirements rather than leaving the agent to infer them.
- Use the QVeris Capability Map to explore adjacent data tools; connectivity and rankings are not investment advice.
Free top gainers API FAQ
Is there a free API for top gaining stocks?
Yes. Some providers offer a free key or trial. Verify market coverage, data delay, quota, fields, licensing, and whether the endpoint remains in the current plan.
Which API returns top gainers and losers?
Alpha Vantage, Massive, FMP, and Webull document market movers or ranking endpoints. Their authentication and access terms differ.
Can I get real-time top gainers data for free?
Sometimes, but free responses may be delayed or end-of-day. Read the result timestamp and provider entitlement notes.
How do I call a top gainers API in Python?
Send a documented GET request, raise for HTTP errors, parse JSON, normalize percentage change, and verify the largest valid percentage gains sort first.
What fields should a stock gainers API return?
Look for symbol, name, price, change, percentage change, volume, market, timestamp, and explicit error or status fields.
Why do very cheap stocks dominate some gainers lists?
A one- or two-cent move can create a large percentage when the starting price is tiny. Add minimum price, dollar-volume, trade-count, and spread filters, then inspect the raw trades before treating the move as meaningful.
How should splits and IPOs be handled?
Use an adjusted prior close for split-affected securities and exclude rows without a comparable baseline. A new listing with no previous regular close should be labeled separately instead of forced into the same return formula.
Why do two top gainers APIs disagree?
They may use different snapshots, sessions, universes, reference closes, adjustment rules, liquidity filters, or quote entitlements. Compare the raw inputs and contract definitions before assuming one ranking is wrong.