Polymarket Data Source

Polymarket adds event and prediction-market context around the assets a clone is allowed to trade.

It is not the trade universe. Hyperliquid remains the trade universe; Polymarket is a related-market signal layer.

In the workflow UI, Polymarket blocks are market-scoped. Users search by keyword and select a concrete Polymarket market. The old asset-linked discovery path remains useful for background ingestion and matching, but users should not be asked to choose a Polymarket asset.

What We Store

Channel	Table	Cadence	Purpose
Market discovery	polymarket_events, polymarket_markets, polymarket_market_asset_links	1h	Discover and link relevant markets to Hyperliquid assets
Immediate market	polymarket_immediate_markets	5m health cadence	Near-term active prediction-market context
Later market	polymarket_later_markets	30m health cadence	Longer-dated context

The current implementation performs discovery as one hourly job, filters to live or upcoming markets only, then writes immediate and later feature rows from that discovered registry.

Discovery Model

Discovery is registry-first:

Hyperliquid asset registry
  -> asset display names and search terms
  -> Gamma crypto tag crawl
  -> Gamma public search by asset term
  -> live/upcoming market filter
  -> local event/market/link registry
  -> derived feature rows

The asset search terms come from hyperliquid_assets, including curated aliases where available. This is important because prediction markets often use names like Bitcoin instead of ticker-only strings like BTC.

How We Fetch Data

Configured endpoint:

Config	Default
POLYMARKET_GAMMA_URL	https://gamma-api.polymarket.com
POLYMARKET_CRYPTO_TAG_ID	21

The ingestor uses Polymarket Gamma HTTP GET requests.

Crypto tag crawl:

GET /events?active=true&closed=false&tag_id=21&order=volume_24hr&ascending=false&limit=100&offset=0

This pulls high-volume active Crypto-tagged events. Pagination continues until the configured page cap or until a short page is returned.

Asset search:

GET /public-search?q=Bitcoin&limit=5

Search terms come from the Hyperliquid asset registry. The ingestor runs throttled searches using POLYMARKET_SEARCH_DELAY_MS and can cap total searched terms with POLYMARKET_MAX_SEARCH_TERMS for local testing.

Workflow market search uses the same Gamma public search endpoint through the backend API:

GET /api/v1/polymarket/markets/search?q=bitcoin

The UI debounces keyword input, displays returned markets, and stores the selected market title, query, and URL on the Polymarket Data Stream Block.

Fetched events and markets are parsed, matched to assets, and written into:

• polymarket_events
• polymarket_markets
• polymarket_market_asset_links
• polymarket_immediate_markets
• polymarket_later_markets

Closed, archived, and ended markets are not stored for v1. A cleanup migration prunes stale Polymarket registry rows from existing local databases.

Matching Policy

Polymarket rows should be linked to assets cautiously:

• Prefer explicit asset-name and alias matches.
• Keep match source and score metadata.
• Store the durable event/market registry separately from derived summaries.
• Avoid querying every CLOB orderbook by default.

CLOB enrichment can be added later for selected high-signal markets, but v1 should keep Polymarket as compact context rather than a heavy market-data stream.

Trading Context

Trading prompts can use Polymarket context to answer:

• Is there a near-term event changing sentiment for this asset?
• Are longer-dated markets implying a macro/narrative shift?

Local Commands

cd backend
npm run polymarket:discover
npm run polymarket:discover -- --dry-run --max-search-terms=5