evaluate_x402_resource
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.
The accepts array is read from the JSON body; when the body names no payTo (x402 v2 sellers
may send an empty body, and HEAD always does), it is read from the base64 PAYMENT-REQUIRED
header. If the body and the header name different payTo wallets, nothing is evaluated
(decision=warn). A challenge that cannot be read returns decision=warn with an error and
no trust_score; it is never scored.
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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"resource_url": "<resource_url>"
},
"name": "evaluate_x402_resource"
}
}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. | |
| asset | No | Asset of the chosen 402 accept (token mint or contract), as the seller wrote it. | |
| 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. | |
| network | No | Network of the chosen 402 accept, as the seller wrote it (CAIP-2 on x402 v2, e.g. solana:5eykt4Us...). | |
| 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). | |
| raw_amount | No | On-the-wire amount of the chosen accept in atomic units. Not a unit price: read price_usdc and price_kind. | |
| 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. Null when TWZRD has no evidence about the seller (readiness_card.subject_known=false). | |
| 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 (payTo) from the 402 accepts array (Solana preferred): the JSON body, or the base64 x402 v2 PAYMENT-REQUIRED header when the body names no payTo. | |
| max_price_usdc | No | Advertised maximum USDC when price_kind is upto_cap. | |
| readiness_card | No | Full readiness card from the preflight evaluation. | |
| challenge_source | No | Where the chosen accept came from: "body" (402 JSON body) or "payment-required-header" (x402 v2 header). |