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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: botsrated
3
- Version: 0.3.0
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 on PyPI as [`botsrated` 0.2.1](https://pypi.org/project/botsrated/).** 0.3.0 (adds `remotePolicy` / `remote_policy`) is pending release.
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. It does not return a score or a grade.
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. It has no score and no grade.
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 copy a score out of it, because the response has none.
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": "closed"}, # base_url defaults to https://botsrated.com
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). It does not turn a missing decision into a pass. `decided_by` and `not_a_botsrated_rating` 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.
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 `safe` block tag,
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 `safe` tag by default) whose timestamp is at or after `validBefore`
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 verified on chain.
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 on PyPI as [`botsrated` 0.2.1](https://pypi.org/project/botsrated/).** 0.3.0 (adds `remotePolicy` / `remote_policy`) is pending release.
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. It does not return a score or a grade.
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. It has no score and no grade.
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 copy a score out of it, because the response has none.
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": "closed"}, # base_url defaults to https://botsrated.com
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). It does not turn a missing decision into a pass. `decided_by` and `not_a_botsrated_rating` 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.
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 `safe` block tag,
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 `safe` tag by default) whose timestamp is at or after `validBefore`
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 verified on chain.
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.0"
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"