delphi-kit 0.1.1__tar.gz → 0.2.0__tar.gz

{delphi_kit-0.1.1 → delphi_kit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: delphi-kit
-Version: 0.1.1
+Version: 0.2.0
 Summary: Read and trade Delphi prediction markets from Python and AI agents, with no API key: every market type, quotes, trades, positions, search, alerts and an MCP server.
 Keywords: delphi,gensyn,prediction-markets,mcp,agents,web3
 License-Expression: MIT
@@ -120,7 +120,7 @@ Claude Desktop, Cursor, or anything else that speaks MCP over stdio:
 }
 ```
 
-The read tools are `list_markets`, `get_market`, `quote_buy`, `quote_sell`, `get_positions` and `wallet_status`.
+The read tools are `list_markets`, `get_market`, `quote_buy`, `quote_sell`, `get_positions`, `wallet_status` and `my_record`.
 The write tools are `buy`, `sell` and `collect`.
 
 Without a key or `DELPHI_ALLOW_TRADING=true` the server is read-only, and the write tools say so instead of
@@ -135,6 +135,37 @@ sending anything. With trading on, every buy is checked first:
 
 Use a separate wallet for the agent and only put in what you're willing to lose.
 
+## Flight recorder: a record nobody can edit
+
+Turn on `record=True` and every buy must first state what the agent believes. That belief is signed by the
+trading wallet, sealed until trading closes, and anchored on Gensyn mainnet by [Agon](https://agon.nerom.site).
+Nobody can see it before then or change it afterwards. When the market settles, the agent's record writes itself:
+
+- **Calibration:** were its probabilities better than the market's price at the time?
+- **Results:** what the same wallet actually bought and sold, read from the chain.
+
+```python
+d = Delphi(private_key=key, record=True, agent_name="my-agent")
+t = d.buy(m, "Yes", usd=2, belief={"Yes": 0.71}, reasoning="Polls moved after the debate.")
+t.record   # {'entry': 200, 'belief': 0.71, 'market_probability': 0.50, 'edge': 0.21,
+           #  'sealed_until': '2027-12-31T23:00:00Z', 'record_url': 'https://agon.nerom.site/#/agent/0x…', ...}
+```
+
+```bash
+delphi buy 0x4F5D… Yes --usd 2 --record --belief 0.71 --reason "Polls moved after the debate."
+```
+
+- **No entry, no trade.** A buy without a belief is refused, and so is one whose entry can't be logged.
+  `record="try"` trades anyway and says why the entry is missing.
+- **When it's logged.** The entry is sent after the trade has been simulated, so failed buys never leave entries.
+- **What it covers.** Mainnet markets whose trading window was at least 12 hours long; shorter ones are refused.
+- **Which server.** Entries go to https://agon.nerom.site. Agon is open source; point `recorder_url` or
+  `DELPHI_RECORDER_URL` at your own instance if you run one.
+- **In the MCP server.** Set `DELPHI_RECORD=true` (plus `DELPHI_AGENT_NAME`) and the `buy` tool requires the
+  agent's `probability` and `reasoning`. `my_record` shows what it has logged and, after settlement, how it scored.
+- **Proof for the model, too.** An entry can carry a receipt from Gensyn's REE (`receipt=`)
+  proving which open model produced the forecast. Agon re-runs receipts on a second machine.
+
 ## Alerts
 
 Delphi has no notifications or webhooks, so `delphi watch` polls the chain and tells you about:
@@ -171,6 +202,7 @@ notes are in [docs/contracts.md](docs/contracts.md).
 | Default approval | unlimited | exact amount |
 | Agent spending limits | no | yes |
 | Alerts | no | yes |
+| Sealed, scored record of what an agent believed | no | yes (`record=True`) |
 
 ## Tests
 
@@ -184,6 +216,8 @@ The fork tests run a private copy of Gensyn mainnet and put a throwaway wallet t
 - **LMSR:** buy with a $3 budget, sell half, jump the clock past the deadline, settle as Delphi's oracle relayer,
   redeem the winnings.
 - **DPM:** buy, let the market expire unsettled, liquidate.
+- **Flight recorder** (with `DELPHI_TEST_RECORDER_URL` pointing at a local Agon): a buy without a belief is
+  refused, then a belief is signed, accepted by Agon and sealed before the buy is sent.
 
 ## License
 

{delphi_kit-0.1.1 → delphi_kit-0.2.0}/README.md

@@ -106,7 +106,7 @@ Claude Desktop, Cursor, or anything else that speaks MCP over stdio:
 }
 ```
 
-The read tools are `list_markets`, `get_market`, `quote_buy`, `quote_sell`, `get_positions` and `wallet_status`.
+The read tools are `list_markets`, `get_market`, `quote_buy`, `quote_sell`, `get_positions`, `wallet_status` and `my_record`.
 The write tools are `buy`, `sell` and `collect`.
 
 Without a key or `DELPHI_ALLOW_TRADING=true` the server is read-only, and the write tools say so instead of
@@ -121,6 +121,37 @@ sending anything. With trading on, every buy is checked first:
 
 Use a separate wallet for the agent and only put in what you're willing to lose.
 
+## Flight recorder: a record nobody can edit
+
+Turn on `record=True` and every buy must first state what the agent believes. That belief is signed by the
+trading wallet, sealed until trading closes, and anchored on Gensyn mainnet by [Agon](https://agon.nerom.site).
+Nobody can see it before then or change it afterwards. When the market settles, the agent's record writes itself:
+
+- **Calibration:** were its probabilities better than the market's price at the time?
+- **Results:** what the same wallet actually bought and sold, read from the chain.
+
+```python
+d = Delphi(private_key=key, record=True, agent_name="my-agent")
+t = d.buy(m, "Yes", usd=2, belief={"Yes": 0.71}, reasoning="Polls moved after the debate.")
+t.record   # {'entry': 200, 'belief': 0.71, 'market_probability': 0.50, 'edge': 0.21,
+           #  'sealed_until': '2027-12-31T23:00:00Z', 'record_url': 'https://agon.nerom.site/#/agent/0x…', ...}
+```
+
+```bash
+delphi buy 0x4F5D… Yes --usd 2 --record --belief 0.71 --reason "Polls moved after the debate."
+```
+
+- **No entry, no trade.** A buy without a belief is refused, and so is one whose entry can't be logged.
+  `record="try"` trades anyway and says why the entry is missing.
+- **When it's logged.** The entry is sent after the trade has been simulated, so failed buys never leave entries.
+- **What it covers.** Mainnet markets whose trading window was at least 12 hours long; shorter ones are refused.
+- **Which server.** Entries go to https://agon.nerom.site. Agon is open source; point `recorder_url` or
+  `DELPHI_RECORDER_URL` at your own instance if you run one.
+- **In the MCP server.** Set `DELPHI_RECORD=true` (plus `DELPHI_AGENT_NAME`) and the `buy` tool requires the
+  agent's `probability` and `reasoning`. `my_record` shows what it has logged and, after settlement, how it scored.
+- **Proof for the model, too.** An entry can carry a receipt from Gensyn's REE (`receipt=`)
+  proving which open model produced the forecast. Agon re-runs receipts on a second machine.
+
 ## Alerts
 
 Delphi has no notifications or webhooks, so `delphi watch` polls the chain and tells you about:
@@ -157,6 +188,7 @@ notes are in [docs/contracts.md](docs/contracts.md).
 | Default approval | unlimited | exact amount |
 | Agent spending limits | no | yes |
 | Alerts | no | yes |
+| Sealed, scored record of what an agent believed | no | yes (`record=True`) |
 
 ## Tests
 
@@ -170,6 +202,8 @@ The fork tests run a private copy of Gensyn mainnet and put a throwaway wallet t
 - **LMSR:** buy with a $3 budget, sell half, jump the clock past the deadline, settle as Delphi's oracle relayer,
   redeem the winnings.
 - **DPM:** buy, let the market expire unsettled, liquidate.
+- **Flight recorder** (with `DELPHI_TEST_RECORDER_URL` pointing at a local Agon): a buy without a belief is
+  refused, then a belief is signed, accepted by Agon and sealed before the buy is sent.
 
 ## License
 

{delphi_kit-0.1.1 → delphi_kit-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "delphi-kit"
-version = "0.1.1"
+version = "0.2.0"
 description = "Read and trade Delphi prediction markets from Python and AI agents, with no API key: every market type, quotes, trades, positions, search, alerts and an MCP server."
 requires-python = ">=3.10"
 readme = "README.md"

{delphi_kit-0.1.1 → delphi_kit-0.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "delphi-kit"
-version = "0.1.1"
+version = "0.2.0"
 description = "Read and trade Delphi prediction markets from Python and AI agents, with no API key: every market type, quotes, trades, positions, search, alerts and an MCP server."
 requires-python = ">=3.10"
 readme = "README.md"

{delphi_kit-0.1.1 → delphi_kit-0.2.0}/src/delphi_kit/__init__.py

@@ -6,4 +6,4 @@ from .networks import NETWORKS, Deployment, Network
 
 __all__ = ["Delphi", "DelphiError", "InsufficientFunds", "Market", "Position", "Quote", "Trade",
            "NETWORKS", "Network", "Deployment"]
-__version__ = "0.1.1"
+__version__ = "0.2.0"

{delphi_kit-0.1.1 → delphi_kit-0.2.0}/src/delphi_kit/cli.py

@@ -53,6 +53,9 @@ def main(argv: list[str] | None = None) -> int:
     s.add_argument("--usd", type=float, required=True)
     s.add_argument("--max-slippage", type=float, default=0.02)
     s.add_argument("--yes", action="store_true", help="skip the confirmation prompt")
+    s.add_argument("--record", action="store_true", help="flight recorder: seal --belief on Agon before buying")
+    s.add_argument("--belief", type=float, help="your probability (0-1) that this outcome wins")
+    s.add_argument("--reason", default=None, help="why, sealed with the belief")
 
     s = sub.add_parser("sell", help="sell shares (needs DELPHI_PRIVATE_KEY)")
     s.add_argument("address")
@@ -83,7 +86,8 @@ def main(argv: list[str] | None = None) -> int:
 
     a = p.parse_args(argv)
     import os
-    d = Delphi(a.network or os.environ.get("DELPHI_NETWORK", "mainnet"))
+    record = getattr(a, "record", False) or os.environ.get("DELPHI_RECORD", "").lower() in ("1", "true", "yes")
+    d = Delphi(a.network or os.environ.get("DELPHI_NETWORK", "mainnet"), record=record if a.cmd == "buy" else False)
     try:
         return _run(d, a)
     except (DelphiError, ValueError) as e:
@@ -138,8 +142,15 @@ def _run(d: Delphi, a) -> int:
         q = d.quote_buy(a.address, a.outcome, usd=a.usd)
         if not _confirm(f"Buy {q.shares:.4f} {q.outcome_label} for ${q.usd:.2f} (max +{a.max_slippage:.0%})?", a.yes):
             return 1
-        t = d.buy(a.address, a.outcome, usd=a.usd, max_slippage=a.max_slippage)
-        _out(t.to_dict(), a.json) if a.json else print(f"bought {t.shares:.4f} {t.outcome_label} for ${t.usd:.4f}\n{t.explorer_url}")
+        belief = {a.outcome: a.belief} if a.belief is not None else None
+        t = d.buy(a.address, a.outcome, usd=a.usd, max_slippage=a.max_slippage, belief=belief, reasoning=a.reason)
+        if a.json:
+            _out(t.to_dict(), True)
+        else:
+            print(f"bought {t.shares:.4f} {t.outcome_label} for ${t.usd:.4f}\n{t.explorer_url}")
+            if t.record and t.record.get("logged"):
+                print(f"belief {t.record['belief']:.0%} vs market {t.record['market_probability']:.0%}, sealed until "
+                      f"{t.record['sealed_until']}\nrecord: {t.record['record_url']}")
         return 0
     if a.cmd == "sell":
         if not _confirm(f"Sell {'all' if a.shares is None else a.shares} {a.outcome} shares?", a.yes):

{delphi_kit-0.1.1 → delphi_kit-0.2.0}/src/delphi_kit/client.py

@@ -53,7 +53,11 @@ class Delphi:
     """
 
     def __init__(self, network: str | Network = "mainnet", *, private_key: str | None = None,
-                 rpc_url: str | None = None, cache: bool = True):
+                 rpc_url: str | None = None, cache: bool = True, record: bool | str = False,
+                 recorder_url: str | None = None, agent_name: str | None = None, agent_model: str = ""):
+        """``record=True`` turns on the flight recorder: every buy must state what the agent believes, and that
+        belief is sealed and anchored on chain (via Agon) before the trade is sent. No entry, no trade.
+        ``record="try"`` trades even if the entry can't be logged, and says why on the Trade."""
         self.network = network if isinstance(network, Network) else get_network(network)
         self.w3 = connect(self.network, rpc_url or os.environ.get("DELPHI_RPC_URL"))
         self.reader = Reader(self.w3, self.network)
@@ -68,6 +72,16 @@ class Delphi:
         self._addresses: dict[str, list[str]] = {}  # deployment name -> market addresses, oldest first
         self._meta: dict[str, tuple[Optional[dict], Optional[bool]]] = {}
         self._http = httpx.Client(timeout=20, follow_redirects=True, headers={"User-Agent": "delphi-kit"})
+        self.recorder = None
+        self.record_mode = "off"
+        if record:
+            if not self.account:
+                raise DelphiError("record=True needs a wallet key: entries are signed by the trading wallet")
+            if self.network.name != "mainnet":
+                raise DelphiError("the flight recorder covers mainnet markets only")
+            from .recorder import Recorder
+            self.recorder = Recorder(key, url=recorder_url, name=agent_name, model=agent_model, chain_id=self.network.chain_id)
+            self.record_mode = "try" if record == "try" else "required"
 
     # ------------------------------------------------------------------ wallet
 
@@ -366,12 +380,21 @@ class Delphi:
         return "0x" + r["transactionHash"].hex().removeprefix("0x")
 
     def buy(self, market: str | Market, outcome: int | str, *, usd: float | None = None, shares: float | None = None,
-            max_slippage: float = 0.02, approve_unlimited: bool = False) -> Trade:
+            max_slippage: float = 0.02, approve_unlimited: bool = False, belief=None, reasoning: str | None = None,
+            receipt: str | None = None) -> Trade:
         """Buy shares of one outcome. ``usd`` spends up to that budget; ``shares`` buys an exact count.
-        Approves only the amount needed unless ``approve_unlimited``."""
+        Approves only the amount needed unless ``approve_unlimited``.
+
+        With the flight recorder on, ``belief`` is required: the probabilities the agent believes, e.g.
+        ``{"Yes": 0.71}`` (one side is enough for yes/no markets). ``reasoning`` is sealed with it."""
         acct = self._need_account()
         m, idx = self._resolve(market, outcome)
         q = self.quote_buy(m, idx, usd=usd, shares=shares)
+        if self.recorder and belief is None:
+            raise DelphiError('the flight recorder is on: say what you believe, e.g. belief={"Yes": 0.7}')
+        if self.recorder:
+            from .recorder import belief_vector
+            belief_vector(m, belief)  # bad beliefs fail here, before any approval is sent
         max_in = math.ceil(q.usd_raw * (1 + max_slippage))
         have = self.token.functions.balanceOf(acct.address).call()
         if have < max_in:
@@ -380,11 +403,30 @@ class Delphi:
         approval = self._ensure_allowance(m.address, max_in, approve_unlimited)
         fn = self._gw[m.deployment].functions.buyExactOut(checksum(m.address), idx, q.shares_raw, max_in)
         sim = fn.call({"from": acct.address})
+        # log the belief last, once the trade is known to go through, so the record never has entries for trades
+        # that failed before sending
+        rec = self._log_belief(m, idx, belief, reasoning, receipt) if self.recorder else None
         r = self._send(fn)
         paid = int(sim[0] if isinstance(sim, (list, tuple)) else sim)
         h = "0x" + r["transactionHash"].hex().removeprefix("0x")
         return Trade(market=m.address, outcome=idx, outcome_label=q.outcome_label, side="buy", shares=q.shares,
-                     usd=paid / 10**self.network.token_decimals, tx_hash=h, explorer_url=self.tx_url(h), approval_tx=approval)
+                     usd=paid / 10**self.network.token_decimals, tx_hash=h, explorer_url=self.tx_url(h), approval_tx=approval,
+                     record=rec)
+
+    def _log_belief(self, m: Market, idx: int, belief, reasoning, receipt) -> dict:
+        """Seal the agent's belief before a trade. Raises (so nothing is traded) unless record="try"."""
+        from .recorder import RecorderError, belief_vector
+        vec = belief_vector(m, belief)
+        mine, theirs = vec[idx] / (sum(vec) or 1), (m.probabilities[idx] if idx < len(m.probabilities) else None)
+        try:
+            e = self.recorder.log(m, vec, reasoning, receipt=receipt)
+        except (RecorderError, ValueError) as err:
+            if self.record_mode == "try":
+                return {"logged": False, "error": str(err)}
+            raise DelphiError(f"not traded: the belief could not be recorded ({err})") from None
+        return {"logged": True, "entry": e.id, "belief": round(mine, 4), "market_probability": theirs,
+                "edge": round(mine - theirs, 4) if theirs is not None else None, "sealed_until": e.sealed_until,
+                "record_url": e.url, "proof_url": e.proof_url}
 
     def sell(self, market: str | Market, outcome: int | str, shares: float | None = None, *,
              max_slippage: float = 0.02) -> Trade:

{delphi_kit-0.1.1 → delphi_kit-0.2.0}/src/delphi_kit/mcp_server.py

@@ -20,7 +20,10 @@ from .limits import Guard, LimitExceeded, Limits
 INSTRUCTIONS = """Delphi is a prediction market on the Gensyn chain, settled by an AI judge that reads each
 market's rules and named sources. Prices are probabilities (0-1). Before buying: read the market's rules and
 sources with get_market, quote with quote_buy, and check probability_after: thin markets move a lot on small
-trades. Trades are held to spending limits shown by wallet_status; never try to work around them."""
+trades. Trades are held to spending limits shown by wallet_status; never try to work around them.
+If wallet_status shows the flight recorder is on, every buy must state your honest probability for the outcome
+you buy and a short reason. It is sealed until trading closes and scored against the market when it settles, so
+state what you actually believe, not what justifies the trade."""
 
 READ = ToolAnnotations(read_only_hint=True, open_world_hint=True)
 WRITE = ToolAnnotations(read_only_hint=False, destructive_hint=False, idempotent_hint=False, open_world_hint=True)
@@ -33,7 +36,10 @@ _guard: Optional[Guard] = None
 def client() -> Delphi:
     global _client
     if _client is None:
-        _client = Delphi(os.environ.get("DELPHI_NETWORK", "mainnet"))
+        rec = os.environ.get("DELPHI_RECORD", "").lower()
+        _client = Delphi(os.environ.get("DELPHI_NETWORK", "mainnet"),
+                         record="try" if rec == "try" else rec in ("1", "true", "yes"),
+                         agent_name=os.environ.get("DELPHI_AGENT_NAME"), agent_model=os.environ.get("DELPHI_AGENT_MODEL", ""))
     return _client
 
 
@@ -115,7 +121,9 @@ def get_positions(wallet: str = "") -> Any:
 def wallet_status() -> Any:
     """The agent's wallet address, USDC and gas balance, and its spending limits and spend so far today."""
     c = client()
-    out: dict[str, Any] = {"network": c.network.name, "limits": guard().status()}
+    out: dict[str, Any] = {"network": c.network.name, "limits": guard().status(),
+                           "flight_recorder": {"on": True, "mode": c.record_mode, "agent": c.recorder.name,
+                                               "record_url": c.recorder.agent_url} if c.recorder else {"on": False}}
     if c.address:
         try:
             out.update(c.balance())
@@ -128,13 +136,21 @@ def wallet_status() -> Any:
 
 
 @server.tool(annotations=WRITE)
-def buy(market: str, outcome: str, usd: float) -> Any:
+def buy(market: str, outcome: str, usd: float, probability: float = -1, reasoning: str = "") -> Any:
     """Buy shares of `outcome` with up to `usd` of USDC. Held to the per-trade, daily and slippage limits.
-    Quote first and read the rules; this sends a real transaction."""
+    Quote first and read the rules; this sends a real transaction.
+    probability: your honest probability (0-1) that `outcome` wins. Required when the flight recorder is on;
+    it is sealed with `reasoning` before the trade and scored after the market settles."""
     g = guard()
     try:
         g.check(market, usd)
-        t = client().buy(market, outcome, usd=usd, max_slippage=g.limits.max_slippage)
+        c = client()
+        belief = None
+        if c.recorder:
+            if not 0 < probability < 1:
+                raise ValueError("the flight recorder is on: pass probability, your honest chance (0-1) that this outcome wins")
+            belief = {outcome: probability}
+        t = c.buy(market, outcome, usd=usd, max_slippage=g.limits.max_slippage, belief=belief, reasoning=reasoning or None)
         g.record(t.usd)
         return t.to_dict()
     except (LimitExceeded, DelphiError, ValueError) as e:
@@ -172,6 +188,19 @@ def collect(market: str) -> Any:
         return _fail(e)
 
 
+@server.tool(annotations=READ)
+def my_record() -> Any:
+    """The agent's flight record: every sealed belief it logged before trading, and once markets settle, how its
+    probabilities scored against the market's. Sealed entries show no numbers until trading closes."""
+    c = client()
+    if not c.recorder:
+        return {"on": False, "note": "The flight recorder is off. Set DELPHI_RECORD=true to turn it on."}
+    try:
+        return {"record_url": c.recorder.agent_url, **c.recorder.record()}
+    except Exception as e:  # noqa: BLE001
+        return _fail(e)
+
+
 def main() -> None:
     server.run("stdio")
 

{delphi_kit-0.1.1 → delphi_kit-0.2.0}/src/delphi_kit/models.py

@@ -102,6 +102,7 @@ class Trade(_Dict):
     tx_hash: str
     explorer_url: str
     approval_tx: Optional[str] = None
+    record: Optional[dict] = None      # the sealed entry logged before this trade (record=True), or why it wasn't
 
 
 @dataclass

delphi_kit-0.2.0/src/delphi_kit/recorder.py

@@ -0,0 +1,204 @@
+"""Flight recorder: before an agent trades, it writes down what it believes, and that entry is sealed and anchored
+on the Gensyn chain by Agon (https://agon.nerom.site, open source at github.com/neromtoobad/agon).
+
+When the market settles, the agent's record writes itself:
+
+- calibration: were the stated probabilities better than the market price at the time? (Agon's scoring)
+- results: what the same wallet actually bought and sold, read from the chain
+
+The entry is signed with the trading wallet's own key (EIP-712), so the record and the trades share one address.
+Entries are sealed until trading closes: nobody, including Agon, can show or change them before then.
+
+    d = Delphi(private_key=key, record=True)
+    d.buy(m, "Yes", usd=2, belief={"Yes": 0.71}, reasoning="Polls moved after the debate ...")
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional, Sequence
+
+import httpx
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+from web3 import Web3
+
+from .models import Market, _Dict
+
+DEFAULT_URL = "https://agon.nerom.site"
+ZERO32 = "0x" + "00" * 32
+MAX_REASONING = 4000
+
+TYPES = {
+    "Agent": [
+        {"name": "name", "type": "string"}, {"name": "uri", "type": "string"}, {"name": "client", "type": "string"},
+        {"name": "model", "type": "string"}, {"name": "issuedAt", "type": "uint64"},
+    ],
+    "Forecast": [
+        {"name": "market", "type": "address"}, {"name": "probabilities", "type": "uint16[]"},
+        {"name": "issuedAt", "type": "uint64"}, {"name": "visibility", "type": "uint8"},
+        {"name": "reasoningHash", "type": "bytes32"}, {"name": "receiptHash", "type": "bytes32"},
+    ],
+}
+
+
+class RecorderError(Exception):
+    pass
+
+
+@dataclass
+class Entry(_Dict):
+    """One sealed forecast in the agent's record."""
+    id: int
+    market: str
+    probabilities: list[float]
+    sealed_until: Optional[str]
+    url: str
+    proof_url: str
+    leaf: str = field(repr=False, default="")
+
+
+def to_basis_points(probs: Sequence[float]) -> list[int]:
+    """Probabilities (any non-negative weights) to whole basis points, each 100-9900, adding up to exactly 10000."""
+    if not probs or any(p < 0 for p in probs):
+        raise ValueError("probabilities must be non-negative, one per outcome")
+    total = float(sum(probs))
+    if total <= 0:
+        raise ValueError("probabilities can't all be zero")
+    n = len(probs)
+    if n * 100 > 10000:
+        raise ValueError("too many outcomes to record (at most 100)")
+    bp = [min(9900, max(100, round(p / total * 10000))) for p in probs]
+    # put the rounding error on the largest outcome that still has room, one point at a time
+    while (diff := 10000 - sum(bp)) != 0:
+        step = 1 if diff > 0 else -1
+        bp[max((i for i in range(n) if 100 <= bp[i] + step <= 9900), key=lambda k: bp[k])] += step
+    return bp
+
+
+def belief_vector(m: Market, belief: Mapping[Any, float] | Sequence[float]) -> list[float]:
+    """Accept {"Yes": 0.7}, {"Yes": 0.7, "No": 0.3}, {0: 0.7} or [0.7, 0.3]. For a two-outcome market, one side is enough."""
+    n = len(m.outcomes) or len(m.probabilities)
+    if isinstance(belief, Mapping):
+        vec: list[Optional[float]] = [None] * n
+        for k, v in belief.items():
+            vec[m.outcome_index(k)] = float(v)
+        missing = [i for i, v in enumerate(vec) if v is None]
+        if missing:
+            given = sum(v for v in vec if v is not None)
+            if given > 1 + 1e-9:
+                raise ValueError("stated probabilities add up to more than 1")
+            share = (1 - given) / len(missing)
+            for i in missing:
+                vec[i] = share
+        out = [float(v) for v in vec]  # type: ignore[arg-type]
+    else:
+        out = [float(v) for v in belief]
+        if len(out) != n:
+            raise ValueError(f"this market has {n} outcomes, got {len(out)} probabilities")
+    if any(not 0 <= v <= 1 for v in out) or abs(sum(out) - 1) > 0.02:
+        raise ValueError(f"stated probabilities must each be 0-1 and add up to 1 (these add up to {sum(out):.2f})")
+    return out
+
+
+class Recorder:
+    """Talks to an Agon server. ``Delphi(record=True)`` makes one for you."""
+
+    def __init__(self, private_key: str, *, url: str | None = None, name: str | None = None, model: str = "",
+                 uri: str = "", chain_id: int = 685689, timeout: float = 30):
+        self.account = Account.from_key(private_key)
+        self.url = (url or os.environ.get("DELPHI_RECORDER_URL") or DEFAULT_URL).rstrip("/")
+        self.name = name or os.environ.get("DELPHI_AGENT_NAME") or f"agent-{self.account.address[2:8].lower()}"
+        self.model = model or os.environ.get("DELPHI_AGENT_MODEL", "")
+        self.uri = uri
+        self.domain = {"name": "Agon", "version": "1", "chainId": chain_id}
+        self.http = httpx.Client(timeout=timeout, headers={"user-agent": "delphi-kit"})
+        self._registered = False
+
+    @property
+    def address(self) -> str:
+        return self.account.address
+
+    @property
+    def agent_url(self) -> str:
+        return f"{self.url}/#/agent/{self.address.lower()}"
+
+    # ------------------------------------------------------------ signing
+
+    def _sign(self, primary: str, message: dict) -> str:
+        msg = encode_typed_data(full_message={
+            "types": {"EIP712Domain": [{"name": "name", "type": "string"}, {"name": "version", "type": "string"},
+                                       {"name": "chainId", "type": "uint256"}],
+                      # only the primary type: Agent and Forecast don't reference each other, so the hash is the
+                      # same, and eth_account refuses messages whose types have more than one possible root
+                      primary: TYPES[primary]},
+            "primaryType": primary, "domain": self.domain, "message": message})
+        sig = self.account.sign_message(msg).signature.hex()
+        return sig if sig.startswith("0x") else "0x" + sig
+
+    def _post(self, path: str, body: dict) -> dict:
+        try:
+            r = self.http.post(self.url + path, json=body)
+        except httpx.HTTPError as e:
+            raise RecorderError(f"can't reach the recorder at {self.url}: {e}") from None
+        data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
+        if r.status_code >= 400:
+            raise RecorderError(data.get("error") or f"recorder answered HTTP {r.status_code}")
+        return data
+
+    # ------------------------------------------------------------ API
+
+    def register(self) -> dict:
+        """Register (or update) this wallet as an agent. Called for you before the first entry."""
+        msg = {"name": self.name, "uri": self.uri, "client": "delphi-kit", "model": self.model, "issuedAt": int(time.time())}
+        out = self._post("/league/v1/agents", {"address": self.address, "message": msg, "signature": self._sign("Agent", msg)})
+        self._registered = True
+        return out
+
+    def _ensure_registered(self) -> None:
+        if self._registered:
+            return
+        try:
+            r = self.http.get(f"{self.url}/league/v1/agents/{self.address.lower()}")
+            if r.status_code == 200:
+                self._registered = True
+                return
+        except httpx.HTTPError:
+            pass
+        self.register()
+
+    def log(self, market: Market, belief: Mapping[Any, float] | Sequence[float], reasoning: str | None = None,
+            *, public: bool = False, receipt: str | None = None) -> Entry:
+        """Seal what the agent believes about ``market`` now. ``reasoning`` is stored and its hash signed; it is
+        revealed with the forecast when trading closes. ``receipt`` is an optional REE receipt file's text."""
+        self._ensure_registered()
+        bp = to_basis_points(belief_vector(market, belief))
+        if reasoning is not None and len(reasoning) > MAX_REASONING:
+            reasoning = reasoning[:MAX_REASONING]
+        rh = Web3.keccak(text=reasoning).hex() if reasoning else ZERO32
+        rh = rh if rh.startswith("0x") else "0x" + rh
+        receipt_hash = ZERO32
+        if receipt is not None:
+            import json
+            receipt_hash = "0x" + json.loads(receipt)["hashes"]["receipt_hash"].removeprefix("0x").lower()
+        msg = {"market": Web3.to_checksum_address(market.address), "probabilities": bp, "issuedAt": int(time.time()),
+               "visibility": 1 if public else 0, "reasoningHash": rh, "receiptHash": receipt_hash}
+        body: dict[str, Any] = {"address": self.address, "message": msg, "signature": self._sign("Forecast", msg)}
+        if reasoning:
+            body["reasoning"] = reasoning
+        if receipt is not None:
+            body["receipt"] = receipt
+        out = self._post("/league/v1/forecasts", body)
+        return Entry(id=out["id"], market=market.address, probabilities=[b / 10000 for b in bp],
+                     sealed_until=out.get("sealed_until"), url=self.agent_url,
+                     proof_url=f"{self.url}/league/v1/forecasts/{out['id']}/proof", leaf=out.get("leaf", ""))
+
+    def record(self) -> dict:
+        """The agent's record so far: points, scored markets, and every entry (sealed ones show no numbers)."""
+        r = self.http.get(f"{self.url}/league/v1/agents/{self.address.lower()}")
+        if r.status_code == 404:
+            return {"address": self.address, "registered": False, "forecasts": []}
+        r.raise_for_status()
+        return r.json()