Skip to main content
Glama

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. 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, exactly its price, after the listing existed; 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 its price, but not who made it; 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 (0, 0.25, 0.5, 0.6 or 1), 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 paid another price, 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

TableJSON 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.6/5.0
Behavior5/5

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

With annotations declaring readOnlyHint=false and openWorldHint=true, the description adds substantial behavioral context: on-chain payment verification, signed versus unsigned proof levels, visibility and waiting states, rate limits, idempotency behavior, conflict cases, and detailed refusal reasons. This goes far beyond structured annotations and makes the mutation behavior transparent.

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?

The purpose is front-loaded, but the body is an enormous single paragraph that reads as a wall of text rather than a structured definition. Much of the detail is relevant, but the lack of division and the sheer length make it poorly sized and hard to scan.

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?

Although there is no output schema, the description lists the reply fields (saved, review_id, proof, counts, visible, waiting_reason, etc.) and comprehensively covers proof semantics, refusals, rate limits, and edge cases. For a complex write tool with nested parameters, this is complete enough for correct invocation.

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 description coverage is 100%, so the schema already documents all parameters in detail, which establishes a baseline of 3. The description still adds workflow meaning by explaining how wallet_proof, tx_hash, resource, and listing_id interact, when each is needed, and how the signed text relates to the payment.

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

Purpose5/5

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

The first sentence states a specific verb and resource: review a seller you paid, in one call, with no API key. It explicitly distinguishes itself from the read-side sibling getReviews by saying that getReviews reads the reviews. An agent can tell what this tool does without opening the schema.

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

Usage Guidelines5/5

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

The description gives explicit timing ('Use it right after an x402 payment'), supported contexts (Agorean listings or any x402 endpoint on Base), and recommended parameters. It also names getReviews as the alternative for reading reviews, so the when-to-use versus sibling distinction is clear.

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