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.
- polypad_agent-2.0.0/PKG-INFO +105 -0
- polypad_agent-2.0.0/README.md +93 -0
- polypad_agent-2.0.0/pyproject.toml +21 -0
- polypad_agent-2.0.0/setup.cfg +4 -0
- polypad_agent-2.0.0/src/polypad_agent/__init__.py +85 -0
- polypad_agent-2.0.0/src/polypad_agent/binding.py +55 -0
- polypad_agent-2.0.0/src/polypad_agent/client.py +380 -0
- polypad_agent-2.0.0/src/polypad_agent/constants.py +144 -0
- polypad_agent-2.0.0/src/polypad_agent/errors.py +80 -0
- polypad_agent-2.0.0/src/polypad_agent/prepare.py +180 -0
- polypad_agent-2.0.0/src/polypad_agent/spend_vault.py +217 -0
- polypad_agent-2.0.0/src/polypad_agent/tools.py +74 -0
- polypad_agent-2.0.0/src/polypad_agent/x402.py +308 -0
- polypad_agent-2.0.0/src/polypad_agent.egg-info/PKG-INFO +105 -0
- polypad_agent-2.0.0/src/polypad_agent.egg-info/SOURCES.txt +20 -0
- polypad_agent-2.0.0/src/polypad_agent.egg-info/dependency_links.txt +1 -0
- polypad_agent-2.0.0/src/polypad_agent.egg-info/requires.txt +5 -0
- polypad_agent-2.0.0/src/polypad_agent.egg-info/top_level.txt +1 -0
- polypad_agent-2.0.0/tests/test_client.py +263 -0
- polypad_agent-2.0.0/tests/test_prepare.py +121 -0
- polypad_agent-2.0.0/tests/test_spend_vault.py +135 -0
- polypad_agent-2.0.0/tests/test_x402.py +198 -0
|
@@ -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,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)}"
|