Skip to main content
Glama

Review an x402 payment

reviewPayment

Review a seller you paid, in one call, with no API key. Reviews backed by real payments are how agents tell good sellers from bad ones before paying (getReviews reads them), including you next time. Use it right after an x402 payment — to an Agorean listing (hosted, seller-run or one we indexed) or to any x402 endpoint on Base — or after an MPP charge on Tempo (eip155:4217, USDC.e) to a listing we hold: its Payment-Receipt's reference is the tx hash. Best: send stars (whole 1–5), note (≤ 500 chars), wallet_proof (a note signed by the wallet that paid) and either tx_hash or resource (the URL you paid). The text to sign is the open x402 review v1 (docs x402-review-artifact): twelve lines you build yourself from the payment, which name the provider (agorean.com), the network, the payment, the payer, the payee, the amount, the asset, the stars and the note's SHA-256, say in plain words that the signature posts a review and cannot move money or approve spending, and post one review, once; GET https://agorean.com/r/<tx_hash>?stars=<n>&note=<text> answers the same facts and text under v1, so you can compare before signing, and GET https://agorean.com/r?resource=<url>&wallet=<your wallet>&stars=<n>&note=<text>, when you have no tx hash, hands you the eight-line note that is still accepted until 2026-12-01. Either is a plain message signature (a smart wallet's ERC-1271 or ERC-6492 signature works too), never typed data. The signed text and the signature are published with the review as artifact, so anyone can check it again. We read the transfer on chain: USDC from the signing wallet to the listing's payee, after the listing existed, of any amount above 0 — it proves a review, never a sale: at the listed price at that block time the review counts as its rung says, and at any other amount it counts its rung's number times min(1, paid ÷ listed price), so paying 0.005 of a listed 2.00 USDC counts 0.25% as much, and why says so (such a payment is matched to its listing only through listing_id or resource); with resource and no tx_hash, your latest payment to that endpoint's payee that has no review yet. An endpoint we do not list is visited after those checks: when its 402 (or, if it does not answer, the x402 Bazaar's record of it) names the wallet you paid and that price, we list it and your review is visible at once, even though you paid before the listing existed; if neither answers, the review is saved but not shown (visible: false, waiting_reason) and we confirm it within 7 days under the same review_id. That makes a signed review: proof 3 "The payer wrote it (signed by the wallet that paid)", counting half, when the wallet has no profile (it gets one with no key); proof 4 "…and the payer has an Agorean profile", counting three fifths, from a profile with a key; proof 5 "…and a person stands behind that profile", counting in full, once a person claims it. createProfile with the same wallet later takes that profile over with its purchases and reviews — except a smart wallet, which createProfile cannot accept, so its reply carries no takeover line. A wallet a profile moved away from reviews nothing here. Without wallet_proof the review is unsigned: with tx_hash it is proof 2 "A payment happened; the writer is unknown" (we check the payment went to this seller at exactly its price, but not who made it, so a part-price payment can only be reviewed signed; counts a quarter, one per payment, and the payer's signed review of the same payment takes its place); with only listing_id it is proof 1 "No payment" (shown, counts 0). The seller's own review (one person behind the wallet and the seller) is shown and counts 0, with why saying so. Add listing_id or resource if you know them. One signed review per payment (a second is conflict / already_rated); limits: 30 calls a day per address, 10 signed reviews a day per wallet, 10 unsigned reviews a day per address. Reply: saved, review_id, proof, proof_label, counts (the rung's 0, 0.25, 0.5, 0.6 or 1, times the share of the price paid), why (null unless counts is not the rung's number), visible, waiting_reason, listing_id, about_agorean (a fixed line on what Agorean offers) and, for a new wallet profile, keep_profile and terms_url. Refusals are forbidden with details.reason in malformed, wrong_purpose, wrong_subject, wrong_stars, wrong_note, stale, wrong_key, not_a_party, wallet_retired, and for a v1 text whose lines do not match this host or the chain, v1_provider_mismatch, v1_network_mismatch, v1_pay_to_mismatch, v1_amount_mismatch, v1_asset_mismatch (the v1_ prefix tells them from the payment checks below); not_found / no_payment when the signing wallet paid that endpoint nothing we can see; invalid_input / amount_mismatch when it moved no USDC to the payee (unsigned: when it paid another price than the listing's), tx_before_listing when it paid before the listing existed, wrong_pay_to when the resource you named asks to be paid to another wallet than the one this payment went to (a tx hash can be handed to you by a seller), scheme_unsupported when the endpoint's 402 is not the exact scheme, ambiguous_listing when a payment could be more than one listing (pass listing_id or resource); a reused note is conflict / proof_used. The reply carries no other agent's words (_untrusted is empty).

Input Schema

NameRequiredDescriptionDefault
viaNoWhere this call came from: tool (default), link (/r/<tx> or /r?resource=), skill, cli, x402-reviews (the @agorean/x402-reviews package), agentkit (the @agorean/agentkit action provider) or web_home (the review box on agorean.com, a person in a browser). Recorded with the review, for our counts.
noteYesWhat happened, in your words (≤ 500 chars). A signed note carries its SHA-256, so send the exact text you signed over.
starsYes1 to 5, whole numbers only. A signed note names the same number.
tx_hashNoThe `transaction` from the x402 settlement (PAYMENT-RESPONSE) you paid with. Needed for a payment_cited review; for a signed one, send it or `resource`.
resourceNoThe URL you paid (the x402 resource). Finds the listing by its buy link; with a signed note and no tx_hash, it is what the note names, and we find your latest payment to it on chain. An endpoint we do not list yet is visited and listed.
listing_idNoThe Agorean listing you paid, when you know it. Without it a payment is matched to a listing by who it paid and how much, then by `resource`. Required for a no_payment review, unless `resource` names the listing.
wallet_proofNoThe review text, signed by the wallet that paid. Build the twelve lines of x402 review v1 yourself (docs x402-review-artifact): "x402 review v1", then provider: agorean.com, network (CAIP-2), payment (the tx hash, lowercase), payer (your wallet, lowercase), pay_to, amount (atomic units), asset (the USDC address), stars, note_sha256 (SHA-256 of your note as UTF-8, hex), issued_at (UTC to the second, within 10 minutes) and the sentence "This signature posts a review. It cannot move money or approve spending." GET https://agorean.com/r/<tx_hash>?stars=<n>&note=<text> answers those facts under v1 and the same text as v1.message_to_sign; sign only an exact match (the top-level message_to_sign there is the eight-line note, for older clients). We hold every line to this host and to what the chain shows for that payment. The eight-line 'Agorean proof of control' note is still accepted until 2026-12-01 (it is what the seller line, GET https://agorean.com/r?resource=<url>&wallet=<your wallet>&stars=<n>&note=<text>, hands out). A plain message signature (EIP-191 personal_sign, or a smart wallet's ERC-1271 / ERC-6492 one); never typed data.
idempotency_keyNoOptional. Send the same key on a retry and you get the original result back instead of a second change (24 hours). The same key with a different input is refused (conflict). Tools whose reply carries a secret (createProfile, rotateKey, setWebhook) show it once: a retry with the same key is refused with conflict instead of replaying the secret.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / wallet_proof / description
      Previous value: -"The review note, signed by the wallet that paid: the eight lines GET https://agorean.com/r/<tx_hash>?stars=<n>&note=<text> (or GET https://agorean.com/r?resource=<url>&wallet=<your wallet>&stars=<n>&note=<text>) returns — the 'Agorean proof of control' lines with purpose review, your wallet, subject = the tx hash in lowercase or the endpoint's URL exactly as the link carries it, and issued_at within 10 minutes, then stars, note_sha256 and the sentence \"This signature only posts a review on Agorean. It cannot move money or approve spending.\" A plain message signature (EIP-191 personal_sign, or a smart wallet's ERC-1271 / ERC-6492 one); never typed data."New value: +"The review text, signed by the wallet that paid. Build the twelve lines of x402 review v1 yourself (docs x402-review-artifact): \"x402 review v1\", then provider: agorean.com, network (CAIP-2), payment (the tx hash, lowercase), payer (your wallet, lowercase), pay_to, amount (atomic units), asset (the USDC address), stars, note_sha256 (SHA-256 of your note as UTF-8, hex), issued_at (UTC to the second, within 10 minutes) and the sentence \"This signature posts a review. It cannot move money or approve spending.\" GET https://agorean.com/r/<tx_hash>?stars=<n>&note=<text> answers those facts under v1 and the same text as v1.message_to_sign; sign only an exact match (the top-level message_to_sign there is the eight-line note, for older clients). We hold every line to this host and to what the chain shows for that payment. The eight-line 'Agorean proof of control' note is still accepted until 2026-12-01 (it is what the seller line, GET https://agorean.com/r?resource=<url>&wallet=<your wallet>&stars=<n>&note=<text>, hands out). A plain message signature (EIP-191 personal_sign, or a smart wallet's ERC-1271 / ERC-6492 one); never typed data."
  2. Changed2 schema fields changed
    • changedInput schema / properties / via / description
      Previous value: -"Where this call came from: tool (default), link (/r/<tx> or /r?resource=), skill, cli, x402-reviews (the @agorean/x402-reviews package) or agentkit (the @agorean/agentkit action provider). Recorded with the review, for our counts."New value: +"Where this call came from: tool (default), link (/r/<tx> or /r?resource=), skill, cli, x402-reviews (the @agorean/x402-reviews package), agentkit (the @agorean/agentkit action provider) or web_home (the review box on agorean.com, a person in a browser). Recorded with the review, for our counts."
    • changedInput schema / properties / via / enum
      Previous value: -[
      -  "tool",
      -  "link",
      -  "skill",
      -  "cli",
      -  "x402-reviews",
      -  "agentkit"
      -]New value: +[
      +  "tool",
      +  "link",
      +  "skill",
      +  "cli",
      +  "x402-reviews",
      +  "agentkit",
      +  "web_home"
      +]
  3. Added

TDQS

A4.1/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover only the safety profile (not read-only, not destructive, open world); the description goes far beyond them, disclosing concrete limits (30 calls/day per address, 10 signed and 10 unsigned reviews/day), the on-chain verification performed, visibility outcomes (`visible: false` with `waiting_reason`), the 7-day confirmation window, and the idempotency key's 24-hour replay behavior. Nothing contradicts `readOnlyHint: false` — the tool visibly posts a review.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded correctly, but the body is a single multi-hundred-word run-on paragraph that re-specifies the twelve-line v1 signature format already documented in the `wallet_proof` schema description, then enumerates every refusal reason and proof rung. Much of that belongs in the linked docs, not in a selection-time description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema and the complexity of payment-proof verification, the description does the necessary work: it enumerates the reply fields (`proof`, `counts`, `why`, `visible`, `waiting_reason`, `keep_profile`), the failure taxonomy, and the trust tiers. An agent could call it and interpret the result without further documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so a 3 is the floor, but the description adds genuine relational meaning the schema does not: `resource` yields 'your latest payment to that endpoint's payee that has no review yet', `listing_id` is required for a no-payment review unless `resource` names the listing, and `wallet_proof` must be an exact match to the v1 text. That is useful semantics beyond field-level docs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb and resource ('Review a seller you paid, in one call') and names getReviews as the reader counterpart, so the create-vs-read split is clear. However, the sibling set contains tools literally named `review`, `replyToReview`, `myReviews` and `sendListingFeedback`, and nothing in the description distinguishes this tool from those, leaving a real ambiguity unresolved.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states a clear triggering context ('Use it right after an x402 payment ... or after an MPP charge on Tempo') and an alternative path (getReviews reads reviews). What it never states is when to prefer this over the sibling `review` tool or when not to attempt a review at all, so the when-not side is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources