From a market question
to a durable workflow.

curl https://parlaymarket.io/api/v1/capabilities

Connect an MCP client

{
  "mcpServers": {
    "parlaymarket": {
      "url": "https://parlaymarket.io/api/mcp"
    }
  }
}

Supports MCP 2026-07-28 and stateless compatibility with 2025-11-25. Public discovery and market reads do not need a wallet. Private tools return an OAuth challenge. Your client opens the owner consent screen, uses PKCE S256, and receives a short-lived token for the https://parlaymarket.io/api resource.

Scopes: markets:read, plans:write, workflows:write, history:read, events:write. OAuth access is separate from permission to run a basket. Models cannot approve plans or expand mandates.

Workspace or agent basket?

The workspace estimates a paper parlay where all chosen outcomes must win under an independence assumption. Agent plans contain separate native US contracts, each with its own quantity, limit, and result. These markets can be correlated. Selections do not transfer between builders because venue identities and payout models differ.

First workflow

1. Call search_markets, then get_market and get_orderbook. Select an exact native instrument and outcome.
2. Call simulate_plan with an inline plan. Review displayed liquidity, incomplete fills, costs, and unknown fees.
3. Authenticate and call create_plan. The immutable plan includes every order parameter.
4. Call request_approval and send the owner to the returned approval URL.
5. After get_authorization_status reports approval, call create_workflow with the plan and approval IDs.
6. Call start_workflow with the current version. Follow get_workflow and list_events for labeled paper results.

Use REST or an SDK

Every tool is available at POST /api/v1/tools/{tool_name}. Both transports run the same schemas, authorization checks, and business services.

curl https://parlaymarket.io/api/v1/tools/search_markets \
  -H 'Content-Type: application/json' \
  -d '{"venue":"kalshi","limit":20}'

import { ParlayMarket } from './client.mjs';
const pm = new ParlayMarket({ token: process.env.PM_AGENT_TOKEN });
const page = await pm.search_markets({ venue: 'polymarket-us', limit: 20 });
console.log(page.markets);

JavaScript client · TypeScript definitions · Python client

Public contract downloads

If the runtime API is unavailable, the published OpenAPI snapshot and schema snapshot remain readable. These describe the build; check runtime capabilities before making requests. Basket source inspection uses public venue observations and remains available without a hosted model or wallet.

Units, limits, and retries

Prepare a two-venue basket within $5

The public preparation example takes one exact native outcome per venue, targets one contract each (adjusted only for native minimums), reserves $1 for fees, and bounds purchases plus that allowance to $5. It checks rules and depth, simulates, reconciles fills against the returned observations, and stops before authentication or approval.

import { ParlayMarket } from './client.mjs';
import { preparePaperBasket } from './prepare-paper-basket.mjs';
const pm = new ParlayMarket(); // Public reads and simulation need no token.
const catalogs = await Promise.allSettled([
  pm.search_markets({ venue: 'polymarket-us', limit: 20 }),
  pm.search_markets({ venue: 'kalshi', limit: 20 })
]);
// Inspect catalogs, follow next_cursor, and choose native outcome IDs.
// Do not replace a failed venue or infer an outcome from a title.
const review = await preparePaperBasket(pm, [polymarketRef, kalshiRef]);
// Inspect outcome, plan, simulation and trace; this does not save a plan.

max_total_cost_micro optionally binds a total budget to the plan hash. The server checks the sum of each quantity × limit price (rounded up to micro-units), plus max_fee_micro, before reading depth. A cheap partial fill cannot make an over-budget proposal valid. USD and USDC cannot be mixed.

Native limits and evidence

get_market includes constraints: native minimum quantity, quantity increment, price ranges and their source fields. Unknown limits block public simulation. Polymarket US uses instrument minimum trade quantity and price tick. Kalshi uses fixed-point quantity granularity and the instrument’s price ranges. Price ranges refer to the native YES price axis; NO prices use its complement. Do not treat six decimal places in the transport as permission to trade arbitrary increments.

simulate_plan rechecks native limits, currency and market cutoff. planned_maximum_cost_micro is the full limit-price purchase bound plus fees; cost_micro is the estimated purchase cost of displayed fills. The older maximum_cost_with_fee_allowance_micro is displayed-fill cost plus allowance, not the full planned bound. Actual fees remain unknown.

Every leg includes requested, filled and remaining quantities, price limit, quote age and its snapshot_id. snapshots retains the complete observed ask depth, UTC receipt time, provenance, native limits, resolution rules and rules hash. Simulation fetches new observations, so their IDs can differ from earlier inspection calls. preparation_status distinguishes ready_for_review, incomplete fills and needs_review evidence. None of these statuses grants approval or guarantees a venue fill.

Recover without changing the user’s intent

REST errors and MCP tool errors share code, status, retryable, details, retry_after_seconds and a request ID. An MCP tool failure can arrive inside HTTP 200 with isError: true; inspect the structured result. Both SDKs retain diagnostics and retry timing. Neither automatically retries mutations.

Honor provider retry timing; when absent, retryable errors use 60 seconds. The Worker coalesces identical in-flight reads and applies an isolate-local cooldown to a failed venue endpoint family. A failed catalog does not disable order books or the other venue. This reduces repeated requests; it does not guarantee recovery from an upstream access restriction. It does not return stale cached markets as fresh data.

Keep both requested venue legs when one fails. Preserve independent successful observations, label the preparation blocked, wait for the reported delay, and make a bounded new attempt. Saving requires an owner wallet session or OAuth plans:write; reading approval status and events requires history:read; workflow creation and starting require workflows:write. Only the owner can approve the exact persisted plan. Idempotent retries keep the original body and key, including expiry.

Bounded paper automation

Owners can create a paper mandate through POST /api/v1/owner/grants, using their wallet session and the published GrantInput schema. It binds a client, accounts, instruments, currency, cumulative budget, per-order limit, and expiry. Only same-origin owner requests may create or expand authority.

A workflow supports an immediate, time, price-below, or resolved-outcome trigger. The owner coordinator rechecks authority when it runs. Unknown venue resolution never triggers a follow-up.

Events and webhooks

Call list_events with the last sequence cursor to resume observation. subscribe_events registers an operator-approved HTTPS destination and returns its signing secret once. Store it securely. Verify HMAC-SHA256 over {timestamp}.{raw_body}, reject timestamps more than five minutes old, compare signatures in constant time, and deduplicate event_id.

Delivery is at least once. Failed deliveries retry with the same event ID, then enter a visible dead-letter state after eight attempts. Webhook delivery never grants execution authority.

Operating the platform

Deployment, local development, migration, and rollback runbook →

Venue data and research are untrusted input. Keep deterministic policy enforcement between model proposals and workflow activity. A basket of independent contracts is not an atomic parlay.