How to Use a Prediction Market Arbitrage API Across Multiple Venues

What does a multi-venue prediction market arbitrage API do?

It turns several incompatible prediction market feeds into one workflow. Without a normalized API, a scanner has to maintain a venue-specific catalog, identifiers, order-book parser, price format and authentication model for every integration. It then has to decide which differently worded contracts represent the same outcome.

A useful arbitrage API handles the shared plumbing while keeping the venue differences visible. The system still needs to know whether a book is real or reconstructed, which settlement rules apply and whether each venue supports the requested operation.

Predictefy divides cross-venue work into four layers:

The separation matters. A discrepancy is useful research output, but it is not evidence that two orders can be filled. The assessed surface performs the stricter calculation.

How do you authenticate with the Predictefy API?

Create an API key in the developer portal, store it as an environment variable and send it in the authorization header. Never put the raw key in the URL, source code or a client-side log.

export PREDICTEFY_API_KEY="pk_live_YOUR_KEY"

curl -s \
  "https://data.predictefy.com/api/router/fetchMarkets?query=election&status=active&limit=25" \
  -H "Authorization: Bearer $PREDICTEFY_API_KEY"

The market objects include normalized outcomes and venue-native identifiers. They also carry an asOf timestamp, provenance and capability flags. Store those fields with the price. Dropping them creates a clean-looking dataset that cannot explain whether a value was current or how it was obtained.

How do you match the same event across venues?

Do not join markets by title alone. A phrase such as "Fed cuts rates" can refer to different meeting dates, threshold sizes or official settlement sources. Near duplicates are especially dangerous because they look convincing until one unusual scenario makes them resolve differently.

Predictefy's cluster routes group contracts that represent equivalent outcomes. A cluster ID stays stable and its members carry their own venue and market identifiers. Similarity scores help describe the relationship, but they are not calibrated probabilities that a match is safe.

Before using a pair, compare:

• The exact outcome and threshold.
• The measurement and closing dates.
• The official resolution source.
• Cancellation, postponement and replacement rules.
• Whether one contract contains scenarios the other excludes.

An automated matcher can narrow the work. A production arbitrage policy still needs an explicit equivalence gate, because a pair that can settle differently is a spread trade rather than a lock.

How do you inspect price differences without overstating them?

Use the discrepancy endpoint to find clusters worth investigating:

curl -s \
  "https://data.predictefy.com/v1/discrepancies?live=true&limit=10" \
  -H "Authorization: Bearer $PREDICTEFY_API_KEY"

The live option recomputes the comparison from current book midpoints where available. That is more useful than a stale stored comparison, but a midpoint still cannot be bought. It sits between the best bid and best ask and may have very little size behind either side.

Label this output an indicative price discrepancy. Its job is to tell the application where to look next. It should not trigger an order or appear as guaranteed return.

How do you request assessed arbitrage across venues?

Call the router-only arbitrage verb with a bounded contract count:

curl -s \
  "https://data.predictefy.com/api/router/fetchArbitrage?contracts=100&executableOnly=true&limit=50" \
  -H "Authorization: Bearer $PREDICTEFY_API_KEY"

The engine tests ordered cross-venue pairs inside each matched cluster. A row earns the executable label only when all of these conditions hold:

These checks are applied to a snapshot, not a reservation. The first book can move before the second leg fills. Even a passing row needs current timestamps and an execution policy for partial fills and leg risk.

Why does contract size change the answer?

The best ask describes the first available level, not the full order. Suppose one leg offers 20 contracts at 44 cents and another 200 at 47 cents. A ten-contract calculation uses 44 cents. A hundred-contract calculation consumes all 20 at 44 cents and another 80 at 47 cents.

The weighted cost is:

(20 x $0.44) + (80 x $0.47) = $46.40
$46.40 / 100 contracts = $0.464 average

Run the same walk on both legs and then apply fees. A gap visible at the top of the book can vanish when the requested size crosses several levels. This is why an arbitrage API that accepts no size can identify candidates but cannot establish an executable acquisition cost.

How do you stream multi-venue arbitrage updates?

For a live terminal or alerting service, subscribe to the WebSocket arbitrage surface rather than polling every underlying venue book.

{
  "op": "auth",
  "apiKey": "pk_live_YOUR_KEY"
}

{
  "op": "subscribeArbitrage",
  "executableOnly": true,
  "venues": ["polymarket", "kalshi"],
  "minEdge": 0.02
}

The subscription sends a complete snapshot and sequence-ordered updates. The server recomputes the assessed surface on a disclosed cadence rather than promising a tick-by-tick view of every upstream change. The client should preserve sequence order, handle non-fatal protocol errors and request fresh state after reconnecting.

How should your application handle errors?

Do not reduce every unsuccessful call to "try again." Predictefy's error envelope includes a stable code and a retryable flag.

• NOT_SUPPORTED means the venue does not provide that capability. Do not retry it.
• RATE_LIMITED is retryable with backoff.
• PLATFORM_UNAVAILABLE or ARBITRAGE_UNAVAILABLE means the assessed surface cannot be produced safely at that moment.
• UNAUTHORIZED requires a valid key, not a retry loop.
• PLAN_REQUIRED requires access to the requested feature.

Fail closed. If a fee model, live book or equivalence check is unavailable, keep the row out of the executable set. Substituting an older midpoint because a book request failed makes the result look complete while removing the evidence it was built on.

How should execution follow the API result?

Keep four states separate: candidate, assessed, approved and submitted.

1. A discrepancy creates a candidate.
2. The arbitrage endpoint assesses that candidate at a fixed size.
3. A human or deterministic policy approves the exact legs and bounds.
4. The execution system builds, signs and submits each venue-shaped order.

Predictefy's execution service is isolated from the reads API. It builds unsigned artifacts while signing stays in the caller's process. Every material write uses an idempotency key, and the current execution venue list must be checked before assuming a data venue can accept an order.

This boundary lets a research service use broad read access without holding venue credentials or gaining trading authority. It also makes the failure point visible when the second leg cannot be completed.

Frequently Asked Questions