# Cross-Venue Prediction Market Spread Monitor (`obsequious_doughnut/cross-venue-market-spread-monitor`) Actor

Read-only, explainable Polymarket and Kalshi candidate spread analysis with fee, depth, and matching evidence.

- **URL**: https://apify.com/obsequious\_doughnut/cross-venue-market-spread-monitor.md
- **Developed by:** [BRADLEY B](https://apify.com/obsequious_doughnut) (community)
- **Categories:** E-commerce, AI, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.05 / actor start

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

### What does Cross-Venue Prediction Market Spread Monitor do?

**Cross-Venue Prediction Market Spread Monitor** retrieves active binary markets from the official public Polymarket and Kalshi market-data APIs, identifies plausible equivalent events, loads executable order-book depth for matched pairs, and emits explainable **candidate spreads**. It is read-only: it has no signer, wallet, account-password, API-key, cookie, or order-placement capability.

Live mode is the default in version 0.2. Fixture mode remains available only for deterministic integration testing and makes zero venue requests.

### Why use this prediction market spread monitor?

- Retrieve current market metadata from Polymarket and Kalshi without account credentials.
- Request order books only after metadata matching, with explicit market, page, response-size, timeout, retry, and hydration caps.
- Walk executable order-book depth for a configurable total capital budget instead of comparing headline prices.
- Include configurable fee estimates and a slippage/safety buffer.
- Reject polarity, numeric-threshold, close-time, event-type, and named-subject mismatches.
- Show matching reasons, both source URLs, bounded resolution-rule evidence, timestamps, and risk flags.
- Export structured results through Apify Dataset, API, schedules, webhooks, Make, Zapier, n8n, or MCP.
- Never describe a spread as guaranteed or risk-free.

### What data can it return?

| Field                                         | Type     | Description                                                          |
| --------------------------------------------- | -------- | -------------------------------------------------------------------- |
| `direction`                                   | string   | The two complementary contracts analyzed                             |
| `netReturnPct`                                | number   | Estimated return on modeled capital after configured fees and buffer |
| `fillableContracts`                           | number   | Contracts supported by executable depth on both books                |
| `similarity`                                  | number   | Explainable title-token match score                                  |
| `matchReasons`                                | array    | Passed compatibility checks                                          |
| `sourceObservedAt`                            | datetime | Latest observation timestamp across both markets                     |
| `riskFlags`                                   | array    | Required human-review warnings                                       |
| `leftResolutionRules`, `rightResolutionRules` | string   | Bounded rule evidence for manual equivalence review                  |

The Dataset contains derived candidate records, not bulk raw venue payloads or complete order books.

### How to analyze current Polymarket and Kalshi spreads

1. Keep **Data mode** set to `live`.
2. Set the total analysis capital, fee estimate, safety buffer, and match thresholds.
3. Keep collection caps at their defaults unless broader coverage is needed.
4. Click **Start**.
5. Review each candidate's rule text, direct links, source time, executable depth, and risk flags.
6. Export the Dataset as JSON, CSV, Excel, XML, or RSS, or consume it through the API.

The default `minNetReturnPct` is `0`, so the Actor emits only candidates whose modeled return is non-negative after the configured estimates. Set it below zero to inspect equivalent-market spreads that are not currently positive.

### Input

See the **Input** tab for all controls. Runtime validation rejects unknown fields, unsafe numeric bounds, and an explicitly incomplete authorization attestation.

- `stakeUsd` is the total USD capital budget across both legs, including configured fees and safety buffer; no trades occur.
- `feeRatePct` is a configurable estimate, not an authoritative venue fee quote.
- `slippageBufferPct` reserves an additional percentage of modeled acquisition cost as a safety margin.
- `maxMarketsPerVenue`, `maxSourcePages`, and `maxBookPairs` bound live collection.
- `mode: fixtures` returns one deterministic demonstration record and is not current market data.

The private deployment's authorization defaults reflect the operator's confirmed data permissions as of `2026-08-13`. Review permissions before copying, commercializing, or publishing a deployment.

### Output

A live record resembles:

```json
{
    "classification": "candidate-spread",
    "direction": "YES Polymarket + NO Kalshi",
    "leftMarketId": "live-polymarket-id",
    "rightMarketId": "LIVE-KALSHI-TICKER",
    "netReturnPct": 0.42,
    "sourceObservedAt": "2026-08-13T23:00:00.000Z",
    "riskFlags": [
        "human-resolution-review-required",
        "simultaneous-fill-not-guaranteed",
        "fees-are-configurable-estimates"
    ]
}
```

Values above illustrate the schema and are not a current quote. The `OUTPUT` key-value record contains the run summary, including actual source-request count, markets loaded, matched pairs, and emitted results.

### API and automation example

```bash
curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~cross-venue-market-spread-monitor/runs" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"mode":"live","stakeUsd":100,"maxResults":100}'
```

Never commit or publish your Apify token. Apply `maxTotalChargeUsd`, memory, and timeout limits when an agent calls any paid Actor automatically.

### Limits, legal boundaries, and support

- This Actor provides research signals, not financial, legal, tax, or investment advice.
- A matching title does not prove identical resolution semantics; manual rule review remains mandatory.
- Displayed order-book depth does not guarantee simultaneous fills or future availability.
- Fee and buffer inputs are estimates; venue fee schedules and account-specific costs may differ.
- Trading eligibility and geographic restrictions are independent of read-only data access.
- No private user data, account passwords, cookies, wallet keys, or trading credentials are accepted.
- Upstream APIs, schemas, availability, and data rights can change. The Actor fails on malformed or unavailable source responses rather than silently substituting fixture records.
- The implementation is clean-room and does not copy hidden Community Actor source, wording, or branding.

Use the Apify **Issues** tab or the linked GitHub repository for reproducible bug reports. Include sanitized input and a run ID; never include credentials.

# Actor input Schema

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

Live retrieves current public market metadata and executable order books. Fixtures provides one deterministic test record.

## `stakeUsd` (type: `number`):

Total USD capital budget across both legs, including configured fees and safety buffer; no orders are placed.

## `maxResults` (type: `integer`):

Maximum number of ranked candidate spread records to emit.

## `minSimilarity` (type: `number`):

Minimum token similarity required before deeper compatibility checks.

## `maxCloseHours` (type: `number`):

Maximum difference between venue market close times.

## `minNetReturnPct` (type: `number`):

Only emit candidates at or above this estimated post-buffer return.

## `feeRatePct` (type: `number`):

Conservative configurable estimate; confirm venue-specific fees manually.

## `slippageBufferPct` (type: `number`):

Additional percentage of modeled acquisition cost reserved as a safety margin.

## `maxMarketsPerVenue` (type: `integer`):

Hard cap on normalized active binary market metadata loaded from each venue.

## `maxSourcePages` (type: `integer`):

Hard pagination cap applied independently to each venue.

## `maxBookPairs` (type: `integer`):

Maximum plausible cross-venue pairs whose executable order books are requested.

## `authorization` (type: `object`):

Operator data-rights attestation. The deployed Actor defaults to the permissions confirmed for this private release.

## Actor input object example

```json
{
  "mode": "live",
  "stakeUsd": 100,
  "maxResults": 100,
  "minSimilarity": 0.55,
  "maxCloseHours": 72,
  "minNetReturnPct": 0,
  "feeRatePct": 1,
  "slippageBufferPct": 0.5,
  "maxMarketsPerVenue": 3000,
  "maxSourcePages": 30,
  "maxBookPairs": 100,
  "authorization": {
    "polymarketPublicApiApproved": true,
    "kalshiDeveloperAgreementReviewed": true,
    "commercialRedistributionApproved": true,
    "termsReviewedOn": "2026-08-13"
  }
}
```

# Actor output Schema

## `dataset` (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("obsequious_doughnut/cross-venue-market-spread-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("obsequious_doughnut/cross-venue-market-spread-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 obsequious_doughnut/cross-venue-market-spread-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,obsequious_doughnut/cross-venue-market-spread-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/kfrR2sDN7Z8gw5FoB/builds/PixOS2wYwI4rjTsge/openapi.json