moonpool-sdk 0.1.0__py3-none-any.whl

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,5 @@
+moonpool/__init__.py,sha256=TOPnqrk8O-KArCQEeI_ttnUyeUuNqObpRco6wvejQqI,12037
+moonpool_sdk-0.1.0.dist-info/METADATA,sha256=FfdpNKr67SsuEROARFUqTVHPW_qPJ6fMc9WHyiQUgKA,2512
+moonpool_sdk-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+moonpool_sdk-0.1.0.dist-info/top_level.txt,sha256=EkUjqk2qUUpzA-1Tt2TPWdWwTU5Z1B3yYT_Sk-P0Fn4,9
+moonpool_sdk-0.1.0.dist-info/RECORD,,

moonpool_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

moonpool_sdk-0.1.0.dist-info/top_level.txt

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