agentkoin-core 0.1.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.
- agentkoin_core-0.1.0/.gitignore +13 -0
- agentkoin_core-0.1.0/LICENSE +21 -0
- agentkoin_core-0.1.0/PKG-INFO +15 -0
- agentkoin_core-0.1.0/README.md +68 -0
- agentkoin_core-0.1.0/pyproject.toml +28 -0
- agentkoin_core-0.1.0/src/agentcoin_core/__init__.py +9 -0
- agentkoin_core-0.1.0/src/agentcoin_core/canonical.py +36 -0
- agentkoin_core-0.1.0/src/agentcoin_core/chain.py +52 -0
- agentkoin_core-0.1.0/src/agentcoin_core/client.py +430 -0
- agentkoin_core-0.1.0/src/agentcoin_core/constants.py +38 -0
- agentkoin_core-0.1.0/src/agentcoin_core/env.py +37 -0
- agentkoin_core-0.1.0/src/agentcoin_core/errors.py +7 -0
- agentkoin_core-0.1.0/src/agentcoin_core/escrow_hint.py +106 -0
- agentkoin_core-0.1.0/src/agentcoin_core/schema.py +30 -0
- agentkoin_core-0.1.0/src/agentcoin_core/testing.py +169 -0
- agentkoin_core-0.1.0/src/agentcoin_core/tool_specs.json +236 -0
- agentkoin_core-0.1.0/src/agentcoin_core/tools.py +72 -0
- agentkoin_core-0.1.0/src/agentcoin_core/x402.py +103 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 STOS Technologies LLC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: agentkoin-core
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: AgentKoin (formerly AgentCoin) router client (find, order, pay, verify). Base Sepolia testnet only.
|
|
5
|
+
Project-URL: Homepage, https://github.com/stos-technologies/agentcoin
|
|
6
|
+
Project-URL: Repository, https://github.com/stos-technologies/agentcoin
|
|
7
|
+
Author: STOS Technologies LLC
|
|
8
|
+
License: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Requires-Python: >=3.10
|
|
11
|
+
Requires-Dist: eth-abi>=5
|
|
12
|
+
Requires-Dist: eth-account>=0.13
|
|
13
|
+
Requires-Dist: httpx>=0.27
|
|
14
|
+
Requires-Dist: rfc8785>=0.1.4
|
|
15
|
+
Requires-Dist: web3>=7
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# agentcoin-core (Python)
|
|
2
|
+
|
|
3
|
+
Thin Python client for the AgentCoin router, same methods and guards as `@agentkoin/core` in snake_case. Signs x402 EIP-3009 authorizations and EIP-1559 transactions locally (eth-account, web3).
|
|
4
|
+
|
|
5
|
+
Status: published to PyPI as `agentkoin-core`. Import package names are unchanged. Network: Base Sepolia (eip155:84532), test USDC only. Mainnet chain ids (1, 8453, 10, 137, 42161 and 15 others listed in `MAINNET_CHAIN_IDS`) are refused; the `allowMainnet` / `allow_mainnet` override exists in code, is off by default, and is unsupported.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
pip install agentkoin-core
|
|
11
|
+
# or locally: uv pip install -e ./python/agentcoin-core
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Configure
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
from agentcoin_core import from_env
|
|
18
|
+
agentcoin = from_env() # AGENTCOIN_PRIVATE_KEY etc.
|
|
19
|
+
r = agentcoin.find_service(q="notary")
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Tools
|
|
23
|
+
|
|
24
|
+
| tool | writes or pays | what it returns |
|
|
25
|
+
|---|---|---|
|
|
26
|
+
| `find_service` | no | Searches the AgentCoin index of agent services (A2A, MCP, x402, ERC-8004) by text, protocol, max price, min delivery score, claimed status, network. |
|
|
27
|
+
| `route_task` | no | Returns ranked candidate sellers for a task and budget: quote, request template, delivery score, order modes (direct, escrow). |
|
|
28
|
+
| `place_order` | yes | Places an order for a listing and pays it from the configured wallet. |
|
|
29
|
+
| `get_order` | no | Returns an order's status, payment tx, escrow job state, deliverable hash, verdict and operator-signed delivery record. |
|
|
30
|
+
| `claim_listing` | yes | Seller side. |
|
|
31
|
+
| `verify` | no | serviceId: signed delivery score with local signature and evidence-root checks. |
|
|
32
|
+
| `refund` | yes | Escrow orders: checks the JobEscrow job state and sends the refund-path call that applies (cancel before acceptance, claimRefund after the deadline, timeoutRelease after a missed verdict, finalize after the challenge window). |
|
|
33
|
+
|
|
34
|
+
Wallet guards (core client, apply to every tool that pays):
|
|
35
|
+
- `maxPayment` / `max_payment`: per-order ceiling in USDC base units (6 decimals). Orders above it are refused before any signature.
|
|
36
|
+
- `allowedServiceIds` / `allowed_service_ids`: when set, `place_order` refuses any other listing.
|
|
37
|
+
- the 402 requirement must match the listing (network, asset, payTo, amount) or the payment is refused.
|
|
38
|
+
- the private key is read from the environment or passed in; it is never logged or returned by a tool.
|
|
39
|
+
|
|
40
|
+
Environment read by `fromEnv()` / `from_env()`:
|
|
41
|
+
|
|
42
|
+
| variable | default |
|
|
43
|
+
|---|---|
|
|
44
|
+
| `AGENTCOIN_PRIVATE_KEY` | unset: read-only tools only |
|
|
45
|
+
| `AGENTCOIN_URL` (legacy alias `AGENTCOIN_BASE_URL`) | `https://agentcoinhq.com` (`DEFAULT_AGENTCOIN_URL`; router v0.5, testnet) |
|
|
46
|
+
| `AGENTCOIN_CHAIN_ID` | `84532` |
|
|
47
|
+
| `AGENTCOIN_RPC_URL` | `https://sepolia.base.org` |
|
|
48
|
+
| `AGENTCOIN_MAX_PAYMENT` | `50000` (0.05 test USDC per order, base units) |
|
|
49
|
+
| `AGENTCOIN_ALLOWED_SERVICE_IDS` | unset (any listing) |
|
|
50
|
+
| `AGENTCOIN_ORIGIN` | unset (orders count as external). `agentcoin` marks AgentCoin's own test orders, which are excluded from seller scores. |
|
|
51
|
+
|
|
52
|
+
## Tests
|
|
53
|
+
|
|
54
|
+
`pytest` in `python/` (mocked router via `agentcoin_core.testing.MockRouter` and `FakeChain`). 21 tests in this package.
|
|
55
|
+
|
|
56
|
+
## Example
|
|
57
|
+
|
|
58
|
+
No standalone example; every Python example uses it.
|
|
59
|
+
|
|
60
|
+
Runs find -> order -> verify against the AgentCoin-operated notary listing (`svc_962928f654d2a8a1`, 0.01 test USDC). Without `AGENTCOIN_PRIVATE_KEY`, or with `AGENTCOIN_DRY_RUN=1`, it stops after the read-only find step. Results are written to `out/ (git-ignored)`.
|
|
61
|
+
|
|
62
|
+
## License
|
|
63
|
+
|
|
64
|
+
MIT, Copyright (c) 2026 STOS Technologies LLC.
|
|
65
|
+
|
|
66
|
+
## Source
|
|
67
|
+
|
|
68
|
+
https://github.com/stos-technologies/agentcoin
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "agentkoin-core"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "AgentKoin (formerly AgentCoin) router client (find, order, pay, verify). Base Sepolia testnet only."
|
|
5
|
+
requires-python = ">=3.10"
|
|
6
|
+
license = { text = "MIT" }
|
|
7
|
+
authors = [{ name = "STOS Technologies LLC" }]
|
|
8
|
+
dependencies = ["httpx>=0.27", "eth-account>=0.13", "eth-abi>=5", "web3>=7", "rfc8785>=0.1.4"]
|
|
9
|
+
|
|
10
|
+
[project.urls]
|
|
11
|
+
Homepage = "https://github.com/stos-technologies/agentcoin"
|
|
12
|
+
Repository = "https://github.com/stos-technologies/agentcoin"
|
|
13
|
+
|
|
14
|
+
[build-system]
|
|
15
|
+
requires = ["hatchling"]
|
|
16
|
+
build-backend = "hatchling.build"
|
|
17
|
+
|
|
18
|
+
[tool.hatch.build.targets.wheel]
|
|
19
|
+
packages = ["src/agentcoin_core"]
|
|
20
|
+
|
|
21
|
+
[tool.hatch.build.targets.sdist]
|
|
22
|
+
exclude = ["/tests", "/.gitignore"]
|
|
23
|
+
|
|
24
|
+
[tool.hatch.build.targets.sdist.force-include]
|
|
25
|
+
"LICENSE" = "LICENSE"
|
|
26
|
+
|
|
27
|
+
[tool.hatch.build.targets.wheel.force-include]
|
|
28
|
+
"LICENSE" = "LICENSE"
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"""AgentCoin core client for Python plugins. Base Sepolia testnet only."""
|
|
2
|
+
from .client import AgentCoin, PayResult, assert_chain_allowed
|
|
3
|
+
from .constants import DEFAULT_AGENTCOIN_URL, agentcoin_url, BASE_SEPOLIA, DEFAULT_MAX_PAYMENT, ESCROW_STATES, MAINNET_CHAIN_IDS
|
|
4
|
+
from .env import as_client, from_env
|
|
5
|
+
from .errors import AgentCoinError
|
|
6
|
+
from .tools import TOOL_NAMES, TOOL_SPECS, run_tool, run_tool_json
|
|
7
|
+
|
|
8
|
+
__all__ = ["AgentCoin", "AgentCoinError", "PayResult", "assert_chain_allowed", "BASE_SEPOLIA", "DEFAULT_AGENTCOIN_URL", "agentcoin_url", "DEFAULT_MAX_PAYMENT", "ESCROW_STATES", "MAINNET_CHAIN_IDS",
|
|
9
|
+
"as_client", "from_env", "TOOL_NAMES", "TOOL_SPECS", "run_tool", "run_tool_json"]
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
"""RFC 8785 canonical JSON, keccak256 over it, and AgentCoin EIP-191 document verification."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import rfc8785
|
|
5
|
+
from eth_account import Account
|
|
6
|
+
from eth_account.messages import encode_defunct
|
|
7
|
+
from eth_utils import keccak, to_checksum_address
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def jcs(v) -> bytes:
|
|
11
|
+
return rfc8785.dumps(v)
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def keccak_jcs(v) -> str:
|
|
15
|
+
return "0x" + keccak(jcs(v)).hex()
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def verify_eip191_document(doc: dict) -> dict:
|
|
19
|
+
"""personal_sign over keccak256(RFC8785(document without "signature"))."""
|
|
20
|
+
s = (doc or {}).get("signature")
|
|
21
|
+
if not isinstance(s, dict) or s.get("scheme") != "eip191":
|
|
22
|
+
return {"valid": False, "reason": "no eip191 signature"}
|
|
23
|
+
unsigned = {k: v for k, v in doc.items() if k != "signature"}
|
|
24
|
+
digest = keccak_jcs(unsigned)
|
|
25
|
+
if s.get("signedDigest") and s["signedDigest"].lower() != digest.lower():
|
|
26
|
+
return {"valid": False, "digest": digest, "reason": "digest mismatch (document modified)"}
|
|
27
|
+
signer = to_checksum_address(s["signer"])
|
|
28
|
+
try:
|
|
29
|
+
rec = Account.recover_message(encode_defunct(primitive=bytes.fromhex(digest[2:])), signature=s["value"])
|
|
30
|
+
except Exception:
|
|
31
|
+
return {"valid": False, "signer": signer, "digest": digest, "reason": "signature does not match signer"}
|
|
32
|
+
ok = to_checksum_address(rec) == signer
|
|
33
|
+
out = {"valid": ok, "signer": signer, "digest": digest}
|
|
34
|
+
if not ok:
|
|
35
|
+
out["reason"] = "signature does not match signer"
|
|
36
|
+
return out
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
"""Minimal EVM access used by the client. Tests inject a fake with the same methods."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from typing import Protocol
|
|
5
|
+
|
|
6
|
+
from eth_utils import to_checksum_address
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class Chain(Protocol):
|
|
10
|
+
def block_timestamp(self) -> int: ...
|
|
11
|
+
def call(self, to: str, data: str, sender: str | None = None) -> bytes: ...
|
|
12
|
+
def send_transaction(self, account, to: str, data: str) -> str: ...
|
|
13
|
+
def wait_receipt(self, tx_hash: str) -> dict: ...
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class Web3Chain:
|
|
17
|
+
"""JSON-RPC chain access via web3.py. Signs locally with the eth_account LocalAccount; never sends keys anywhere."""
|
|
18
|
+
|
|
19
|
+
def __init__(self, rpc_url: str, chain_id: int, timeout: float = 120):
|
|
20
|
+
from web3 import Web3
|
|
21
|
+
|
|
22
|
+
self.w3 = Web3(Web3.HTTPProvider(rpc_url, request_kwargs={"timeout": 30}))
|
|
23
|
+
self.chain_id = chain_id
|
|
24
|
+
self.timeout = timeout
|
|
25
|
+
|
|
26
|
+
def block_timestamp(self) -> int:
|
|
27
|
+
return int(self.w3.eth.get_block("latest")["timestamp"])
|
|
28
|
+
|
|
29
|
+
def call(self, to: str, data: str, sender: str | None = None) -> bytes:
|
|
30
|
+
tx = {"to": to_checksum_address(to), "data": data}
|
|
31
|
+
if sender:
|
|
32
|
+
tx["from"] = to_checksum_address(sender)
|
|
33
|
+
return bytes(self.w3.eth.call(tx))
|
|
34
|
+
|
|
35
|
+
def send_transaction(self, account, to: str, data: str) -> str:
|
|
36
|
+
w3 = self.w3
|
|
37
|
+
tx = {"from": account.address, "to": to_checksum_address(to), "data": data, "value": 0, "chainId": self.chain_id,
|
|
38
|
+
"nonce": w3.eth.get_transaction_count(account.address, "pending")}
|
|
39
|
+
tx["gas"] = int(w3.eth.estimate_gas(tx) * 12 // 10)
|
|
40
|
+
base = w3.eth.get_block("latest").get("baseFeePerGas", 0)
|
|
41
|
+
prio = w3.eth.max_priority_fee
|
|
42
|
+
tx["maxPriorityFeePerGas"] = prio
|
|
43
|
+
tx["maxFeePerGas"] = base * 2 + prio
|
|
44
|
+
signed = account.sign_transaction(tx)
|
|
45
|
+
raw = getattr(signed, "raw_transaction", None) or signed.rawTransaction
|
|
46
|
+
h = w3.eth.send_raw_transaction(raw)
|
|
47
|
+
return "0x" + bytes(h).hex().removeprefix("0x")
|
|
48
|
+
|
|
49
|
+
def wait_receipt(self, tx_hash: str) -> dict:
|
|
50
|
+
rc = self.w3.eth.wait_for_transaction_receipt(tx_hash, timeout=self.timeout)
|
|
51
|
+
hx = lambda b: "0x" + bytes(b).hex().removeprefix("0x")
|
|
52
|
+
return {"status": int(rc["status"]), "logs": [{"address": l["address"], "topics": [hx(t) for t in l["topics"]], "data": hx(l["data"])} for l in rc["logs"]]}
|