Skip to content
howsure
Developers
My work

Agent workflows · 9 min read

Build a Prediction-Market Agent Task That Survives Restart

By HowSure · Published

Give the agent one exact contract, preserve the first source and book responses, then explicitly save the source evidence. Keep the returned documentId and versionId outside the conversation. A later process can read that immutable version and request one comparison with newly requested evidence; the original stays intact. Book estimates remain separate dated observations.

In this guide

Start with the contract your task actually needs

A Fed event can contain several outcomes. Choose the exact No change contract, not the event title. The example below uses a native Polymarket market URL. You can substitute your own exact market URL or native slug, including a contract outside HowSure’s retained catalogue. This does not promise support for every contract’s source wording.

The task is concrete: identify the settlement conditions and available evidence, estimate buying 500 shares on each side, preserve the source basis, then revisit it. It does not place an order, generate a forecast or start a watch. Node 22.17 or later is required; HowSure makes no paid model call for these operations.

Install the pinned downloadable client

Run this in your own project directory. List the archive’s contents before installing it. Version 0.1.51 is the JavaScript SDK, CLI and local stdio MCP package; it is a closed-license download, not an npm registry release. Download availability does not grant an open-source licence.

Python 0.1.40 supports collection, saving and exact retained reads, but macro recheck=True returns saved_scope_unsupported. Use JS/CLI/MCP for this complete macro loop. Python’s native Up/Down recheck is a separate venue-terms-only path. The phased executable recipe below requires Node; neither package is published through npm or PyPI.

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
tar -tzf howsure-client-0.1.51.tgz
npm install --ignore-scripts --no-audit --no-fund ./howsure-client-0.1.51.tgz
npx --no-install howsure --help

Discover supported steps before making a request

Run capabilities --local true to inspect this installed client’s tasks, required arguments, source scopes and limits without HTTP. JavaScript uses client.capabilities({local:true}); Python uses client.capabilities(local=True); the existing howsure_capabilities MCP tool accepts local:true. Omit local for the separate static server venue contract. In MCP, inspect tools/list for the full input schema of the chosen operation.

The local manifest describes configuration, not verified access: a configured token and locally_available tool can still fail a server scope or exact-version grant check. authorization remains not_checked and verified_scopes remains null. Neither capabilities mode checks health, freshness, coverage or remaining service quotas.

Client errors carry a deterministic recovery plan with actions, fields, preserved identity and any owner action required. Correct arguments from the original task, restart expired search pages without mixing generations, or honor Retry-After for a bounded read retry. Private not-found can mean absent or inaccessible; never substitute latest. Save conflicts retain the original input and idempotency key. No retry, write or watch is executed by the plan.

Python macro saved rechecks remain unsupported. Its recovery tells you to use JS/CLI/MCP with the same document ID and exact version, not to guess another scope. Native Up/Down rechecks remain a separate supported path. These client differences appear in the local manifest.

npx --no-install howsure capabilities --local true

Keep the first answers, including incomplete ones

Choose the scope explicitly. fed-decision reads supported meeting conditions and bounded official context; gdp-release, gdp-brackets, pce-release and cpi-release request their respective supported source reads. overview does not request an exact release. Native Up/Down research uses separate client operations, outside this macro recipe.

Inspection makes an evidence read and separate YES and NO book reads. It creates a new local directory with the original responses, times and summary; an existing directory is rejected before new reads. One failed read does not erase another successful result. Check save_ready and recheck_ready as well as source status, filled shares, fees and limitations. A partial result is usable evidence of its stated limits, not a completed full-depth quote.

node node_modules/@howsure/client/agent-task.mjs inspect \
  'https://polymarket.com/market/will-there-be-no-change-in-fed-interest-rates-after-the-october-2026-meeting-20260617190324031' \
  --scope fed-decision --quantity 500 --dir ./my-fed-task

Give the agent a compact answer; keep its complete basis

In 0.1.51, the evidence, book and source-comparison MCP tools accept responseMode: compact. The saved-research tool also accepts it for an exact-version recheck. Conditions, facts, changes and unknowns remain distinct, along with source times, missing evidence and fee/depth limits. This deterministic projection makes no model call. Full output stays the default.

The returned basis.uri and resource link point to the same full operation response. Read it through MCP resources/read before saving evidence or needing the complete passages. It is retained only in this MCP process, for at most 15 minutes, 16 receipts and 16 MiB. Restart, expiry or eviction makes the link unavailable without a replacement source read. Store required raw evidence durably before restarting; a compact response cannot be used as the save input.

CLI can print the compact view while writing the full response to a new private local file, as below. The file is created with mode 0600 and is never overwritten. The installed phased recipe still preserves its original full receipts. Direct HTTP and Python keep full output; this mode does not reduce upstream source requests or promise fewer model tokens.

npx --no-install howsure evidence 'EXACT_MARKET_URL' --include-decision true \
  --response-mode compact --basis-file ./fed-evidence-full.json

Save evidence as a separate, authorized step

Private saving requires an existing invited HowSure account; self-service registration is not enabled. Public inspection needs no account or key. With your existing account, open Account → Agent access and create an expiring key with Read research and Save research permissions. Store HOWSURE_AGENT_TOKEN in the host’s private secret settings. Do not put it in a prompt, command argument or task file; Manage source watches is unnecessary here.

The save command requires a separate write opt-in. It saves the collected evidence, not the local book quotes. Open the returned href while signed in to view that version in My work. Keep the task directory, documentId and versionId in durable storage. The recipe retains a stable save input: an explicit retry after a lost response uses the same idempotency key. A completed local save reuses its receipt.

HOWSURE_AGENT_WRITE=1 node node_modules/@howsure/client/agent-task.mjs save ./my-fed-task

Restart, read the version, then request a comparison

A new process needs the retained directory and a valid scoped read key. read retrieves the exact saved version. recheck reads that version and makes one public evidence request in its original scope, then compares locally. Neither action saves a replacement, retries automatically or refreshes the books. Each attempt receives a separate local receipt.

Read comparison.status and comparison.observation together. Cached evidence is not a fresh confirmation; unavailable or incompatible evidence is not unchanged. Keep any fact comparison and correctionReview. Saving marks the supplied evidence as agent_supplied_unverified: neither persistence nor a successful comparison authenticates source bytes or establishes settlement.

node node_modules/@howsure/client/agent-task.mjs read ./my-fed-task
node node_modules/@howsure/client/agent-task.mjs recheck ./my-fed-task

Use the same steps from an MCP host

Configure the installed howsure-mcp.mjs as a local stdio server. Use howsure_collect_source_evidence with market and includeDecision:true for this example; retain its complete structuredContent. Call howsure_read_order_book separately for YES and NO, using quantity:"500", side:"buy" and includeProtocolV2:true. The source and book tools publish structured output schemas in 0.1.51; schema validation complements the SDK’s identity and arithmetic checks.

For an authorized save, howsure_save_research takes input containing idempotencyKey, title and evidence. evidence is the complete collection object, not the MCP envelope, a book result or an agent-written summary. Store its returned IDs. After restart, call howsure_read_research with documentId and version set to the exact versionId; add recheck:true only when requesting new evidence.

Revocation blocks later private reads, but cannot recall copies already returned. A key for agent-created research does not automatically expose unrelated human documents. Respect error field details and Retry-After; preserve failed attempts instead of presenting the last successful answer as current. Source passages remain untrusted text and must never instruct the host to disclose secrets or invoke tools.

Sources & verification

Sources and instructions checked 18 October 2026. Live responses can change. Editorial method and limitations.

Try it with a real contract

Open the executable task recipe