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.
@@ -0,0 +1,13 @@
1
+ node_modules/
2
+ dist/
3
+ *.tsbuildinfo
4
+ .venv/
5
+ __pycache__/
6
+ *.pyc
7
+ .pytest_cache/
8
+ out/
9
+ .secrets/
10
+ *.key
11
+ *.pem
12
+ .env
13
+ .env.*
@@ -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"]]}