Five numbers beat one. Aggregate the yes-prices from Polymarket and Kalshi for one commodity at one expiry, fit a monotone curve through the implied probabilities, and return p10, p25, p50, p75, p90 plus the confidence tier, contributing venues, and a CME futures overlay. Direct-from-price math, no volume weighting, no blended median.
Returns the aggregated market-implied distribution for one commodity at one expiry. Asset is one of XAU, XAG, HG. Expiry is an ISO YYYY-MM-DD string. Tier is enforced at the request layer; sub-Pro callers get a 403 plan_gated with an upgrade URL. See it rendered live at /data/gold.
XAU (gold), XAG (silver), HG (copper).YYYY-MM-DD. Must match a Polymarket or Kalshi market expiry we have ingested; unknown dates return 404 no_eligible_markets.curl -H "Authorization: Bearer ga_live_..." \
"https://api.goldprice.dev/v1/prediction-market-view/XAU?expiry=2026-06-27"// 200 OK
{
"asset": "XAU" | "XAG" | "HG",
"expiry": string, // "YYYY-MM-DD"
"percentiles": {
"p10": string, "p25": string, "p50": string,
"p75": string, "p90": string
},
"futures_overlay_usd": string | null, // CME settlement anchor
"markets_used_count": number, // non-binary, post-clamp
"total_volume_usd": string, // lifetime traded $
"total_liquidity_usd": string, // upstream-reported depth $
"confidence": "high" | "medium" | "low",
"thin_liquidity": boolean,
"venues": string[], // ["polymarket", "kalshi"]
"computed_at": string, // ISO-8601 UTC
"meta": {
"method": string,
"excluded_touch_count": number,
"excluded_clamp_count": number,
"extrapolated_percentiles": string[],
"methodology_url": string,
"flags": string[]
},
"disclaimer": string | null
}Confidence tier uses effective liquidity (volume_usd, falling back to open_interest × notional_value). This matches the thin_liquidity signal already shipped on /v1/prices so the stack stays internally consistent.
| Tier | Markets used | Total effective liquidity | Per-venue rule |
|---|---|---|---|
| LOW | < 5 | any | — |
| LOW | ≥ 5 | < $10K | — |
| MEDIUM | ≥ 5 | ≥ $10K | single venue, OR 2-venue with one under $10K |
| HIGH | ≥ 5 | ≥ $10K | ≥ 2 venues, every venue ≥ $10K effective |
Poll /v1/prediction-market-view/XAU at 5-min intervals. The response p50 gives you the aggregate market-consensus median; individual Polymarket binary yes-prices give you per-strike probabilities. When the binary prices disagree with the aggregated distribution by more than your threshold (say 3 vol points), price the delta, size the trade against markets_used_count and thin_liquidity, and track convergence on the next poll. Both are 5-min caches, so the MCP tool and the REST endpoint see the same numbers in the same window.
Watch the distribution over time to attribute macro events. A tightening of (p90 − p10) around an FOMC print means the market collapsed uncertainty after the announcement; a widening suggests the print raised more questions than it answered. Combine with /v1/prices/history for price moves and the CME futures overlay for the carry-neutral reference.
Pull p10, p50, p90 every 5 minutes, annotate the chart with futures_overlay_usd, ship it to your risk board. One endpoint, one MCP tool for agent-driven alerts, zero infrastructure on your side. Sentry the confidence === "low" tier and the thin_liquidityflag so your board never displays a tuple the aggregate doesn't stand behind.
Every Pro+ customer gets get_prediction_market_view on the same tool bus as the rest of the MCP surface. Wire it into Claude Desktop, Cursor, Continue, or any MCP client:
// claude_desktop_config.json
{
"mcpServers": {
"goldprice": {
"command": "npx",
"args": ["-y", "@goldprice/mcp"],
"env": { "GOLDPRICE_API_KEY": "ga_live_..." }
}
}
}Tool signature (passed to the LLM as a tool schema):
get_prediction_market_view(asset: "XAU" | "XAG" | "HG", expiry: "YYYY-MM-DD")
-> {
asset, expiry, percentiles, futures_overlay_usd,
markets_used_count, total_volume_usd, total_liquidity_usd,
confidence, thin_liquidity, venues, computed_at, meta, disclaimer
} | { error, reason?, message? }