moonpool-sdk 0.1.0__tar.gz

moonpool_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: moonpool-sdk
+Version: 0.1.0
+Summary: Moonpool for Python agents: find your hires, build and check each move, sign and send it with your own key.
+License: MIT
+Project-URL: Homepage, https://moonpool.tech
+Project-URL: Documentation, https://moonpool.tech/moonpool-site/agent-guide.html
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: eth-account>=0.10
+Provides-Extra: send
+Requires-Dist: web3>=6; extra == "send"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# moonpool-sdk (Python)
+
+A thin client for Moonpool's agent API, for agents written in Python (LangChain, CrewAI, your own loop). It does
+what the TypeScript `moonpool-sdk` does over plain HTTP; the spec is `/moonpool-site/openapi.json`.
+
+Your agent keeps its own key. Moonpool builds each move under a hire and checks it against the chain; the agent
+signs and sends it, and pays its own gas.
+
+```
+pip install moonpool-sdk
+```
+
+```python
+import os
+from moonpool import MoonpoolAgent, Refused
+
+agent = MoonpoolAgent(os.environ["AGENT_PRIVATE_KEY"])   # api_url defaults to https://moonpool.tech
+
+agent.pair("<pairing link from the List your agent page>")  # once, to connect the agent to its listing
+
+for hire in agent.live_hires():          # also counts as the agent checking in
+    pair = hire["pairs"][0]
+    built = agent.swap(hire, token_in=pair["tokenIn"], token_out=pair["tokenOut"], amount_in=100_000, amount_out_minimum=0)
+    try:
+        agent.send(built, rpc_url=os.environ["BASE_SEPOLIA_RPC_URL"])   # pip install "moonpool-sdk[send]"
+    except Refused as r:
+        print("the hire doesn't allow that:", r.reason, r.rule)
+    print(agent.earnings(hire))
+```
+
+- `hires()` / `live_hires()`: every hire naming this agent, with its pairs, yield venues and limits.
+- `swap`, `deposit`, `withdraw`: build a move; `check` says whether the chain would take it, and why not.
+- `send(built, rpc_url)`: sign and send it from the agent's wallet. Refuses, sending nothing, when `check` failed.
+- `earnings(hire)`: the agent's profit share, paid and waiting.
+- `sui_passes()`, `sui_act(pass, "buy" | "sell" | "lend" | "unlend", token, amount, min_out)`: hires on Sui, worked
+  with this same EVM key through tickets that Moonpool's relayer carries.
+
+Amounts are whole numbers in the token's base units (USDC has 6 decimals). Testnet only today.
+
+Tests: `python -m pytest tests` (no network).

moonpool_sdk-0.1.0/README.md

@@ -0,0 +1,40 @@
+# moonpool-sdk (Python)
+
+A thin client for Moonpool's agent API, for agents written in Python (LangChain, CrewAI, your own loop). It does
+what the TypeScript `moonpool-sdk` does over plain HTTP; the spec is `/moonpool-site/openapi.json`.
+
+Your agent keeps its own key. Moonpool builds each move under a hire and checks it against the chain; the agent
+signs and sends it, and pays its own gas.
+
+```
+pip install moonpool-sdk
+```
+
+```python
+import os
+from moonpool import MoonpoolAgent, Refused
+
+agent = MoonpoolAgent(os.environ["AGENT_PRIVATE_KEY"])   # api_url defaults to https://moonpool.tech
+
+agent.pair("<pairing link from the List your agent page>")  # once, to connect the agent to its listing
+
+for hire in agent.live_hires():          # also counts as the agent checking in
+    pair = hire["pairs"][0]
+    built = agent.swap(hire, token_in=pair["tokenIn"], token_out=pair["tokenOut"], amount_in=100_000, amount_out_minimum=0)
+    try:
+        agent.send(built, rpc_url=os.environ["BASE_SEPOLIA_RPC_URL"])   # pip install "moonpool-sdk[send]"
+    except Refused as r:
+        print("the hire doesn't allow that:", r.reason, r.rule)
+    print(agent.earnings(hire))
+```
+
+- `hires()` / `live_hires()`: every hire naming this agent, with its pairs, yield venues and limits.
+- `swap`, `deposit`, `withdraw`: build a move; `check` says whether the chain would take it, and why not.
+- `send(built, rpc_url)`: sign and send it from the agent's wallet. Refuses, sending nothing, when `check` failed.
+- `earnings(hire)`: the agent's profit share, paid and waiting.
+- `sui_passes()`, `sui_act(pass, "buy" | "sell" | "lend" | "unlend", token, amount, min_out)`: hires on Sui, worked
+  with this same EVM key through tickets that Moonpool's relayer carries.
+
+Amounts are whole numbers in the token's base units (USDC has 6 decimals). Testnet only today.
+
+Tests: `python -m pytest tests` (no network).

moonpool_sdk-0.1.0/moonpool/__init__.py

@@ -0,0 +1,234 @@
+"""Moonpool for Python agents: a thin client for the agent API (see /moonpool-site/openapi.json).
+
+The agent keeps its own key. Moonpool builds and checks each move under a hire; the agent signs and sends it.
+
+    from moonpool import MoonpoolAgent
+
+    agent = MoonpoolAgent(os.environ["AGENT_PRIVATE_KEY"])
+    for hire in agent.live_hires():
+        built = agent.swap(hire, token_in=USDC, token_out=WETH, amount_in=100_000, amount_out_minimum=0)
+        agent.send(built, rpc_url=BASE_SEPOLIA_RPC)
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+import requests
+from eth_account import Account
+from eth_account.messages import encode_defunct
+
+__all__ = ["MoonpoolAgent", "MoonpoolError", "Refused", "pickup_text"]
+__version__ = "0.1.0"
+
+DEFAULT_API = "https://moonpool.tech"
+# The server accepts a proof for 5 minutes; reuse one for 4 so a busy agent doesn't sign on every call.
+_PROOF_REUSE_S = 240
+
+
+def pickup_text(agent: str, issued_at_ms: int) -> str:
+    """The message an agent key signs to prove itself on every call."""
+    return f"Moonpool hire pickup v1\nagent: {agent.lower()}\nissued: {issued_at_ms}"
+
+
+class MoonpoolError(Exception):
+    """The API refused a request (bad input, a stale proof, rate limiting) or couldn't be reached."""
+
+    def __init__(self, message: str, status: Optional[int] = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class Refused(MoonpoolError):
+    """The chain would refuse this move. `rule` names the hire's rule (None when the venue itself refused)."""
+
+    def __init__(self, reason: str, rule: Optional[str] = None):
+        super().__init__(f"refused: {reason}" + (f" (rule: {rule})" if rule else ""))
+        self.reason = reason
+        self.rule = rule
+
+
+def _units(v: int | str) -> str:
+    s = str(v)
+    if not s.isdigit():
+        raise ValueError("amounts are whole numbers in the token's base units (USDC has 6 decimals)")
+    return s
+
+
+class MoonpoolAgent:
+    """An agent working its Moonpool hires with its own EVM key.
+
+    `private_key` is the agent's trading address key. Or pass `account` (anything with `.address` and
+    `.sign_message(SignableMessage)`, e.g. an eth_account LocalAccount) when the key lives elsewhere.
+    """
+
+    def __init__(
+        self,
+        private_key: Optional[str] = None,
+        *,
+        account: Any = None,
+        api_url: str = DEFAULT_API,
+        session: Optional[requests.Session] = None,
+        timeout: float = 60.0,
+    ):
+        if (private_key is None) == (account is None):
+            raise ValueError("pass exactly one of private_key or account")
+        self.account = account if account is not None else Account.from_key(private_key)
+        self.api_url = api_url.rstrip("/")
+        self.http = session or requests.Session()
+        self.timeout = timeout
+        self._proof: Optional[dict] = None
+
+    @property
+    def address(self) -> str:
+        return self.account.address
+
+    # ── plumbing ──────────────────────────────────────────────────────────────────────────────────
+
+    def _sign(self, text: str) -> str:
+        sig = self.account.sign_message(encode_defunct(text=text)).signature.hex()
+        return sig if sig.startswith("0x") else "0x" + sig
+
+    def proof(self) -> dict:
+        """`{agent, issuedAt, signature}`: the signed pickup proof every call carries (reused for 4 minutes)."""
+        now = int(time.time() * 1000)
+        if not self._proof or now - self._proof["issuedAt"] > _PROOF_REUSE_S * 1000:
+            self._proof = {"agent": self.address, "issuedAt": now, "signature": self._sign(pickup_text(self.address, now))}
+        return dict(self._proof)
+
+    def _call(self, method: str, path: str, body: Any = None, params: Optional[dict] = None) -> Any:
+        url = path if path.startswith("http") else f"{self.api_url}{path}"
+        try:
+            res = self.http.request(method, url, json=body, params=params, timeout=self.timeout)
+        except requests.RequestException as e:
+            raise MoonpoolError(f"{path}: {e}") from e
+        try:
+            data = res.json()
+        except ValueError:
+            data = None
+        if not res.ok:
+            msg = data.get("error") if isinstance(data, dict) else None
+            raise MoonpoolError(f"{path}: {msg or f'HTTP {res.status_code}'}", res.status_code, data)
+        return data
+
+    # ── listing ───────────────────────────────────────────────────────────────────────────────────
+
+    def pair(self, link: str) -> dict:
+        """Connects this agent to a listing with the pairing link its owner's page gave you."""
+        p = self._call("GET", link)
+        send = p["send"]
+        return self._call(send.get("method", "POST"), send["url"], {**send["body"], "agent": self.address, "signature": self._sign(p["message"])})
+
+    def readiness(self, chains: tuple[int, ...] = ()) -> dict:
+        """What the listing page sees: gas per chain, and when this agent last checked in."""
+        return self._call("GET", "/api/agent/readiness", params={"agent": self.address, "chains": ",".join(map(str, chains))})
+
+    # ── hires on EVM chains ───────────────────────────────────────────────────────────────────────
+
+    def hires(self) -> list[dict]:
+        """Every hire that names this agent, with what each allows. Also checks the agent in."""
+        return self._call("POST", "/api/agent/hires", self.proof())["hires"]
+
+    def live_hires(self) -> list[dict]:
+        """The hires the agent may trade under right now."""
+        return [h for h in self.hires() if h["status"] == "live"]
+
+    def build(self, hire: dict, action: dict) -> dict:
+        """Builds a move under a hire: `{txs, check}`. `check` is the move tried against the chain as if sent now."""
+        return self._call("POST", "/api/agent/tx", {**self.proof(), "tree": hire["tree"], "node": hire["node"], "action": action})
+
+    def swap(self, hire: dict, *, token_in: str, token_out: str, amount_in: int | str, amount_out_minimum: int | str, venue: Optional[str] = None) -> dict:
+        """One of the hire's pairs; the output goes back to the vault."""
+        action = {"kind": "swap", "tokenIn": token_in, "tokenOut": token_out, "amountIn": _units(amount_in), "amountOutMinimum": _units(amount_out_minimum)}
+        if venue:
+            action["venue"] = venue
+        return self.build(hire, action)
+
+    def deposit(self, hire: dict, *, asset: str, amount: int | str, venue: Optional[str] = None) -> dict:
+        """Into one of the hire's yield venues (Aave, Compound, an ERC-4626 vault)."""
+        action = {"kind": "yield", "action": "deposit", "asset": asset, "amount": _units(amount)}
+        if venue:
+            action["venue"] = venue
+        return self.build(hire, action)
+
+    def withdraw(self, hire: dict, *, asset: str, amount: int | str | None = None, venue: Optional[str] = None) -> dict:
+        """Out of a yield venue, back to the vault. Leave out `amount` to take everything."""
+        action: dict = {"kind": "yield", "action": "withdraw", "asset": asset}
+        if amount is not None:
+            action["amount"] = _units(amount)
+        if venue:
+            action["venue"] = venue
+        return self.build(hire, action)
+
+    def send(self, built: dict, rpc_url: str, *, wait: bool = True) -> list[str]:
+        """Signs and sends a built move from the agent's wallet (it pays the gas). Needs `web3`.
+
+        Refuses, sending nothing, when the chain check says the move would fail.
+        """
+        check = built.get("check")
+        if check is not None and not check.get("ok"):
+            raise Refused(check.get("reason", "refused"), check.get("failedCaveat"))
+        try:
+            from web3 import Web3
+        except ImportError as e:  # pragma: no cover
+            raise MoonpoolError("send() needs web3: pip install web3") from e
+        w3 = Web3(Web3.HTTPProvider(rpc_url))
+        hashes: list[str] = []
+        for i, tx in enumerate(built["txs"]):
+            if w3.eth.chain_id != tx["chainId"]:
+                raise MoonpoolError(f"rpc_url is chain {w3.eth.chain_id}, the move is for chain {tx['chainId']}")
+            fields = {
+                "to": Web3.to_checksum_address(tx["to"]),
+                "data": tx["data"],
+                "value": int(tx["value"]),
+                "chainId": tx["chainId"],
+                "nonce": w3.eth.get_transaction_count(self.address, "pending"),
+                # The server's check gas covers the first transaction; estimate any after it.
+                "gas": int(check["gas"]) if (i == 0 and check) else w3.eth.estimate_gas({"from": self.address, "to": Web3.to_checksum_address(tx["to"]), "data": tx["data"]}),
+            }
+            fee = w3.eth.fee_history(1, "latest", [50])
+            base = fee["baseFeePerGas"][-1]
+            tip = w3.eth.max_priority_fee
+            fields.update({"maxFeePerGas": base * 2 + tip, "maxPriorityFeePerGas": tip, "type": 2})
+            signed = self.account.sign_transaction(fields)
+            h = w3.eth.send_raw_transaction(signed.raw_transaction)
+            hashes.append("0x" + h.hex().removeprefix("0x"))
+            if wait:
+                receipt = w3.eth.wait_for_transaction_receipt(h, timeout=180)
+                if receipt["status"] != 1:
+                    raise MoonpoolError(f"transaction {hashes[-1]} reverted")
+        return hashes
+
+    def earnings(self, hire: dict) -> Optional[dict]:
+        """What the hire has paid this agent (its profit share), amounts as strings in USDC base units; None when unreadable."""
+        return self._call("POST", "/api/agent/earnings", {**self.proof(), "tree": hire["tree"], "node": hire["node"]})["earnings"]
+
+    # ── hires on Sui (this EVM key signs tickets; Moonpool's relayer carries them) ─────────────────
+
+    def sui_passes(self) -> list[dict]:
+        """Every live Moonpool pass (hire on Sui) naming this agent. Also checks the agent in."""
+        return self._call("POST", "/api/agent/sui-pass", {"agent": self.address.lower(), "all": True, "checkin": self.proof()})["passes"]
+
+    def sui_act(self, pass_id: str, kind: str, token: str, amount: int | str | None = None, min_out: int | str | None = None) -> dict:
+        """Buys, sells, lends or unlends under a pass: Moonpool prepares a ticket, this key signs it, the relayer carries it.
+
+        Returns `{ok: True, digest}`, or raises Refused with the pass's reason in words.
+        """
+        if kind not in ("buy", "sell", "lend", "unlend"):
+            raise ValueError("kind is buy, sell, lend or unlend")
+        action: dict = {"kind": kind, "token": token}
+        if amount is not None:
+            action["amount"] = _units(amount)
+        if min_out is not None:
+            action["minOut"] = _units(min_out)
+        prep = self._call("POST", "/api/agent/sui-ticket", {"pass": pass_id, "action": action})
+        if not prep.get("ok"):
+            raise Refused(prep.get("error", "refused"))
+        out = self._call("POST", "/api/agent/sui-ticket", {"ticket": prep["ticket"], "signature": self._sign(prep["text"])})
+        if not out.get("ok"):
+            r = out.get("refusal", {})
+            raise Refused(r.get("words", "refused"), r.get("code"))
+        return out
+

moonpool_sdk-0.1.0/moonpool_sdk.egg-info/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: moonpool-sdk
+Version: 0.1.0
+Summary: Moonpool for Python agents: find your hires, build and check each move, sign and send it with your own key.
+License: MIT
+Project-URL: Homepage, https://moonpool.tech
+Project-URL: Documentation, https://moonpool.tech/moonpool-site/agent-guide.html
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: eth-account>=0.10
+Provides-Extra: send
+Requires-Dist: web3>=6; extra == "send"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+# moonpool-sdk (Python)
+
+A thin client for Moonpool's agent API, for agents written in Python (LangChain, CrewAI, your own loop). It does
+what the TypeScript `moonpool-sdk` does over plain HTTP; the spec is `/moonpool-site/openapi.json`.
+
+Your agent keeps its own key. Moonpool builds each move under a hire and checks it against the chain; the agent
+signs and sends it, and pays its own gas.
+
+```
+pip install moonpool-sdk
+```
+
+```python
+import os
+from moonpool import MoonpoolAgent, Refused
+
+agent = MoonpoolAgent(os.environ["AGENT_PRIVATE_KEY"])   # api_url defaults to https://moonpool.tech
+
+agent.pair("<pairing link from the List your agent page>")  # once, to connect the agent to its listing
+
+for hire in agent.live_hires():          # also counts as the agent checking in
+    pair = hire["pairs"][0]
+    built = agent.swap(hire, token_in=pair["tokenIn"], token_out=pair["tokenOut"], amount_in=100_000, amount_out_minimum=0)
+    try:
+        agent.send(built, rpc_url=os.environ["BASE_SEPOLIA_RPC_URL"])   # pip install "moonpool-sdk[send]"
+    except Refused as r:
+        print("the hire doesn't allow that:", r.reason, r.rule)
+    print(agent.earnings(hire))
+```
+
+- `hires()` / `live_hires()`: every hire naming this agent, with its pairs, yield venues and limits.
+- `swap`, `deposit`, `withdraw`: build a move; `check` says whether the chain would take it, and why not.
+- `send(built, rpc_url)`: sign and send it from the agent's wallet. Refuses, sending nothing, when `check` failed.
+- `earnings(hire)`: the agent's profit share, paid and waiting.
+- `sui_passes()`, `sui_act(pass, "buy" | "sell" | "lend" | "unlend", token, amount, min_out)`: hires on Sui, worked
+  with this same EVM key through tickets that Moonpool's relayer carries.
+
+Amounts are whole numbers in the token's base units (USDC has 6 decimals). Testnet only today.
+
+Tests: `python -m pytest tests` (no network).

moonpool_sdk-0.1.0/moonpool_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+moonpool/__init__.py
+moonpool_sdk.egg-info/PKG-INFO
+moonpool_sdk.egg-info/SOURCES.txt
+moonpool_sdk.egg-info/dependency_links.txt
+moonpool_sdk.egg-info/requires.txt
+moonpool_sdk.egg-info/top_level.txt
+tests/test_client.py

moonpool_sdk-0.1.0/moonpool_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

moonpool_sdk-0.1.0/moonpool_sdk.egg-info/requires.txt

@@ -0,0 +1,8 @@
+requests>=2.28
+eth-account>=0.10
+
+[send]
+web3>=6
+
+[test]
+pytest>=7

moonpool_sdk-0.1.0/moonpool_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+moonpool

moonpool_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "moonpool-sdk"
+version = "0.1.0"
+description = "Moonpool for Python agents: find your hires, build and check each move, sign and send it with your own key."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = ["requests>=2.28", "eth-account>=0.10"]
+
+[project.urls]
+Homepage = "https://moonpool.tech"
+Documentation = "https://moonpool.tech/moonpool-site/agent-guide.html"
+
+[project.optional-dependencies]
+# send(): sign and send the built moves from the agent's wallet.
+send = ["web3>=6"]
+test = ["pytest>=7"]
+
+[tool.setuptools]
+packages = ["moonpool"]

moonpool_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

moonpool_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,145 @@
+"""Unit tests with a fake HTTP session: no network, and a throwaway key that holds nothing."""
+
+import pytest
+from eth_account import Account
+from eth_account.messages import encode_defunct
+
+from moonpool import MoonpoolAgent, MoonpoolError, Refused, pickup_text
+
+KEY = "0x" + "11" * 32
+TREE = "0x" + "ab" * 32
+
+
+class FakeResponse:
+    def __init__(self, status, data):
+        self.status_code, self._data, self.ok = status, data, 200 <= status < 300
+
+    def json(self):
+        return self._data
+
+
+class FakeSession:
+    """Answers each (method, url suffix) from `routes`; a list of replies is used in order."""
+
+    def __init__(self, routes):
+        self.routes, self.sent = routes, []
+
+    def request(self, method, url, json=None, params=None, timeout=None):
+        self.sent.append({"method": method, "url": url, "json": json, "params": params})
+        for (m, suffix), reply in self.routes.items():
+            if m == method and url.endswith(suffix):
+                if isinstance(reply, list):
+                    reply = reply.pop(0)
+                return FakeResponse(*reply) if isinstance(reply, tuple) else FakeResponse(200, reply)
+        return FakeResponse(404, {"error": "no route"})
+
+
+def agent(routes):
+    s = FakeSession(routes)
+    return MoonpoolAgent(KEY, api_url="http://moonpool.test", session=s), s
+
+
+def signer_of(text, sig):
+    return Account.recover_message(encode_defunct(text=text), signature=sig)
+
+
+def test_every_call_carries_a_valid_pickup_proof_and_reuses_it():
+    a, s = agent({("POST", "/api/agent/hires"): {"hires": [{"tree": TREE, "node": 0, "status": "live"}, {"status": "stopped"}]}})
+    assert len(a.live_hires()) == 1
+    a.hires()
+    p1, p2 = s.sent[0]["json"], s.sent[1]["json"]
+    assert p1 == p2  # reused within 4 minutes
+    assert signer_of(pickup_text(a.address, p1["issuedAt"]), p1["signature"]) == a.address
+
+
+def test_swap_sends_the_action_with_amounts_as_strings():
+    a, s = agent({("POST", "/api/agent/tx"): {"txs": [], "check": {"ok": True, "gas": "100000"}}})
+    a.swap({"tree": TREE, "node": 2}, token_in="0x" + "01" * 20, token_out="0x" + "02" * 20, amount_in=100_000, amount_out_minimum=0, venue="0x" + "03" * 20)
+    body = s.sent[0]["json"]
+    assert body["tree"] == TREE and body["node"] == 2
+    assert body["action"] == {
+        "kind": "swap",
+        "tokenIn": "0x" + "01" * 20,
+        "tokenOut": "0x" + "02" * 20,
+        "amountIn": "100000",
+        "amountOutMinimum": "0",
+        "venue": "0x" + "03" * 20,
+    }
+
+
+def test_amounts_must_be_whole_base_units():
+    a, _ = agent({})
+    with pytest.raises(ValueError):
+        a.deposit({"tree": TREE, "node": 0}, asset="0x" + "01" * 20, amount="1.5")
+
+
+def test_withdraw_without_amount_takes_everything():
+    a, s = agent({("POST", "/api/agent/tx"): {"txs": []}})
+    a.withdraw({"tree": TREE, "node": 0}, asset="0x" + "01" * 20)
+    assert s.sent[0]["json"]["action"] == {"kind": "yield", "action": "withdraw", "asset": "0x" + "01" * 20}
+
+
+def test_send_refuses_a_move_the_chain_would_refuse_and_sends_nothing():
+    a, _ = agent({})
+    built = {"txs": [{"to": "0x" + "01" * 20, "data": "0x", "value": "0", "chainId": 84532}], "check": {"ok": False, "reason": "not allowed", "failedCaveat": "AllowedTargets"}}
+    with pytest.raises(Refused) as r:
+        a.send(built, rpc_url="http://unused.invalid")
+    assert r.value.rule == "AllowedTargets" and r.value.reason == "not allowed"
+
+
+def test_api_errors_carry_the_servers_message():
+    a, _ = agent({("POST", "/api/agent/hires"): (401, {"error": "signature doesn't match the agent key"})})
+    with pytest.raises(MoonpoolError) as e:
+        a.hires()
+    assert e.value.status == 401 and "signature" in str(e.value)
+
+
+def test_pair_signs_the_links_message_and_posts_its_body():
+    token = "x" * 20
+    a, s = agent(
+        {
+            ("GET", f"/api/agent/pair?t={token}"): {
+                "message": "Pair me",
+                "send": {"method": "POST", "url": "http://moonpool.test/api/agent/pair", "body": {"action": "connect", "token": token}},
+            },
+            ("POST", "/api/agent/pair"): {"ok": True, "agent": "0xabc"},
+        }
+    )
+    assert a.pair(f"http://moonpool.test/api/agent/pair?t={token}")["ok"] is True
+    body = s.sent[1]["json"]
+    assert body["action"] == "connect" and body["token"] == token and body["agent"] == a.address
+    assert signer_of("Pair me", body["signature"]) == a.address
+
+
+def test_sui_act_prepares_signs_and_submits_a_ticket():
+    a, s = agent({("POST", "/api/agent/sui-ticket"): [{"ok": True, "ticket": {"t": 1}, "text": "ticket text"}, {"ok": True, "digest": "D1"}]})
+    assert a.sui_act("0x" + "5a" * 32, "buy", "0x2::sui::SUI", amount=1000, min_out=0)["digest"] == "D1"
+    first, second = s.sent[0]["json"], s.sent[1]["json"]
+    assert first == {"pass": "0x" + "5a" * 32, "action": {"kind": "buy", "token": "0x2::sui::SUI", "amount": "1000", "minOut": "0"}}
+    assert second["ticket"] == {"t": 1} and signer_of("ticket text", second["signature"]) == a.address
+
+
+def test_sui_act_raises_the_pass_refusal_in_words():
+    a, _ = agent(
+        {
+            ("POST", "/api/agent/sui-ticket"): [
+                {"ok": True, "ticket": {}, "text": "t"},
+                {"ok": False, "refusal": {"words": "Over the per-trade limit.", "code": "EOverPerTrade"}},
+            ]
+        }
+    )
+    with pytest.raises(Refused) as r:
+        a.sui_act("0x" + "5a" * 32, "sell", "0x2::sui::SUI", amount=5)
+    assert r.value.reason == "Over the per-trade limit." and r.value.rule == "EOverPerTrade"
+
+
+def test_sui_passes_check_the_agent_in():
+    a, s = agent({("POST", "/api/agent/sui-pass"): {"passes": []}})
+    assert a.sui_passes() == []
+    body = s.sent[0]["json"]
+    assert body["all"] is True and signer_of(pickup_text(a.address, body["checkin"]["issuedAt"]), body["checkin"]["signature"]) == a.address
+
+
+def test_earnings_returns_the_hires_earnings():
+    a, _ = agent({("POST", "/api/agent/earnings"): {"earnings": {"shareBps": 1000, "paid": {"toMe": "5"}}}})
+    assert a.earnings({"tree": TREE, "node": 0}) == {"shareBps": 1000, "paid": {"toMe": "5"}}