Skip to main content
AGG News Feed connects real-world news to tradeable prediction markets. Use it to power category feeds, market detail pages, related-news modules, and agent workflows with articles that are already linked to markets and summarized for market impact. Instead of showing generic news links, partner apps can show why a story may matter to a specific prediction market. News Feed is an app-tier Discovery API for market-aware articles, live market links, and market-impact summaries.

Public API access

All News Feed endpoints require your app header:
x-app-id
string
required
Your AGG app identifier.
No user JWT is required. App venue and category settings are applied automatically, so responses only include markets your app is configured to show.

Endpoint map

API ReferenceUse when
List feedsYou want the available feed categories and item counts.
Get article feedYou want an article-first feed with linked markets for each article.
Get market feedYou want a market-first feed where each market includes recent related articles.
Get market newsYou have specific markets or events and want recent articles for them.
Available categories are politics, geopolitics, world, finance, climate, and entertainment.

What you get

  • Article-first feeds for discovery pages and editorial-style layouts.
  • Market-first feeds where each market carries its recent article timeline.
  • On-demand related-news lookup for specific venueMarketIds or venueEventIds.
  • Article metadata, publisher/source labels, images when available, publish timestamps, and links to original sources.
  • LLM-generated market-impact summaries and relevance scores for ranking related articles.
  • App-scoped filtering so disabled venues and categories do not leak into partner feeds.

Which call should I use?

Use getMarketNews when the user is already looking at a specific market or event. This is the call for “related news” modules on market detail pages. Use getNewsFeed when you want a category news feed where articles are the main object. Use getNewsFeedMarkets when you want a category feed where markets are the main object and each market carries its recent article timeline. Most partner integrations use both patterns:
  1. Category or homepage: call getNewsFeed("finance") or getNewsFeedMarkets("finance").
  2. Market detail page: call getMarketNews({ venueMarketIds: [market.id] }).
  3. Event detail page: collect the event’s market ids, then call getMarketNews for the set.

Which id should I pass?

If your UI hasPass this fieldExample request
A market card or market detail objectvenueMarket.id{ "venueMarketIds": ["vm_abc123"] }
A matched sibling marketvenueMarket.matchedVenueMarkets[].id{ "venueMarketIds": ["vm_abc123", "vm_def456"] }
An event objectvenueEvent.id{ "venueEventIds": ["ve_abc123"] }
An event detail with markets loadedvenueEvent.venueMarkets[].id{ "venueMarketIds": ["vm_1", "vm_2"] }

Choose a feed shape

Use the article feed for homepages, discovery rails, and editorial-style layouts:
const { data, nextCursor, hasMore } = await client.getNewsFeed("finance", {
  limit: 20,
});

for (const item of data) {
  console.log(item.article.title);
  console.log(item.markets.map((market) => market.question));
}
Use the market feed for market pages, event pages, and category views where the market is the main object:
const { data } = await client.getNewsFeedMarkets("politics", {
  limit: 12,
});

for (const market of data) {
  console.log(market.question);
  console.log(market.articles.map((article) => article.title));
}

Pagination and refresh

Both feed shapes support the same query options:
OptionTypeNotes
limitnumberPage size from 1 to 50.
cursorstringPass the previous response’s nextCursor to fetch the next page.
sincestringISO timestamp for a lower time bound.
beforestringISO timestamp for an upper time bound.
const firstPage = await client.getNewsFeed("world", { limit: 20 });

if (firstPage.nextCursor) {
  const nextPage = await client.getNewsFeed("world", {
    cursor: firstPage.nextCursor,
    limit: 20,
  });
}
For repeated refreshes of the same feed or market request, poll no more than once per minute unless the user explicitly asks for a manual refresh. If your UI is rendering a market card or market detail page, you already have the AGG market id at venueMarket.id. Pass that id as venueMarketIds.
const news = await client.getMarketNews({
  venueMarketIds: ["vm_abc123"],
  limit: 3,
});

for (const result of news.results) {
  console.log(result.question);
  console.log(result.articles.map((article) => article.summary));
}
The response is grouped by market. For a single market, render the first result:
const [marketNews] = news.results;

const cards =
  marketNews?.articles.map((article) => ({
    headline: article.title,
    source: article.source,
    publishedAt: article.publishedAt,
    href: article.url,
    imageUrl: article.imageUrl,
    marketContext: article.summary,
  })) ?? [];
In the UI, label this module as related news for the market question:
const title = marketNews ? `Related news for ${marketNews.question}` : "Related news";
For request and response details, use the Get market news API reference.

Include matched venues

If your market object includes matchedVenueMarkets, include those ids too. This lets a single market detail page show related news for the same market across venues.
const venueMarketIds = [
  market.id,
  ...(market.matchedVenueMarkets ?? []).map((matched) => matched.id),
].slice(0, 10);

const relatedNews = await client.getMarketNews({
  venueMarketIds,
  limit: 3,
});
Deduplicate articles by url before rendering if you merge results from multiple markets:
const uniqueArticles = [
  ...new Map(
    relatedNews.results
      .flatMap((result) => result.articles)
      .map((article) => [article.url, article]),
  ).values(),
];
If the user is on an event detail page, fetch the event’s markets first, then request news for the markets you plan to render.
const { data: markets } = await client.getVenueMarkets({
  venueEventId: "ve_abc123",
  status: "open",
  limit: 10,
});

const venueMarketIds = markets
  .flatMap((market) => [
    market.id,
    ...(market.matchedVenueMarkets ?? []).map((matched) => matched.id),
  ])
  .slice(0, 10);

const eventNews = await client.getMarketNews({
  venueMarketIds,
  limit: 2,
});
Render each group under its market question:
for (const result of eventNews.results) {
  console.log(result.question);

  for (const article of result.articles) {
    console.log(article.title, article.summary);
  }
}
If you only have the event id and do not need market-level control, pass venueEventIds directly. For the exact body shape, use the Get market news API reference. You can pass venueMarketIds, venueEventIds, or both. The request accepts up to 10 ids total, and limit is capped at 5 articles per result. Use customQuery only when you want to bias the search toward a user-selected topic. Use tbs only when you need to override the time window for a dedicated experience, such as “past 24 hours”.

Integration notes

  • Feed endpoints are cached for 60 seconds per request and app scope. Do not poll more frequently unless the user explicitly refreshes.
  • On-demand market-news requests accept up to 10 ids total across venueMarketIds and venueEventIds.
  • limit is capped at 5 articles per market-news result and 50 rows for feed pages.
  • relevanceScore is a ranking signal within the response, not an absolute quality score across unrelated markets or categories.
  • News summaries explain why an article may matter to a market; they are not a replacement for the linked source article.

Response fields to render

FieldRender it as
result.questionThe market question the articles relate to.
result.eventTitleOptional event context above the market question.
article.titleThe article headline.
article.sourcePublisher/source label.
article.publishedAtTimestamp or recency label.
article.urlExternal link to the original article.
article.summaryShort explanation of why the article matters for the market.
article.relevanceScoreSort or filter signal within this response.

Render recommendations

Show source, publishedAt, and url with each article so users can inspect the original source. Treat summary as market-context copy: it explains why the article may matter to the linked market, not a replacement for the article itself. relevanceScore is a relative ranking signal. Use it to order or hide low-confidence links inside a single response, but do not compare scores across unrelated pages as an absolute measure.

Error handling

StatusHandle it as
400The category, ids, or query options are invalid. Fix the request before retrying.
401 / 403The app header is missing or not allowed for the endpoint.
429The on-demand market-news request limit was reached. Back off and retry later.
If a category is disabled for your app, feed endpoints return an empty page with data: [], nextCursor: null, and hasMore: false.

FAQ

Is News Feed just a list of article links?

No. News Feed links articles to specific prediction markets and includes market-impact summaries so apps can show why a story may matter to a tradeable market.

Should I use article-first or market-first feeds?

Use article-first feeds when the news story is the main object, such as a homepage or discovery rail. Use market-first feeds when the market is the main object, such as a market page, event page, or category page built around trading opportunities.

Can agents use News Feed?

Yes. Agents can use News Feed as structured market context: article metadata, market ids, summaries, relevance scores, and live linked-market prices are returned in API responses.

API Reference

View schemas and try the News Feed endpoints.

Building Market Views

Compose Discovery endpoints into category pages, market details, and event grids.