botsrated 0.3.0__tar.gz → 0.3.1__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.
- {botsrated-0.3.0 → botsrated-0.3.1}/PKG-INFO +25 -10
- {botsrated-0.3.0 → botsrated-0.3.1}/README.md +24 -9
- {botsrated-0.3.0 → botsrated-0.3.1}/pyproject.toml +1 -1
- {botsrated-0.3.0 → botsrated-0.3.1}/src/botsrated/util.py +1 -1
- {botsrated-0.3.0 → botsrated-0.3.1}/.gitignore +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/LICENSE +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/src/botsrated/__init__.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/src/botsrated/client.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/src/botsrated/guard.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/src/botsrated/onchain.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/src/botsrated/payment_guard.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/src/botsrated/py.typed +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/tests/conftest.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/tests/test_c1_no_repay.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/tests/test_guard.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/tests/test_onchain.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/tests/test_payment_guard.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/tests/test_remote_policy.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.1}/tests/test_x402_sdk.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: botsrated
|
|
3
|
-
Version: 0.3.
|
|
3
|
+
Version: 0.3.1
|
|
4
4
|
Summary: Payment guard for x402 agents: checks facts BotsRated measured about a seller before paying (advice-only by default), adds a payment-identifier retry key where supported, and checks on chain, read-only, whether a payment settled once. Not affiliated with Coinbase or the x402 Foundation.
|
|
5
5
|
Project-URL: Homepage, https://botsrated.com
|
|
6
6
|
Project-URL: Repository, https://github.com/botsrated/botsrated
|
|
@@ -19,6 +19,19 @@ Description-Content-Type: text/markdown
|
|
|
19
19
|
|
|
20
20
|
# botsrated (Python)
|
|
21
21
|
|
|
22
|
+
## Install in 3 steps
|
|
23
|
+
|
|
24
|
+
1. Install: `pip install "botsrated[x402]"` (PyPI 0.3.1).
|
|
25
|
+
2. Attach to your x402 client:
|
|
26
|
+
```python
|
|
27
|
+
from botsrated import PaymentGuard
|
|
28
|
+
guard = PaymentGuard(preset="carefulBuyer")
|
|
29
|
+
guard.install(client)
|
|
30
|
+
```
|
|
31
|
+
3. Pick `preset` (omit it, or call `PaymentGuard()`, for advice only; `carefulBuyer` / `strict` stop an unobserved payTo). Omit `fail_mode` inside `remote_policy` to stay open. `"closed"` stops the payment when BotsRated or your policy cannot answer. A missing decision is never a pass. A remote pass never clears a local block. Wrap the paying call with `guard.wrap_get` / `guard.wrap_async_get` so the guard knows the paid URL.
|
|
32
|
+
|
|
33
|
+
`BOTSRATED_TOKEN` is optional. Framework attaches read it when `token` is omitted and send it only as `remote_policy` on botsrated 0.3.0 and later, never as a bare string. A configured token on a core without `parse_remote_policy` raises and is not dropped. The policy decision is not signed. Get a token in [Desk](https://botsrated.com/desk). Nothing defaults you to closed.
|
|
34
|
+
|
|
22
35
|
The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment check.
|
|
23
36
|
|
|
24
37
|
- **Before your agent signs**, it looks up facts [BotsRated](https://botsrated.com) measured about the seller's host
|
|
@@ -30,7 +43,7 @@ The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment che
|
|
|
30
43
|
|
|
31
44
|
It lowers the chance of paying the wrong address or paying twice; it can't rule either out.
|
|
32
45
|
|
|
33
|
-
**Status: published on PyPI as [`botsrated` 0.
|
|
46
|
+
**Status: published on PyPI as [`botsrated` 0.3.1](https://pypi.org/project/botsrated/)** (this release; includes `remote_policy`).
|
|
34
47
|
|
|
35
48
|
**What this does and doesn't do.** This package checks facts BotsRated measured about a seller before your agent signs, adds a retry key to the payment request, and reads the blockchain to see whether a payment already settled. It can't promise that a payment is right, that a seller will deliver, or that you'll never pay twice: a retry key only stops a second charge if the seller supports the x402 `payment-identifier` extension, and on-chain reads can be late or fail. You choose the rules that stop a payment, and you remain responsible for what your agent pays. Provided under the MIT license, "as is", without warranty.
|
|
36
49
|
|
|
@@ -48,7 +61,7 @@ uses the hook and extension points of the x402 client you pass in.
|
|
|
48
61
|
## Payment Guard: Pick A Preset
|
|
49
62
|
|
|
50
63
|
You set the thresholds. The guard compares the payment with facts BotsRated measured and, when the preflight included
|
|
51
|
-
one, a receipt link.
|
|
64
|
+
one, a receipt link.
|
|
52
65
|
|
|
53
66
|
Pick a named preset. The zero-config call (`PaymentGuard()`) is `warn`: advice only, it never stops a payment.
|
|
54
67
|
Dry-run is optional: it logs `would_block` and still never stops a payment.
|
|
@@ -127,7 +140,7 @@ never echoed except a parsed host name.
|
|
|
127
140
|
|
|
128
141
|
### Facts Bundle
|
|
129
142
|
|
|
130
|
-
`decision.facts` is the bundle the guard compared. It is measurements plus a receipt link.
|
|
143
|
+
`decision.facts` is the bundle the guard compared. It is measurements plus a receipt link.
|
|
131
144
|
|
|
132
145
|
| Field | What it is |
|
|
133
146
|
|---|---|
|
|
@@ -145,7 +158,7 @@ https://botsrated.com/disputes. `would_block` is true when a rule's effect is `b
|
|
|
145
158
|
`action` stays `allow`.
|
|
146
159
|
|
|
147
160
|
The hosted preflight body is larger (see the MCP facts bundle in the repository README). The guard keeps this
|
|
148
|
-
smaller local bundle and does not
|
|
161
|
+
smaller local bundle and does not add a summary number, because the response has none.
|
|
149
162
|
|
|
150
163
|
### Options
|
|
151
164
|
|
|
@@ -181,11 +194,13 @@ This is the path that makes `BOTSRATED_TOKEN` work in framework attaches. The to
|
|
|
181
194
|
```python
|
|
182
195
|
guard = PaymentGuard(
|
|
183
196
|
preset="carefulBuyer",
|
|
184
|
-
remote_policy={"token": "<bearer>", "fail_mode": "
|
|
197
|
+
remote_policy={"token": "<bearer>", "fail_mode": "open"}, # omit fail_mode for open; "closed" is opt-in
|
|
185
198
|
)
|
|
186
199
|
```
|
|
187
200
|
|
|
188
|
-
`fail_mode` is yours: `open` or `closed`. The guard `POST`s `/v1/policy/check` with the seller host and the quote (`payTo`, `amount`, `asset`, `network`). On HTTP 503, HTTP 404, or `"decision": null`, it applies `fail_mode` (`open`: an info reason, payment continues unless a local rule stops it; `closed`: the payment stops).
|
|
201
|
+
`fail_mode` is yours: `open` or `closed`. Omit it and the check stays open. Nothing defaults you to closed. `"closed"` stops the payment when BotsRated or your policy cannot answer. The guard `POST`s `/v1/policy/check` with the seller host and the quote (`payTo`, `amount`, `asset`, `network`). On HTTP 503, HTTP 404, or `"decision": null`, it applies `fail_mode` (`open`: an info reason, payment continues unless a local rule stops it; `closed`: the payment stops). A missing decision is never a pass. A remote pass never clears a local block. Server fields are kept when the server sends them. The last `policy_version` is remembered on the guard. The policy decision is not signed. Leave `remote_policy` unset and local presets behave as before.
|
|
202
|
+
|
|
203
|
+
`BOTSRATED_TOKEN` is optional. Framework attaches read it when `token` is omitted and send it only as `remote_policy` on botsrated 0.3.0 and later. A configured token on a core without `parse_remote_policy` raises and is not dropped. Get a token in [Desk](https://botsrated.com/desk).
|
|
189
204
|
|
|
190
205
|
### What The Guard Sends, And To Whom
|
|
191
206
|
|
|
@@ -224,7 +239,7 @@ state = guard.payment_state(rec) # or: await guard.apayment_state(rec). Re
|
|
|
224
239
|
|
|
225
240
|
There are three answers only:
|
|
226
241
|
|
|
227
|
-
- `settled`: two RPCs on different hosts (or two of three, see below) show the EIP-3009 authorization used at Base's
|
|
242
|
+
- `settled`: two RPCs on different hosts (or two of three, see below) show the EIP-3009 authorization used at Base's default confirmation tag,
|
|
228
243
|
the chain id is 8453, and the transaction receipt has `AuthorizationUsed(from, nonce)` and
|
|
229
244
|
`Transfer(from, payTo, amount)` emitted by the pinned USDC contract `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.
|
|
230
245
|
- `unknown` (`payment_state_unknown`) with `wait_until`: not settled yet, the RPCs disagree or failed, the blocks
|
|
@@ -232,7 +247,7 @@ There are three answers only:
|
|
|
232
247
|
checked. **Do not sign a new payment for that purchase before `wait_until`** (the signed authorization stays
|
|
233
248
|
valid until its `validBefore`, plus a margin of at least 30 s).
|
|
234
249
|
- `expired_unsettled`: `validBefore` plus the margin has passed on the clock **and** in the chain: both RPCs show
|
|
235
|
-
the authorization unused at a block (Base's
|
|
250
|
+
the authorization unused at a block (Base's default confirmation tag) whose timestamp is at or after `validBefore`
|
|
236
251
|
plus the margin. USDC accepts an authorization in any block before `validBefore`, so "unused" only counts in a
|
|
237
252
|
later block. With the default 60 s margin this is usually 1 to 3 minutes after expiry. Only then is a fresh
|
|
238
253
|
payment free of a double-charge risk from the first one.
|
|
@@ -243,7 +258,7 @@ It is clamped, not rejected: a value below 30 (including negative values and `-i
|
|
|
243
258
|
`expiry_tag="finalized"` waits for a finalized block past expiry instead (more conservative, usually 20+ minutes).
|
|
244
259
|
|
|
245
260
|
The guard never retries on `unknown`. botsrated.com is never asked; a tx hash the seller reports is only a hint
|
|
246
|
-
that is
|
|
261
|
+
that is checked on chain.
|
|
247
262
|
|
|
248
263
|
**Default RPCs** (two operators; both must answer and agree):
|
|
249
264
|
|
|
@@ -1,5 +1,18 @@
|
|
|
1
1
|
# botsrated (Python)
|
|
2
2
|
|
|
3
|
+
## Install in 3 steps
|
|
4
|
+
|
|
5
|
+
1. Install: `pip install "botsrated[x402]"` (PyPI 0.3.1).
|
|
6
|
+
2. Attach to your x402 client:
|
|
7
|
+
```python
|
|
8
|
+
from botsrated import PaymentGuard
|
|
9
|
+
guard = PaymentGuard(preset="carefulBuyer")
|
|
10
|
+
guard.install(client)
|
|
11
|
+
```
|
|
12
|
+
3. Pick `preset` (omit it, or call `PaymentGuard()`, for advice only; `carefulBuyer` / `strict` stop an unobserved payTo). Omit `fail_mode` inside `remote_policy` to stay open. `"closed"` stops the payment when BotsRated or your policy cannot answer. A missing decision is never a pass. A remote pass never clears a local block. Wrap the paying call with `guard.wrap_get` / `guard.wrap_async_get` so the guard knows the paid URL.
|
|
13
|
+
|
|
14
|
+
`BOTSRATED_TOKEN` is optional. Framework attaches read it when `token` is omitted and send it only as `remote_policy` on botsrated 0.3.0 and later, never as a bare string. A configured token on a core without `parse_remote_policy` raises and is not dropped. The policy decision is not signed. Get a token in [Desk](https://botsrated.com/desk). Nothing defaults you to closed.
|
|
15
|
+
|
|
3
16
|
The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment check.
|
|
4
17
|
|
|
5
18
|
- **Before your agent signs**, it looks up facts [BotsRated](https://botsrated.com) measured about the seller's host
|
|
@@ -11,7 +24,7 @@ The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment che
|
|
|
11
24
|
|
|
12
25
|
It lowers the chance of paying the wrong address or paying twice; it can't rule either out.
|
|
13
26
|
|
|
14
|
-
**Status: published on PyPI as [`botsrated` 0.
|
|
27
|
+
**Status: published on PyPI as [`botsrated` 0.3.1](https://pypi.org/project/botsrated/)** (this release; includes `remote_policy`).
|
|
15
28
|
|
|
16
29
|
**What this does and doesn't do.** This package checks facts BotsRated measured about a seller before your agent signs, adds a retry key to the payment request, and reads the blockchain to see whether a payment already settled. It can't promise that a payment is right, that a seller will deliver, or that you'll never pay twice: a retry key only stops a second charge if the seller supports the x402 `payment-identifier` extension, and on-chain reads can be late or fail. You choose the rules that stop a payment, and you remain responsible for what your agent pays. Provided under the MIT license, "as is", without warranty.
|
|
17
30
|
|
|
@@ -29,7 +42,7 @@ uses the hook and extension points of the x402 client you pass in.
|
|
|
29
42
|
## Payment Guard: Pick A Preset
|
|
30
43
|
|
|
31
44
|
You set the thresholds. The guard compares the payment with facts BotsRated measured and, when the preflight included
|
|
32
|
-
one, a receipt link.
|
|
45
|
+
one, a receipt link.
|
|
33
46
|
|
|
34
47
|
Pick a named preset. The zero-config call (`PaymentGuard()`) is `warn`: advice only, it never stops a payment.
|
|
35
48
|
Dry-run is optional: it logs `would_block` and still never stops a payment.
|
|
@@ -108,7 +121,7 @@ never echoed except a parsed host name.
|
|
|
108
121
|
|
|
109
122
|
### Facts Bundle
|
|
110
123
|
|
|
111
|
-
`decision.facts` is the bundle the guard compared. It is measurements plus a receipt link.
|
|
124
|
+
`decision.facts` is the bundle the guard compared. It is measurements plus a receipt link.
|
|
112
125
|
|
|
113
126
|
| Field | What it is |
|
|
114
127
|
|---|---|
|
|
@@ -126,7 +139,7 @@ https://botsrated.com/disputes. `would_block` is true when a rule's effect is `b
|
|
|
126
139
|
`action` stays `allow`.
|
|
127
140
|
|
|
128
141
|
The hosted preflight body is larger (see the MCP facts bundle in the repository README). The guard keeps this
|
|
129
|
-
smaller local bundle and does not
|
|
142
|
+
smaller local bundle and does not add a summary number, because the response has none.
|
|
130
143
|
|
|
131
144
|
### Options
|
|
132
145
|
|
|
@@ -162,11 +175,13 @@ This is the path that makes `BOTSRATED_TOKEN` work in framework attaches. The to
|
|
|
162
175
|
```python
|
|
163
176
|
guard = PaymentGuard(
|
|
164
177
|
preset="carefulBuyer",
|
|
165
|
-
remote_policy={"token": "<bearer>", "fail_mode": "
|
|
178
|
+
remote_policy={"token": "<bearer>", "fail_mode": "open"}, # omit fail_mode for open; "closed" is opt-in
|
|
166
179
|
)
|
|
167
180
|
```
|
|
168
181
|
|
|
169
|
-
`fail_mode` is yours: `open` or `closed`. The guard `POST`s `/v1/policy/check` with the seller host and the quote (`payTo`, `amount`, `asset`, `network`). On HTTP 503, HTTP 404, or `"decision": null`, it applies `fail_mode` (`open`: an info reason, payment continues unless a local rule stops it; `closed`: the payment stops).
|
|
182
|
+
`fail_mode` is yours: `open` or `closed`. Omit it and the check stays open. Nothing defaults you to closed. `"closed"` stops the payment when BotsRated or your policy cannot answer. The guard `POST`s `/v1/policy/check` with the seller host and the quote (`payTo`, `amount`, `asset`, `network`). On HTTP 503, HTTP 404, or `"decision": null`, it applies `fail_mode` (`open`: an info reason, payment continues unless a local rule stops it; `closed`: the payment stops). A missing decision is never a pass. A remote pass never clears a local block. Server fields are kept when the server sends them. The last `policy_version` is remembered on the guard. The policy decision is not signed. Leave `remote_policy` unset and local presets behave as before.
|
|
183
|
+
|
|
184
|
+
`BOTSRATED_TOKEN` is optional. Framework attaches read it when `token` is omitted and send it only as `remote_policy` on botsrated 0.3.0 and later. A configured token on a core without `parse_remote_policy` raises and is not dropped. Get a token in [Desk](https://botsrated.com/desk).
|
|
170
185
|
|
|
171
186
|
### What The Guard Sends, And To Whom
|
|
172
187
|
|
|
@@ -205,7 +220,7 @@ state = guard.payment_state(rec) # or: await guard.apayment_state(rec). Re
|
|
|
205
220
|
|
|
206
221
|
There are three answers only:
|
|
207
222
|
|
|
208
|
-
- `settled`: two RPCs on different hosts (or two of three, see below) show the EIP-3009 authorization used at Base's
|
|
223
|
+
- `settled`: two RPCs on different hosts (or two of three, see below) show the EIP-3009 authorization used at Base's default confirmation tag,
|
|
209
224
|
the chain id is 8453, and the transaction receipt has `AuthorizationUsed(from, nonce)` and
|
|
210
225
|
`Transfer(from, payTo, amount)` emitted by the pinned USDC contract `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.
|
|
211
226
|
- `unknown` (`payment_state_unknown`) with `wait_until`: not settled yet, the RPCs disagree or failed, the blocks
|
|
@@ -213,7 +228,7 @@ There are three answers only:
|
|
|
213
228
|
checked. **Do not sign a new payment for that purchase before `wait_until`** (the signed authorization stays
|
|
214
229
|
valid until its `validBefore`, plus a margin of at least 30 s).
|
|
215
230
|
- `expired_unsettled`: `validBefore` plus the margin has passed on the clock **and** in the chain: both RPCs show
|
|
216
|
-
the authorization unused at a block (Base's
|
|
231
|
+
the authorization unused at a block (Base's default confirmation tag) whose timestamp is at or after `validBefore`
|
|
217
232
|
plus the margin. USDC accepts an authorization in any block before `validBefore`, so "unused" only counts in a
|
|
218
233
|
later block. With the default 60 s margin this is usually 1 to 3 minutes after expiry. Only then is a fresh
|
|
219
234
|
payment free of a double-charge risk from the first one.
|
|
@@ -224,7 +239,7 @@ It is clamped, not rejected: a value below 30 (including negative values and `-i
|
|
|
224
239
|
`expiry_tag="finalized"` waits for a finalized block past expiry instead (more conservative, usually 20+ minutes).
|
|
225
240
|
|
|
226
241
|
The guard never retries on `unknown`. botsrated.com is never asked; a tx hash the seller reports is only a hint
|
|
227
|
-
that is
|
|
242
|
+
that is checked on chain.
|
|
228
243
|
|
|
229
244
|
**Default RPCs** (two operators; both must answer and agree):
|
|
230
245
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "botsrated"
|
|
3
|
-
version = "0.3.
|
|
3
|
+
version = "0.3.1"
|
|
4
4
|
description = "Payment guard for x402 agents: checks facts BotsRated measured about a seller before paying (advice-only by default), adds a payment-identifier retry key where supported, and checks on chain, read-only, whether a payment settled once. Not affiliated with Coinbase or the x402 Foundation."
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = "MIT"
|
|
@@ -6,7 +6,7 @@ import re
|
|
|
6
6
|
from typing import Any
|
|
7
7
|
from urllib.parse import urlsplit
|
|
8
8
|
|
|
9
|
-
VERSION = "0.3.
|
|
9
|
+
VERSION = "0.3.1"
|
|
10
10
|
# Sent on hosted BotsRated calls. No install id, wallet or other user identifier.
|
|
11
11
|
USER_AGENT = f"botsrated-python/{VERSION}"
|
|
12
12
|
BOTSRATED_BASE_URL = "https://botsrated.com"
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|