# Polymarket + Kalshi Resolution Evidence & Settlement Monitor (`nexascout/prediction-market-resolution-evidence-monitor`) Actor

Parse market resolution rules, retrieve official evidence, evaluate evidence-supported outcomes, and monitor settlement changes for supported Polymarket and Kalshi markets.

- **URL**: https://apify.com/nexascout/prediction-market-resolution-evidence-monitor.md
- **Developed by:** [NexaScout](https://apify.com/nexascout) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $40.00 / 1,000 resolution evidence reports

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Polymarket + Kalshi Resolution Evidence & Settlement Monitor

Turn a prediction-market URL into a structured answer to a harder question than “what are the odds?”:

**What exactly resolves this market, which official source determines it, what does that source say now, what outcome does the evidence support, and how certain is that conclusion?**

This Actor is a deterministic resolution-evidence engine for **Kalshi + Polymarket**. V1.1 supports two high-value evidence families: **weather** (including The Weather Company settlement data used by current Kalshi weather markets) and **U.S. macroeconomic releases**. Unsupported markets return a safe `UNKNOWN` result instead of fabricated evidence.

### What it does

1. Loads the market and its resolution rules from Kalshi or Polymarket public market metadata.
2. Normalizes the resolution condition.
3. Detects the evidence family and the authoritative source.
4. Queries an **official** source only.
5. Converts raw official data into the metric the market actually resolves on.
6. Evaluates the evidence-supported YES/NO state when deterministic.
7. Separates evidence state from the platform's actual final settlement.
8. In `MONITOR` mode, compares the report with the prior run and returns only meaningful state-change signals in a `monitor` object.

### V1.1 official sources

| Evidence family | Official source | Current V1.1 handling |
|---|---|---|
| Kalshi weather markets that name The Weather Company | The Weather Company (`weather.com/kalshi`) | Extract the market's `CLI...` settlement location and target date from the rules, query the official `/kalshi/api/climate/primary` endpoint, match the location record, and evaluate daily high/low or precipitation when the official value is available. |
| Weather markets that explicitly name NWS/NOAA | National Weather Service / NOAA (`api.weather.gov`) | Extract station from rules when possible and aggregate official observations. NWS is used only when the market rules actually name NWS/NOAA as the authoritative source. |
| CPI / inflation | U.S. Bureau of Labor Statistics | CPI-U series; computes YoY or MoM only when the market wording clearly requests it |
| Unemployment | U.S. Bureau of Labor Statistics | Official unemployment-rate series |
| Payrolls / jobs | U.S. Bureau of Labor Statistics | Total nonfarm payroll level or monthly change when clearly requested |
| FOMC decisions | Federal Reserve | Official monetary-policy RSS + FOMC statements; can compute target-rate change in basis points |
| GDP | Bureau of Economic Analysis | Current official GDP headline; historical-quarter evaluation remains conservative unless the exact target can be verified |

Generic weather apps, news articles, social media, market prices, and third-party aggregators are **not** used as settlement evidence.

### Input

```json
{
  "marketUrls": [
    "https://kalshi.com/markets/...",
    "https://polymarket.com/event/..."
  ],
  "mode": "CHECK",
  "maxMarkets": 25,
  "includeRawEvidence": false,
  "failOnUnsupported": false
}
```

`marketUrls` also accepts a bare Kalshi ticker such as `KX...` and a Polymarket slug. Kalshi event URLs/tickers and Polymarket event URLs can expand to multiple child markets, bounded by `maxMarkets`.

#### Store health-check default

The published input schema uses `https://kalshi.com/markets/kxu3/unemployment/kxu3-26aug/kxu3-26aug-t4.0` as a stable finalized one-market default so Apify Store daily auto-tests produce a non-empty dataset. This is only a demo/health-check input; replace it with the market URL, ticker, or slug you actually want to evaluate.

### CHECK example

```json
{
  "marketUrls": ["KXHIGHNY-EXAMPLE"],
  "mode": "CHECK"
}
```

The Actor writes one standardized report per market to the default dataset.

For a Kalshi weather market whose rules name The Weather Company, the report uses the official `weather.com/kalshi` climate endpoint and returns a source type such as `OFFICIAL_TWC_KALSHI_CLIMATE`. If the exact `CLI...` record is not published yet, the state is `AWAITING_OFFICIAL_SOURCE`; NWS is not substituted.

### MONITOR example

```json
{
  "marketUrls": [
    "KXHIGHNY-EXAMPLE",
    "https://polymarket.com/event/example-fed-market"
  ],
  "mode": "MONITOR",
  "monitorStateKey": "my-resolution-watch"
}
```

A persistent named Apify key-value store keeps the prior report across separate runs. Each new dataset item receives:

```json
{
  "monitor": {
    "previousEvidence": {},
    "currentEvidence": {},
    "evidenceChanged": true,
    "resolutionStateChanged": true,
    "confidenceChanged": false,
    "newOfficialData": true
  }
}
```

### Output

```json
{
  "platform": "KALSHI",
  "marketId": "KX...",
  "marketUrl": "https://kalshi.com/markets/...",
  "question": "Will ...?",
  "marketStatus": "OPEN",
  "resolutionCondition": "value > 80",
  "resolutionSourceName": "National Weather Service / NOAA station KNYC",
  "resolutionSourceUrl": "https://api.weather.gov/stations/KNYC/observations?...",
  "resolutionSourceType": "OFFICIAL_WEATHER_OBSERVATIONS",
  "observedValue": "82.0 °F",
  "observedAt": "2026-09-23T19:51:00Z",
  "sourcePublishedAt": "2026-09-23T19:51:00Z",
  "expectedOutcome": "YES",
  "resolutionState": "CONDITION_MET",
  "confidenceScore": 0.93,
  "confidenceLevel": "HIGH",
  "evidenceFreshness": "IN_PROGRESS",
  "sourceMatchConfidence": 0.96,
  "warnings": [],
  "evidence": []
}
```

Supported states:

`UNRESOLVED`, `LIKELY_YES`, `LIKELY_NO`, `CONDITION_MET`, `CONDITION_NOT_MET`, `AWAITING_OFFICIAL_SOURCE`, `SOURCE_CONFLICT`, `DISPUTED`, `FINAL`, `UNKNOWN`.

#### Important state semantics

`CONDITION_MET` means the **official evidence currently satisfies the parsed market condition**. It does not by itself mean the exchange has settled the contract.

`FINAL` is reserved for a final/resolved settlement only when the platform exposes an unambiguous YES/NO outcome or supported official evidence deterministically establishes the outcome. A closed/resolved flag by itself does not force `FINAL`. Polymarket markets can involve UMA challenge/dispute workflows; if platform metadata indicates a challenge/dispute and the market is not final, this Actor returns `DISPUTED`.

### Pricing

The project contains `.actor/pay_per_event.json` with:

- `apify-actor-start`: **$0.005** per run (one-time synthetic start event)
- `resolution-evidence`: **$0.04** per supported market report (**primary event**)

The Actor checks the user's PPE spending limit before doing the official-source evidence work. A market that is obviously outside the V1.1 evidence families returns `UNKNOWN` **without charging the `resolution-evidence` event**.

### x402 / agent use

This product is designed for a predictable agent call:

```text
resolve_evidence(market_url) -> structured JSON report
```

For direct Apify agentic eligibility, keep the published Actor on **Pay per event only**, do not pass platform usage through to the user, use **limited permissions**, keep **Standby disabled**, and complete the developer KYC. No browser, proxy, LLM, or paid Actor-to-Actor dependency is used in the normal path.

### Architecture

```text
Market URL / ticker / slug
        ↓
Platform detector + metadata client
        ↓
Resolution rule normalizer
        ↓
Evidence-family classifier
        ↓
Authoritative source resolver
        ↓
Official evidence adapter
        ↓
Deterministic condition evaluator
        ↓
Resolution state + confidence + evidence trail
        ↓
Dataset / API / agent / x402
```

The normal path uses plain HTTP and is designed for **256 MB** memory. TWC metric selection prioritizes the explicit market question/rule clause so generic Kalshi "maximum/minimum" boilerplate cannot invert high vs. low markets.

### Limitations

- V1.1 does not try to resolve arbitrary politics, sports, crypto, awards, or legal/news markets.
- Weather support is intentionally conservative when the exact official station cannot be identified from the rules. A small city-to-station fallback map is available but is explicitly downgraded in source-match confidence and emits a warning.
- The Weather Company connector only evaluates a market when it can deterministically extract the market's `CLI...` settlement location and identify the matching record in the official `weather.com/kalshi` response. If the value is not published yet, the Actor returns `AWAITING_OFFICIAL_SOURCE` rather than substituting NWS data.
- The Weather Company endpoint is treated as the settlement source only when the market rules declare it. NWS-settled weather markets continue to use official NWS/NOAA observations only.
- The TWC parser is intentionally schema-tolerant because the public `weather.com/kalshi` JSON shape may evolve; it anchors on the exact `CLI...` location code and metric names and refuses to use a different location's value.
- BLS series can be revised. The report describes the official evidence it retrieved; exchange settlement rules remain authoritative.
- The no-key BEA adapter is strongest for the latest GDP headline. It will not pretend a current headline proves a historical quarter.
- A parser ambiguity results in `UNKNOWN`/`UNRESOLVED`, not a guessed outcome.

This Actor provides resolution research and monitoring data, **not financial advice**.

### Local tests

The test suite uses deterministic fixtures and Node's built-in test runner:

```bash
node --test test/*.test.js
```

Network access is only needed for live Actor runs, not for the fixture tests.

#### TWC station-code normalization

Kalshi rules may identify a CLI product as `CLINYC`, while the Weather Company API returns `cliId` / `stationId` as `NYC`. The connector deterministically strips only the `CLI` prefix before exact station matching.

#### TWC settlement guard

The Weather Company connector never substitutes `avgTemp` or current temperature for a daily high/low settlement value. When the CLI report is not yet published, the Actor returns `AWAITING_OFFICIAL_SOURCE`.

# Changelog

This Actor's version history is a separate document: https://apify.com/nexascout/prediction-market-resolution-evidence-monitor/changelog.md

# Actor input Schema

## `marketUrls` (type: `array`):

One or more Kalshi/Polymarket market references. Kalshi and Polymarket event URLs may expand to multiple child markets. The default is a stable finalized Kalshi unemployment market URL used as a Store health-check example; replace it with your own market.

## `mode` (type: `string`):

CHECK returns the current evidence report. MONITOR also compares against the previous run stored under the monitor state key.

## `monitorStateKey` (type: `string`):

Optional stable key for recurring runs. If omitted, one is derived from the market references.

## `maxMarkets` (type: `integer`):

Safety cap for the number of individual market reports produced in one run.

## `includeRawEvidence` (type: `boolean`):

Include short raw official-source snippets for debugging. Disabled by default.

## `failOnUnsupported` (type: `boolean`):

If enabled, unsupported/ambiguous markets fail the run instead of returning UNKNOWN with warnings.

## Actor input object example

```json
{
  "marketUrls": [
    "https://kalshi.com/markets/kxu3/unemployment/kxu3-26aug/kxu3-26aug-t4.0"
  ],
  "mode": "CHECK",
  "monitorStateKey": "",
  "maxMarkets": 25,
  "includeRawEvidence": false,
  "failOnUnsupported": false
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("nexascout/prediction-market-resolution-evidence-monitor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("nexascout/prediction-market-resolution-evidence-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call nexascout/prediction-market-resolution-evidence-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nexascout/prediction-market-resolution-evidence-monitor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/nrJ5xJfpDNvIuZrY8/builds/sj7jRX2HpjxZjEzKX/openapi.json