evaluate_x402_resource
Destructive
One-shot x402 guard. Fetches resource_url, extracts the seller wallet from the 402 accepts
array (prefers Solana network entries), runs TWZRD preflight, and returns a spending decision.
Side effect: a live 402 observation (resource_url, payTo, price) is upserted into the
service catalog when the catalog database is configured; this tool is not read-only.
wash_flagged=true never soft-allows. Unlabeled leftover 0.05 / leftover=0 is not a unit price.
Decision:
"allow" -> proceed only under agent policy. Never when wash_flagged=true.
"warn" -> proceed with caution up to the cap; first paid hop is teaser_url ($0.001 /quick). Optional V7 receipt_url is $0.05.
"block" -> DO NOT PAY. Stop immediately.
"unknown" -> is_x402 == False: no 402 challenge was issued at all, so nothing was
evaluated -- this is NOT a trust verdict. A seller can trivially make
this happen by returning a non-402 status to this probe while charging
through a different path for a real caller. Never treat "unknown" as
a green light; if the caller actually intends to pay this resource_url,
that separate payment path needs its own evaluation.
Hard-stops:
wash_flagged=true never soft-allows (decision=block).
price_usdc is a unit price only when price_kind=exact. Unlabeled leftover 0.05 /
leftover=0 and scheme=upto leftover defaults are not a per-request price.
Revenue path: when decision is "warn", fetch teaser_url first ($0.001 USDC to TWZRD,
GET /v1/intel/quick/{seller}). Optional receipt_url is the $0.05 V7 signed credential.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | HTTP method to use when probing the resource. Default: GET. | GET |
| price_usdc | No | Caller-supplied exact unit price in USDC — overrides a 402 exact quote. Leave unset to use the 402-reported amount when price_kind=exact. Unlabeled leftover 0.05 / leftover=0 is not a unit price. | |
| agent_intent | No | Natural-language description of what the agent intends to purchase. | |
| resource_url | Yes | URL of the x402 resource to evaluate before paying. Will be fetched to extract 402 payment requirements. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | The evaluated resource URL. | |
| error | No | Error or info message; present on non-402 and degraded paths. | |
| is_x402 | No | True if the resource returned HTTP 402 with x402 payment requirements. | |
| decision | No | Spend decision: "allow" | "warn" | "block" | "unknown". wash_flagged=true never soft-allows — this field is block. "unknown" means is_x402 is False -- no 402 challenge was issued, so no trust evaluation happened. Never treat "unknown" as a green light. | |
| price_kind | No | exact | upto_cap | unknown. upto_cap means price_usdc is not a unit price. | |
| price_usdc | No | Quoted unit price in USDC from the 402 response. Null when the accept is scheme=upto / price_kind=upto_cap, or the figure is unlabeled leftover 0.05 / leftover=0 (not a unit price). | |
| teaser_url | No | First paid hop: $0.001 score-only teaser URL. | |
| receipt_url | No | Optional $0.05 V7 portable receipt URL. | |
| trust_score | No | Composite trust signal, 0-100. | |
| upsell_usdc | No | Cost of the first paid hop in USDC (0.001 teaser). | |
| receipt_usdc | No | Cost of the optional V7 receipt in USDC (0.05). | |
| seller_wallet | No | Seller wallet extracted from the 402 accepts array (Solana preferred). | |
| max_price_usdc | No | Advertised maximum USDC when price_kind is upto_cap. | |
| readiness_card | No | Full readiness card from the preflight evaluation. |