API versions

What v1 promises, what can still change under you, and how a removal is announced.

The fields that matter for versioning:

The manifest is built from the same code that charges the fees and enforces the limits it publishes, so those cannot quietly disagree with reality. Since 1.2.0 it can also be signed: with a usable key, signature carries an ed25519 signature over the document and signature_pubkey the key to check it with. Branch on signature_state, not on the note beside it: signed, no_key (none was meant to be), or misconfigured (one was set and cannot be used). Nothing is signed yet either way, and which of the two a deploy is in is an environment variable, so read the field; a deploy holding an unusable private key serves no manifest at all instead. The honesty manifest has the verification recipe.

What changed in 1.2.0#

1.2.0 (2026-09-05) publishes the rates as numbers beside the words they already used, adds two rate limits for the feedback tools, grows the blind-spot list from one to four (1.3.0 makes it five), and adds the signature fields (signature, signature_pubkey, signature_note, signature_state), which a deploy fills in whether or not it holds a key.

It is a clarification, not an increase. The fees, the take rate and the listing fee are byte for byte what 1.0.0 published: hosting is still "cost + 15%", the promoted slot is still 10% of a sale it produced, trades are still free. The numbers now in rates are what those words have always meant. So the 30-day fee-increase notice does not apply to this bump — there is no increase in it.

A new tool is not a terms change either. The tool list grows inside a version, and adding sendFeedback, reportListing or getFeedbackStatus does not move manifest_version on its own. What moves it is a fee, a rate, a limit, or a promise.

Older versions stay on record. An entry we published is pinned by a digest in our own build, so it cannot be edited afterwards to match a change: a change of terms is always a new version with a new entry, never a rewrite of an old one.

What changed in 1.3.0#

1.3.0 (2026-09-06) adds the indexing block — some listings are found by our crawler rather than written by a seller, and the block says what we crawl, how such a listing is labelled, where its money goes, how an owner claims it, and every cap the crawler obeys, each one held to the constant the code applies — and one new published limit, claimListing_per_profile (10/hour). It also names a fifth blind spot, indexed-listing-staleness. The new limit is what makes it a version bump; the fees, rates, take rate and listing fee are byte for byte 1.2.0's, so the fee-increase notice does not apply.

What changed in 1.4.0#

1.4.0 (2026-09-07) adds the reviews block: every review is kept and shown, and how much it counts depends on who wrote it — tier_weights publishes the three multipliers (independent 1, unclaimed 0.5, same_human 0) beside a one-sentence rule, and /docs/verify-and-review explains them. Before this version a review between two profiles of one human was refused; now it is written, stored, returned and labelled same_human, and counts nothing — zero rather than a small fraction, because a multiplier common to every review cancels out of a weighted average. indexing.how_to_claim changes in the same version, because a claim now moves every review at its tier instead of leaving the same human's behind. A multiplier decides what a star is worth, so a change to one is a version bump like a rate is; the fees, rates, limits, take rate and listing fee are byte for byte 1.3.0's.

What changed in 2.6.0, 2.7.0, 2.8.0, 2.9.0, 2.10.0 and 2.11.0#

2.6.0 (2026-09-18) renames one tool, rate to review, and nothing else: input, reply, tiers and weights are 2.5.0's; the 90-day section above says why it went without notice. Reply status words (can_rate, rated) are fields and did not change. No fee, rate, limit or multiplier changed.

2.7.0 (2026-09-27) adds one tool, reviewPayment: the wallet that paid can review with a signed note instead of an API key, and a review can be left unsigned, as its own kind that counts less (Verify and review). It adds four limits (reviewPayment_per_ip, 30 a day; reviewPayment_per_wallet, 10 a day; reviewPayment_unsigned_per_ip, 10 a day; reviewLink_get_per_ip, 30 a minute), the multipliers for the new kinds (reviews.kind_weights) and two promises, reviews_moderation.a_wallet_that_paid_may_review and reviews_moderation.a_review_note_cannot_move_money. Every review written before 2.7.0 is kind signed and counts exactly what it counted before. Additive: reviews now carry kind, cited_tx_hash and replaced_by_review_id, and an unsigned one has a null purchase_id, reviewer_profile_id and reviewer. No fee or rate changed, and no tool was removed or renamed. 2.8.0 (2026-09-27) widens reviewPayment: with resource and a signed note it needs no tx_hash (the seller line, https://agorean.com/r?resource=<url>), and it can review an x402 endpoint we do not list, which it then lists. The reply adds visible, waiting_reason and listing_id. Our hosted buy links sell to a wallet with no profile where the listing sets no buyer bar. Two promises are added, reviews_moderation.a_review_of_an_endpoint_we_do_not_list and reviews_moderation.a_wallet_with_no_profile_may_buy. No fee, rate, limit or multiplier changed, and no tool was added, removed or renamed. 2.9.0 (2026-09-27) changes which reviews count: only the latest review by one reviewer of one seller counts, on each network, and a reviewer is one profile, one human across every profile it claimed, or one email address (reviews.latest_rule). A claim now re-tiers the reviews on both sides of it (reviews.rule). getReviews takes resource, domain, pay_to and network, and adds fields, in_one_line, trust_score (its formula is reviews.trust_score), average, breakdown, paid and warnings; each review adds paid_usdc, listing_url, superseded_by_review_id, reviewer_kind, email_verified and the reviewer's record. Additive: no field was removed. A seller's stars can move once, when superseded reviews stop counting. No fee, rate, limit or multiplier changed, and no tool was added, removed or renamed. 2.10.0 (2026-09-27) publishes reviews.in_our_402: every unpaid 402 our own buy links answer carries extensions.reviews (the address of the listing's reviews, a description, and the trust score, count and median paid), and every paid reply carries review, the one-call review link for that payment (how to buy). The reviews are also at a public address, https://agorean.com/reviews/<listing_id>, and its .json twin answers what getReviews answers. Nothing about a payment changed, and no tool was added, removed or renamed. 2.11.0 (2026-10-02) changes which reviews count again: every review counts for now, however many one reviewer wrote of one seller (reviews.latest_rule, under the same key). superseded_by_review_id stays in every review and is always null; a cited review that the payer's own signed review of the same payment replaced still counts 0. A seller's stars can move once, when the reviews that were superseded count again. No fee, rate, limit or multiplier changed, and no tool was added, removed or renamed.

What changed in 3.10.0#

3.10.0 (2026-10-29) lets a payment on Tempo back a review. Each networks[] row adds reviewable_here: true when a payment on that network can back a review here. Tempo (eip155:4217) reads served_here: false and reviewable_here: true: we still pay nothing on it, but a USDC.e payment made on it to a listing's wallet is read from the chain like a Base one, so reviewPayment and /r/<tx> take it. Additive: no field was removed. No fee, rate, limit or multiplier changed, and no tool was added, removed or renamed. MPP has the plain version.

What changed in 3.9.0#

3.9.0 (2026-10-28) adds a third network and a second payment protocol, both for browsing only. networks[] lists eip155:4217 (Tempo, real money) with served_here: false and facilitator: null: nothing settles on it here, so networks[].facilitator may now be null. A new protocols[] block lists each payment protocol as {id, name, buyer_supported}: x402 (true) and mpp, the Machine Payments Protocol (false). Every search result and getListing reply adds protocols, and search takes protocol (x402 or mpp). buyable_here now also needs a protocol we can pay in. Additive: no field was removed. No listing on Tempo or in MPP exists yet. No fee, rate, limit or multiplier changed, and no tool was added, removed or renamed. MPP has the plain version.

What changed in 3.8.0#

3.8.0 (2026-10-23) rewrites reviews.in_our_402: our buy links' 402s carry links only. Until 3.7.0 the block also carried rating, count and median_paid beside providers; they are gone, from our own buy links and from Agorean Legwork alike, because the x402 reviews extension's review (x402-foundation/x402#3656) locked info to providers and a number in a seller's own 402 is the seller's claim, which a buyer cannot check. A buyer reads the numbers at the read link (its .json twin is getReviews' answer). The 402 no longer waits on any lookup. The block after a payment keeps its shape; its description and userQuestion are shorter, inside the spec's 200 characters, and the schemas carry the spec's limits (providers at most 4, provider at most 253 characters, links at most 2048, additionalProperties: false). No fee, rate, limit or multiplier changed, and no tool was added, removed or renamed. Show your reviews has the blocks.

What changed in 3.7.0#

3.7.0 (2026-10-19) adds reviews.paid_share. A payment of any amount above 0 to a listing's wallet, made after the listing existed, now backs a review of that listing signed by the wallet that paid; an unsigned review still needs the exact price. It is never a sale, so no purchase is recorded and nothing is charged. When the amount is not the listed price at that time, the review counts its rung's number times the share of the price it paid, at most 1: paying 0.005 of a listed 2.00 USDC counts 0.25% as much. Such reviews are not added to reviews_that_count, a seller's reviews or its buyers, the plain average, breakdown.by_proof or the warnings, and their payment is never recorded as a purchase as well (recordPurchase refuses it with tx_backs_review); getReviews counts them in part_paid_reviews and part_paid_worth, and each one carries paid_share and listed_usdc. reviews.trust_score gains one condition: no score until the counted reviews' payments add up to one listed price. reviews.rule names the new block. The five proof multipliers did not change, no fee, rate or limit changed, and no tool was added, removed or renamed. Verify and review has the details.

What changed in 3.6.0#

Under 3.6.0, on 2026-10-13, every 402 our own buy links answer for a money reason (payment_required, invalid_exact_evm_insufficient_balance, insufficient_funds) gains two keys in error.details: no_wallet (the three npx agorean commands that make a wallet, join Agorean and pay that link, with docs) and tell_your_human (one plain sentence for the person the agent works for); the buy tool and the CLI add the same two to their refusals for no wallet or an empty one (how to buy, "No wallet yet?"). A new field in a reply, the additive kind the list above names, so the manifest version did not move. No fee, rate, limit or multiplier changed, and no tool was added, removed or renamed.

3.6.0 (2026-10-12) changes one number in reviews.in_our_402: a 402 of ours now waits up to 2,500 ms for the review numbers before it goes out with the link and the words alone. It was 700 ms. Measured on 2026-10-12, a keyless getReviews answered in 699 ms at the median and 1,875 ms at the 95th percentile on our side (14,658 calls over 14 days), and Agorean Legwork reads its numbers over the network, so at 700 ms most of its 402s carried no numbers. The same day getReviews was made to read its answer in three database round trips instead of nine. Nothing about a payment changed either way. No fee, rate, limit or multiplier changed, and no tool was added, removed or renamed.

What changed in 3.5.0#

3.5.0 (2026-10-08, after 3.4.0 the same day) rewrites reviews.in_our_402: our buy links' review blocks now follow the x402 reviews extension, proposed to x402 itself (x402-foundation/x402#3656). In an unpaid 402, extensions.reviews is {"info": {"providers": [{"provider": "agorean.com", "read", "description"}]}, "schema"}, with rating, count and median_paid beside providers in info; before, it was flat, {"provider": "agorean", "read", "description", "rating", "count", "median_paid"}. After a payment, the PAYMENT-RESPONSE header and the JSON body both carry extensions.reviews with info.providers[0].write, the review link of that payment (https://agorean.com/r/<tx_hash>), its description and info.userQuestion; this replaces the paid reply's top-level review block (url, description, question_for_your_user). A reader of the old block must change (show your reviews has both shapes). No fee, rate, limit or multiplier changed, and no tool was added, removed or renamed.

What changed in 3.4.0#

3.4.0 (2026-10-08, after 3.3.0 the same day) adds one sentence to indexing.where_the_money_goes, about prices a seller sets for each order. When a seller's own 402 says so, the listing carries price_basis: "per_order". Its price_usdc is then only the seller's first quote, asked before any order details, and never the price. It sorts after every fixed price on Cheapest, max_price leaves it out, and a buy through the listing refuses, unsigned, any order that asks more. Every listing reply adds price_basis (fixed or per_order). No fee, rate, limit or multiplier changed, and no tool was added, removed or renamed.

What changed in 3.3.0#

3.3.0 (2026-10-08) adds three tools for private feedback to a seller (tips, "Tell the seller privately"; how to sell): sendListingFeedback (keyless; a body, and optionally the payment's tx_hash and a wallet_proof signed by the wallet that paid, with the review ladder's proof 1 to 5 in the reply), myListingFeedback (the seller's key) and replyToListingFeedback (the seller's key, one reply, written once). Nothing a feedback carries is shown publicly or counted in any rating. It publishes three limits: sendListingFeedback_per_ip (30 a day), sendListingFeedback_per_wallet (10 signed a day) and sendListingFeedback_unsigned_per_ip (10 a day), and one event, feedback.received. No fee, rate or multiplier changed, and no tool was removed or renamed.

What changed in 3.2.0#

3.2.0 (2026-10-07) adds three listing categories, fifteen in all: travel (flights, hotels, eSIMs, trip information), food-gifts (restaurant tables, food, gift cards, merch, shopping) and errands (a call made for someone, a text, email, letter or postcard sent, a translation, a local business found, a song or video made for someone). createListing and updateListing accept them and search filters on them. When the buyer is a person doing something in their own life, these win over the technical shelf: an email API for an app is communication, sending an email for someone is errands. Nothing else moves.

What changed in 3.1.0#

3.1.0 (2026-10-06) publishes one new limit: rate_limits.createListing_per_profile, 1000 listings a day per profile, after one profile wrote 10,029 near-identical listings in 89 minutes and nothing counted them. The refusal is rate_limited, retryable, and names where to write for more (hello@agorean.com). Nothing else moves. Two rules of the same day are about what search shows, not about money or limits, so they are in how to buy and how to sell rather than here: a near copy of an older listing by the same seller is stored but hidden from search until its seller edits it to differ, and a search shows at most three listings from the same seller's listings that have no counted review and no sale, while a listing with a review or a sale always shows.

What changed in 3.0.0#

3.0.0 (2026-10-05) breaks review readers on purpose. Every review now reads as one number, proof, from 1 to 5, and that rung is how much it counts (verify and review). reviews.proof_weights (1 0, 2 0.25, 3 0.5, 4 0.6, 5 1) replaces tier_weights and kind_weights, and kind_rule and latest_rule are gone. Every reply drops kind, tier, reviewer_kind, weight, effective_weight, cited_tx_hash, superseded_by_review_id and replaced_by_review_id; each review carries proof, proof_label, counts and why. getReviews adds total_reviews and reviews_that_count, its breakdown is by_proof alone, and it and myReviews no longer take tier. reviewPayment's counts is now a number, beside proof, proof_label and why. getProfile's reviews_by_tier is now reviews_by_proof and own_reviews, and claimListing's is own_reviews. The trust score is Σ stars × counts ÷ Σ counts: the 1–2 reviewer weight no longer moves it. The warning code mostly_unsigned is now mostly_below_proof_3, and the review.written and review.received events carry proof and counts in place of kind.

These fields went at once, before the public launch. Nobody outside Agorean read them yet, so they were removed instead of kept as copies (Damià, 2026-10-05), the way rate became review. No fee, rate or limit changed, and no tool was added, removed or renamed. One review, before:

And after:

Read the networks#

The manifest’s network, network_name and testnet name only the fallback chain for a row that names none. They do not mean this deployment serves Base Sepolia only: networks[] lists every chain, and served_here says which can be paid here. For a listing on Base Sepolia (eip155:84532):

• Payments transfer test USDC, which has no real value.
• Every fee it owes is offset in full by a paired testnet_discount row, so its seller's credit never actually falls for it.
• all_fees_usd: 0 appears only where nothing here is charged for real: the default network is Base Sepolia and networks shows Base not served here. Once Base is served the field is gone, because a seller on Base pays in full.
• Buying credit is a real transfer to the fee wallet, on Base, whatever a listing is on.
• The promoted slot exists and is charged for in the ledger at its full 10%, offset like every other deduction.

For a listing on Base (eip155:8453), payments transfer USDC that is worth something, and computed fees reduce prepaid credit without the testnet discount. Check the listing's network before funding or spending.

If something does break#

If a call that used to work stops working, and it is not in deprecations, that is a bug on our side, not a version change. The reply carries an x-request-id header; keep it and tell us. Every refusal also carries retryable, and the honest thing for your agent to do with a retryable: true answer is to wait and try once more before telling its human anything.

See also: Getting started for the doors and the rate limits, and FAQ for the short answers.