polypad-agent 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,105 @@
1
+ Metadata-Version: 2.4
2
+ Name: polypad-agent
3
+ Version: 2.0.0
4
+ Summary: Thin typed client for the Polypad agent API (MCP) on Robinhood Chain: prepare → sign → confirm, persistent wallet binding, and x402 pay-per-call.
5
+ License: MIT
6
+ Requires-Python: >=3.10
7
+ Description-Content-Type: text/markdown
8
+ Requires-Dist: requests>=2.0
9
+ Requires-Dist: eth-account>=0.13
10
+ Provides-Extra: dev
11
+ Requires-Dist: pytest>=7.0; extra == "dev"
12
+
13
+ # polypad-agent (Python)
14
+
15
+ Thin typed client for the Polypad agent API (MCP) on Robinhood Chain. Version 2.0.0, matching the
16
+ server. Not yet published to PyPI — install from the repo for now: `pip install -e py/`.
17
+
18
+ ## Install (once published)
19
+
20
+ ```bash
21
+ pip install polypad-agent
22
+ ```
23
+
24
+ ## Connect once
25
+
26
+ ```python
27
+ from polypad_agent import PolypadClient
28
+
29
+ client = PolypadClient()
30
+ # Show the user this URL: they connect their wallet, sign one message, and get a token.
31
+ print(client.connect_url(return_url="https://example.com/agent/done"))
32
+ # Store the token as POLYPAD_WALLET_TOKEN. The client reads it automatically.
33
+ ```
34
+
35
+ ## Quickstart
36
+
37
+ ```python
38
+ from polypad_agent import PolypadClient
39
+
40
+ client = PolypadClient() # reads POLYPAD_WALLET_TOKEN
41
+ print(client.list_tokens(sort="new", limit=5))
42
+ print(client.quote_trade(token="POLYDASH", side="buy", amountEth="0.01"))
43
+ mint = client.prepare_fund_mint(fund="0x7c1d31629ac68aebe83f230edbc7eacfc26285ef", quantity=1)
44
+ print(mint["signing"]["url"]) # the user opens this and signs
45
+ ```
46
+
47
+ ## The loop
48
+
49
+ ```python
50
+ # Chat agent: prepare, show the link, wait for the hash, poll until confirmed.
51
+ done = client.prepare_sign_confirm(
52
+ "polypad_prepare_fund_mint",
53
+ {"fund": "0x7c1d31629ac68aebe83f230edbc7eacfc26285ef", "quantity": 1},
54
+ on_signing_link=lambda url, summary: print(summary["headline"], url),
55
+ get_tx_hash=read_hash_from_return_callback,
56
+ return_url="https://example.com/agent/done",
57
+ )
58
+ print(done["status"], done["tx_hash"], done["result"])
59
+
60
+ # Script with its own wallet (the Forge path): prepare, sign, broadcast, confirm.
61
+ launched = client.prepare_sign_broadcast(
62
+ "polypad_prepare_token_launch",
63
+ {"name": "Agent Swarm", "symbol": "SWARM", "creatorFeeBps": 100, "devBuyEth": "0"},
64
+ private_key=os.environ["LAUNCHER_PRIVATE_KEY"],
65
+ )
66
+ print(launched["status"], launched["tx_hash"])
67
+ ```
68
+
69
+ ## Pay-per-call
70
+
71
+ ```python
72
+ from polypad_agent import pay_for_report
73
+
74
+ report = pay_for_report(
75
+ "token-report",
76
+ "address=0x3Da9244DDE38284017fD15e45d1Fdf66D3617B4B",
77
+ private_key=os.environ["PAYER_PRIVATE_KEY"],
78
+ )
79
+ ```
80
+
81
+ ## Recipes
82
+
83
+ - `examples/launch_token.py` — launch a token from a script, then create its staking pool.
84
+ - `examples/run_fund.py` — create a tokenized fund, then mint the manager's skin shares.
85
+ - `examples/smoke.py` — read-only live smoke test (initialize, tools/list, stats).
86
+
87
+ ## More in the package
88
+
89
+ - `confirm` / `sign_and_send` / `sign_send_and_confirm` — the standalone sign-loop helpers
90
+ (`confirm` polls `polypad_get_tx_status` until the transaction confirms or fails).
91
+ - `sign_x402_payment` / `fetch_with_x402` / `product_url` / `next_permit2_nonce` — x402
92
+ building blocks for USDG (EIP-3009) and POLYDASH (Permit2) payments.
93
+ - `build_create_key_tx` / `build_deposit_tx` / `build_withdraw_tx` / `build_revoke_key_tx` /
94
+ `get_key_status` / `get_vault_balance` — SpendVault spending keys.
95
+ - `TOOL_NAMES` / `PREPARE_TOOLS` / `is_prepare_tool`, `RATE_LIMITS`, `ACTION_LIMITS`,
96
+ `ERROR_MEANINGS` — the 21 tools, the published limits, and the server's error meanings.
97
+
98
+ ## Tests
99
+
100
+ ```bash
101
+ PYTHONPATH=src python -m unittest discover -s tests -v # 44 tests (mocked transport, no network)
102
+ ```
103
+
104
+ Per-call `from` still works: pass it explicitly and the client leaves the token out for that call.
105
+ Contracts are unaudited.
@@ -0,0 +1,93 @@
1
+ # polypad-agent (Python)
2
+
3
+ Thin typed client for the Polypad agent API (MCP) on Robinhood Chain. Version 2.0.0, matching the
4
+ server. Not yet published to PyPI — install from the repo for now: `pip install -e py/`.
5
+
6
+ ## Install (once published)
7
+
8
+ ```bash
9
+ pip install polypad-agent
10
+ ```
11
+
12
+ ## Connect once
13
+
14
+ ```python
15
+ from polypad_agent import PolypadClient
16
+
17
+ client = PolypadClient()
18
+ # Show the user this URL: they connect their wallet, sign one message, and get a token.
19
+ print(client.connect_url(return_url="https://example.com/agent/done"))
20
+ # Store the token as POLYPAD_WALLET_TOKEN. The client reads it automatically.
21
+ ```
22
+
23
+ ## Quickstart
24
+
25
+ ```python
26
+ from polypad_agent import PolypadClient
27
+
28
+ client = PolypadClient() # reads POLYPAD_WALLET_TOKEN
29
+ print(client.list_tokens(sort="new", limit=5))
30
+ print(client.quote_trade(token="POLYDASH", side="buy", amountEth="0.01"))
31
+ mint = client.prepare_fund_mint(fund="0x7c1d31629ac68aebe83f230edbc7eacfc26285ef", quantity=1)
32
+ print(mint["signing"]["url"]) # the user opens this and signs
33
+ ```
34
+
35
+ ## The loop
36
+
37
+ ```python
38
+ # Chat agent: prepare, show the link, wait for the hash, poll until confirmed.
39
+ done = client.prepare_sign_confirm(
40
+ "polypad_prepare_fund_mint",
41
+ {"fund": "0x7c1d31629ac68aebe83f230edbc7eacfc26285ef", "quantity": 1},
42
+ on_signing_link=lambda url, summary: print(summary["headline"], url),
43
+ get_tx_hash=read_hash_from_return_callback,
44
+ return_url="https://example.com/agent/done",
45
+ )
46
+ print(done["status"], done["tx_hash"], done["result"])
47
+
48
+ # Script with its own wallet (the Forge path): prepare, sign, broadcast, confirm.
49
+ launched = client.prepare_sign_broadcast(
50
+ "polypad_prepare_token_launch",
51
+ {"name": "Agent Swarm", "symbol": "SWARM", "creatorFeeBps": 100, "devBuyEth": "0"},
52
+ private_key=os.environ["LAUNCHER_PRIVATE_KEY"],
53
+ )
54
+ print(launched["status"], launched["tx_hash"])
55
+ ```
56
+
57
+ ## Pay-per-call
58
+
59
+ ```python
60
+ from polypad_agent import pay_for_report
61
+
62
+ report = pay_for_report(
63
+ "token-report",
64
+ "address=0x3Da9244DDE38284017fD15e45d1Fdf66D3617B4B",
65
+ private_key=os.environ["PAYER_PRIVATE_KEY"],
66
+ )
67
+ ```
68
+
69
+ ## Recipes
70
+
71
+ - `examples/launch_token.py` — launch a token from a script, then create its staking pool.
72
+ - `examples/run_fund.py` — create a tokenized fund, then mint the manager's skin shares.
73
+ - `examples/smoke.py` — read-only live smoke test (initialize, tools/list, stats).
74
+
75
+ ## More in the package
76
+
77
+ - `confirm` / `sign_and_send` / `sign_send_and_confirm` — the standalone sign-loop helpers
78
+ (`confirm` polls `polypad_get_tx_status` until the transaction confirms or fails).
79
+ - `sign_x402_payment` / `fetch_with_x402` / `product_url` / `next_permit2_nonce` — x402
80
+ building blocks for USDG (EIP-3009) and POLYDASH (Permit2) payments.
81
+ - `build_create_key_tx` / `build_deposit_tx` / `build_withdraw_tx` / `build_revoke_key_tx` /
82
+ `get_key_status` / `get_vault_balance` — SpendVault spending keys.
83
+ - `TOOL_NAMES` / `PREPARE_TOOLS` / `is_prepare_tool`, `RATE_LIMITS`, `ACTION_LIMITS`,
84
+ `ERROR_MEANINGS` — the 21 tools, the published limits, and the server's error meanings.
85
+
86
+ ## Tests
87
+
88
+ ```bash
89
+ PYTHONPATH=src python -m unittest discover -s tests -v # 44 tests (mocked transport, no network)
90
+ ```
91
+
92
+ Per-call `from` still works: pass it explicitly and the client leaves the token out for that call.
93
+ Contracts are unaudited.
@@ -0,0 +1,21 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "polypad-agent"
7
+ version = "2.0.0"
8
+ description = "Thin typed client for the Polypad agent API (MCP) on Robinhood Chain: prepare → sign → confirm, persistent wallet binding, and x402 pay-per-call."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "MIT" }
12
+ dependencies = [
13
+ "requests>=2.0",
14
+ "eth-account>=0.13",
15
+ ]
16
+
17
+ [project.optional-dependencies]
18
+ dev = ["pytest>=7.0"]
19
+
20
+ [tool.setuptools.packages.find]
21
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,85 @@
1
+ """polypad-agent — thin typed client for the Polypad agent API (MCP) on Robinhood Chain."""
2
+
3
+ from .binding import connect_url, decode_wallet_token
4
+ from .client import CHAIN_ID, DEFAULT_RPC_URL, MCP_URL, SITE_ORIGIN, PolypadClient
5
+ from .constants import (
6
+ ACTION_LIMITS,
7
+ CHAIN_NAME,
8
+ ERROR_MEANINGS,
9
+ EXPLORER,
10
+ MCP_ENDPOINT,
11
+ MCP_PROTOCOL_VERSION,
12
+ RATE_LIMITS,
13
+ SERVER_VERSION,
14
+ SPEND_VAULT_ADDRESS,
15
+ VAULT_TOKENS,
16
+ X402,
17
+ X402_PRODUCTS,
18
+ x402_product,
19
+ )
20
+ from .errors import PolypadConfirmTimeoutError, PolypadError, PolypadTxFailedError
21
+ from .prepare import confirm, sign_and_send, sign_send_and_confirm
22
+ from .spend_vault import (
23
+ build_create_key_tx,
24
+ build_deposit_tx,
25
+ build_revoke_key_tx,
26
+ build_withdraw_tx,
27
+ get_key_status,
28
+ get_vault_balance,
29
+ spend_vault_key_flow,
30
+ )
31
+ from .tools import PREPARE_TOOLS, TOOL_NAMES, is_prepare_tool
32
+ from .x402 import (
33
+ encode_payment_header,
34
+ fetch_with_x402,
35
+ next_permit2_nonce,
36
+ pay_for_report,
37
+ product_url,
38
+ sign_x402_payment,
39
+ )
40
+
41
+ __all__ = [
42
+ "PolypadClient",
43
+ "PolypadError",
44
+ "PolypadTxFailedError",
45
+ "PolypadConfirmTimeoutError",
46
+ "MCP_URL",
47
+ "MCP_ENDPOINT",
48
+ "SITE_ORIGIN",
49
+ "CHAIN_ID",
50
+ "DEFAULT_RPC_URL",
51
+ "connect_url",
52
+ "decode_wallet_token",
53
+ "pay_for_report",
54
+ "confirm",
55
+ "sign_and_send",
56
+ "sign_send_and_confirm",
57
+ "TOOL_NAMES",
58
+ "PREPARE_TOOLS",
59
+ "is_prepare_tool",
60
+ "build_create_key_tx",
61
+ "build_deposit_tx",
62
+ "build_revoke_key_tx",
63
+ "build_withdraw_tx",
64
+ "get_key_status",
65
+ "get_vault_balance",
66
+ "spend_vault_key_flow",
67
+ "encode_payment_header",
68
+ "fetch_with_x402",
69
+ "next_permit2_nonce",
70
+ "product_url",
71
+ "sign_x402_payment",
72
+ "ACTION_LIMITS",
73
+ "CHAIN_NAME",
74
+ "ERROR_MEANINGS",
75
+ "EXPLORER",
76
+ "MCP_PROTOCOL_VERSION",
77
+ "RATE_LIMITS",
78
+ "SERVER_VERSION",
79
+ "SPEND_VAULT_ADDRESS",
80
+ "VAULT_TOKENS",
81
+ "X402",
82
+ "X402_PRODUCTS",
83
+ "x402_product",
84
+ ]
85
+ __version__ = "2.0.0"
@@ -0,0 +1,55 @@
1
+ """Persistent wallet binding — the token from /sign?connect=1.
2
+
3
+ Connect once: the user opens the connect URL, signs one message (not a transaction), and gets
4
+ a token. The SDK stores it (POLYPAD_WALLET_TOKEN) and passes it instead of a wallet address on
5
+ every prepare call. The server recovers the wallet from the signature — no server storage, no
6
+ per-call `from`. The token lasts 90 days; after that, connect again.
7
+
8
+ The token is base64url JSON {v: 1, address, exp, sig}. This module only decodes it (to show
9
+ which wallet is bound and when it expires). Verification happens server-side on every call.
10
+ """
11
+
12
+ import base64
13
+ import json
14
+ import time
15
+
16
+ SITE_ORIGIN = "https://polypad.family"
17
+
18
+
19
+ def decode_wallet_token(token: str):
20
+ """Decode a wallet token. Returns None when it is not a token at all."""
21
+ try:
22
+ padded = token.strip() + "=" * (-len(token.strip()) % 4)
23
+ text = base64.urlsafe_b64decode(padded).decode("utf-8")
24
+ parsed = json.loads(text)
25
+ except Exception:
26
+ return None
27
+ if not isinstance(parsed, dict):
28
+ return None
29
+ if parsed.get("v") != 1 or not isinstance(parsed.get("address"), str):
30
+ return None
31
+ if not isinstance(parsed.get("exp"), (int, float)) or not isinstance(parsed.get("sig"), str):
32
+ return None
33
+ address = parsed["address"]
34
+ if len(address) != 42 or not address.startswith("0x"):
35
+ return None
36
+ try:
37
+ int(address[2:], 16)
38
+ except ValueError:
39
+ return None
40
+ exp = int(parsed["exp"])
41
+ return {"address": address, "exp": exp, "expired": exp <= int(time.time())}
42
+
43
+
44
+ def connect_url(return_url=None, origin=SITE_ORIGIN):
45
+ """The connect URL to show the user so they can bind a wallet and get a token.
46
+
47
+ When return_url is given, the page sends them back to it with
48
+ ?walletToken=...&wallet=... after connecting.
49
+ """
50
+ from urllib.parse import urlencode
51
+
52
+ params = {"connect": "1"}
53
+ if return_url:
54
+ params["r"] = return_url
55
+ return f"{origin}/sign?{urlencode(params)}"