botsrated 0.3.0__tar.gz → 0.3.2__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.2}/PKG-INFO +47 -15
- {botsrated-0.3.0 → botsrated-0.3.2}/README.md +46 -14
- {botsrated-0.3.0 → botsrated-0.3.2}/pyproject.toml +1 -1
- {botsrated-0.3.0 → botsrated-0.3.2}/src/botsrated/guard.py +179 -24
- botsrated-0.3.2/src/botsrated/guard_checks.py +560 -0
- {botsrated-0.3.0 → botsrated-0.3.2}/src/botsrated/payment_guard.py +350 -43
- {botsrated-0.3.0 → botsrated-0.3.2}/src/botsrated/util.py +109 -1
- {botsrated-0.3.0 → botsrated-0.3.2}/tests/conftest.py +11 -0
- {botsrated-0.3.0 → botsrated-0.3.2}/tests/test_c1_no_repay.py +2 -2
- botsrated-0.3.2/tests/test_guard_checks.py +581 -0
- botsrated-0.3.2/tests/test_hosted_circuit.py +297 -0
- {botsrated-0.3.0 → botsrated-0.3.2}/tests/test_remote_policy.py +7 -1
- {botsrated-0.3.0 → botsrated-0.3.2}/.gitignore +0 -0
- {botsrated-0.3.0 → botsrated-0.3.2}/LICENSE +0 -0
- {botsrated-0.3.0 → botsrated-0.3.2}/src/botsrated/__init__.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.2}/src/botsrated/client.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.2}/src/botsrated/onchain.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.2}/src/botsrated/py.typed +0 -0
- {botsrated-0.3.0 → botsrated-0.3.2}/tests/test_guard.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.2}/tests/test_onchain.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.2}/tests/test_payment_guard.py +0 -0
- {botsrated-0.3.0 → botsrated-0.3.2}/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.2
|
|
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,22 @@ 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]"` (this tree is 0.3.2; PyPI still serves 0.3.1 until a later publish).
|
|
25
|
+
2. Attach to your x402 client (omit `preset` for advice only; omit `fail_mode` to stay open):
|
|
26
|
+
```python
|
|
27
|
+
from botsrated import PaymentGuard
|
|
28
|
+
guard = PaymentGuard() # omit preset = advice; omit fail_mode = open
|
|
29
|
+
guard.install(x402_client)
|
|
30
|
+
paid_get = guard.wrap_get(session.get) # or guard.wrap_async_get(http.get)
|
|
31
|
+
```
|
|
32
|
+
3. Omit `preset`, or call `PaymentGuard()`, for advice only. That never stops a payment. Pick `preset="carefulBuyer"` only when you want it (same stops as `POLICIES["strict"]`; stops an unobserved payTo). `strict` is not a preset name. 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.
|
|
33
|
+
|
|
34
|
+
Same paste in TypeScript / JS, Python, and curl (curl reads free preflight facts and does not attach): [`docs/guard/copy-paste-attach.md`](../../docs/guard/copy-paste-attach.md).
|
|
35
|
+
|
|
36
|
+
`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.
|
|
37
|
+
|
|
22
38
|
The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment check.
|
|
23
39
|
|
|
24
40
|
- **Before your agent signs**, it looks up facts [BotsRated](https://botsrated.com) measured about the seller's host
|
|
@@ -30,7 +46,7 @@ The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment che
|
|
|
30
46
|
|
|
31
47
|
It lowers the chance of paying the wrong address or paying twice; it can't rule either out.
|
|
32
48
|
|
|
33
|
-
**Status: published
|
|
49
|
+
**Status: source version 0.3.2 in this repo. Not published.** PyPI still serves [`botsrated` 0.3.1](https://pypi.org/project/botsrated/). 0.3.2 adds `repeat_payment`, `delivery_check`, `payto_base58_format`, and `quote_above_listing`. Each warns by default. None of them is a new default block. `replay_tested` stays false.
|
|
34
50
|
|
|
35
51
|
**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
52
|
|
|
@@ -48,16 +64,16 @@ uses the hook and extension points of the x402 client you pass in.
|
|
|
48
64
|
## Payment Guard: Pick A Preset
|
|
49
65
|
|
|
50
66
|
You set the thresholds. The guard compares the payment with facts BotsRated measured and, when the preflight included
|
|
51
|
-
one, a receipt link.
|
|
67
|
+
one, a receipt link.
|
|
52
68
|
|
|
53
|
-
Pick a named preset. The zero-config call (`PaymentGuard()`) is `warn`: advice only, it never stops a payment.
|
|
69
|
+
Pick a named preset. Preset keys are `warn`, `carefulBuyer`, and `dry-run-only`. `strict` is not a preset key; it is `POLICIES["strict"]`. The zero-config call (`PaymentGuard()`) is `warn`: advice only, it never stops a payment.
|
|
54
70
|
Dry-run is optional: it logs `would_block` and still never stops a payment.
|
|
55
71
|
|
|
56
72
|
| Name | How to select it | What you get |
|
|
57
73
|
|---|---|---|
|
|
58
74
|
| `warn` | `PaymentGuard()` or `preset="warn"` or `policy=POLICIES["warn"]` | Advice only. The default. |
|
|
59
75
|
| `carefulBuyer` | `preset="carefulBuyer"` or `policy=POLICIES["carefulBuyer"]` | Same rule effects as `POLICIES["strict"]`. Stops when the payTo wasn't observed, is invalid, the host mismatches, or the paid URL is unknown. |
|
|
60
|
-
| `strict` | `policy=POLICIES["strict"]` | The same stops as `carefulBuyer`. |
|
|
76
|
+
| `POLICIES["strict"]` | `policy=POLICIES["strict"]` | The same stops as `carefulBuyer`. Not a preset. |
|
|
61
77
|
| `dry-run-only` | `dry_run_only(...)`, `preset="dry-run-only"`, or `PaymentGuard(**PRESETS["dry-run-only"])` | Logs `would_block` and never stops a payment. No retry key. `preset="dry-run-only"` and `dry_run_only()` force dry-run. |
|
|
62
78
|
|
|
63
79
|
```python
|
|
@@ -109,10 +125,14 @@ A stopped payment raises the x402 abort error with text like:
|
|
|
109
125
|
| Rule (`PaymentGuardPolicy(...)`) | Reason code | `POLICIES["warn"]` (default) | `POLICIES["carefulBuyer"]` / `POLICIES["strict"]` |
|
|
110
126
|
|---|---|---|---|
|
|
111
127
|
| `pay_to_mismatch`: the payTo is not among the payTos BotsRated's probes recorded for the host | `payto_not_observed` | warn | **block** |
|
|
112
|
-
| `pay_to_invalid`: the payTo is not a 20-byte hex address | `payto_invalid` | warn | **block** |
|
|
128
|
+
| `pay_to_invalid`: the payTo is not a 20-byte hex address on `eip155` or v1 `base`. A Solana payTo that is not a base58 32-byte public key is `payto_base58_format`, not this code | `payto_invalid` | warn | **block** |
|
|
113
129
|
| `resource_host_mismatch`: the 402's `resource.url` names another host than the URL being paid (checked locally) | `resource_host_mismatch` | warn | **block** |
|
|
114
130
|
| `paid_url_unknown`: the URL being paid is unknown (no `wrap_get` / `guard.request(url)`), so the only host is the 402's own claim | `paid_url_unknown` | warn | **block** |
|
|
115
131
|
| `price_above_observed`: same route, amount above the last amount BotsRated recorded (compared locally) | `price_above_observed` | warn | warn |
|
|
132
|
+
| `quote_above_listing`: same route, amount above the listed amount. A server policy reason with this code uses the same effect | `quote_above_listing` | warn | warn |
|
|
133
|
+
| `repeat_payment`: the same payment identifier, or the same host, route, amount and nonce, repeats within 60 seconds. Local only. `replay_tested` stays false | `repeat_payment` | warn | warn |
|
|
134
|
+
| `pay_to_base58_format`: a Solana payTo is not a base58 32-byte public key. A Base payTo is not judged. The Base USDC rule is unchanged | `payto_base58_format` | warn | warn |
|
|
135
|
+
| After payment, on `wrap_get` / `wrap_async_get`, once a payload was created: a 2xx is not a delivery unless the body is non-empty, the content type is one this check accepts (`application/json`, `application/problem+json`, `text/plain`, `text/json`, or a `+json` type), and a JSON schema the seller declared matches. This check does not block | `delivery_check` | warn | warn |
|
|
116
136
|
| `not_covered`: BotsRated has no probe record for the host | `not_covered` | info | info |
|
|
117
137
|
| `stale`: BotsRated's latest probe is older than 24 h | `data_stale` | info | info |
|
|
118
138
|
| BotsRated unreachable (3 s timeout) | `botsrated_unreachable` | info (`fail_open=True`) | info unless `fail_open=False` |
|
|
@@ -127,7 +147,7 @@ never echoed except a parsed host name.
|
|
|
127
147
|
|
|
128
148
|
### Facts Bundle
|
|
129
149
|
|
|
130
|
-
`decision.facts` is the bundle the guard compared. It is measurements plus a receipt link.
|
|
150
|
+
`decision.facts` is the bundle the guard compared. It is measurements plus a receipt link.
|
|
131
151
|
|
|
132
152
|
| Field | What it is |
|
|
133
153
|
|---|---|
|
|
@@ -145,7 +165,7 @@ https://botsrated.com/disputes. `would_block` is true when a rule's effect is `b
|
|
|
145
165
|
`action` stays `allow`.
|
|
146
166
|
|
|
147
167
|
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
|
|
168
|
+
smaller local bundle and does not add a summary number, because the response has none.
|
|
149
169
|
|
|
150
170
|
### Options
|
|
151
171
|
|
|
@@ -158,7 +178,7 @@ smaller local bundle and does not copy a score out of it, because the response h
|
|
|
158
178
|
| `fail_open` | `True` | `False`: stop the payment when BotsRated can't be reached or the guard errors |
|
|
159
179
|
| `retry_key` | `True` | Add a `payment-identifier` id where the seller advertises it |
|
|
160
180
|
| `onchain` | default RPCs | RPC settings for `payment_state` (`rpcs`, `extra_rpc`, `margin_seconds`, `expiry_tag`, `confirm_tag`), or `False` |
|
|
161
|
-
| `timeout` / `cache_ttl` | 3 s / 5 min | Hosted lookup timeout and per-host cache |
|
|
181
|
+
| `timeout` / `cache_ttl` | 3 s / 5 min | Hosted lookup timeout, clamped to 10 s, and per-host cache |
|
|
162
182
|
| `preflight` | hosted call | Your own lookup `(host) -> (found, body)` |
|
|
163
183
|
| `on_decision` | none | Receives every decision (errors in it are ignored) |
|
|
164
184
|
| `remote_policy` | unset | Private policy check. See below. Unset: local presets only |
|
|
@@ -167,7 +187,9 @@ smaller local bundle and does not copy a score out of it, because the response h
|
|
|
167
187
|
|
|
168
188
|
- **Fail-open (default):** if botsrated.com is down or slow, or the guard itself hits an error, the payment goes
|
|
169
189
|
ahead and the decision says `botsrated_unreachable` (or `hook_error`). Our outage never stops your agent, but
|
|
170
|
-
during an outage you get no seller facts.
|
|
190
|
+
during an outage you get no seller facts. HTTP 503, HTTP 429 and a timeout are that miss: the guard reads
|
|
191
|
+
`Retry-After` (or waits 5 s, at most 60 s) and skips further hosted lookups in the process until then.
|
|
192
|
+
A skipped lookup is not a pass. A fresh cached success is still used.
|
|
171
193
|
- **Fail-closed (`fail_open=False`):** the same cases stop the payment. Use it only if an unchecked payment is worse
|
|
172
194
|
for you than a missed call.
|
|
173
195
|
- Local checks (`resource_host_mismatch`, `payto_invalid`) and the on-chain check never depend on botsrated.com.
|
|
@@ -181,11 +203,21 @@ This is the path that makes `BOTSRATED_TOKEN` work in framework attaches. The to
|
|
|
181
203
|
```python
|
|
182
204
|
guard = PaymentGuard(
|
|
183
205
|
preset="carefulBuyer",
|
|
184
|
-
remote_policy={"token": "<bearer>", "fail_mode": "
|
|
206
|
+
remote_policy={"token": "<bearer>", "fail_mode": "open"}, # omit fail_mode for open; "closed" is opt-in
|
|
185
207
|
)
|
|
186
208
|
```
|
|
187
209
|
|
|
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).
|
|
210
|
+
`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 429, HTTP 404, a timeout, or `"decision": null`, it applies `fail_mode` (`open`: an info reason, payment continues unless a local rule stops it; `closed`: the payment stops). A 503, 429 or timeout also opens the in-process circuit above, and the next hosted lookup is skipped. 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.
|
|
211
|
+
|
|
212
|
+
`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).
|
|
213
|
+
|
|
214
|
+
**Save a policy first.** `remote_policy` only checks; it never saves. With no saved policy every check answers `404 no_policy_saved`, and the guard applies your `fail_mode` (`closed` stops every payment). Start from a private pack (`none`, `warn`, `careful-buyer`, `strict`; list at `GET https://botsrated.com/v1/policy/packs`), then `PUT /v1/policy` with your token, or use [Desk → Policy](https://botsrated.com/desk/policy). The smallest one is `none` (only the two always-on checks):
|
|
215
|
+
|
|
216
|
+
```bash
|
|
217
|
+
curl -X PUT https://botsrated.com/v1/policy -H "Authorization: Bearer $BOTSRATED_TOKEN" -H "Content-Type: application/json" -d '{"preset":"none","fail_mode":"open"}'
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
`fail_mode` in that body is yours to pick (`open` or `closed`). The token needs `policy-write` (a paid-plan `brs_` token, or a `brk_` org key with that scope). Server pack names (`careful-buyer`) are your saved server rules. The local `preset` (`carefulBuyer`) is a separate client table. They don't have to match.
|
|
189
221
|
|
|
190
222
|
### What The Guard Sends, And To Whom
|
|
191
223
|
|
|
@@ -224,7 +256,7 @@ state = guard.payment_state(rec) # or: await guard.apayment_state(rec). Re
|
|
|
224
256
|
|
|
225
257
|
There are three answers only:
|
|
226
258
|
|
|
227
|
-
- `settled`: two RPCs on different hosts (or two of three, see below) show the EIP-3009 authorization used at Base's
|
|
259
|
+
- `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
260
|
the chain id is 8453, and the transaction receipt has `AuthorizationUsed(from, nonce)` and
|
|
229
261
|
`Transfer(from, payTo, amount)` emitted by the pinned USDC contract `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.
|
|
230
262
|
- `unknown` (`payment_state_unknown`) with `wait_until`: not settled yet, the RPCs disagree or failed, the blocks
|
|
@@ -232,7 +264,7 @@ There are three answers only:
|
|
|
232
264
|
checked. **Do not sign a new payment for that purchase before `wait_until`** (the signed authorization stays
|
|
233
265
|
valid until its `validBefore`, plus a margin of at least 30 s).
|
|
234
266
|
- `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
|
|
267
|
+
the authorization unused at a block (Base's default confirmation tag) whose timestamp is at or after `validBefore`
|
|
236
268
|
plus the margin. USDC accepts an authorization in any block before `validBefore`, so "unused" only counts in a
|
|
237
269
|
later block. With the default 60 s margin this is usually 1 to 3 minutes after expiry. Only then is a fresh
|
|
238
270
|
payment free of a double-charge risk from the first one.
|
|
@@ -243,7 +275,7 @@ It is clamped, not rejected: a value below 30 (including negative values and `-i
|
|
|
243
275
|
`expiry_tag="finalized"` waits for a finalized block past expiry instead (more conservative, usually 20+ minutes).
|
|
244
276
|
|
|
245
277
|
The guard never retries on `unknown`. botsrated.com is never asked; a tx hash the seller reports is only a hint
|
|
246
|
-
that is
|
|
278
|
+
that is checked on chain.
|
|
247
279
|
|
|
248
280
|
**Default RPCs** (two operators; both must answer and agree):
|
|
249
281
|
|
|
@@ -1,5 +1,21 @@
|
|
|
1
1
|
# botsrated (Python)
|
|
2
2
|
|
|
3
|
+
## Install in 3 steps
|
|
4
|
+
|
|
5
|
+
1. Install: `pip install "botsrated[x402]"` (this tree is 0.3.2; PyPI still serves 0.3.1 until a later publish).
|
|
6
|
+
2. Attach to your x402 client (omit `preset` for advice only; omit `fail_mode` to stay open):
|
|
7
|
+
```python
|
|
8
|
+
from botsrated import PaymentGuard
|
|
9
|
+
guard = PaymentGuard() # omit preset = advice; omit fail_mode = open
|
|
10
|
+
guard.install(x402_client)
|
|
11
|
+
paid_get = guard.wrap_get(session.get) # or guard.wrap_async_get(http.get)
|
|
12
|
+
```
|
|
13
|
+
3. Omit `preset`, or call `PaymentGuard()`, for advice only. That never stops a payment. Pick `preset="carefulBuyer"` only when you want it (same stops as `POLICIES["strict"]`; stops an unobserved payTo). `strict` is not a preset name. 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.
|
|
14
|
+
|
|
15
|
+
Same paste in TypeScript / JS, Python, and curl (curl reads free preflight facts and does not attach): [`docs/guard/copy-paste-attach.md`](../../docs/guard/copy-paste-attach.md).
|
|
16
|
+
|
|
17
|
+
`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.
|
|
18
|
+
|
|
3
19
|
The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment check.
|
|
4
20
|
|
|
5
21
|
- **Before your agent signs**, it looks up facts [BotsRated](https://botsrated.com) measured about the seller's host
|
|
@@ -11,7 +27,7 @@ The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment che
|
|
|
11
27
|
|
|
12
28
|
It lowers the chance of paying the wrong address or paying twice; it can't rule either out.
|
|
13
29
|
|
|
14
|
-
**Status: published
|
|
30
|
+
**Status: source version 0.3.2 in this repo. Not published.** PyPI still serves [`botsrated` 0.3.1](https://pypi.org/project/botsrated/). 0.3.2 adds `repeat_payment`, `delivery_check`, `payto_base58_format`, and `quote_above_listing`. Each warns by default. None of them is a new default block. `replay_tested` stays false.
|
|
15
31
|
|
|
16
32
|
**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
33
|
|
|
@@ -29,16 +45,16 @@ uses the hook and extension points of the x402 client you pass in.
|
|
|
29
45
|
## Payment Guard: Pick A Preset
|
|
30
46
|
|
|
31
47
|
You set the thresholds. The guard compares the payment with facts BotsRated measured and, when the preflight included
|
|
32
|
-
one, a receipt link.
|
|
48
|
+
one, a receipt link.
|
|
33
49
|
|
|
34
|
-
Pick a named preset. The zero-config call (`PaymentGuard()`) is `warn`: advice only, it never stops a payment.
|
|
50
|
+
Pick a named preset. Preset keys are `warn`, `carefulBuyer`, and `dry-run-only`. `strict` is not a preset key; it is `POLICIES["strict"]`. The zero-config call (`PaymentGuard()`) is `warn`: advice only, it never stops a payment.
|
|
35
51
|
Dry-run is optional: it logs `would_block` and still never stops a payment.
|
|
36
52
|
|
|
37
53
|
| Name | How to select it | What you get |
|
|
38
54
|
|---|---|---|
|
|
39
55
|
| `warn` | `PaymentGuard()` or `preset="warn"` or `policy=POLICIES["warn"]` | Advice only. The default. |
|
|
40
56
|
| `carefulBuyer` | `preset="carefulBuyer"` or `policy=POLICIES["carefulBuyer"]` | Same rule effects as `POLICIES["strict"]`. Stops when the payTo wasn't observed, is invalid, the host mismatches, or the paid URL is unknown. |
|
|
41
|
-
| `strict` | `policy=POLICIES["strict"]` | The same stops as `carefulBuyer`. |
|
|
57
|
+
| `POLICIES["strict"]` | `policy=POLICIES["strict"]` | The same stops as `carefulBuyer`. Not a preset. |
|
|
42
58
|
| `dry-run-only` | `dry_run_only(...)`, `preset="dry-run-only"`, or `PaymentGuard(**PRESETS["dry-run-only"])` | Logs `would_block` and never stops a payment. No retry key. `preset="dry-run-only"` and `dry_run_only()` force dry-run. |
|
|
43
59
|
|
|
44
60
|
```python
|
|
@@ -90,10 +106,14 @@ A stopped payment raises the x402 abort error with text like:
|
|
|
90
106
|
| Rule (`PaymentGuardPolicy(...)`) | Reason code | `POLICIES["warn"]` (default) | `POLICIES["carefulBuyer"]` / `POLICIES["strict"]` |
|
|
91
107
|
|---|---|---|---|
|
|
92
108
|
| `pay_to_mismatch`: the payTo is not among the payTos BotsRated's probes recorded for the host | `payto_not_observed` | warn | **block** |
|
|
93
|
-
| `pay_to_invalid`: the payTo is not a 20-byte hex address | `payto_invalid` | warn | **block** |
|
|
109
|
+
| `pay_to_invalid`: the payTo is not a 20-byte hex address on `eip155` or v1 `base`. A Solana payTo that is not a base58 32-byte public key is `payto_base58_format`, not this code | `payto_invalid` | warn | **block** |
|
|
94
110
|
| `resource_host_mismatch`: the 402's `resource.url` names another host than the URL being paid (checked locally) | `resource_host_mismatch` | warn | **block** |
|
|
95
111
|
| `paid_url_unknown`: the URL being paid is unknown (no `wrap_get` / `guard.request(url)`), so the only host is the 402's own claim | `paid_url_unknown` | warn | **block** |
|
|
96
112
|
| `price_above_observed`: same route, amount above the last amount BotsRated recorded (compared locally) | `price_above_observed` | warn | warn |
|
|
113
|
+
| `quote_above_listing`: same route, amount above the listed amount. A server policy reason with this code uses the same effect | `quote_above_listing` | warn | warn |
|
|
114
|
+
| `repeat_payment`: the same payment identifier, or the same host, route, amount and nonce, repeats within 60 seconds. Local only. `replay_tested` stays false | `repeat_payment` | warn | warn |
|
|
115
|
+
| `pay_to_base58_format`: a Solana payTo is not a base58 32-byte public key. A Base payTo is not judged. The Base USDC rule is unchanged | `payto_base58_format` | warn | warn |
|
|
116
|
+
| After payment, on `wrap_get` / `wrap_async_get`, once a payload was created: a 2xx is not a delivery unless the body is non-empty, the content type is one this check accepts (`application/json`, `application/problem+json`, `text/plain`, `text/json`, or a `+json` type), and a JSON schema the seller declared matches. This check does not block | `delivery_check` | warn | warn |
|
|
97
117
|
| `not_covered`: BotsRated has no probe record for the host | `not_covered` | info | info |
|
|
98
118
|
| `stale`: BotsRated's latest probe is older than 24 h | `data_stale` | info | info |
|
|
99
119
|
| BotsRated unreachable (3 s timeout) | `botsrated_unreachable` | info (`fail_open=True`) | info unless `fail_open=False` |
|
|
@@ -108,7 +128,7 @@ never echoed except a parsed host name.
|
|
|
108
128
|
|
|
109
129
|
### Facts Bundle
|
|
110
130
|
|
|
111
|
-
`decision.facts` is the bundle the guard compared. It is measurements plus a receipt link.
|
|
131
|
+
`decision.facts` is the bundle the guard compared. It is measurements plus a receipt link.
|
|
112
132
|
|
|
113
133
|
| Field | What it is |
|
|
114
134
|
|---|---|
|
|
@@ -126,7 +146,7 @@ https://botsrated.com/disputes. `would_block` is true when a rule's effect is `b
|
|
|
126
146
|
`action` stays `allow`.
|
|
127
147
|
|
|
128
148
|
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
|
|
149
|
+
smaller local bundle and does not add a summary number, because the response has none.
|
|
130
150
|
|
|
131
151
|
### Options
|
|
132
152
|
|
|
@@ -139,7 +159,7 @@ smaller local bundle and does not copy a score out of it, because the response h
|
|
|
139
159
|
| `fail_open` | `True` | `False`: stop the payment when BotsRated can't be reached or the guard errors |
|
|
140
160
|
| `retry_key` | `True` | Add a `payment-identifier` id where the seller advertises it |
|
|
141
161
|
| `onchain` | default RPCs | RPC settings for `payment_state` (`rpcs`, `extra_rpc`, `margin_seconds`, `expiry_tag`, `confirm_tag`), or `False` |
|
|
142
|
-
| `timeout` / `cache_ttl` | 3 s / 5 min | Hosted lookup timeout and per-host cache |
|
|
162
|
+
| `timeout` / `cache_ttl` | 3 s / 5 min | Hosted lookup timeout, clamped to 10 s, and per-host cache |
|
|
143
163
|
| `preflight` | hosted call | Your own lookup `(host) -> (found, body)` |
|
|
144
164
|
| `on_decision` | none | Receives every decision (errors in it are ignored) |
|
|
145
165
|
| `remote_policy` | unset | Private policy check. See below. Unset: local presets only |
|
|
@@ -148,7 +168,9 @@ smaller local bundle and does not copy a score out of it, because the response h
|
|
|
148
168
|
|
|
149
169
|
- **Fail-open (default):** if botsrated.com is down or slow, or the guard itself hits an error, the payment goes
|
|
150
170
|
ahead and the decision says `botsrated_unreachable` (or `hook_error`). Our outage never stops your agent, but
|
|
151
|
-
during an outage you get no seller facts.
|
|
171
|
+
during an outage you get no seller facts. HTTP 503, HTTP 429 and a timeout are that miss: the guard reads
|
|
172
|
+
`Retry-After` (or waits 5 s, at most 60 s) and skips further hosted lookups in the process until then.
|
|
173
|
+
A skipped lookup is not a pass. A fresh cached success is still used.
|
|
152
174
|
- **Fail-closed (`fail_open=False`):** the same cases stop the payment. Use it only if an unchecked payment is worse
|
|
153
175
|
for you than a missed call.
|
|
154
176
|
- Local checks (`resource_host_mismatch`, `payto_invalid`) and the on-chain check never depend on botsrated.com.
|
|
@@ -162,11 +184,21 @@ This is the path that makes `BOTSRATED_TOKEN` work in framework attaches. The to
|
|
|
162
184
|
```python
|
|
163
185
|
guard = PaymentGuard(
|
|
164
186
|
preset="carefulBuyer",
|
|
165
|
-
remote_policy={"token": "<bearer>", "fail_mode": "
|
|
187
|
+
remote_policy={"token": "<bearer>", "fail_mode": "open"}, # omit fail_mode for open; "closed" is opt-in
|
|
166
188
|
)
|
|
167
189
|
```
|
|
168
190
|
|
|
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).
|
|
191
|
+
`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 429, HTTP 404, a timeout, or `"decision": null`, it applies `fail_mode` (`open`: an info reason, payment continues unless a local rule stops it; `closed`: the payment stops). A 503, 429 or timeout also opens the in-process circuit above, and the next hosted lookup is skipped. 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.
|
|
192
|
+
|
|
193
|
+
`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).
|
|
194
|
+
|
|
195
|
+
**Save a policy first.** `remote_policy` only checks; it never saves. With no saved policy every check answers `404 no_policy_saved`, and the guard applies your `fail_mode` (`closed` stops every payment). Start from a private pack (`none`, `warn`, `careful-buyer`, `strict`; list at `GET https://botsrated.com/v1/policy/packs`), then `PUT /v1/policy` with your token, or use [Desk → Policy](https://botsrated.com/desk/policy). The smallest one is `none` (only the two always-on checks):
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
curl -X PUT https://botsrated.com/v1/policy -H "Authorization: Bearer $BOTSRATED_TOKEN" -H "Content-Type: application/json" -d '{"preset":"none","fail_mode":"open"}'
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
`fail_mode` in that body is yours to pick (`open` or `closed`). The token needs `policy-write` (a paid-plan `brs_` token, or a `brk_` org key with that scope). Server pack names (`careful-buyer`) are your saved server rules. The local `preset` (`carefulBuyer`) is a separate client table. They don't have to match.
|
|
170
202
|
|
|
171
203
|
### What The Guard Sends, And To Whom
|
|
172
204
|
|
|
@@ -205,7 +237,7 @@ state = guard.payment_state(rec) # or: await guard.apayment_state(rec). Re
|
|
|
205
237
|
|
|
206
238
|
There are three answers only:
|
|
207
239
|
|
|
208
|
-
- `settled`: two RPCs on different hosts (or two of three, see below) show the EIP-3009 authorization used at Base's
|
|
240
|
+
- `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
241
|
the chain id is 8453, and the transaction receipt has `AuthorizationUsed(from, nonce)` and
|
|
210
242
|
`Transfer(from, payTo, amount)` emitted by the pinned USDC contract `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.
|
|
211
243
|
- `unknown` (`payment_state_unknown`) with `wait_until`: not settled yet, the RPCs disagree or failed, the blocks
|
|
@@ -213,7 +245,7 @@ There are three answers only:
|
|
|
213
245
|
checked. **Do not sign a new payment for that purchase before `wait_until`** (the signed authorization stays
|
|
214
246
|
valid until its `validBefore`, plus a margin of at least 30 s).
|
|
215
247
|
- `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
|
|
248
|
+
the authorization unused at a block (Base's default confirmation tag) whose timestamp is at or after `validBefore`
|
|
217
249
|
plus the margin. USDC accepts an authorization in any block before `validBefore`, so "unused" only counts in a
|
|
218
250
|
later block. With the default 60 s margin this is usually 1 to 3 minutes after expiry. Only then is a fresh
|
|
219
251
|
payment free of a double-charge risk from the first one.
|
|
@@ -224,7 +256,7 @@ It is clamped, not rejected: a value below 30 (including negative values and `-i
|
|
|
224
256
|
`expiry_tag="finalized"` waits for a finalized block past expiry instead (more conservative, usually 20+ minutes).
|
|
225
257
|
|
|
226
258
|
The guard never retries on `unknown`. botsrated.com is never asked; a tx hash the seller reports is only a hint
|
|
227
|
-
that is
|
|
259
|
+
that is checked on chain.
|
|
228
260
|
|
|
229
261
|
**Default RPCs** (two operators; both must answer and agree):
|
|
230
262
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "botsrated"
|
|
3
|
-
version = "0.3.
|
|
3
|
+
version = "0.3.2"
|
|
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"
|