botsrated 0.2.0__tar.gz → 0.3.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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: botsrated
3
- Version: 0.2.0
3
+ Version: 0.3.0
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
@@ -30,12 +30,11 @@ The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment che
30
30
 
31
31
  It lowers the chance of paying the wrong address or paying twice; it can't rule either out.
32
32
 
33
- **Status: 0.2.0 is not released yet. The latest version on PyPI is
34
- [`botsrated` 0.1.6](https://pypi.org/project/botsrated/), which does not include the payment guard.**
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.
35
34
 
36
35
  **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.
37
36
 
38
- **Hosted checks.** By default (`hosted=True`) this package calls BotsRated's free API (`https://botsrated.com/v1/preflight`) and sends it **only the seller's host name** (never the path, query, wallet, amount, nonce, payment header or request body). Those calls are covered by the BotsRated Terms (https://botsrated.com/terms) and Privacy Policy (https://botsrated.com/privacy), not by the MIT license. `hosted=False` turns hosted checks off: nothing is then sent to botsrated.com, and only the local checks, the retry key and the on-chain check (which goes only to the RPCs you set) run.
37
+ **Hosted checks.** By default (`hosted=True`) this package calls BotsRated's preflight (`https://botsrated.com/v1/preflight`; free, no key, rate limits) and sends it **only the seller's host name** (never the path, query, wallet, amount, nonce, payment header or request body). Those calls are covered by the BotsRated Terms (https://botsrated.com/terms) and Privacy Policy (https://botsrated.com/privacy), not by the MIT license. `hosted=False` turns hosted checks off: nothing is then sent to botsrated.com, and only the local checks, the retry key and the on-chain check (which goes only to the RPCs you set) run.
39
38
 
40
39
  ## Install
41
40
 
@@ -46,7 +45,20 @@ pip install "botsrated[x402]"
46
45
  Runtime dependencies: `httpx>=0.27,<1` (and, with the `x402` extra, `x402[httpx,evm]>=2.25,<3`). The guard only
47
46
  uses the hook and extension points of the x402 client you pass in.
48
47
 
49
- ## Payment Guard: Start With Dry-Run
48
+ ## Payment Guard: Pick A Preset
49
+
50
+ 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.
52
+
53
+ Pick a named preset. The zero-config call (`PaymentGuard()`) is `warn`: advice only, it never stops a payment.
54
+ Dry-run is optional: it logs `would_block` and still never stops a payment.
55
+
56
+ | Name | How to select it | What you get |
57
+ |---|---|---|
58
+ | `warn` | `PaymentGuard()` or `preset="warn"` or `policy=POLICIES["warn"]` | Advice only. The default. |
59
+ | `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`. |
61
+ | `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. |
50
62
 
51
63
  ```python
52
64
  import httpx
@@ -54,17 +66,21 @@ from x402 import x402Client
54
66
  from x402.http.clients.httpx import x402AsyncTransport
55
67
  from x402.mechanisms.evm import EthAccountSigner
56
68
  from x402.mechanisms.evm.exact import ExactEvmScheme
57
- from botsrated import PaymentGuard
69
+ from botsrated import POLICIES, PaymentGuard, dry_run_only
58
70
 
59
71
  client = x402Client()
60
72
  client.register("eip155:*", ExactEvmScheme(signer=EthAccountSigner(account)))
61
73
 
62
- # Recommended first setting: log what the guard sees, change nothing.
63
- guard = PaymentGuard(dry_run=True, on_decision=lambda d: print(d.message))
64
- guard.install(client) # before/after/response hooks (+ the retry-key extension when not in dry-run)
74
+ # Install one of these. `guard` stops payments; `looking` only logs.
75
+ # 1. Pick a named preset. This one stops the four cases above.
76
+ guard = PaymentGuard(preset="carefulBuyer", on_decision=lambda d: print(d.message, d.facts))
77
+
78
+ # 2. Or look first: log would_block for those same stops, and never stop a payment.
79
+ looking = dry_run_only(policy=POLICIES["carefulBuyer"], on_decision=lambda d: print(d.would_block, d.message))
65
80
 
81
+ looking.install(client) # before/after/response hooks (+ the retry-key extension when not in dry-run)
66
82
  http = httpx.AsyncClient(transport=x402AsyncTransport(client, httpx.AsyncHTTPTransport()))
67
- paid_get = guard.wrap_async_get(http.get) # tells the guard which URL is being paid
83
+ paid_get = looking.wrap_async_get(http.get) # tells the guard which URL is being paid
68
84
  await paid_get("https://seller.example/api")
69
85
  ```
70
86
 
@@ -77,16 +93,12 @@ you use it.
77
93
 
78
94
  Always tell the guard the URL being paid (`wrap_async_get`, `wrap_get` or `with guard.request(url):`). Without it
79
95
  the guard only knows the host the seller's 402 *claims* (`resource.url`), so it reports `paid_url_unknown` (a
80
- warning by default; `POLICIES["strict"]` stops the payment).
96
+ warning by default; `POLICIES["carefulBuyer"]` and `POLICIES["strict"]` stop the payment).
81
97
 
82
- When the log looks right, drop `dry_run`. The zero-config setting (`PaymentGuard()`) is advice only: it reports
83
- facts and never stops a payment. To stop payments, choose a policy yourself:
84
-
85
- ```python
86
- from botsrated import POLICIES, PaymentGuard
87
-
88
- guard = PaymentGuard(policy=POLICIES["strict"]) # your choice
89
- ```
98
+ `POLICIES["carefulBuyer"]` is `POLICIES["strict"]` (one rule table, two names). A price above the last observed
99
+ amount still warns. An uncovered host and a stale probe stay informational. To stop payments on your own mix,
100
+ pass a policy yourself: `dataclasses.replace(POLICIES["carefulBuyer"], price_above_observed="block")`. An explicit
101
+ `policy=` replaces the preset's rule table.
90
102
 
91
103
  A stopped payment raises the x402 abort error with text like:
92
104
 
@@ -94,7 +106,7 @@ A stopped payment raises the x402 abort error with text like:
94
106
 
95
107
  ### Rules And Defaults
96
108
 
97
- | Rule (`PaymentGuardPolicy(...)`) | Reason code | `POLICIES["warn"]` (default) | `POLICIES["strict"]` |
109
+ | Rule (`PaymentGuardPolicy(...)`) | Reason code | `POLICIES["warn"]` (default) | `POLICIES["carefulBuyer"]` / `POLICIES["strict"]` |
98
110
  |---|---|---|---|
99
111
  | `pay_to_mismatch`: the payTo is not among the payTos BotsRated's probes recorded for the host | `payto_not_observed` | warn | **block** |
100
112
  | `pay_to_invalid`: the payTo is not a 20-byte hex address | `payto_invalid` | warn | **block** |
@@ -108,17 +120,40 @@ A stopped payment raises the x402 abort error with text like:
108
120
 
109
121
  Each rule takes `"allow"`, `"warn"` or `"block"`, e.g.
110
122
  `dataclasses.replace(POLICIES["warn"], pay_to_mismatch="block")`. A custom `PaymentGuardPolicy(...)` leaves
111
- `paid_url_unknown` at `"warn"` unless you set it: add `paid_url_unknown="block"` (as `POLICIES["strict"]` does) if an
112
- unknown paid URL should stop the payment. Every decision carries `reasons` (code, effect,
123
+ `paid_url_unknown` at `"warn"` unless you set it: add `paid_url_unknown="block"` (as `POLICIES["carefulBuyer"]` /
124
+ `POLICIES["strict"]` do) if an unknown paid URL should stop the payment. Every decision carries `reasons` (code, effect,
113
125
  rule, fact), `facts`, `policy_rule`, `dispute_url` and a `message`. Reason texts state facts only; seller text is
114
126
  never echoed except a parsed host name.
115
127
 
128
+ ### Facts Bundle
129
+
130
+ `decision.facts` is the bundle the guard compared. It is measurements plus a receipt link. It has no score and no grade.
131
+
132
+ | Field | What it is |
133
+ |---|---|
134
+ | `covered` | Whether BotsRated has a probe record for the host |
135
+ | `host` | Host that was looked up (only the host name was sent) |
136
+ | `known_pay_tos` | payTo addresses BotsRated's probes recorded |
137
+ | `listing_pay_to` | payTo from a directory listing, when present. A listing is not a probe observation |
138
+ | `observed_network` | Network the probes recorded |
139
+ | `observed_amount` | Last amount recorded on the probed route, in atomic units |
140
+ | `stale` | True when the latest probe is older than 24 hours |
141
+ | `receipt_url` | `https://botsrated.com/receipt/...` when the preflight included a receipt on botsrated.com |
142
+
143
+ `reasons` lists each fact (`code`, `effect` of `info`, `warn` or `block`, `rule`, `fact`). `dispute_url` is
144
+ https://botsrated.com/disputes. `would_block` is true when a rule's effect is `block`, including in dry-run, where
145
+ `action` stays `allow`.
146
+
147
+ 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.
149
+
116
150
  ### Options
117
151
 
118
152
  | Option | Default | Meaning |
119
153
  |---|---|---|
120
- | `policy` | `POLICIES["warn"]` | Which facts warn and which stop a payment |
121
- | `dry_run` | `False` | Log decisions, stop nothing, add no retry key. Recommended first setting |
154
+ | `preset` | omitted (behaves as `warn`) | `warn`, `carefulBuyer`, or `dry-run-only`. `dry-run-only` forces dry-run |
155
+ | `policy` | `POLICIES["warn"]` | Which facts warn and which stop a payment. Replaces the preset's rule table when set |
156
+ | `dry_run` | `False` | Log decisions, stop nothing, add no retry key. Forced on for preset `dry-run-only` |
122
157
  | `hosted` | `True` | `False`: nothing is sent to botsrated.com |
123
158
  | `fail_open` | `True` | `False`: stop the payment when BotsRated can't be reached or the guard errors |
124
159
  | `retry_key` | `True` | Add a `payment-identifier` id where the seller advertises it |
@@ -126,6 +161,7 @@ never echoed except a parsed host name.
126
161
  | `timeout` / `cache_ttl` | 3 s / 5 min | Hosted lookup timeout and per-host cache |
127
162
  | `preflight` | hosted call | Your own lookup `(host) -> (found, body)` |
128
163
  | `on_decision` | none | Receives every decision (errors in it are ignored) |
164
+ | `remote_policy` | unset | Private policy check. See below. Unset: local presets only |
129
165
 
130
166
  ### Fail-Open Or Fail-Closed
131
167
 
@@ -136,16 +172,34 @@ never echoed except a parsed host name.
136
172
  for you than a missed call.
137
173
  - Local checks (`resource_host_mismatch`, `payto_invalid`) and the on-chain check never depend on botsrated.com.
138
174
 
175
+ ### Remote Policy
176
+
177
+ Optional. Set `remote_policy` to ask your private policy on BotsRated before a payment. The guard merges that answer with the local rules. A remote block stops the payment. A remote pass does not clear a local block. `PrePaymentGuard(..., remote_policy=...)` uses the same check.
178
+
179
+ This is the path that makes `BOTSRATED_TOKEN` work in framework attaches. The token is optional. The guard defaults to advice-only with no key, so anyone can install it as a default. The client enforces. BotsRated holds no funds, signs nothing, and has no escrow.
180
+
181
+ ```python
182
+ guard = PaymentGuard(
183
+ preset="carefulBuyer",
184
+ remote_policy={"token": "<bearer>", "fail_mode": "closed"}, # base_url defaults to https://botsrated.com
185
+ )
186
+ ```
187
+
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.
189
+
139
190
  ### What The Guard Sends, And To Whom
140
191
 
141
- - **botsrated.com:** `GET /v1/preflight?url=<host name>` with `User-Agent: botsrated-python/<version>`.
192
+ - **botsrated.com (preflight):** `GET /v1/preflight?url=<host name>` with `User-Agent: botsrated-python/<version>`.
142
193
  Never the path, query, wallet, amount, nonce, tx hash, payment header or request body. No install id. Covered by
143
194
  the [Terms](https://botsrated.com/terms) and [Privacy Policy](https://botsrated.com/privacy). Turn it off with
144
195
  `hosted=False`.
196
+ - **botsrated.com (only when `remote_policy` is set):** `POST /v1/policy/check` with the host, the quote
197
+ (`payTo`, `amount`, `asset`, `network`) and your bearer token. Not the path, query, payer wallet, nonce or a
198
+ payment header. The decision is not signed. `hosted=False` does not turn this off.
145
199
  - **Base RPCs (only when you call `payment_state`; nothing calls them automatically):** JSON-RPC reads that include
146
200
  the payer address and the payment's nonce, sent straight from your machine to the RPCs, never to BotsRated.
147
201
  See the privacy note under "Did It Settle Once?".
148
- - No remote configuration, feature flags or auto-update: behavior changes only with a new package version.
202
+ - No feature flags or auto-update: behavior changes only with a new package version, or with `remote_policy` when you set it.
149
203
 
150
204
  ### Retry Key (`payment-identifier`)
151
205
 
@@ -284,8 +338,8 @@ botsrated = BotsRatedClient(budget_usd="0.05", x402_client=client) # signs onl
284
338
  guard = PrePaymentGuard(botsrated, paid_check_at_or_above_usd=0.25)
285
339
  client.on_before_payment_creation(guard.x402_hook)
286
340
 
287
- botsrated.check("seller.example") # $0.001 (first 100/day free)
288
- botsrated.report("seller.example") # $0.002 (first 10/day free)
341
+ botsrated.check("seller.example") # $0.001 (first 25 per client IP per UTC day free)
342
+ botsrated.report("seller.example") # $0.002 (first 3 per client IP per UTC day free)
289
343
  botsrated.best("web search") # $0.01
290
344
  ```
291
345
 
@@ -297,10 +351,11 @@ the allowlisted fields only (scheme, network, asset, amount, payTo, maxTimeoutSe
297
351
  itself, so register the guard on the same x402 client so the re-served 402 is checked again before signing.
298
352
 
299
353
  How paid calls work:
300
- - Free daily quota: the first 100 `/v1/check` and 10 `/v1/report` calls per client per UTC day are
354
+ - Free daily quota (`FREE_DAILY_QUOTA`): the first 25 `/v1/check` and 3 `/v1/report` calls per client IP per UTC day are
301
355
  served free (200 with `charged: false` and a `free_quota` block). The client asks unpaid first, so
302
356
  inside the quota nothing is paid and the budget is untouched; `check()`/`report()` also work without
303
357
  a budget until the quota is used up (then `paid_disabled`). `client.last_free_quota` shows what is left.
358
+ `/v1/best` has no free quota. Preflight stays free, no key, rate limits.
304
359
  - Otherwise the client reads the 402 quote unpaid first. It accepts the quote only if **every** option is `exact` USDC on Base to BotsRated's payTo
305
360
  `0x7F936f42F46B6c4Cbd3242cF8A1759dfe829E349`, at or below the published price.
306
361
  - The amount is reserved from the budget before paying. If the paid call fails or raises, it stays counted
@@ -11,12 +11,11 @@ The BotsRated **payment guard** for x402 clients, plus a simpler pre-payment che
11
11
 
12
12
  It lowers the chance of paying the wrong address or paying twice; it can't rule either out.
13
13
 
14
- **Status: 0.2.0 is not released yet. The latest version on PyPI is
15
- [`botsrated` 0.1.6](https://pypi.org/project/botsrated/), which does not include the payment guard.**
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.
16
15
 
17
16
  **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.
18
17
 
19
- **Hosted checks.** By default (`hosted=True`) this package calls BotsRated's free API (`https://botsrated.com/v1/preflight`) and sends it **only the seller's host name** (never the path, query, wallet, amount, nonce, payment header or request body). Those calls are covered by the BotsRated Terms (https://botsrated.com/terms) and Privacy Policy (https://botsrated.com/privacy), not by the MIT license. `hosted=False` turns hosted checks off: nothing is then sent to botsrated.com, and only the local checks, the retry key and the on-chain check (which goes only to the RPCs you set) run.
18
+ **Hosted checks.** By default (`hosted=True`) this package calls BotsRated's preflight (`https://botsrated.com/v1/preflight`; free, no key, rate limits) and sends it **only the seller's host name** (never the path, query, wallet, amount, nonce, payment header or request body). Those calls are covered by the BotsRated Terms (https://botsrated.com/terms) and Privacy Policy (https://botsrated.com/privacy), not by the MIT license. `hosted=False` turns hosted checks off: nothing is then sent to botsrated.com, and only the local checks, the retry key and the on-chain check (which goes only to the RPCs you set) run.
20
19
 
21
20
  ## Install
22
21
 
@@ -27,7 +26,20 @@ pip install "botsrated[x402]"
27
26
  Runtime dependencies: `httpx>=0.27,<1` (and, with the `x402` extra, `x402[httpx,evm]>=2.25,<3`). The guard only
28
27
  uses the hook and extension points of the x402 client you pass in.
29
28
 
30
- ## Payment Guard: Start With Dry-Run
29
+ ## Payment Guard: Pick A Preset
30
+
31
+ 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.
33
+
34
+ Pick a named preset. The zero-config call (`PaymentGuard()`) is `warn`: advice only, it never stops a payment.
35
+ Dry-run is optional: it logs `would_block` and still never stops a payment.
36
+
37
+ | Name | How to select it | What you get |
38
+ |---|---|---|
39
+ | `warn` | `PaymentGuard()` or `preset="warn"` or `policy=POLICIES["warn"]` | Advice only. The default. |
40
+ | `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`. |
42
+ | `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. |
31
43
 
32
44
  ```python
33
45
  import httpx
@@ -35,17 +47,21 @@ from x402 import x402Client
35
47
  from x402.http.clients.httpx import x402AsyncTransport
36
48
  from x402.mechanisms.evm import EthAccountSigner
37
49
  from x402.mechanisms.evm.exact import ExactEvmScheme
38
- from botsrated import PaymentGuard
50
+ from botsrated import POLICIES, PaymentGuard, dry_run_only
39
51
 
40
52
  client = x402Client()
41
53
  client.register("eip155:*", ExactEvmScheme(signer=EthAccountSigner(account)))
42
54
 
43
- # Recommended first setting: log what the guard sees, change nothing.
44
- guard = PaymentGuard(dry_run=True, on_decision=lambda d: print(d.message))
45
- guard.install(client) # before/after/response hooks (+ the retry-key extension when not in dry-run)
55
+ # Install one of these. `guard` stops payments; `looking` only logs.
56
+ # 1. Pick a named preset. This one stops the four cases above.
57
+ guard = PaymentGuard(preset="carefulBuyer", on_decision=lambda d: print(d.message, d.facts))
58
+
59
+ # 2. Or look first: log would_block for those same stops, and never stop a payment.
60
+ looking = dry_run_only(policy=POLICIES["carefulBuyer"], on_decision=lambda d: print(d.would_block, d.message))
46
61
 
62
+ looking.install(client) # before/after/response hooks (+ the retry-key extension when not in dry-run)
47
63
  http = httpx.AsyncClient(transport=x402AsyncTransport(client, httpx.AsyncHTTPTransport()))
48
- paid_get = guard.wrap_async_get(http.get) # tells the guard which URL is being paid
64
+ paid_get = looking.wrap_async_get(http.get) # tells the guard which URL is being paid
49
65
  await paid_get("https://seller.example/api")
50
66
  ```
51
67
 
@@ -58,16 +74,12 @@ you use it.
58
74
 
59
75
  Always tell the guard the URL being paid (`wrap_async_get`, `wrap_get` or `with guard.request(url):`). Without it
60
76
  the guard only knows the host the seller's 402 *claims* (`resource.url`), so it reports `paid_url_unknown` (a
61
- warning by default; `POLICIES["strict"]` stops the payment).
77
+ warning by default; `POLICIES["carefulBuyer"]` and `POLICIES["strict"]` stop the payment).
62
78
 
63
- When the log looks right, drop `dry_run`. The zero-config setting (`PaymentGuard()`) is advice only: it reports
64
- facts and never stops a payment. To stop payments, choose a policy yourself:
65
-
66
- ```python
67
- from botsrated import POLICIES, PaymentGuard
68
-
69
- guard = PaymentGuard(policy=POLICIES["strict"]) # your choice
70
- ```
79
+ `POLICIES["carefulBuyer"]` is `POLICIES["strict"]` (one rule table, two names). A price above the last observed
80
+ amount still warns. An uncovered host and a stale probe stay informational. To stop payments on your own mix,
81
+ pass a policy yourself: `dataclasses.replace(POLICIES["carefulBuyer"], price_above_observed="block")`. An explicit
82
+ `policy=` replaces the preset's rule table.
71
83
 
72
84
  A stopped payment raises the x402 abort error with text like:
73
85
 
@@ -75,7 +87,7 @@ A stopped payment raises the x402 abort error with text like:
75
87
 
76
88
  ### Rules And Defaults
77
89
 
78
- | Rule (`PaymentGuardPolicy(...)`) | Reason code | `POLICIES["warn"]` (default) | `POLICIES["strict"]` |
90
+ | Rule (`PaymentGuardPolicy(...)`) | Reason code | `POLICIES["warn"]` (default) | `POLICIES["carefulBuyer"]` / `POLICIES["strict"]` |
79
91
  |---|---|---|---|
80
92
  | `pay_to_mismatch`: the payTo is not among the payTos BotsRated's probes recorded for the host | `payto_not_observed` | warn | **block** |
81
93
  | `pay_to_invalid`: the payTo is not a 20-byte hex address | `payto_invalid` | warn | **block** |
@@ -89,17 +101,40 @@ A stopped payment raises the x402 abort error with text like:
89
101
 
90
102
  Each rule takes `"allow"`, `"warn"` or `"block"`, e.g.
91
103
  `dataclasses.replace(POLICIES["warn"], pay_to_mismatch="block")`. A custom `PaymentGuardPolicy(...)` leaves
92
- `paid_url_unknown` at `"warn"` unless you set it: add `paid_url_unknown="block"` (as `POLICIES["strict"]` does) if an
93
- unknown paid URL should stop the payment. Every decision carries `reasons` (code, effect,
104
+ `paid_url_unknown` at `"warn"` unless you set it: add `paid_url_unknown="block"` (as `POLICIES["carefulBuyer"]` /
105
+ `POLICIES["strict"]` do) if an unknown paid URL should stop the payment. Every decision carries `reasons` (code, effect,
94
106
  rule, fact), `facts`, `policy_rule`, `dispute_url` and a `message`. Reason texts state facts only; seller text is
95
107
  never echoed except a parsed host name.
96
108
 
109
+ ### Facts Bundle
110
+
111
+ `decision.facts` is the bundle the guard compared. It is measurements plus a receipt link. It has no score and no grade.
112
+
113
+ | Field | What it is |
114
+ |---|---|
115
+ | `covered` | Whether BotsRated has a probe record for the host |
116
+ | `host` | Host that was looked up (only the host name was sent) |
117
+ | `known_pay_tos` | payTo addresses BotsRated's probes recorded |
118
+ | `listing_pay_to` | payTo from a directory listing, when present. A listing is not a probe observation |
119
+ | `observed_network` | Network the probes recorded |
120
+ | `observed_amount` | Last amount recorded on the probed route, in atomic units |
121
+ | `stale` | True when the latest probe is older than 24 hours |
122
+ | `receipt_url` | `https://botsrated.com/receipt/...` when the preflight included a receipt on botsrated.com |
123
+
124
+ `reasons` lists each fact (`code`, `effect` of `info`, `warn` or `block`, `rule`, `fact`). `dispute_url` is
125
+ https://botsrated.com/disputes. `would_block` is true when a rule's effect is `block`, including in dry-run, where
126
+ `action` stays `allow`.
127
+
128
+ 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.
130
+
97
131
  ### Options
98
132
 
99
133
  | Option | Default | Meaning |
100
134
  |---|---|---|
101
- | `policy` | `POLICIES["warn"]` | Which facts warn and which stop a payment |
102
- | `dry_run` | `False` | Log decisions, stop nothing, add no retry key. Recommended first setting |
135
+ | `preset` | omitted (behaves as `warn`) | `warn`, `carefulBuyer`, or `dry-run-only`. `dry-run-only` forces dry-run |
136
+ | `policy` | `POLICIES["warn"]` | Which facts warn and which stop a payment. Replaces the preset's rule table when set |
137
+ | `dry_run` | `False` | Log decisions, stop nothing, add no retry key. Forced on for preset `dry-run-only` |
103
138
  | `hosted` | `True` | `False`: nothing is sent to botsrated.com |
104
139
  | `fail_open` | `True` | `False`: stop the payment when BotsRated can't be reached or the guard errors |
105
140
  | `retry_key` | `True` | Add a `payment-identifier` id where the seller advertises it |
@@ -107,6 +142,7 @@ never echoed except a parsed host name.
107
142
  | `timeout` / `cache_ttl` | 3 s / 5 min | Hosted lookup timeout and per-host cache |
108
143
  | `preflight` | hosted call | Your own lookup `(host) -> (found, body)` |
109
144
  | `on_decision` | none | Receives every decision (errors in it are ignored) |
145
+ | `remote_policy` | unset | Private policy check. See below. Unset: local presets only |
110
146
 
111
147
  ### Fail-Open Or Fail-Closed
112
148
 
@@ -117,16 +153,34 @@ never echoed except a parsed host name.
117
153
  for you than a missed call.
118
154
  - Local checks (`resource_host_mismatch`, `payto_invalid`) and the on-chain check never depend on botsrated.com.
119
155
 
156
+ ### Remote Policy
157
+
158
+ Optional. Set `remote_policy` to ask your private policy on BotsRated before a payment. The guard merges that answer with the local rules. A remote block stops the payment. A remote pass does not clear a local block. `PrePaymentGuard(..., remote_policy=...)` uses the same check.
159
+
160
+ This is the path that makes `BOTSRATED_TOKEN` work in framework attaches. The token is optional. The guard defaults to advice-only with no key, so anyone can install it as a default. The client enforces. BotsRated holds no funds, signs nothing, and has no escrow.
161
+
162
+ ```python
163
+ guard = PaymentGuard(
164
+ preset="carefulBuyer",
165
+ remote_policy={"token": "<bearer>", "fail_mode": "closed"}, # base_url defaults to https://botsrated.com
166
+ )
167
+ ```
168
+
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.
170
+
120
171
  ### What The Guard Sends, And To Whom
121
172
 
122
- - **botsrated.com:** `GET /v1/preflight?url=<host name>` with `User-Agent: botsrated-python/<version>`.
173
+ - **botsrated.com (preflight):** `GET /v1/preflight?url=<host name>` with `User-Agent: botsrated-python/<version>`.
123
174
  Never the path, query, wallet, amount, nonce, tx hash, payment header or request body. No install id. Covered by
124
175
  the [Terms](https://botsrated.com/terms) and [Privacy Policy](https://botsrated.com/privacy). Turn it off with
125
176
  `hosted=False`.
177
+ - **botsrated.com (only when `remote_policy` is set):** `POST /v1/policy/check` with the host, the quote
178
+ (`payTo`, `amount`, `asset`, `network`) and your bearer token. Not the path, query, payer wallet, nonce or a
179
+ payment header. The decision is not signed. `hosted=False` does not turn this off.
126
180
  - **Base RPCs (only when you call `payment_state`; nothing calls them automatically):** JSON-RPC reads that include
127
181
  the payer address and the payment's nonce, sent straight from your machine to the RPCs, never to BotsRated.
128
182
  See the privacy note under "Did It Settle Once?".
129
- - No remote configuration, feature flags or auto-update: behavior changes only with a new package version.
183
+ - No feature flags or auto-update: behavior changes only with a new package version, or with `remote_policy` when you set it.
130
184
 
131
185
  ### Retry Key (`payment-identifier`)
132
186
 
@@ -265,8 +319,8 @@ botsrated = BotsRatedClient(budget_usd="0.05", x402_client=client) # signs onl
265
319
  guard = PrePaymentGuard(botsrated, paid_check_at_or_above_usd=0.25)
266
320
  client.on_before_payment_creation(guard.x402_hook)
267
321
 
268
- botsrated.check("seller.example") # $0.001 (first 100/day free)
269
- botsrated.report("seller.example") # $0.002 (first 10/day free)
322
+ botsrated.check("seller.example") # $0.001 (first 25 per client IP per UTC day free)
323
+ botsrated.report("seller.example") # $0.002 (first 3 per client IP per UTC day free)
270
324
  botsrated.best("web search") # $0.01
271
325
  ```
272
326
 
@@ -278,10 +332,11 @@ the allowlisted fields only (scheme, network, asset, amount, payTo, maxTimeoutSe
278
332
  itself, so register the guard on the same x402 client so the re-served 402 is checked again before signing.
279
333
 
280
334
  How paid calls work:
281
- - Free daily quota: the first 100 `/v1/check` and 10 `/v1/report` calls per client per UTC day are
335
+ - Free daily quota (`FREE_DAILY_QUOTA`): the first 25 `/v1/check` and 3 `/v1/report` calls per client IP per UTC day are
282
336
  served free (200 with `charged: false` and a `free_quota` block). The client asks unpaid first, so
283
337
  inside the quota nothing is paid and the budget is untouched; `check()`/`report()` also work without
284
338
  a budget until the quota is used up (then `paid_disabled`). `client.last_free_quota` shows what is left.
339
+ `/v1/best` has no free quota. Preflight stays free, no key, rate limits.
285
340
  - Otherwise the client reads the 402 quote unpaid first. It accepts the quote only if **every** option is `exact` USDC on Base to BotsRated's payTo
286
341
  `0x7F936f42F46B6c4Cbd3242cF8A1759dfe829E349`, at or below the published price.
287
342
  - The amount is reserved from the budget before paying. If the paid call fails or raises, it stays counted
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "botsrated"
3
- version = "0.2.0"
3
+ version = "0.3.0"
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"
@@ -14,11 +14,14 @@ from botsrated.onchain import (
14
14
  )
15
15
  from botsrated.payment_guard import (
16
16
  POLICIES,
17
+ PRESETS,
17
18
  GuardDecision,
18
19
  GuardFacts,
19
20
  GuardReason,
20
21
  PaymentGuard,
21
22
  PaymentGuardPolicy,
23
+ RemotePolicy,
24
+ dry_run_only,
22
25
  )
23
26
  from botsrated.util import (
24
27
  BASE_MAINNET,
@@ -110,6 +113,7 @@ __all__ = [
110
113
  "FREE_DAILY_QUOTA",
111
114
  "PAID_ROUTE_MAX_ATOMIC",
112
115
  "POLICIES",
116
+ "PRESETS",
113
117
  "PRIVACY_URL",
114
118
  "STRICT_GUARD_POLICY",
115
119
  "TERMS_URL",
@@ -130,10 +134,12 @@ __all__ = [
130
134
  "PrePaymentGuard",
131
135
  "PreflightResult",
132
136
  "Reason",
137
+ "RemotePolicy",
133
138
  "SellerFacts",
134
139
  "acheck_payment_state",
135
140
  "check_payment_state",
136
141
  "current_request_url",
142
+ "dry_run_only",
137
143
  "evaluate_payment",
138
144
  "facts_from",
139
145
  "host_of",
@@ -42,8 +42,8 @@ __all__ = [
42
42
  BOTSRATED_PAY_TO = "0x7F936f42F46B6c4Cbd3242cF8A1759dfe829E349"
43
43
  # Published prices (since 2026-10-23) in atomic USDC. Quotes above these are refused.
44
44
  PAID_ROUTE_MAX_ATOMIC: dict[str, int] = {"check": 1000, "report": 2000, "best": 10000}
45
- # Free calls per client (IP) per UTC day. Inside the quota BotsRated answers 200 with charged: false, no 402.
46
- FREE_DAILY_QUOTA: dict[str, int] = {"check": 100, "report": 10, "best": 0}
45
+ # Free calls per client (IP) per UTC day: 25 checks, 3 reports. Inside the quota BotsRated answers 200 with charged: false, no 402.
46
+ FREE_DAILY_QUOTA: dict[str, int] = {"check": 25, "report": 3, "best": 0}
47
47
  # Longest payment authorization window accepted for a BotsRated payment.
48
48
  MAX_TIMEOUT_SECONDS = 600
49
49
  # EIP-3009 needs only the token's EIP-712 domain name/version. Any other ``extra`` key (e.g.
@@ -226,6 +226,10 @@ class BotsRatedClient:
226
226
  except httpx.HTTPError as e:
227
227
  raise BotsRatedError(f"BotsRated unreachable: {clean_text(e, 80)}", "unreachable") from e
228
228
 
229
+ def unpaid_http(self) -> httpx.Client:
230
+ """HTTP client for unpaid calls. A remote policy check uses this and does not create a payment."""
231
+ return self._http
232
+
229
233
  def preflight(self, url_or_host: str) -> PreflightResult:
230
234
  """Free. Latest stored probe for a seller; ``found=False`` when the host is not covered.
231
235
 
@@ -254,11 +258,11 @@ class BotsRatedClient:
254
258
  return result
255
259
 
256
260
  def check(self, url_or_host: str) -> dict[str, Any]:
257
- """Paid ($0.001; first 100/day free). Facts, paid test-buys and recent receipts for one host."""
261
+ """Paid ($0.001; first 25 per client IP per UTC day free). Facts, paid test-buys and recent receipts for one host."""
258
262
  return self._paid(f"/v1/check?host={quote(host_of(url_or_host), safe='')}", "check")
259
263
 
260
264
  def report(self, url_or_host: str) -> dict[str, Any]:
261
- """Paid ($0.002; first 10/day free). Full receipt history for one host."""
265
+ """Paid ($0.002; first 3 per client IP per UTC day free). Full receipt history for one host."""
262
266
  return self._paid(f"/v1/report/{quote(host_of(url_or_host), safe='')}", "report")
263
267
 
264
268
  def best(self, task: str, sort: str | None = None, max_price_usd: float | None = None) -> dict[str, Any]:
@@ -2,7 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from collections.abc import Awaitable, Callable
5
+ from collections.abc import Awaitable, Callable, Mapping
6
6
  from dataclasses import dataclass, field
7
7
  from typing import Any, Literal, TypeVar
8
8
  from urllib.parse import urlsplit
@@ -15,6 +15,12 @@ from botsrated.client import (
15
15
  paying_request,
16
16
  usd_to_atomic,
17
17
  )
18
+ from botsrated.payment_guard import (
19
+ RemotePolicy,
20
+ fetch_remote_policy,
21
+ interpret_policy_body,
22
+ parse_remote_policy,
23
+ )
18
24
  from botsrated.util import (
19
25
  DISPUTE_URL,
20
26
  clean_text,
@@ -62,6 +68,11 @@ class Decision:
62
68
  reasons: list[Reason]
63
69
  facts: SellerFacts | None = None
64
70
  dispute_url: str = DISPUTE_URL
71
+ # Set when a remote policy check ran. ``remote_decision`` stays None when the server sent none.
72
+ decided_by: str | None = None
73
+ not_a_botsrated_rating: bool | None = None
74
+ policy_version: str | None = None
75
+ remote_decision: Literal["pass", "warn", "block"] | None = None
65
76
 
66
77
  def summary(self) -> str:
67
78
  """Fact-only text with the dispute link. Seller text is never echoed beyond a parsed host name."""
@@ -221,8 +232,12 @@ class PrePaymentGuard:
221
232
  policy: What to block or warn on.
222
233
  fail_open: Allow the payment when BotsRated is unreachable. Default True.
223
234
  paid_check_at_or_above_usd: Run a check for payments at or above this: free within the daily quota
224
- (100/day), then a $0.001 paid check with a paid-enabled client (skipped otherwise).
235
+ (25 per UTC day), then a $0.001 paid check with a paid-enabled client (skipped otherwise).
225
236
  on_decision: Called with every decision.
237
+ remote_policy: Optional private policy check (``token``, ``fail_mode`` ``open`` or ``closed``, optional
238
+ ``base_url``). Before paying, ``POST /v1/policy/check`` with the host and quote. A remote block stops
239
+ the payment. HTTP 503, 404 or ``decision: null`` follows ``fail_mode`` and is never read as a pass.
240
+ The last ``policy_version`` is kept on ``remote_policy_version``. Unset: local rules only.
226
241
  """
227
242
 
228
243
  def __init__(
@@ -233,12 +248,15 @@ class PrePaymentGuard:
233
248
  fail_open: bool = True,
234
249
  paid_check_at_or_above_usd: float | None = None,
235
250
  on_decision: Callable[[Decision], None] | None = None,
251
+ remote_policy: RemotePolicy | Mapping[str, Any] | None = None,
236
252
  ) -> None:
237
253
  self.client = client or BotsRatedClient()
238
254
  self.policy = policy or GuardPolicy()
239
255
  self.fail_open = fail_open
240
256
  self.paid_threshold = paid_check_at_or_above_usd
241
257
  self.on_decision = on_decision
258
+ self.remote_policy = parse_remote_policy(remote_policy)
259
+ self.remote_policy_version: str | None = None
242
260
 
243
261
  def _open_or_closed(self, code: str, detail: str, host: str | None = None) -> Decision:
244
262
  eff: Effect = "info" if self.fail_open else "block"
@@ -257,9 +275,33 @@ class PrePaymentGuard:
257
275
  difference (a redirect between the two) is tolerated. Only host names are sent to BotsRated.
258
276
  """
259
277
  try:
260
- return self._decide(resource_url, requirements, request_url)
278
+ decision = self._decide(resource_url, requirements, request_url)
279
+ except Exception: # noqa: BLE001
280
+ decision = self._open_or_closed("hook_error", "the pre-payment check could not evaluate this payment.")
281
+ return self._merge_remote(decision, requirements)
282
+
283
+ def _merge_remote(self, decision: Decision, requirements: Any) -> Decision:
284
+ """POST /v1/policy/check when configured. A remote block wins. A missing decision follows fail_mode."""
285
+ policy = self.remote_policy
286
+ host = decision.host
287
+ if policy is None or not host:
288
+ return decision
289
+ try:
290
+ effect = fetch_remote_policy(self.client.unpaid_http(), policy, host, requirements)
261
291
  except Exception: # noqa: BLE001
262
- return self._open_or_closed("hook_error", "the pre-payment check could not evaluate this payment.")
292
+ effect = interpret_policy_body(None, {}, policy.fail_mode, host)
293
+ version = effect.policy_version or self.remote_policy_version
294
+ if effect.policy_version:
295
+ self.remote_policy_version = effect.policy_version
296
+ if effect.effect and effect.code and effect.fact:
297
+ decision.reasons.append(Reason(effect.code, effect.fact, effect.effect))
298
+ if effect.effect == "block":
299
+ decision.action = "block"
300
+ decision.decided_by = effect.decided_by
301
+ decision.not_a_botsrated_rating = effect.not_a_botsrated_rating
302
+ decision.policy_version = version
303
+ decision.remote_decision = effect.decision
304
+ return decision
263
305
 
264
306
  def _decide(self, resource_url: str | None, requirements: Any, request_url: str | None) -> Decision:
265
307
  req = as_requirements(requirements)