Bring a market.
Keep the evidence.

One task: understand your Fed contract and its visible depth.

1. Install the source package below and search Fed October. FOMC also helps find rate-related contracts; search results are not equivalent contracts or recommendations.
2. Read the questions and choose your exact returned Polymarket id. Keep that ID through conditions, evidence and book requests.
3. Run the example with that ID. It makes four explicit public GETs: search, retained conditions, source evidence and depth. No polling or automatic retry occurs.
4. Read the unknowns and save the whole JSON. 500 means outcome shares, not $500; a depth estimate is not an order.

# Node >=22.17; run in your project directory.
curl --fail --show-error --proto '=https' --max-time 30 \
  'https://www.howsure.com/downloads/howsure-client-0.1.33.tgz' -o howsure-client-0.1.33.tgz
# Inspect the archive before installing.
npm install ./howsure-client-0.1.33.tgz
npx --no-install howsure markets --query 'Fed October' --limit 20

// Save as howsure-task.mjs. First run: node howsure-task.mjs
// Read the questions, then run: node howsure-task.mjs 'EXACT_RETURNED_ID'
import { HowsureClient, HowsureApiError } from '@howsure/client';
const client = new HowsureClient();
const search = await client.searchMarkets({ q: 'Fed October', limit: 20 });
if (!process.argv[2]) {
  console.log(JSON.stringify(search, null, 2)); // choose, do not assume first = best
  process.exit(0);
}
const market = search.data.results.find(row => row.id === process.argv[2]);
if (!market || market.source.venue !== 'polymarket') {
  throw new Error('Select an exact Polymarket ID from this search response.');
}
async function capture(read) {
  try { return { ok: true, data: await read() }; }
  catch (error) {
    if (!(error instanceof HowsureApiError)) throw error;
    return { ok: false, error: { code: error.code, status: error.status,
      api_error: error.apiError, message: error.message, details: error.details,
      retryable: error.retryable, retry_after: error.retryAfter, hint: error.hint } };
  }
}
const [conditions, evidence, depth] = await Promise.all([
  capture(() => client.readConditions(market.id, { limit: 10 })),
  capture(() => client.collectSourceEvidence(market.id)),
  capture(() => client.readOrderBook(market.id, {
    quantity: '500', outcome: 'YES', side: 'buy',
  })),
]);
console.log(JSON.stringify({ receivedAt: new Date().toISOString(),
  selectedMarketId: market.id, search, conditions, evidence, depth }, null, 2));

# Replace the value with the exact ID you chose from the search response.
howsure_market_id='EXACT_RETURNED_ID'
npx --no-install howsure conditions "$howsure_market_id" --limit 10
npx --no-install howsure evidence "$howsure_market_id"
npx --no-install howsure book "$howsure_market_id" --quantity 500 --outcome YES --side buy

Useful output: exact rules and their observation time; captured sources and gaps; filled/unfilled shares, VWAP, gross, and estimated purchase fees/cost where the exact market tariff is confirmed. Unsupported fees stay unknown. Opt-in sale proceeds subtract the modeled fee from covered gross; the unfilled remainder has no estimated proceeds. Evidence may contain optional contract_reading for recognized Fed meeting/annual, US GDP growth, complete Core PCE/Core CPI MoM equality or exact 0.6% or more templates, or Binance price-threshold terms. The field can be null or absent; it explains captured terms and does not verify an outcome. Supported primary-source policies read the exact declared Federal Reserve calendar or BEA GDP page. A current BEA passage can concern a different quarter or estimate vintage; it does not establish this contract’s outcome.

Choose a client.

JS/CLI/MCP 0.1.33 and Python 0.1.25 support the live canonical https://www.howsure.com and compatibility https://howsure-web.vercel.app API origins. Immutable package defaults remain Vercel for compatibility; choose www explicitly through HOWSURE_ORIGIN for CLI/MCP or the client constructor. Keys are never forwarded through redirects, including between these two hosts. This online guide can be updated independently; older archives and their historical READMEs remain unchanged.

Current clients also verify native condition identity and recompute visible-depth estimates even when fees are unknown. Check updates distinguish a changed deadline from equivalent UTC formatting, preserving the original captures and hashes. Client validation is not proof of source truth or an execution guarantee.

Current JS/CLI/MCP 0.1.33, Python 0.1.25 and OpenAPI 1.22.0 read an existing owner watch after separate explicit permission for this exact watch and key. Exact reads preserve schedule/status in sharedWatch; the existing updates feed returns retained comparisons. Version-only grants do not expand. A future schedule is not a completed observation. Old versions, source limitations and author probabilities remain unchanged.

JS/CLI/MCP 0.1.29, Python 0.1.21 and OpenAPI 1.20.0 add owner-selected sharing of one exact saved Check version with an existing key. New clients request include_shared=true; shared reads require version and return owner_shared_unverified with sharedAccess. Only the previewed claim and retained evidence are returned. Personal notes, thesis, context and assessment stay excluded. Existing tools preserve sharing metadata and correction notices on a source recheck. Agents cannot grant access, append to shared Checks or enable their watches. Revoke sharing or the key to block later reads; copies already read cannot be recalled.

JS/CLI/MCP 0.1.28, Python 0.1.20 and OpenAPI 1.19.0 add a separate correctionReview on exact saved-version reads. Clients request include_corrections=true; raw HTTP without the flag retains its old shape. An affected finding identifies a known HowSure interpretation error, what changed and what to review. Unknown is unresolved; not_affected only means no match to the finite known registry. The original answer, sources and old exports remain unchanged. The existing MCP read tool carries this review even when a source recheck is cached or unavailable. No extra source call, automatic revision, watch or paid model is added; offline copies receive no notification until a new read.

JS/CLI/MCP 0.1.27, Python 0.1.19 and OpenAPI 1.18.0 retain the next scheduled meeting for a supported December Fed contract. calendar.nextMeeting separates the tentative January dates from confirmed status. The no-statement cutoff carries a date only: time and time zone stay unknown, and the exception is not established. Both complete calendar rows and their qualifications must support the result. Upgrade both clients to validate the new field; older packages may pass it through without checking it. Existing flags and old saved calendar readings remain unchanged.

JS/CLI/MCP 0.1.26 and Python 0.1.18 introduced the exact monthly CPI/PCE “0.6% or more” template. Optional reportedValueComparison compares a retained one-decimal figure with the inclusive numeric threshold; exactly 0.6% is included. The qualifying contract result remains unknown, and missing data stays unavailable. Existing flags and equality responses are unchanged. Upgrade older Python to validate this new field and bind complete terms to the selected period; older JS may reject these new readings.

JS/CLI/MCP 0.1.25, Python 0.1.17 and OpenAPI 1.16.0 retain the exact historical Q4 2025 GDP release. The January 29 contract date is preserved; an official postponement notice and matching schedule must corroborate the February 20 Advance release. Advance 1.4% remains separate from the independently indexed April 9 Third Estimate of 0.5%. The existing explicit GDP flag permits up to five sources, or six with the full event roster. Earlier clients may reject this reading. Original-release bytes and venue settlement remain unverified.

JS/CLI/MCP 0.1.24 and Python 0.1.16 admit the exact July CPI prior-month unchanged wording and June PCE annual-update/archive notices. The CPI statement is checked against the prior core Table A value; PCE notices retain the publisher’s wording and their exact month/release context. Earlier packages may reject these new readings. HTTP/OpenAPI 1.15.0 and existing request flags stay unchanged; original-release bytes, PCE seasonal basis and settlement remain unverified.

JS/CLI/MCP 0.1.23 adds typed monthly CPI/PCE changes to saved-version rechecking. It separates changed numbers, source-version changes, reused observations and unavailable evidence. For two raw responses, the existing source comparison tool accepts includeMonthly: true; CLI: evidence-compare first.json repeat.json --include-monthly true. A same-value CPI move from current summary to archive is provenance change, not a numeric revision. PCE seasonal basis and original-release bytes remain unverified; settlement and author probability stay unchanged. No monthly automatic watch is added. HTTP and Python keep their existing lower-level operations.

JS/CLI/MCP 0.1.21, Python 0.1.15 and OpenAPI 1.15.0 add exact selected-period CPI archive observations. The existing CPI release flag follows only the archive link retained in the official BLS index, and binds its URL date, printed release label, month/year and core monthly measure. The current-summary payload remains valid. Archive reads do not prove unchanged original-release bytes. Install the new clients for this sourceVersion; earlier archives preserve their prior coverage.

JS/CLI/MCP 0.1.20 and Python 0.1.14 introduced the complete July PCE precision-example wording and August CPI em-dash wording. July source values retain the future annual-update notice; GDP guidance acknowledges an already validated event roster while the qualifying value is pending. Those wording and GDP guidance fixes kept the HTTP fields, flags and OpenAPI 1.14.0 unchanged; the later CPI archive capability is described above.

JS/CLI/MCP 0.1.19 and Python 0.1.13 introduced explicit exact-month PCE/CPI release reads on the existing evidence tool. Release values, publication/read clocks and version limits survive save/export; no PCE/CPI automatic watch is added. JS/CLI/MCP 0.1.17 adds typed bounded fact-watch receipts and exact official-source recovery in local fact comparison. Expanded automatic watches remain off until explicitly enabled by the service. JS/CLI/MCP 0.1.16 and Python 0.1.12 add explicit complete GDP bracket-roster evidence. JS/CLI/MCP 0.1.16 also add local GDP fact comparison v3, keeping Advance, revisions and bracket changes separate. JS/CLI/MCP 0.1.15 adds explicit retained Fed decision-fact comparison v2. JS/CLI/MCP 0.1.15 and Python 0.1.11 add optional GDP Advance release evidence with later revisions kept separate. JS/CLI/MCP 0.1.14 and Python 0.1.10 added explicit Fed decision-source reads on the existing evidence tool. Default reads and legacy overview watches keep their original scope. Expanded fact watches remain disabled by default. Pending current-rate context is provisional; observed policy facts do not establish venue settlement. JS/CLI/MCP 0.1.13 and Python 0.1.9 added opt-in annual Fed and election comparison readings while preserving older response formats. Version 0.1.12 / Python 0.1.8 added optional scoped private research: save an immutable baseline, read it again and explicitly manage bounded source watches. MCP returns structured results with output schemas. Version 0.1.11 added comparison of listed Fed/GDP publication links, with explicit unknown coverage for older captures. Linked publication content is not fetched or assessed. Version 0.1.10 and Python 0.1.7 added optional structured Fed/GDP rule comparison. Earlier packages remain compatible with their existing methods. Without a private token MCP has ten public tools; the local source-comparison helper introduced in 0.1.9 remains available. Sale fees and net proceeds were added in 0.1.8 / Python 0.1.6.

These are downloadable source archives, not npm or PyPI registry releases. Installation may fetch the pinned MCP dependency; running HowSure does not install or invoke a model. Use npx --no-install to avoid fetching an unrelated package. Python runtime uses the standard library; building its source archive uses setuptools.

Full method reference and Python example · JavaScript source · TypeScript declarations · Python source. Published archives keep their original bytes; the online guide can receive documentation corrections independently.

Connect your local agent through MCP.

Install the JS archive first, then use this configuration in a client that supports stdio. Replace the module path with an absolute path to your installation. node must resolve to Node ≥22.17 in that application; use an absolute Node binary path if needed.

{
  "mcpServers": {
    "howsure": {
      "command": "node",
      "args": [
        "/absolute/path/to/your-project/node_modules/@howsure/client/howsure-mcp.mjs"
      ],
      "env": {
        "HOWSURE_ORIGIN": "https://www.howsure.com"
      }
    }
  }
}

This is a local process, not a hosted MCP URL. Public reads use HTTPS; the source-comparison tool works only on supplied objects. This public setup needs no HowSure token. Ten public tools are available:

• howsure_capabilities, howsure_search_markets, howsure_read_snapshot
• howsure_read_conditions, howsure_collect_source_evidence, howsure_read_order_book
• howsure_list_checks, howsure_read_check, howsure_compare_contracts
• howsure_compare_source_evidence · compare saved responses locally

For the first task, call search with {"q":"Fed October","limit":20}, select a returned ID, then pass it as marketId to conditions and market to evidence/book. The book arguments are {"market":"EXACT_RETURNED_ID","quantity":"500","outcome":"YES","side":"buy"}. Preserve the tool’s structured result, including gaps.

Save the basis. Return to its changes.

Owner watch results: in My work → Agent access to this version, separately permit saved/future results for the chosen read key. New clients request include_watch=true; older reads keep their response shape. Use howsure_read_research for status and howsure_read_research_updates for retained results. On agent_updates_access_changed, restart explicitly without cursor and deduplicate update IDs. Revoking result access does not stop the owner watch. Scope and recovery.

Resume after restart: JS/CLI/MCP 0.1.22 can recheck a saved version using only its document/version IDs and your scoped read key. The existing MCP tool howsure_read_research accepts {"documentId":"DOCUMENT_ID","version":"VERSION_ID","recheck":true}. CLI: howsure research-read DOCUMENT_ID --version VERSION_ID --recheck true. Without recheck, reading stays retained-only.

One private version read is followed by one public source request and a local comparison. Inspect status, observation times and gaps; a failed read is unavailable, not unchanged. The report contains the exact saved-version link and comparable captures, excluding your title, summary and notes. No save, watch or paid model starts. See the restart example and result contract; Python and HTTP retain their existing lower-level operations.

Public reading stays keyless. For continuity, sign in and open Account → Agent access. Create a named key and store its one-time value as HOWSURE_AGENT_TOKEN in your agent host’s secret settings. A recent verified login is required. Never paste it into a conversation, tool argument, source file or shared configuration.

1. Read access is the default. Select Save research to create or append an immutable version; select Manage source watches only if the agent should enable or disable source checks.
2. Read evidence for the exact contract, save that complete capture with a stable task ID, and keep the returned document, version, claim and link.
3. Open the returned link while signed in to the same account, or use My work. The human and agent read the same saved basis. Saving alone starts no watch.
4. Explicitly enable a watch when wanted. Later read updates using the last returned cursor, preserving changed, unchanged, unavailable and incomplete states.

import { HowsureClient } from '@howsure/client';
const client = new HowsureClient({
  agentToken: process.env.HOWSURE_AGENT_TOKEN,
  allowAgentWrites: true,
});
const evidence = await client.collectSourceEvidence('EXACT_POLYMARKET_REFERENCE');
const saved = await client.saveResearch({
  idempotencyKey: 'my-stable-task-id-001', title: 'My contract baseline', evidence,
});
const fixed = await client.readResearch(saved.documentId, { version: saved.versionId });
console.log(saved.href); // Open this exact version in your signed-in browser.
// Only if the user requested bounded source checks:
await client.setResearchWatch({ documentId: saved.documentId,
  versionId: saved.versionId, claimId: saved.claimId, enabled: true });
const updates = await client.readResearchUpdates({ limit: 10 });
// Keep nextCursor and pass it unchanged on the next read; do not invent one.

MCP: privately provide HOWSURE_AGENT_TOKEN to the installed local process. This enables howsure_list_research, howsure_read_research and howsure_read_research_updates. Additionally set HOWSURE_AGENT_WRITE=1 to expose howsure_save_research and howsure_set_research_watch; the token must still hold the corresponding permission. Keep host confirmation enabled for writes.

CLI: use research-list, research-read DOCUMENT_ID --version VERSION_ID, research-save INPUT.json, research-watch INPUT.json and research-updates --cursor CURSOR. Write inputs also accept stdin (-). Python provides the same operations; see the complete client reference.

Idempotency protects a retry of the identical save. To append, supply the document ID and latest expectedVersionId; conflicting edits fail instead of overwriting. Source captures are client-supplied and explicitly unverified. Hashes bind retained bytes, not truth or independent certification. A changed passage identifies a basis to review; its effect on a conclusion or probability can remain unknown.

Access boundary: keys can read agent-created versions and one-claim Check projections explicitly shared by the owner with that key. Other personal documents and Private notes stay inaccessible. In My work, open the exact Check version, choose Agent access to this version, preview the projection and choose an existing key. Shared reads require the exact version; grants are read-only and do not include future revisions. Several versions of one document can be listed, so retain each version ID. This is owner-scoped pilot access, not team roles or arbitrary workspace access. Revoke from Account; revocation blocks the credential and preserves saved work. Expanded fact watches enabled by that key stop on revocation or expiry. Legacy overview watches keep their existing limits and expiry; manage those separately in My work.

Five active keys per account, default expiry 30 days (UI offers 7 or 30; API maximum 90); 60 requests/minute per key, 120/minute and 2,000/day per account, 40 research/watch writes/day. The pilot retains at most 100 agent versions and 8 MB per account, alongside existing workspace limits. Keys are shown once and stored as hashes. Private responses are not cached. Credentials go only to fixed private HowSure paths; public calls never receive them and redirects are refused.

Exact PCE observation uses an independent default-off pilot: one lifetime target, 28 attempts and the same shared six-hour schedule. Its fixed seven-day UTC window runs from the day before the confirmed BEA date through six days after; this is not the official publication time. The saved month, core monthly measure, threshold and named-release version cannot expand. Enable through the existing watch action only for an authorized agent-created baseline; owner-shared human Checks cannot be watched by an agent. Revocation stops later checks; retained results remain readable. Preserve factComparison.kind: pce_release and the preceding-check comparison, including pending, cached and unavailable states.

Legacy overview watches retain the six-hour schedule and 14-day expiry. Expanded Fed decision and GDP release/bracket watches are off by default; an enabled pilot is limited to three targets, seven days and 28 attempts per target under shared capacity. The saved baseline fixes its exact scope. An expanded agent watch stops when its enabling key expires or is revoked. Updates preserve before/after facts, separate GDP revisions, cached and incomplete states. Coverage and omissions travel with each updates page; an empty page is not proof that sources stayed unchanged. Clients neither poll nor retry writes automatically. No paid model or new background collector is required.

Use the right identity for each read.

• Snapshot: the returned public slug in its path. No query parameters; as_of and generation return 400. It is a separate observation, not pinned to your search page.
• Conditions and Compare: exact canonical IDs. Conditions are Polymarket-only; Compare accepts 2–3 distinct retained Polymarket/HIP-4 IDs.
• Evidence and books: a returned Polymarket ID/public slug with a retained native mapping, or an exact native slug / https://polymarket.com/market/SLUG. Unknown IDs fail without a substitute. Event URLs do not identify one contract. Successful responses return the native market_slug.

Continue a bounded search.

Start with offset 0; limit is 1–100. Keep query, category and limit fixed, follow pagination.next_offset, and carry the returned non-null generation. Stop at null and inspect scope.truncated. A null generation is unpinned; do not invent a token or claim consistent pages. On 409, discard collected pages and restart at offset 0 without the old token. Clients do not loop for you.

Condition history has a different cursor: pass its returned nextCursor as before, with limit 1–20. Omit it on the first page, stop at null, and never convert it to an offset. not_retained means no saved history, not unchanged rules.

Read a fixed Check; assess applicability separately.

Use listChecks({ marketId }) to discover published versions for your exact contract, then readCheck(checkId, { marketId }). An empty registry is not a negative finding. Keep the fixed ID, reviewedAt, sources, limitations and links.page; a later version never silently replaces it.

The JS/CLI/MCP Check operation combines up to three GETs and returns an envelope with status, errors, fixed_record and separate updates. Preserve a validated historical record even if applicability fails. Python read_check reads only that record; call read_updates separately. Validated partial updates at HTTP 503 raise PartialResponseError with .data.

Updates compare retained contract context and saved source passages. They neither recrawl external sources nor create a new Check. unchanged describes comparable retained text, not the whole source or present truth. Source freshness can remain not_established; review provenance is not a claim of human or independent certification. The standalone Check reference client remains available.

Read the exact PCE or CPI monthly release.

The existing evidence tool recognizes the complete Core PCE MoM equality and exact 0.6% or more templates as contract_reading.family:us-core-pce. Preserve its exact month/year, seasonally adjusted core one-month measure, the question’s equality or inclusive 0.6% threshold at the official release’s one-decimal precision, venue-named schedule and delayed-release fallback. Headline PCE, CPI, annual changes, another month and arbitrary threshold wording are outside this reading.

The default BEA PCE overview is context only. Set includePceRelease: true (HTTP include_pce_release=true; CLI --include-pce-release true) to locate the exact month in the official BEA schedule and follow its listed Personal Income and Outlays release. The monthly paragraph and table must agree. The retained named release keeps its annual-update/archive notices; it is not proof of unchanged original bytes. Missing seasonal-adjustment provenance or unclear correction policy stays unknown. A future release without a publication link is pending; another month cannot fill the gap.

For the complete Core CPI-U monthly equality or exact 0.6% or more template, set includeCpiRelease: true (HTTP include_cpi_release=true; CLI --include-cpi-release true). Default CPI collection keeps the venue terms without a BLS source read. The optional path follows the official BLS index to its exact selected-month archive when listed, otherwise the fixed current summary; selected month/year, seasonally adjusted core monthly measure, Table A and release time must agree. Headline/annual values and the BLS seasonal-revision note remain separate. Automated requests identify HowSure with its public documentation URL. A source refusal remains unavailable; it is never replaced by an older successful capture. The fixed September 2026 Check retains its original October 14 source read separately from each new request. The archive URL date and printed release date must match the contract schedule; the reference month/year and monthly core measure must also match. sourceVersion distinguishes retained_archive_release from retained_current_summary. An existing retained current-summary response remains valid even if its index lists an archive. Unlisted destinations are never guessed, and another month cannot fill a missing selected release. Neither archive nor current bytes prove the original release was unchanged. Choose only one release/decision scope per call. JS/CLI/MCP 0.1.29 and Python 0.1.21 preserve these readings through explicit private save, exact-version read and export. Saving starts no observation. Exact monthly PCE uses only the separate explicit pilot; CPI watches remain unsupported. Existing Fed/GDP policies and budgets retain their scope.

For the retained September CPI source review, read the fixed October 14 Check. Keep its original source read time and unknown initial-version/correction status separate from each new BLS request.

Keep the GDP Advance figure separate from revisions.

Use collectSourceEvidence(market, { includeRelease: true }), CLI howsure evidence MARKET --include-release true, Python collect_source_evidence(market, include_release=True), or includeRelease:true on the existing MCP evidence tool. HTTP uses include_release=true; every opt-in result carries collection_scope:gdp_release. Choose this or Fed decision evidence; both cannot be true.

The bounded read follows the official BEA index to the selected quarter’s Advance release. contract_reading.release keeps the required quarter and vintage, observed figure and publication time, and any later estimate separately. Pending or missing evidence is explicit and does not establish a fallback. A condition assessment is not venue settlement. Omitted/false preserves ordinary collection; no model, account save or automatic monitoring is started.

For an exact shared boundary, add includeBrackets:true (CLI --include-brackets true, Python include_brackets=True, HTTP include_brackets=true). Release collection is required. The scope becomes gdp_release_brackets with up to six sources, including the complete event roster, closed contracts and an indexed historical revision when supported. release.brackets identifies the selected and assigned contracts. Missing or incompatible rosters and strict greater-than upper-tail equality remain unknown; no settlement is inferred.

Find what changed between two saved source reads.

Keep the first evidence response, make a separate explicit read when needed, and compare the retained responses for the same exact contract. JavaScript/CLI/MCP 0.1.9 and later use the product’s retained-text comparison. This does not refresh a source, replace your baseline or rewrite a saved conclusion.

Input: two raw SourceEvidenceResult objects with schema_version: howsure.evidence-request.v1. Use the earlier response as previous and the later one as current. If you saved the complete task above, first check response.evidence.ok, then extract response.evidence.data from each receipt. A mixed-task wrapper, an ID, a private document or an evidence_bundle alone is not accepted.

# Both files already contain raw source-evidence responses.
npx --no-install howsure evidence-compare first.json repeat.json

The CLI reads regular UTF-8 JSON files and prints JSON without rewriting either input. Its optional flags are --include-decision true|false or --include-release true|false, never both true; origin/timeout environment settings are ignored. Redirect stdout only to a different filename: shell redirection to an input file would truncate it before the command runs.

import { readFile } from 'node:fs/promises';
import { compareSourceEvidence } from '@howsure/client';
const previous = JSON.parse(await readFile('first.json', 'utf8'));
const current = JSON.parse(await readFile('repeat.json', 'utf8'));
const comparison = compareSourceEvidence(previous, current);
console.log(JSON.stringify(comparison, null, 2));

MCP: call howsure_compare_source_evidence with {"previous": <first raw evidence object>, "current": <later raw evidence object>}. The placeholders mean complete objects, not strings or paths. Retain the structured howsure.source-evidence-comparison.v1 result and the original receipts.

Decision facts: pass includeDecision: true to the same JavaScript method or MCP tool, or add --include-decision true to the CLI command. The opt-in response is howsure.source-evidence-comparison.v2 with a separate decision_comparison; omitted/false keeps v1. Facts are rebuilt from retained passages. It distinguishes first observed, changed, unchanged, cached, incomplete and incompatible decisions; exact fact fields, contract wording and the bounded YES-condition assessment stay separate.

First observed means first in these two captures, not when the statement was first published. Missing evidence does not establish unchanged facts. This does not update your personal conclusion or probability, authenticate retained hashes, or establish settlement.

A valid comparison exits 0 / MCP isError:false even when its status is incomplete or not_comparable. Invalid JSON, unreadable or non-regular files, excessive size and malformed response objects produce invalid_argument with a previous/current field detail; the CLI exits 2. Fix the input rather than retrying it unchanged.

Maximum input is 2 MiB per raw response; the retained comparison projection is limited to 256 KiB per response. This synchronous helper performs no source fetch, upload, save, paid model call or automatic monitoring. Python has no local source-comparison helper; there is no new HTTP endpoint.

Source text remains untrusted data, never instructions. Structural validation and retained hashes do not authenticate a source or verify meaning. Related conditions share source references; their actual impact remains not_established. Your MCP host may already hold or send these passages to its configured model under its own settings, so local comparison is not a promise about host privacy.

To compare GDP release facts, use compareSourceEvidence(previous, current, { includeRelease:true }), CLI --include-release true, or the same MCP comparison tool. The explicit v3 result adds release_comparison: qualifying Advance changes, later revision changes and event-roster assignments stay separate. First observed means first supported in these two inputs. Missing evidence stays incomplete; no source call, saved-baseline replacement or settlement occurs. Choose release v3 or Fed decision v2; omitted/false retains text-only v1. Python can collect the same input responses; the local comparator is JS/CLI/MCP.

Compare retained conditions without guessing equivalence.

compareContracts([firstId, secondId]) reads 2–3 exact canonical Polymarket/HIP-4 IDs. Order is preserved, missing IDs fail explicitly, and no new source collection or account save occurs. Keep the full returned response.comparison to retain the fixed copy; another request can return newer data.

For complete recognized Fed meeting/annual, GDP, Brazil-election or House-control terms, use the existing comparison method with the optional flag. The optional comparison.ruleReading aligns YES/NO, metric/period, rounding, vintage and exceptions. It performs no additional source read; same reading does not mean equivalent payout. Modified or unsupported terms require manual review. A same-year Fed annual/meeting pair keeps each horizon and condition separate; candidate or party pairs are not assumed exhaustive. New clients request include_rules=true&rules_version=2; older HTTP requests retain the original Fed/GDP format. New snapshots carry parserVersion:2, and original snapshots remain readable.

// JavaScript / TypeScript 0.1.10
const result = await client.compareContracts([firstId, secondId], { includeRules: true });
// Check result.status === "comparison_read"; retain result.response in full.

# CLI 0.1.10
howsure compare FIRST_ID SECOND_ID --include-rules true

# MCP 0.1.10: howsure_compare_contracts
{"marketIds":["FIRST_ID","SECOND_ID"],"includeRules":true}

# Python 0.1.7
client.compare_contracts([first_id, second_id], include_rules=True)

const query = new URLSearchParams([
  ["market_id", firstId], ["market_id", secondId], ["include_rules", "true"]
]);
const response = await fetch(origin + "/api/free/v1/contracts/compare?" + query);
const body = await response.json(); // Check response.ok before using comparison
// Keep the complete body.comparison, including original fields and times.

Omitting the flag or using false preserves the previous v1 response. All clients keep that default. An explicit request rejects a missing or malformed rule block as malformed_response; unsupported terms remain a valid, limited result. The web Compare uses the same interpretation in its JSON, Markdown and saved versions. Interpretation does not refresh observations or establish independent source evidence.

scope: retained_serving_only and equivalence: not_assessed are deliberate. Matching text does not prove equal payouts; price differences do not prove arbitrage. This endpoint does not accept Kalshi, native venue links or public slugs. Kalshi is not enabled in the public product. An internal one-pair research read is not an integration or data-use permission.

Partial data and failed operations are different.

For quantity: 'banana', inspect details and correct the next call to a decimal share string such as '500'. Quantity is positive, ≤1,000,000, with ≤8 decimal places. Outcomes are YES/NO; sides are buy/sell.

JS errors preserve code, status, apiError, message, retryable, details, hint and retryAfter. Python uses api_error/retry_after; CLI/MCP expose a structured error. Fields absent from an endpoint stay absent; not every route supplies every field. JS Check/Compare return result envelopes rather than throwing for all failed reads.

HTTP 400 means fix the request; 404 is an exact record absent from a successful read; 409 means restart pagination; 429 means respect retry guidance; 503 means unavailable or partial, never zero or unchanged. retryable is information, not an automatic retry instruction. SDKs return partial evidence/books without changing them; use the statuses inside the response.

Retain a receipt, not just a number.

• Keep the full response: selected ID, raw contract question, source URLs, source/metadata/book times, expiry, hashes, gaps, quantity/outcome/side and fee status.
• Client receipt time and HTTP fetched_at do not replace a source observation time. Separate calls and the two outcome books are not atomic.
• A content digest binds bytes; it does not establish factual truth, independent review, rights or settlement. A public market URL may change; fixed Check IDs are separately versioned.
• Market price is not a HowSure forecast. Null is not zero, 50%, or a negative outcome; an empty search only covers its bounded selection.
• Buy walks asks, sell walks bids. Gross uses collateral units. With include_cost=true, confirmed CTF/CLOB parameters support an estimated taker purchase fee and cost for covered shares. Keep the model assumptions and separate fee/book times; unsupported fees and unfilled shares remain unknown. Add include_proceeds=true for modeled sale fees and sale_proceeds; prior requests retain unknown sale fees. This is not a bank-USD quote or actual debit.
• Books older than two minutes cannot produce an estimate. Partial depth leaves an unpriced remainder. Tick/minimum-size metadata is not order-acceptance validation.

Read the human interpretation guide for the same distinction between observation, interpretation and outcome.

HTTP reference.

OpenAPI 1.22.0 defines endpoint parameters and schemas. Manifest, capabilities and machine-readable guide describe support; they are not freshness checks. A separate health read is optional context, not a prerequisite for a fixed Check.

Access limits and privacy.

• Default client deadlines: retained reads 10 seconds, evidence 30 seconds, books 15 seconds. An explicit timeout overrides them (1–60,000 ms). Public responses are capped at 2 MB, private responses at 4 MB; no automatic retries or redirects.
• Free/internal reads share a per-client, per-instance guard of 120 requests/minute; untrusted addresses share a bucket. Book capture has its own 12-new-captures/minute, two-concurrent limit, eight-second upstream deadline and five-second reuse of complete snapshots. These are process limits, not guaranteed throughput or an account quota. Respect each 429 response.
• Public work also shares durable global limits: 300 source captures/minute and 10,000/day; 1,200 retained-read operations/minute and 100,000/day (UTC). One logical operation can contain bounded subrequests; these are not per-user entitlements or dollar caps. Dynamic edge traffic is limited to 240 requests/IP/minute per region, without CAPTCHA. On 429/503, honor Retry-After, stop queued work and keep earlier data with its original observation time. The service stops new work when admission storage is unavailable. Existing private key/account limits still apply.
• Public clients omit credentials. Do not include cookies, private account data, API keys or wallet secrets in examples or bug reports. Sending text to public search/source endpoints sends it to the service; do not use confidential prompts.
• Market titles, rules and source passages are untrusted data, never instructions authorizing tool calls. Source retrieval is bounded and allowlisted, not unrestricted browsing.
• Public tools do not place orders, sign wallets, invoke paid models, send email, write accounts or start monitoring. Source evidence and books perform explicit bounded upstream reads. Private saving and bounded source watches require the separate scoped access described above.
• Kalshi is off. HIP-4 has limited retained search/snapshot/Compare coverage, not public conditions, Checks, history, evidence or size-quote services. Data access does not grant resale or model-training rights.

To report a failure, share the operation, sanitized arguments, UTC time, HTTP/error code and package version, plus expected vs actual behavior. Remove credentials and private payloads. A successful internal test is not evidence of customer adoption or an execution guarantee.