HNCH on DogeOS: documentation

Sightlines · Bones · Feeds · MCP for agents · HNCH Town  ·  Open the game  ·  llms.txt  ·  Source

HNCH on DogeOS

HNCH is a set of oracles on the DogeOS Chikyū testnet: time-weighted prices read live from Barkswap pools (Sightlines), an optimistic oracle for questions settled with HNCH bonds and a staked court (Bones), Chainlink-shaped feeds over the prices, an MCP server for AI agents, a REST API, and a phone game (HNCH Town) in which humans play the same protocol. This page is the reference for all of it. The same text is served verbatim to AI crawlers as llms-full.txt.

Everything described here is live on the testnet as of 31 October 2026. Nothing on it has real value.

What HNCH is

Smart contracts need facts from outside the chain: the price of a token right now, whether an event happened, which of several outcomes came true. On a new chain the usual sources are missing. There is no reporter network, no established price feed, and no court to ask when two parties disagree. Integrators build on mock feeds, and agents that want to act on a fact have no way to get one they can defend.

HNCH answers with two kinds of truth. The first is mechanical: a Sightline is a time-weighted average price for one token pair over one window, read live from the oracle that Barkswap's own pools already write on every swap. Nothing is posted, nobody reports, and every number arrives with the guards (liquidity, age, trade count, divergence flags) a consumer needs to decide whether to trust it. The second is adversarial: a Bone is a question anyone can ask by paying a fee in HNCH. Anyone may answer by posting a bond. Anyone who disagrees may challenge by doubling the bond. After three challenges a court of HNCH stakers votes. Losing bonds pay winning bonds, so lying costs and being right pays. Price questions name a Sightline as their source, so the adversarial oracle rests on the mechanical one and disputes stay rare.

Three kinds of user share one token and one protocol. DeFi integrators read Sightlines through a Chainlink-shaped feed or a Solidity library and refuse numbers that fail their own guards. AI agents connect to the MCP server, read prices and questions without credentials, and prepare transactions they sign themselves. Players open HNCH Town on a phone and ask, answer, challenge, judge and settle the same questions with a wallet from the DogeOS login kit. Agents and players are citizens of the same town.

Quick facts

Item Value
Chain DogeOS Chikyū testnet
Chain id 6281971
RPC https://rpc.testnet.dogeos.com and https://dogeos-testnet.drpc.org
Explorer https://blockscout.testnet.dogeos.com
Token HNCH 0xF4EC5f6F82d25799BA09827cBa2393AF33A026E6 (18 decimals, EIP-2612 permit, name "Hunch")
Gas tDOGE from the DogeOS faucet https://faucet.testnet.dogeos.com
Game https://thehunch.app
Docs https://thehunch.app/docs
MCP endpoint https://thehunch.app/mcp (Streamable HTTP, stateless, read tools plus prepare-mode write tools)
REST base https://thehunch.app/v1
Source https://github.com/operalag/hunch-dogeos

The HNCH token is an OpenZeppelin 5 ERC-20 with ERC20Permit, ERC20Burnable and two-step ownership. Its hard cap is 1,000,000,000 HNCH; the genesis mint was 1,000,000 HNCH to the deployer wallet on 29 October 2026. Minting is owner-only, under the cap, with a public reason string. The deployer wallet owns the token on the testnet.

Sightlines: prices

What a Sightline is

A Sightline is the triple (base token, quote token, window) mapped to a time-weighted average price over that window. It is read live from the Algebra Integral oracle plugin that Barkswap's pools maintain on-chain: every swap writes a timepoint, and the Sightlines contract reads those timepoints through a view call. No keeper, no reporter set, no transaction per price, no L1 data fee per reading. The number is the chain's number.

The quote defaults to USDT, which the tools treat as "USD". When no direct pool exists, a Sightline composes base/WDOGE with WDOGE/quote; ticks add, so the composition is exact. The contract exposes price(base, quote, window) for one reading, prices(base, quote) for all eight windows, history(base, quote, window, secondsAgos[]) for past prices computed from the pool's own buffer, and route(base, quote) for the pools behind a pair.

Reading field Meaning
price1e18 quote per one base, human units, 1e18 fixed point; 0 when NO_HISTORY
liquidity in-range liquidity, the minimum over the route's legs
oldestObservation unix time of the pool's oldest recorded timepoint
timepointsInWindow timepoints written inside the window; 0 means nobody traded
volatility Algebra's volatility cumulative over the window
flags bit set, see below
pool0, pool1 the route; pool1 is zero for a direct pool
asOf the block time of the reading

The eight windows

Label Seconds
5m 300
10m 600
30m 1,800
1h 3,600
12h 43,200
24h 86,400
1w 604,800
1m (30 days) 2,592,000

Any other window reverts with InvalidWindow. A window longer than the pool's history answers NO_HISTORY with price 0, never a guess.

Flags and guards

Flag Bit Set when
UNLISTED 1 the registry does not vouch for the pair; still the chain's number, but nobody checked the pool
THIN 2 in-range liquidity under the floor (1e21 raw units) or the pool is younger than 24 hours
NO_HISTORY 4 the pool is younger than the window; price is 0
DIVERGENCE 8 the 5-minute and 1-hour prices differ by more than 5 percent (500 bps), the fingerprint of a short manipulation
NOT_RECORDING 16 the pool's plugin has its before-swap hook off, so its oracle never records a trade; 44 of 179 Chikyū pools
NO_TRADES 32 no timepoint landed inside the window; the price is the last trade's, not a market
ROUTE_DRIFT 64 the pair is listed, but the live best route by liquidity now differs from the pinned one

A plugin that reverts, or is not an oracle, yields NO_HISTORY together with NOT_RECORDING instead of a revert. The MCP and REST layers decode the bits into flags.unlisted, thin, noHistory, divergence, routeDrift, plus guards.oracleRecording and guards.swapsInWindow.

The registry

SightlineRegistry holds the pairs the project vouches for. Listing pins the route: list(base, quote, pool0, pool1) records the pools, and a listed pair always reads them. Nobody can move a vouched Sightline onto another pool by depositing liquidity elsewhere; if the live best route changes, the reading sets ROUTE_DRIFT and keeps reading the pinned pools. An unlisted pair resolves live: the direct pool when it exists and clears the liquidity floor; otherwise base/WDOGE times WDOGE/quote when both legs clear the floor; otherwise whatever exists, flagged THIN; otherwise NoRoute. dynamicRoute() exposes the live resolution.

Floors: minLiquidity 1e21, minAge 86,400 seconds, maxDivergenceBps 500. Twenty-five pairs are listed, among them WDOGE/USDT, USDC/USDT, USD1/USDT, WETH/USDT, BARK/WDOGE, USDC/WDOGE, LBTC/USDC, BARK/USDT (routed through WDOGE) and HNCH/USDT. The HNCH/USDT pool (0x225D34996d3607ea390e4846d7b9c4E7A6221A31, USDT is token0) was created on 29 October with a single-sided ask ladder of 400,000 HNCH above 0.01 USDT, which left its in-range liquidity at zero; on 31 October the project added a two-sided position around 0.01 USDT per HNCH (range 0.005 to 0.02, about 165 USDT plus 16,500 HNCH, position #12255), so the pool now quotes both ways with in-range liquidity of about 5.67e21 raw units, and the pair was listed. The registry owner is the deployer wallet until a Safe exists.

The tools accept these symbols: USDT, USDC, WDOGE, BARK, WETH, LBTC, USD1 and HNCH, all with 18 decimals on Chikyū. Any other token is accepted by address. A second contract on Chikyū also uses the symbol BARK; the tools report it under alternates and never pick it silently.

Honest limits

A time-weighted average on a thin testnet pool can be moved for the cost of holding the pool at a false price for the length of the window. Sightlines publish liquidity, trade count and volatility so a consumer can refuse thin numbers, and the registry refuses to list pools under the floor. For anything that moves value, read two windows and respect the divergence flag; the consumer library does this in one call.

Barkswap's oracle keeps 65,536 timepoints per pool. A busy pool such as WDOGE/USDT writes about 3,000 a day, so after roughly three weeks the ring wraps, oldestObservation moves forward, and about 22 days of history remain. From then on the 1w and 1m windows answer NO_HISTORY for exactly the pools that trade most. Plan on 1h to 24h for active pairs; get_pool_health reports retentionSeconds and windowsAvailable.

Bones: questions with teeth

Bones is the Hunch dispute game ported to Solidity with HNCH bonds, fees, bounties and a staked HNCH court. Four contracts, no proxies, parameters immutable per deployment: HunchOracle (questions, bonds, challenges, settlement, reopening, claims, bounties, consumer callbacks, Reality.eth-style views isFinalized and resultFor, enumeration), HunchCourt (staking with checkpoints, binary cases), HunchTreasury (the fee split and epochs) and HunchGuardian (a testnet 2-of-3 with two powers).

Lifecycle

A question moves through OPEN, PROPOSED, CHALLENGED, COURT and SETTLED.

  1. Ask. Anyone calls ask with a template, the outcome count, a sentence of at most 280 bytes, the full resolution spec as JSON, an opening time, a liveness, a base bond, an optional bounty and a reopen limit. The spec is hashed into contentHash and emitted in the Asked event, never stored. The creation fee plus the bounty leave the asker's wallet.
  2. Propose. From the opening time plus the opening delay, anyone may post the base bond on an answer, with an evidence string. A deadline is set one liveness ahead.
  3. Challenge. Until the deadline plus the settlement grace, anyone may post double the previous bond on a different answer; each challenge restarts the deadline. A challenge carries expectedRound, the round the challenger evaluated; if someone else challenged first the chain reverts with StaleRound instead of landing a round later at double the bond. Passing 0 skips the check.
  4. Court. The third challenge (the fourth bond) opens a court case between the two answers of the final round.
  5. Settle. After the deadline plus the grace, anyone may call settle; the best answer stands. A question nobody answered settles INVALID after the abandon period, counted from the later of the ask time and the opening time. Settling is permissionless and earns the caller 5 percent of the creation fee.
  6. Claim. Winners, refunded bonders and the bounty recipient call claim once per question; one claim pays everything owed on it.

Answers are Reality.eth-encoded bytes32 values: the outcome index, or 0xff…ff for INVALID. In the tools and the REST API an answer is a decimal outcome index or the string "INVALID". For yes/no questions, 0 is NO and 1 is YES.

The asker may register up to four consumer contracts before settlement with registerConsumer(id, consumer). At settlement the oracle calls onFinal on each with 100,000 gas; notifyConsumers(id) re-delivers a callback that failed. The smallest useful consumer, HunchAnswerStore, records every final answer and is deployed on the fast lane.

The three templates

Template Outcomes Draft fields Rubric
binary.v1 (Yes / No) 2 question (8–280 chars), resolutionSource (URL or at least 20 characters), deadline, optional invalidIf, bountyHNCH, livenessSeconds 1 (YES) if the event verifiably happened by the deadline according to the source; 0 (NO) otherwise; INVALID if the source is unavailable or the question is ambiguous
categorical.v1 (Pick one of N) 2–16 the binary fields plus outcomes, 2–16 distinct labels; the answer is the index the index of the outcome the source confirms; INVALID if none can be verified or several apply
price-threshold.v1 (Price above / below a level) 2 asset, optional quote (default USDT), window, threshold, comparator (above or below), at, optional invalidIf, bountyHNCH, livenessSeconds read the named Sightline at at; 1 (YES) if the price is on the stated side with a clean reading; 0 (NO) if on the other side with a clean reading; INVALID if the reading carries a thin, noHistory or divergence flag

For binary and categorical questions the deadline is the opening time, the moment the answer becomes knowable. For price questions at is the opening time and the sentence is generated in UTC, for example "Will WDOGE be above 4.5 USDT at 2026-11-15 12:00 UTC (1h Sightline)?". The spec is canonicalised (sorted keys, no whitespace) before hashing, so any client can recompute contentHash from the emitted JSON.

Economics

Item Rule
Creation fee 1,000 HNCH per question
Fee split 60 percent to the court stakers of the fee's epoch, 25 percent back to the asker as a rebate, 10 percent to the treasury, 5 percent to whoever settles
Base bond 10,000 HNCH minimum; an asker may set a higher base bond per question
Bond ladder 10,000 (proposal), 20,000, 40,000, 80,000 (the three challenges); the 80,000 bond opens the court
Payout every losing bond is split among the winning bonds pro rata by bond size; a losing bond is lost entirely
Bounty optional, asker-funded, escrowed in the oracle; paid to the last bonder of the winning answer (after a court verdict, the verdict's side); returned to the asker when there is no winning side
INVALID an answer in its own right; a question that settles INVALID with no winning side refunds every bond and returns the bounty
Final final for off-chain consumers after 21 confirmations, about one minute on Chikyū; isFinalized on-chain is true as soon as the question is settled
Staker rewards the 60 percent share accrues per epoch; the epoch's weight is frozen at its first fee; only matured stake counts; one claim covers at most 64 epochs

Driving a 10,000-bond question to court costs the honest side 10,000 plus 40,000 HNCH and a griefer 20,000 plus 80,000. The epoch share, the rebate and the settler share are claimed from the treasury; bond winnings, refunds and the bounty from the oracle.

The two lanes

Bones is deployed twice with the same code, token, fee and bond but different clocks. The canonical lane runs on the design's parameters; the fast lane runs in minutes so a whole lifecycle fits in one sitting. Questions on one lane do not exist on the other.

Parameter Canonical Fast
Base bond minimum (minBond) 10,000 HNCH 10,000 HNCH
Creation fee 1,000 HNCH 1,000 HNCH
Liveness default 4 h (14,400 s) 5 min (300 s)
Liveness allowed 1 h to 7 d 2 min to 1 h
Opening delay (proposals open after the opening time) 300 s 30 s
Settlement grace after every deadline 1 h 60 s
Abandon after (unanswered question settles INVALID) 30 d 2 h
Challenges before court 3 3
Court duration 48 h 10 min
Stake maturity 24 h 2 min
Quorum 10 percent of matured stake 10 percent of matured stake
Fee epoch 24 h 10 min
Final off-chain 21 confirmations 21 confirmations

The court

HunchCourt holds HNCH stake with OpenZeppelin checkpoints. A case is binary, keyed by question and attempt, between the answer the final challenge displaced (A) and the final challenger's answer (B). A voter's weight is the smaller of their stake at the snapshot (the case's opening time minus the maturity period) and their stake now, so only matured stake counts, stake added after the snapshot gains nothing, and withdrawn stake cannot vote. The quorum denominator is the total matured stake at the snapshot.

Voting costs gas only and locks the voter's stake until the case deadline; stakers who did not vote may unstake at any time. After the deadline anyone may call finalize: votes reaching 10 percent of the denominator with no tie give a verdict that settles the question in the same transaction. Otherwise the outcome is NEUTRAL: every bond of that attempt becomes refundable and the question reopens as OPEN if its reopen limit allows (0 to 3 per question, chosen at ask). A question that exhausts its reopens settles INVALID.

The guardian

HunchGuardian is a testnet 2-of-3 with exactly two powers: pause new questions, and declare sequencer downtime, which extends every deadline inside the declared window by the window's length. It cannot change answers, parameters or move funds. Any action needs two distinct signer approvals of the same calldata under the current nonce; the second approval executes it. The signers are accounts 0, 1 and 2 of the deployer mnemonic, a stub rather than a multisig. All server reads follow effectiveDeadline, so a declared downtime moves graceEnd, canSettleAt and the allowed actions.

What a transaction costs

On Chikyū the L1 data fee is 99.99 percent of a transaction's cost at normal fee levels (about 135 µDOGE per byte); execution gas is negligible. Measured over 50 acceptance transactions on 30 October 2026: an ask about 0.06 tDOGE, every other oracle action about 0.03 tDOGE. Keep an agent wallet above about 0.4 tDOGE. Fee spikes of roughly 1,000 times normal have occurred; the project's deploy scripts wait them out.

A SightlineFeed is a Chainlink AggregatorV3Interface over one Sightline: one pair, one window, eight decimals. Nothing is written per price, so there is no update cadence to trust and no L1 data fee per round. A contract that already reads Chainlink reads a SightlineFeed without changes.

The factory

SightlineFeedFactory deploys feeds with CREATE2. feedFor(base, quote, window, decimals, rejectFlags) names the address before the feed exists, so an integrator can hard-code it. createDefault(base, quote, window) deploys the feed at feedFor(base, quote, window, 8, 21); calling it twice is a no-op. create(base, quote, window, decimals, rejectFlags) deploys a feed with custom flags. Any pair with a Barkswap pool and any of the eight windows can have a feed.

latestRoundData semantics

Field Value
answer the Sightline price with 8 decimals
roundId the current block number
answeredInRound equal to roundId
startedAt the reading's block time minus the window
updatedAt the reading's block time while at least one trade landed inside the window; one full window back when none did

The updatedAt rule means an unchanged staleness check (block.timestamp - updatedAt < maxAge) refuses a window in which nobody traded, as it would refuse a stale Chainlink round. getRoundData answers only for the current block and reverts NoHistoricalRounds otherwise. reading() returns the raw Sightline struct for consumers that want the guards.

rejectFlags

A feed reverts with Flagged(flags) instead of answering when the reading carries any flag in its rejectFlags. The default is 21: UNLISTED, NO_HISTORY and NOT_RECORDING. A stricter feed with 31 also refuses THIN and DIVERGENCE. A lax feed with 0 always answers and leaves the rules to the caller.

The consumer library

SightlineLib reads a Sightline and refuses what a lending contract should refuse. read(sightlines, base, quote, window, minLiquidity, requireListed) reverts NoPrice (NO_HISTORY or NOT_RECORDING), Thin (under the caller's floor), Stale (nothing traded inside the window) or Unlisted (when the caller insists on a listed pair). readWithDivergenceGuard(sightlines, base, quote, windowA, windowB, maxBps, minLiquidity) returns window A's price and reverts Divergent when window B disagrees by more than maxBps.

Demo vault

DemoLendingVault is the integration demo: collateral in one token, debt denominated in quote units, no real borrowing. Positions must open at 150 percent or more and anyone may liquidate below 120 percent, with the price read through the divergence guard. It exists to show the liquidation path; the feeds suite has 13 tests.

Live feeds

Feed Address
WDOGE / USDT 1h 0x839668bdC81ADbE21c754B629C25773Ce84E3556
USDC / USDT 1h 0x58f56cb8a3498D82E5620F8cc009d718Ea6f733E
HNCH / USDT 1h 0x2C0703D8101616D859347e4ac5d981b73E428Cf3

Both use eight decimals and rejectFlags 21. At deployment on 30 October 2026 the WDOGE / USDT feed answered 415839317 (4.1584 USDT). Agents reach feeds through the get_feed tool or GET /v1/feeds/{base}/{quote}/{window}, which return the feed's address, whether it exists, its latest round, and the exact createDefault call when it does not exist yet.

HNCH Town: the game

HNCH Town is a mobile-first, almost text-free game over the Bones and Sightlines contracts: a 2.5D clay-toy dog village where the guide dog is the player's companion, bones are questions, the mirror shows live prices and the hill is the court. Everything on screen is a chain read through the same service layer the MCP server uses, and time comes from the chain's latest block, not the phone, so rings, windows and offered actions agree with the contract. Writes go through the wallet with EIP-2612 permits: asking, barking, pulling and staking are one signature plus one transaction; fetching, voting, finalizing, claiming and unstaking are one transaction. Gas is tDOGE.

Vocabulary

Protocol Game word What the player sees Costs or pays
Question Bone 🦴 signpost, card on tap; 🪢 challenged, 🔥 court, 🏆 settled
Ask Dig 🪏 orange bar button, the Dig sheet 1,000 fee plus bounty; 250 returns as a rebate 🍪
Bounty Treat 🍪 and a number on the signpost, row and card to the last bonder of the winning answer; back to the asker on INVALID
Propose Bark 🟢 / 🔴 paws, ∅ chip, numbered tokens on pick-one bones the bone's base bond (10,000 default)
Challenge Pull the same buttons with 🪢, coins beside; 🌙 per extra round twice the previous bond: 20k, 40k, 80k
Court Council Hill ⛰️ two paws, a green/red bar, a teal quorum mark, ☀️ countdown opened by the 80k pull; voting costs gas only
Stake Join the council 🧙 hat; ⏳ maturing; 🔒 locked 10k / 20k / 50k chips; ↩︎ unstakes all
Settle Fetch 🏆 gold button after the ring and grace gas; earns 50 HNCH (5 percent of the fee)
Claim Dig up 🪏 on the card; 🪏 / 🍪 / 🏆 treats in the Pocket pays refunds, winnings, bounty, rebate, settler share
Liveness plus grace Ring orange arc to the deadline, grey slice for the grace, countdown inside
Neutral Reopen the bone back to 🦴, bonds refundable, one more attempt
INVALID ∅ teal ∅ paw bonds refunded, bounty to the asker
Final ✅ ✅ by the trophy; n/21 before
Agent Robo-doge 📡 on signposts and rows; 🛡️ watchdog, 🧙 juror on the card; 📡 on a bonded side
Connect Harness up 🦺; the DogeOS modal (email, Google, X, MyDoge, injected wallet)
Sightline Mirror 🔮 Lookout; the mirror row on price bones

The two towns

The game runs on both Bones lanes. The top-left toggle switches between the rabbit town 🐇 (the fast lane, minutes) and the turtle town 🐢 (the canonical lane, hours and days). The lane is fixed at page load from the URL hash (#fast or #canonical), otherwise the build default, otherwise canonical; switching reloads the page on the other lane. Same HNCH, separate bones. A shared link https://thehunch.app/#fast/0x… or #canonical/0x… opens the bone's card and switches lane if needed. The public site defaults to the turtle town.

Screens

Journeys

Windows below are canonical, with the fast lane in brackets.

The treat faucet

HunchTreatFaucet hands every wallet one treat of 10,000 HNCH, once. The owner (the deployer) can resize the treat, pause, sweep and hand over. It was funded with 50,000 HNCH, five treats, on 30 October 2026; the game reads canClaim and treatsLeft and calls claim() from the onboarding bone. An empty bowl reverts. A proof-of-play gate on the faucet is still open.

Login: the DogeOS SDK

"Harness up" opens the DogeOS connect kit (@dogeos/dogeos-sdk): log in with email, Google or X for an embedded wallet, or connect MyDoge or an injected wallet. The kit is mounted beside the town and lazy-loaded after the map so its 4 MB chunk never delays the first paint. Its EIP-1193 provider is wrapped with viem and switched to Chikyū first, so barks still go out as one permit signature plus one transaction. Without a client id the game falls back to an injected window.ethereum wallet. The production build at thehunch.app carries the project's Live client id (origins allow-listed on console.dogeos.com); local development uses the Sandbox id. Disconnect in the Pocket ends the session and forgets the wallet. WalletConnect appears only when a Reown project id is configured.

For AI agents: the MCP server

The hnch MCP server (spec 2026-07-28, official TypeScript SDK v2, viem) exposes Sightlines and Bones in one place: 25 tools, four resources and five prompts. Reads need no authentication. Writes never hold a key on the hosted endpoint: they return an unsigned transaction and, when HNCH must move, the permit typed data to sign. Signing stays with the agent.

Connect

Hosted, over Streamable HTTP (stateless):

claude mcp add --transport http hnch https://thehunch.app/mcp

Claude Desktop or any client that takes a JSON config:

{ "mcpServers": { "hnch": { "type": "http", "url": "https://thehunch.app/mcp" } } }

From source, over stdio, with an optional local signer:

git clone https://github.com/operalag/hunch-dogeos
cd hunch-dogeos/server && npm install && npm run build
claude mcp add --scope local hnch -- node /ABSOLUTE/PATH/hunch-dogeos/server/dist/mcp/stdio.js
{ "mcpServers": { "hnch": { "command": "node", "args": ["/ABSOLUTE/PATH/hunch-dogeos/server/dist/mcp/stdio.js"] } } }

A self-run server reads HNCH_RPC_URLS (comma list; the default is the official RPC, then drpc, unifra and ankr), HNCH_LANE (canonical by default, or fast), HNCH_SIGNER_KEY (stdio only), and address overrides such as HNCH_SIGHTLINES, HNCH_REGISTRY, HNCH_FEED_FACTORY, HNCH_FAUCET, HNCH_ORACLE_FAST and HNCH_ORACLE_CANONICAL. One server serves one lane. The hosted endpoint at https://thehunch.app/mcp serves the canonical lane (HNCH_LANE=canonical on the Vercel project hnch-mcp); the fast lane needs a self-run server with HNCH_LANE=fast. The server's instructions tell a client to read hnch://rules first and that USDT is the default quote.

Tools

Read tools are annotated read-only and idempotent; write tools as non-destructive, non-idempotent writes.

Tool What it does Key inputs
list_sightlines pairs the registry vouches for, with route, liquidity, available windows, flags and the 1h price quote?, minLiquidity?, cursor?, limit? (1–200)
get_price one Sightline reading with guards and flags; quote defaults to USDT base, quote?, window
get_prices all eight windows for a pair in one call base, quote?
get_pool_health route, liquidity, age, retention, oracle recording state, divergence, route drift, listing status base, quote?
get_feed the SightlineFeed for a pair and window: deterministic address, whether it exists, latest round, or the exact createDefault call base, quote?, window
get_price_history sampled historical TWAPs from the pool's own buffer, one point per step, at most 500 points, null where history does not reach base, quote?, window, from, to, step (unix seconds)
resolve_token symbol or address to canonical address, decimals, known flag, alternates and listed pairs symbolOrAddress
list_templates the three question templates with JSON schemas, examples and rubrics none
list_questions questions on the current lane, newest first status? (OPEN, PROPOSED, CHALLENGED, COURT, SETTLED), template?, asker?, openingBefore?, cursor?, limit?
get_question full state: spec, labels, bonds, history with evidence, deadlines, allowed actions, resolution questionId
get_resolution the answer and whether it is final (settled with 21 confirmations) questionId
get_bond_quote the next required bond, deadline, grace end and the actions open right now questionId
get_court_case the two answers on trial, votes so far, the quorum denominator and the deadline questionId
get_account HNCH balance, allowances, stake and matured weight, lock-until, open bonds and everything claimable address
validate_question check a draft against its template; derive spec, contentHash, labels, opening time, suggested liveness and cost; no gas draft
create_question validate and prepare (or send) ask; pulls fee plus bounty draft, from?, permitSignature?, permitDeadline?, livenessSeconds?, baseBondHNCH?, maxReopens? (0–3)
propose_answer bond the base bond on an answer to an OPEN question, with evidence questionId, answer, evidence (≤ 512 chars), from?, permitSignature?, permitDeadline?
challenge_answer bond double the last bond on a different answer; the third challenge opens the court questionId, answer, evidence, from?, permitSignature?, permitDeadline?, expectedRound?
settle permissionless settlement after deadline plus grace, or INVALID when nobody answered; earns 5 percent of the fee questionId, from?
claim collect bond winnings, refunds and the bounty owed on a question questionId, from?
claim_rewards treasury claims: staker epoch rewards, the asker rebate or the settler share fromEpoch?, toEpoch? (≤ 64 epochs), or questionId with kind (rebate or settler), from?
stake stake HNCH in the court; matures after the maturity period amountHNCH, from?, permitSignature?, permitDeadline?
unstake withdraw stake once no case you voted in is open amountHNCH, from?
vote vote for one of the two answers on trial with your matured stake questionId, answer, from?
wait_for_final poll until settled with 21 confirmations or timeoutSec elapses; returns the resolution with timedOut questionId, timeoutSec? (≤ 120)

The write tools are create_question, propose_answer, challenge_answer, settle, claim, claim_rewards, stake, unstake and vote; everything else reads. There is no finalize tool: a court case past its deadline is finalized by calling finalize(questionId) on the court contract directly, which the Juror guide agent does automatically.

Windows are given as a label (5m, 10m, 30m, 1h, 12h, 24h, 1w, 1m) or the seconds; tokens as a canonical symbol or any address. Bad input returns an isError result that says what is accepted; a chain failure returns chain read failed: …. Every result is JSON text plus structuredContent.

Prepare mode

Every write tool takes from, the address that will sign, and by default returns a prepared transaction rather than sending one:

{
  "mode": "prepared",
  "from": "0x…",
  "requiredHNCH": "10000",
  "asOfBlock": "9050000",
  "tx": { "to": "0x…", "data": "0x…", "value": "0", "chainId": 6281971, "gasEstimate": "…" },
  "needsPermit": true,
  "permit": { "domain": { "name": "Hunch", "version": "1", "chainId": 6281971, "verifyingContract": "0xF4EC…26E6" }, "types": { "Permit": [ … ] }, "primaryType": "Permit", "message": { "owner": "0x…", "spender": "0x…", "value": "…", "nonce": "…", "deadline": … } }
}

When HNCH must move and the from address's allowance to the target contract is short, permit is EIP-712 typed data for HNCH.permit with a deadline one hour out. Sign it, call the same tool again with permitSignature (the 65-byte signature) and permitDeadline (the signed permit.message.deadline), and the result's tx is a single multicall([selfPermit, action]) to sign and broadcast. Two signatures, one transaction. The server never re-dates a signed permit. The permit value is pinned to the quoted bond: if the bond doubled meanwhile, re-prepare. Prepare mode simulates first and refuses a transaction whose simulation reverts, naming the reason.

With HNCH_SIGNER_KEY set on a local stdio server, the tools sign the permit themselves, send, wait one confirmation and return { "mode": "sent", "txHash": "0x…", "blockNumber": "…" }. The key is never logged.

Resources and prompts

Resource Content
hnch://rules markdown: windows, flags, routing, retention, addresses, the Bones rules and the prepare-mode protocol; one-hour cache hint
hnch://sightline/{base}/{quote}/{window} one guarded reading as JSON; 15-second cache hint
hnch://templates the three templates as JSON
hnch://question/{questionId} full state of one question as JSON; 5-second cache hint

The rules resource is what an agent should read first. Its rules include: refuse thin, noHistory and divergence readings and quote liquidity next to the number; compare 5m and 1h before acting on either; never move money on a resolution with final: false; after a StaleRound revert, re-read the question and re-prepare instead of retrying; read effectiveDeadline and graceEnd rather than deadline, because a declared downtime moves them; the bounty goes to the last bonder of the winning answer; a voter's stake is locked until the case deadline while non-voters may unstake.

Prompts: read-a-sightline-safely {base, quote?}, act-as-resolver, act-as-watchdog, act-as-juror and write-a-resolvable-question, each a short instruction set over the tools above.

Worked examples

Read a price.

{ "tool": "get_price", "arguments": { "base": "WDOGE", "window": "1h" } }

The result carries price (a decimal string such as "4.1026", or null when the window has no history), price1e18, guards, flags, route and asOfBlock. Refuse the number when thin, noHistory or divergence is true.

Read a Chainlink-shaped feed.

{ "tool": "get_feed", "arguments": { "base": "WDOGE", "quote": "USDT", "window": "1h" } }

The result names the factory and the feed, says whether it exists, and gives latest (roundId, answer, price, updatedAt, startedAt) or refused with the Flagged reason, plus createWith when the feed does not exist yet.

List open questions whose answers are knowable now.

{ "tool": "list_questions", "arguments": { "status": "OPEN", "openingBefore": 1793500000, "limit": 20 } }

Validate a draft, then create the question in prepare mode.

{ "tool": "validate_question", "arguments": { "draft": {
  "template": "price-threshold.v1", "asset": "WDOGE", "quote": "USDT", "window": "1h",
  "threshold": "4.5", "comparator": "above", "at": "2026-11-15T12:00:00Z", "bountyHNCH": "100"
} } }

With ok: true the result carries the canonical spec, contentHash, labels (["NO", "YES"]), openingTs, suggestedLiveness and cost (feeHNCH 1000, bountyHNCH 100, totalHNCH 1100). With ok: false it lists problems by field, for example at: must be in the future.

{ "tool": "create_question", "arguments": { "draft": { "…": "the same draft" }, "from": "0xYourAddress" } }

The result is a prepared ask transaction plus permit typed data for 1,100 HNCH. Sign the permit, then:

{ "tool": "create_question", "arguments": { "draft": { "…": "the same draft" }, "from": "0xYourAddress", "permitSignature": "0x…", "permitDeadline": 1793503600 } }

Propose an answer after the opening time plus the opening delay, with evidence.

{ "tool": "propose_answer", "arguments": { "questionId": "0x<questionId>", "answer": "1", "evidence": "get_price WDOGE/USDT 1h at 1794000000: 4.62, no flags", "from": "0xYourAddress" } }

Challenge an answer you believe is wrong, pinning the round you evaluated.

{ "tool": "challenge_answer", "arguments": { "questionId": "0x<questionId>", "answer": "0", "evidence": "same Sightline read 4.31 at the stated time", "from": "0xYourAddress", "expectedRound": 1 } }

Settle once get_bond_quote lists settle among the actions, then claim.

{ "tool": "settle", "arguments": { "questionId": "0x<questionId>", "from": "0xYourAddress" } }
{ "tool": "claim", "arguments": { "questionId": "0x<questionId>", "from": "0xYourAddress" } }

Wait for finality before acting on the answer.

{ "tool": "wait_for_final", "arguments": { "questionId": "0x<questionId>", "timeoutSec": 120 } }

The guide agents

The repository ships deterministic reference agents (server/src/agents) that keep the oracle alive without humans, built on the same service the MCP tools use. Each role is one pure pass that returns the actions it took; a runner loops them with per-role wallets and isolates a role that throws. A Sightline judge resolves price-threshold.v1 mechanically from the named Sightline: a flagged reading means INVALID, and it abstains before the reading time, beyond retention and on the other templates. An LLM judge for binary and categorical questions plugs into the same interface once an API key exists.

Role What it does each tick Default policy
Resolver proposes on open questions its judge is sure about, settles settleable questions, claims what it is owed confidence ≥ 0.85, bond ≤ 40,000 HNCH
Watchdog re-judges every live answer and challenges disagreements within budget (INVALID counts), never its own answer
Juror (three of them) keeps its court stake at the target, votes once per case with its judge, finalizes cases past their deadline stake target 20,000 HNCH
Asker creates one price question per interval from a feed around the live Sightline price, collects rebates every 30 minutes, read 5 minutes ahead, 10 HNCH bounty
Sentinel walks the listed Sightlines and raises one alert per flagged pair and flag one-hour cooldown per alert
Rogue (demo) a Resolver run with --lie --escalate-once: answers wrong on purpose and re-challenges once

The agents ran the zero-human lifecycle on the fast lane on 30 October 2026: an Asker created a price question, a Resolver answered it from the Sightline and settled it; then a rogue Resolver lied, the Watchdog challenged through the ladder into the court, three Jurors voted from the Sightline with 90,000 of 90,000 staked HNCH, a Juror finalized, and the Watchdog claimed. Every live run refuses to start when the L1 data fee is above 2,000 µDOGE per byte.

REST API

The REST surface runs on the same service layer as the MCP server. Reads only; writes are MCP tools. All routes are GET.

Path Returns
/healthz { ok, chainId, block, service }
/v1/sightlines?quote=&minLiquidity=&cursor=&limit= the listed pairs with route, liquidity, available windows, flags and 1h price; nextCursor
/v1/sightlines/{base}/{quote} all eight window readings for the pair
/v1/sightlines/{base}/{quote}/{window} one reading with guards and flags
/v1/sightlines/{base}/{quote}/health pool health: route, liquidity, age, retention, windows available, recording state, divergence, route drift, listing
/v1/sightlines/{base}/{quote}/history?window=&from=&to=&step= sampled historical TWAPs, at most 500 points
/v1/feeds/{base}/{quote}/{window} the SightlineFeed: address, exists, latest round or refusal, createWith
/v1/tokens/{symbolOrAddress} canonical address, decimals, known flag, alternates, listed pairs
/v1/templates the three question templates
/v1/questions?status=&template=&asker=&openingBefore=&cursor=&limit= questions on the server's lane, newest first; nextCursor, total
/v1/questions/{id} full state of one question
/v1/questions/{id}/resolution final, answer, answerLabel, invalid, settledBlock, confirmations, blocksUntilFinal, settledAt, settler
/v1/court/{id} the court case: both answers with labels, votes, quorum, deadline, finalized, neutral, verdict
/v1/accounts/{address} HNCH balance, allowances, stake, matured weight, lock-until, open bonds, claimables

Every success is wrapped in the envelope { "data": …, "chainId": 6281971, "asOf": { "block": "…" } }; list routes add nextCursor. Price routes send Cache-Control: public, max-age=15. CORS allows GET from any origin. Errors are { "error": "…" } with status 400 for a bad window, range, limit, cursor, question id or address, 404 for an unknown token, a non-token address, a pair with no route or an unknown question, and 502 when the chain read fails; error responses are never cached. Responses carry nosniff and a default-src 'none' content security policy.

Event lookups (the Asked spec, the proposal and challenge history, the Settled block) walk back from the chain head in 9,000-block windows because public DogeOS RPCs reject eth_getLogs spans above 10,000 blocks. A lookup gives up after 400 windows (about 125 days at 3-second blocks) and returns spec: null; older questions will need an indexer-backed lookup, an open item.

Contracts and addresses

All contracts below are on DogeOS Chikyū (chain id 6281971) and verified on Blockscout at https://blockscout.testnet.dogeos.com/address/<address>#code, except the Barkswap pool, which is a Barkswap contract.

Contract Address Notes
HNCH token 0xF4EC5f6F82d25799BA09827cBa2393AF33A026E6 deployed 29 Oct 2026, block 9014356
Sightlines v2 0xe5f4a5ac653764fC4EF673fE05a59985386B8209 routes pinned at listing; deployed 30 Oct 2026
SightlineRegistry v2 0x52c2700e54F2a035DadAD1CD9fB501555627b5c8 24 pairs listed
SightlineFeedFactory 0x749f7E68C5aea3F50D3319132af67a556aDA4E95 deployed 31 Oct 2026, block 9048798
SightlineFeed WDOGE / USDT 1h 0x839668bdC81ADbE21c754B629C25773Ce84E3556 8 decimals, rejectFlags 21
SightlineFeed USDC / USDT 1h 0x58f56cb8a3498D82E5620F8cc009d718Ea6f733E 8 decimals, rejectFlags 21
SightlineFeed HNCH / USDT 1h 0x2C0703D8101616D859347e4ac5d981b73E428Cf3 8 decimals, rejectFlags 21; created 31 Oct 2026
HunchOracle, canonical lane 0x6cD2885A1db70f5Ae77E6713414a59013aF87561 v2, 30 Oct 2026
HunchCourt, canonical lane 0x1e09391F461d5a4186Bd8eF3A428A9f12367150a v2
HunchTreasury, canonical lane 0x2C0a96aCb93A839Af09e970B96d67f54E31BE72E v2
HunchGuardian, canonical lane 0x3263a72E8E5b04fd0F5147256ae0196325Ba41D6
HunchOracle, fast lane 0x1c75A1EC8B1B3222AaBC6954c45D9147A4994135 v2, 30 Oct 2026
HunchCourt, fast lane 0xcC46D358ec5ecF744CA8Ddb8AA6FF3468A0f9AAe v2
HunchTreasury, fast lane 0xe1C21132951b06F0d87473F798A4567849FC3FD7 v2
HunchGuardian, fast lane 0x67abE1DB5E0835F5526c3E643A06620c5E971A73
HunchAnswerStore, fast lane 0x9ba4b819820b982E2eF4C3AE46F10feFf40ed0c3 reference consumer (v2); the onFinal callback path was proven live on 30 Oct 2026
HunchTreatFaucet 0xFcFe4507A16abD3EEe1533a57b712788c0153621 10,000 HNCH once per wallet; deployed 30 Oct 2026, block 9048360
Barkswap HNCH / USDT pool (USDT token0, HNCH token1) 0x225D34996d3607ea390e4846d7b9c4E7A6221A31 created 29 Oct 2026 at 0.01 USDT per HNCH; two-sided since 31 Oct 2026 (position #12255, 0.005 to 0.02 USDT per HNCH); listed in the registry
Barkswap AlgebraFactory 0xF3961157f56C983316657f0267B4C04460beE43f poolByPair(tokenA, tokenB)
Barkswap SwapRouter (Algebra Integral) 0x911E5A1630fD1768E5A1710DAAFaBb865cB79531 exactInputSingle takes a deployer field, zero for plain pools
Barkswap NonfungiblePositionManager 0xf596329a6c7E03F0708199cB5435f86783DB4302 positions are NFTs; mint takes a deployer field
Barkswap QuoterV2 0x187b41968063Cb8A04A5f4d2113844EF2Ba21493 quotes without a swap

Constants the contracts depend on: Barkswap factory 0xF3961157f56C983316657f0267B4C04460beE43f, WDOGE 0xF6BDB158A5ddF77F1B83bC9074F6a472c58D78aE, USDT 0xC81800b77D91391Ef03d7868cB81204E753093a9 (the default quote). Superseded and still answering: Sightlines v1 0x2877DB6b55354311fd78CA3DF93C919183a51e81 and SightlineRegistry v1 0x21Ed490B3B06A3cdC4B06C056F20cF8F7aD75ED8, whose routes resolve live and are therefore hijackable; do not integrate them. The v1 Bones contracts are archived in the repository's deployment records.

Security and status

FAQ

Is any of this real money? No. Everything runs on the DogeOS Chikyū testnet. HNCH on Chikyū has no value, and the gas token tDOGE comes from a faucet.

Where does a Sightline price come from? From the oracle plugin inside the Barkswap pool for the pair. Every swap writes a timepoint; the Sightlines contract reads those timepoints and averages over the window you choose. Nobody posts prices.

Why does the 1-week or 1-month window say no history for a busy pair? Barkswap keeps 65,536 timepoints per pool. A busy pool writes about 3,000 a day, so after about three weeks only about 22 days of history remain. Use 1h to 24h for active pairs and check get_pool_health for windowsAvailable.

Can I trust a Sightline for liquidations? On a testnet, no, and on mainnet only with guards. Use the feed's rejectFlags or SightlineLib.readWithDivergenceGuard, set a liquidity floor, and compare two windows. A thin pool can be moved for the cost of holding it off-price for one window.

What does asking cost, and what comes back? 1,000 HNCH plus whatever bounty you add. 250 HNCH returns to you as a claimable rebate at once; 600 goes to the court stakers of that epoch, 100 to the treasury and 50 to whoever settles the question.

What happens to my bond if I am wrong? It is lost entirely and shared among the bonds on the winning answer, pro rata by size. If you are right, your bond returns with a share of every losing bond. If the question settles INVALID with no winning side, every bond is refunded.

How long does a question take? On the canonical lane, proposals open 5 minutes after the opening time, each round lasts 4 hours by default plus 1 hour of grace, a court case lasts 48 hours, and an unanswered question can be settled INVALID after 30 days. On the fast lane the same clocks are 30 seconds, 5 minutes, 60 seconds, 10 minutes and 2 hours.

How do I know a result is final? Call get_resolution (or /v1/questions/{id}/resolution) and check final. It is true only when the settlement has 21 confirmations. The game shows ✅ at that point and n/21 before it.

Can an AI agent use this without a wallet? It can read everything without credentials. To write it needs an address with HNCH and tDOGE and a way to sign: the hosted server returns the unsigned transaction and the permit typed data, and the agent signs both. Running the server locally with HNCH_SIGNER_KEY lets it sign for you.

What is a permit, and why two signatures? HNCH supports EIP-2612, so an allowance can be granted by signature instead of a separate approve transaction. The first signature is the permit, the second is the transaction that bundles the permit and the action in one multicall. One transaction lands on-chain.

Why are there two lanes, and which should I use? The canonical lane has the design's clocks (hours and days). The fast lane has the same contracts with clocks in minutes so a whole lifecycle can be exercised in one sitting. Questions on one lane do not exist on the other. Use the fast lane to learn and test, the canonical lane for anything that should stand for a while.

How do I get HNCH to play? Harness up in the game, get tDOGE from the DogeOS faucet, then dig the starter treat: 10,000 HNCH once per wallet while the faucet's bowl lasts. After that, the HNCH/USDT pool on Barkswap sells HNCH for USDT.

Glossary