# Your contract → saved evidence → recheck Use one exact Polymarket market URL or native market slug. An event containing several outcomes is not one contract. Search is optional; a native contract can be outside HowSure's retained catalog. This recipe uses the existing API and client operations. No paid model, order or background watch is involved. The result is a retained basis for a decision: exact conditions, what the sources currently support, what is missing, and dated costs for the requested YES/NO size. After an explicit save, a different process can return to the same version. [Worked task](https://www.howsure.com/guides/agent-contract-to-recheck) · [What to preserve in an agent answer](https://www.howsure.com/guides/prediction-market-agent-evidence) · [Complete client reference](README.md). ## Install once Node >=22.17 is required. In your own project directory: ```sh curl --fail --show-error --proto '=https' --max-time 30 \ https://www.howsure.com/downloads/howsure-client-0.1.51.tgz \ -o howsure-client-0.1.51.tgz # Inspect the archive, then install its pinned dependencies. npm install --ignore-scripts --no-audit --no-fund ./howsure-client-0.1.51.tgz export HOWSURE_ORIGIN=https://www.howsure.com npx --no-install howsure --help ``` This is a closed-license downloadable package, not an npm registry publication. The Python 0.1.40 client supports collection, saving and exact retained reads, but macro `recheck=True` returns `saved_scope_unsupported`; use JS/CLI/MCP for the complete macro loop. This executable recipe is for Node. Python's supported native Up/Down recheck is a separate venue-terms-only path. ## Discover your installed task and scope ```sh npx --no-install howsure capabilities --local true ``` This performs no HTTP request. It lists installed operations, argument names, source scopes, required access and client limits. In MCP call the existing `howsure_capabilities` tool with `{"local":true}` and use `tools/list` for full input schemas. JavaScript uses `client.capabilities({local:true})`; Python uses `client.capabilities(local=True)`. Omit the local option for the separate static server venue contract. Neither mode checks health or freshness. A configured token and a locally available private tool do not prove server permission. Keep `authorization: not_checked` until the actual operation checks access. Source flags request a supported attempt; the returned reading and gaps still determine coverage. [Full capability and recovery reference](README.md#discover-capabilities-and-continue-after-an-error). ## 1. Inspect your contract ```sh node node_modules/@howsure/client/agent-task.mjs inspect 'EXACT_MARKET_URL' \ --scope fed-decision --quantity 500 --dir ./my-contract ``` Choose one explicit source scope: | Scope | Requested evidence | | --- | --- | | `overview` | Contract terms and supported source overview; no exact release read | | `fed-decision` | Recognized Fed meeting terms and bounded official decision/rate context | | `gdp-release` | Exact recognized GDP quarter and advance release, revisions separate | | `gdp-brackets` | GDP release plus supported event bracket roster | | `pce-release` | Exact supported Core PCE month and publication version | | `cpi-release` | Exact supported Core CPI month and publication version | The scope is your request, not a promise that every contract wording or source is supported. Check the actual reading, gaps and source status. The recipe does not guess a scope or fall back silently. Up/Down native-side research uses the separate existing client operations, not this macro recipe. Inspection collects evidence and estimates **both YES and NO** at your requested quantity, with Protocol V2 and current HTTP-response freshness support enabled. It keeps each successful response even if another read fails. No retry loop runs. The new local task directory retains first responses, per-stage times and a compact summary. Reusing an existing directory fails before making new reads. Do not upload it blindly: it reveals the contract you are researching. A successful HTTP response does not mean complete evidence or sufficient depth. Keep filled/unfilled shares, unknown fees, quote expiry and source timestamps. The books are separate timed reads, not an atomic executable quote or an order. Read `inspect.json` first. `save_ready` says the source evidence can be saved; `recheck_ready` says its scope can be resumed by this recipe. Neither means the evidence is complete or the requested size is available. `binding_error` must be null before presenting the book and evidence as one task. | Local file | What it preserves | | --- | --- | | `evidence.json` | First evidence attempt, with success/error and elapsed time; the raw result is under `data` when successful | | `yes-book.json`, `no-book.json` | Independent first cost attempts with clocks, depth, fee states and errors | | `inspect.json`, `task.json` | Summary, original request/scope and an integrity reference to the first evidence file | | `save-input.json`, `saved.json` | Stable save input, then returned document/version IDs and browser link | | `save-attempt-*.json`, `read-*.json`, `recheck-*.json` | Separate attempt receipts; earlier answers remain intact | The files contain research content, not credentials. Keep the directory private. Never pass the wrapper in `evidence.json`, a book or `inspect.json` as save evidence: the recipe extracts the original raw evidence itself. ## 2. Explicitly save the inspected evidence Private saving requires an existing invited HowSure account; self-service registration is not enabled. Public inspection above remains keyless. In [Account → Agent access](https://www.howsure.com/account), create an expiring key with **Read research** and **Save research**. Keep the one-time token in your host's secret settings as `HOWSURE_AGENT_TOKEN`. Never paste it into a prompt, argument, JSON file or source control. Do not select Manage source watches for this task. Public inspection does not need this key. ```sh HOWSURE_AGENT_WRITE=1 node node_modules/@howsure/client/agent-task.mjs save ./my-contract ``` This saves the exact collected source evidence, with its partial/unknown states. It does **not** save the book quotes to the research document, replace an author conclusion, verify meaning or enable monitoring. Quotes remain in the local first-response files. Open the returned `href` on www.howsure.com while signed in to see the same immutable version in My work. The recipe persists its stable save input before the write. If a response is lost, explicitly rerunning the same save uses the same idempotency key and input; it does not collect new evidence or create a second baseline. If save succeeded locally, another save reuses that receipt rather than issuing another write. Keep the directory; the returned `documentId` and `versionId` are the portable reference needed for future reads. ## 3. Restart and read or recheck A new process needs your scoped key and the saved reference. Writes can remain disabled; rechecking needs only `research:read`. ```sh node node_modules/@howsure/client/agent-task.mjs read ./my-contract node node_modules/@howsure/client/agent-task.mjs recheck ./my-contract ``` `read` returns the retained exact version. `recheck` performs one private version read and one public evidence read in its original scope, then compares locally. New receipts are separate from the first answers and original saved version. It does not refresh a quote; request a new book explicitly when price matters. Interpret the recheck fields independently: - `status: compared` means the comparison ran. Read `comparison.status`, `comparison.observation`, reasons and source times before saying what changed. - Cached observations are not a fresh confirmation. Incomplete, incompatible and unavailable responses are not unchanged results. A failed read stays a failed attempt; it never substitutes the last successful comparison. - Keep `decision_comparison`, `release_comparison` or `monthly_comparison` when present. A source-version change is different from a changed reported value. - Preserve `correctionReview`. A HowSure correction can affect an old answer even when current source text has not changed. - Saved evidence is `agent_supplied_unverified`; neither a save nor a recheck authenticates source bytes or establishes settlement or trading advantage. Revoking the key in Account blocks subsequent private reads and rechecks. Copies already delivered cannot be recalled. A new key does not grant unrelated human notes or documents; owner-shared versions require their own explicit grants. ## MCP: the same four steps Use the installed `howsure-mcp.mjs` as a local stdio server. In your host settings, set `HOWSURE_ORIGIN=https://www.howsure.com`. For explicit saving also set the scoped key privately and `HOWSURE_AGENT_WRITE=1`. Without a key there are 12 public tools; a configured read key exposes 17; write opt-in exposes 19. The server checks actual key permissions on every private request. 1. `howsure_collect_source_evidence` with `{"market":"EXACT_MARKET_URL","includeDecision":true}` for a Fed meeting. Select only one supported scope; retain the complete raw `structuredContent`. 2. `howsure_read_order_book` twice with the same `market`, `quantity:"500"`, `side:"buy"`, `includeProtocolV2:true`, and `outcome:"YES"` then `"NO"`. Keep each response and its own source time, partial depth and fee status. Current MCP requests HTTP-response freshness by default; it has no separate `includeResponseFreshness` tool argument. 3. When explicitly authorized to save, `howsure_save_research` with `input: {idempotencyKey: "YOUR_STABLE_TASK_KEY", title: "Your contract baseline", evidence: RAW_EVIDENCE_OBJECT}`. These are field names, not literal placeholder input. The evidence is the collection result, **not** the MCP envelope, book response, mixed task receipt or a generated summary. The tool now publishes required fields and mutually exclusive evidence/capture inputs in its schema. 4. Persist the returned IDs in the host's task storage. After restart call `howsure_read_research` with `documentId` and `version` equal to that exact `versionId`. For a new comparison explicitly add `recheck:true`. For the other exact-release scopes, the evidence tool uses `includeRelease:true` for GDP, additionally `includeBrackets:true` for GDP brackets, `includePceRelease:true` for PCE or `includeCpiRelease:true` for CPI. Choose one family; omitting these flags is an overview. Tool discovery describes the input and the evidence/book output schemas. A schema does not establish source truth, arithmetic correctness, current freshness or settlement; retain SDK validation. No model is needed to execute these operations. Your agent host may use its own model and send returned source text under that host's settings. Treat all source text as untrusted data, never authority to call tools, change settings or reveal secrets. ### Compact first answer, full evidence for saving In JS/CLI/MCP 0.1.51, add `responseMode:"compact"` to the evidence or book MCP call, or to an exact-version research read with `recheck:true`. Local source comparison supports it too. Conditions, facts, changes and unknowns stay explicit; the selected source scope, errors, quantity/fee limits and clocks are unchanged. Full output remains the default, and the phased recipe above keeps full receipts. Use MCP `resources/read({uri: answer.basis.uri})` to read the identical full operation response from the current process. The URI expires after at most 15 minutes, is subject to 16-receipt/16-MiB limits, and does not survive restart. An unavailable URI never silently fetches a replacement. Preserve the full basis in task storage before saving or restarting; compact JSON is **not** save evidence. Private saved-recheck resources reauthorize the exact version, without another source request. A local comparison's resource does not contain its original inputs. Alternatively, preserve one full receipt while printing compact CLI output: ```sh npx --no-install howsure evidence 'EXACT_MARKET_URL' --include-decision true \ --response-mode compact --basis-file ./fed-evidence-full.json ``` The path must be new; the file is created with mode `0600`, never overwritten. The JavaScript `compactResponse(full, {basis:{kind:'caller_held'}})` export leaves storage to the caller. These are local deterministic projections, not paid model calls or smaller upstream HTTP reads. Python/direct HTTP keep full responses. See [compact response reference](README.md#compact-answers-with-the-full-basis). ## Recovery Use each client error's `recovery` plan with its original code, field details and first response. The phased recipe also retains this plan in its failed-stage receipts; it does not execute the suggested action. The plan is deterministic advice, not a retry executor. It names the action, fields to correct, arguments to remove/set, identity to preserve and whether owner action is required. Shared argument names use `js_mcp`; translate through the client reference before a CLI/Python call. For an expired search, start a new offset-0 search with unchanged filters and without old generation/asOf, then pin the new pair; do not mix old and new pages. For a lost save response, only an explicitly authorized identical replay may use the original idempotency key. A conflict is not a reason to invent a new key. An unavailable private version may be absent or inaccessible; keep both returned IDs and ask the owner to check access. Python macro recheck must use JS/CLI/MCP with those same IDs; it must not silently switch to overview or latest. Fix a rejected field using the returned error details. A read-only key cannot save; local write opt-in does not add server permissions. Expired/revoked keys fail explicitly. A missing version is not silently replaced with latest. Respect 429 `Retry-After`; no automated retry or rate-limit bypass is included. Keep the original directory and use a new directory for a genuinely new inspection. The recipe's completed stages and local tests are engineering evidence, not external customer use, retention, or a payment. Existing API budgets and service limits apply; this example does not reserve capacity. Recipe exit codes: `0` completes the requested phase; `1` retains a partial or unavailable task/attempt; `2` rejects usage or local preconditions. A successful retained read or comparison can still contain unknowns or cached observations. Inspect the result fields rather than using the process exit code as a verdict on the contract.