Settings and simulators

Four screens with one thing in common: none of them is gated by WalletGate. The two settings screens render, then ask for a wallet; the two simulators need none at all. The shell they sit in is on The console.

/settings — spending limits

What it needs. A connected wallet to read or write anything. The page itself renders without one, showing Connect a wallet to view and set its limits.

Which chain it addresses. This is the one screen that follows the wallet's connected chain rather than the console's hardcoded network: the chain id goes into the query, into the request body, and into the signature summary. Switching networks in the wallet re-reads the limits for that chain, and a response for a superseded chain or address is dropped rather than allowed to overwrite the form.

What it renders. Three fields, and a notice.

The caps are advisory, not enforced, which is what the screen's own notice says. The backend serves them to a polling agent, which is expected to check each candidate purchase against them; nothing in the protocol rejects a payment that exceeds them, and software you did not write can ignore them entirely.

What it does.

GET /settings
→ POST /v1/auth/session                            one wallet signature, cached
→ GET  /v1/spending-limits?chain_id={walletChain}

POST /settings  (Save limits)
→ a browser confirmation listing all three caps, or the word unlimited for each blank one
→ POST /v1/spending-limits { chain_id, per_tx_cap_usdc, daily_cap_usdc, total_cap_usdc }
→ the form is re-applied from the response, so what you see is what persisted

Amounts go over the wire in USDC base units, six decimals, and are displayed as decimal USDC. The confirmation dialog exists because the save overwrites all three caps at once: it names the chain and every cap before the request goes out. The dialog's wording asks you to sign and the screen says each change is signed with your wallet, but the save itself carries the cached session token — the one wallet signature was the session mint, and there is no per-save signature.

Errors.

The unavailable case is distinguished from a real failure by the shape of the response, not by the status alone — an unmounted route answers in plaintext where the live one answers in JSON.

The routes are on Telegram and limits, and what a polling agent sees of these caps is on Telegram and intent tools.

/settings/telegram — the chat link

What it needs. A connected wallet. Without one: Connect a wallet to manage its Telegram link.

What it renders. A status panel, a confirmation panel when one is due, a link-generation panel, and an unlink button when linked.

The link can be established from either direction, and the screen handles both:

• Starting here. Generate a deep link, open it in Telegram or send the bot a start command with the code, and the link completes.
• Starting in Telegram. The backend sends the owner back to this screen with the code in the URL, and the screen renders a confirmation panel for it directly.

GET /settings/telegram
→ POST /v1/auth/session                     one wallet signature, cached
→ POST /v1/telegram/link/status  {}         { linked, telegram_username?, linked_at? }

POST /settings/telegram  (Get Telegram link)
→ POST /v1/telegram/link/start   {}         { deep_link, code, expires_at }

POST /settings/telegram  (Confirm link)
→ POST /v1/telegram/link/confirm { code }

POST /settings/telegram  (Unlink Telegram)
→ a browser confirmation naming what stops
→ POST /v1/telegram/link/unlink  {}

Status is a POST, not a GET. Every route here identifies the owner from the request signature and takes no address argument, so there is nothing to put in a path — which also means there is no way to read or change somebody else's link.

The generated deep link is shown as a clickable link and again as copyable text, with its expiry and the equivalent start command. Generating again does not revoke the previous code: each one is minted independently and stays redeemable until it is used or its ten-minute expiry passes, so clicking twice leaves two codes that can each bind your wallet to a chat. A background sweep purges the expired ones.

Errors.

The two simulators

Both are client-side formula explorers. They take no wallet, no signature and make no requests — every number on the screen is computed in the browser from inputs you set, and each carries a copy of the formula and its constants in its own module, with unit tests beside it. The copies are written to mirror the backend implementation, and their comments name the Go functions they mirror, but they are copies: a simulator can be out of step with what actually ranked your agent, and nothing on the screen would say so.

For your real ranks use Rank tools or Escrows and ranks; for the definitions, Ranks.

/rank-simulator — Review Rank

What it needs. Nothing.

What it renders. A toolbar, a signal-input column and a sticky results panel.

The toolbar switches between Repeat and One-off products — which selects a different weight set — and opens two modals: Config constants and Config weights. Reset all restores every default.

Six signals feed the score. Five are event logs: each entry is a value and a "days ago", and the editor shows the decayed contribution of each.

The sixth, Wallet / Agent Age, is not an event log: it is derived from an agent age in whole months. Under Platform Settings, two more inputs set the Bayesian prior — the platform-wide published review count, and the platform mean rank for the selected product type.

Each signal panel shows its raw decayed sum, its saturated value, its weight and its contribution, each with a bar. Decay halves every twelve months, and the same decayed sums that drive the score also drive the observation count that shrinkage uses.

The results panel shows the Review Rank from 0 to 1, then the commission multiplier it maps to, in both a multiple and basis points, with the arithmetic printed: 0.4 + 0.6 × rank. The multiplier's floor and ceiling — ×0.4 and ×1.0 — are the same bounds SplitRouter enforces on a payment, so that part of the model is verifiable against the contract; see Escrow and router.

Below the prior inputs, the screen states the cold-start rule it is applying: under the threshold review count, the cold-start base rate is used as the prior instead of the live platform mean.

GET /rank-simulator
→ no requests, on any input; the page has no network surface

# What it computes for a Review Rank of 0.50, on the default constants:
rank       = 0.50
multiplier = 0.4 + 0.6 × 0.50  =  0.70   →  7000 bps
                                             the commissionMultiplierBps a payment would carry

Errors. None surfaced, and none reachable. Every input is a number field or a slider, unparseable input coerces to zero rather than raising anything, days-ago is floored at zero, and weights are clamped to 0–1. Nothing is saved either: reloading the page discards every change.

/product-rank-simulator — Product Rank

What it needs. Nothing.

What it renders. The same three-part layout, with a different model. One purchase log drives two of the three signals at once, and a satisfaction log drives the third.

The purchase editor shows a per-buyer retention breakdown, including which buyers hit their cap, and the distinct-buyer count the conversions signal is saturated against.

A one-off product simply uses the one-off weight set, in which retention's weight is zero. The blended weighting is a repeat-product mechanism: a repeat product's weights ramp from the one-off set toward the repeat set as first purchases age past the repurchase window, and the screen prints the ramp figure g alongside the retention weight it produced. Its constant, k_opp under Config constants, defaults to zero, which forces g to 1 — so on the defaults a repeat product uses the repeat weights outright and the figure is not rendered at all. Raise k_opp to see it.

Under Prior Settings the score is shrunk toward a resolved prior, and the panel names which of three sources won: the mean of the merchant's other same-type ranked products, the platform mean, or the cold-start base rate. The merchant prior only applies once the merchant has enough other ranked products of the same type.

Decay here halves every six months — half the Review Rank half-life.

GET /product-rank-simulator
→ no requests, on any input; the page has no network surface

# The weighted score, before shrinkage, on the default weight sets:
one-off  score = 0.50 × satisfaction + 0.00 × retention + 0.50 × conversions
repeat   score = 0.40 × satisfaction + 0.50 × retention + 0.10 × conversions

Errors. None surfaced, on the same terms as the other simulator: numeric inputs that coerce rather than raise, local compute, nothing persisted.

Next steps

• The console — the shell, and the merchant screens
• Agents and wallets — identity setup and the reviewer dashboard
• Telegram and limits — the routes both settings screens call