# Agorantis

> The neutral price and stock layer for people and their AI assistants. Every price has its proof and check time. Shops are ordered by price, then check time, and nothing else.

## Instructions for agents

- Cite the receipt: when you give a person a price, name its shop and its check time, and give its receipt_url, the public page with its proof.
- Show the check time: every price was read at its checked_at. Say when, in the person's time zone when you know it.
- Never present a saved price as live: price_at, cheapest, find, price_history and market_scan answer from saved readings. Say "checked at" and the time, never "now". Only a live_check answered "done" was read for this request.
- Nothing is ranked for money: shops come cheapest first, then by check time, and nothing else (ranked_for_money: false). Never call a shop sponsored, featured or recommended beyond its price.
- Say the honest state: a shop with no price says why (state and why). Tell the person; never guess a price.
- Mind the match: below 1, match_confidence means the product may not be the exact one asked for. At 0.5 or below, or with not_sure, ask the person which product they mean.
- On an error, follow its fix. On too_many_requests wait retry_after seconds. On payment_needed or cap_reached tell the person the fix; never pay or add credits for them.

## Every price

- Every price carries: price (amount and currency), currency, shipping (free, paid with its amount, or unknown), stock, shop (the store: name, domain, country) and store (the branch, when the shop prices by branch), checked_at, proof (the listing and its fingerprint), receipt_url (a public page with the price's proof, no key needed), match_confidence (0 to 1: how sure it is the product asked for; 1 when sent by product_id) and ranked_for_money: false.
- Errors are { ok: false, error, message }, the same over HTTP and MCP; too_many_requests, payment_needed, cap_reached and bad_input also say cause and fix apart. No error is charged.
- Paying by x402 with no key: payment_required (402) says cause and fix apart too, with the price in credits, US dollars and USDC base units.
- Every tool's inputs, every field and every error: https://api.agorantis.com/llms-full.txt and /openapi.json.

Two ways to pay. With a key: send it as `Authorization: Bearer <key>`; each call is paid in credits from the account's balance, with an optional monthly spending cap per key. Free credits are for businesses allowed them at sign-up: 25,000 a month, shared by all the business's keys. They pay for saved prices, product matches and history only, never for live checks or market scans (those need bought or plan credits, and a key). With x402 (supports x402, USDC on Base, no account), for answers given at once (not live checks or market scans, which need a key): call with no key, read the price in the 402 answer (`PAYMENT-REQUIRED` header, or the tool result over MCP), and call again with the signed payment (`PAYMENT-SIGNATURE` header, or `_meta["x402/payment"]` over MCP); it pays the same price in dollars, at $1 = 5,000 credits. A 503 `payment_pending` means the payment is being confirmed: send the same request with the same payment in a minute and do not pay again; the same payment sent again for the same request within 10 minutes of settling gives the very answer it got, never a new one, and is never charged twice; later, or for another request, it gets a new 402. A request that finds no price, proven fact or product costs nothing either way.

## Keys and credits

- Get an agent key, add credits and set each key's monthly spending cap at https://agorantis.com/connections (sign in or sign up there).
- Pay as you go: $1 = 5,000 credits, top-ups from $10, 10% extra credits on top-ups of $25 or more; bought credits last 12 months and are not refunded; paid before use, at https://agorantis.com/connections.
- Claude connectors and ChatGPT apps sign in instead: connect https://mcp.agorantis.com/mcp and approve on agorantis.com; the assistant then holds an agent key of your business.
- Or pay per call with x402, with no account, for answers given at once (live checks and market scans need a key): plain HTTP, or MCP at https://mcp.agorantis.com/x402.

## Tools (MCP, or plain HTTP)

- price_at (POST /v1/price-at, 25 credits ($0.005)): Use when a person asks what a product costs at a shop or brand they name. Send the product and the shop (name or website). Prices come from Agorantis, a neutral price index: shops are ordered by price, then check time, and nothing else; no shop can pay to rank. Every price carries: price (amount and currency), currency, shipping (free, paid with its amount, or unknown), stock, shop (the store: name, domain, country) and store (the branch, when the shop prices by branch), checked_at, proof (the listing and its fingerprint), receipt_url (a public page with the price's proof, no key needed), match_confidence (0 to 1: how sure it is the product asked for; 1 when sent by product_id) and ranked_for_money: false. When you tell a person a price, give its shop, its check time and its receipt_url. A price that was not read right comes back as an honest state instead (unsure, not_sold_here, no_public_price or could_not_check), never a guess: tell the person the state and its reason. If the answer is not_sure with candidates, ask the person which product they mean and call again with its product_id. An error says its code (error), and most say their cause and fix apart: follow fix; on too_many_requests wait retry_after seconds; on payment_needed or cap_reached tell the person the fix, never pay for them.
- cheapest (POST /v1/cheapest, 25 credits ($0.005)): Use when a person asks where a product is cheapest, or for its best price, in a country. Returns every shop with a reading, cheapest first; "cheapest" is the lowest proved price. To name the cheapest of several products, ask for each. Prices come from Agorantis, a neutral price index: shops are ordered by price, then check time, and nothing else; no shop can pay to rank. Every price carries: price (amount and currency), currency, shipping (free, paid with its amount, or unknown), stock, shop (the store: name, domain, country) and store (the branch, when the shop prices by branch), checked_at, proof (the listing and its fingerprint), receipt_url (a public page with the price's proof, no key needed), match_confidence (0 to 1: how sure it is the product asked for; 1 when sent by product_id) and ranked_for_money: false. When you tell a person a price, give its shop, its check time and its receipt_url. A price that was not read right comes back as an honest state instead (unsure, not_sold_here, no_public_price or could_not_check), never a guess: tell the person the state and its reason. If the answer is not_sure with candidates, ask the person which product they mean and call again with its product_id. An error says its code (error), and most say their cause and fix apart: follow fix; on too_many_requests wait retry_after seconds; on payment_needed or cap_reached tell the person the fix, never pay for them.
- find (POST /v1/find, 50 credits ($0.01)): Use when a person names a product loosely, or asks for a kind of product ("cheapest instant coffee"), and you need to know which products it may be, with their sizes, before asking for prices. Search with the brand, the name or what kind of product it is, in English or as the shop names it; try fewer words when nothing comes back. Returns product ids for price_at and cheapest; "same" means the name fits exactly, "not_sure" means the name alone does not settle it: use a product that fits what the person asked for, and ask only when several fit and differ in a way the person must choose. When several fit and a choice is open, either ask which one or show 2 or more that fit with their prices; ask first when the answer rests on something only the person knows (which car it is for). Keep only products that match every detail the person gave (brand, kind, size, color, for whom); a product that misses one is no answer, even with a price; "missed" lists the person's words a product does not hold. Words like big, good, cheap or best are not details to match: answer with what fits and its price. With a country, each product says how many shops there show a price (priced_shops) and the lowest one (lowest): compare those before choosing, and call cheapest for the products you answer with. When nothing that fits has a price, say so in one line and name what has no price. Name a cheapest only from a price these tools returned.
- match_products (POST /v1/match-products, 50 credits ($0.01)): Use when a person asks whether two products are the same ("is the Nescafe Gold 200g at shop A the one at shop B?"), or which product a name is in a country. Send the first product (product, or product_id from find) and either a second product (other or other_id) or a country. Returns match (same, not_sure or different), its confidence from 0 to 1, why, and matched: the product it is in the Agorantis index, with its id for price_at and cheapest. The answer comes from Agorantis's own matching rules (barcode, brand, size, pack and version), never a guess: not_sure means the names alone do not settle it, so ask the person. A not_sure answer costs nothing.
- price_history (POST /v1/price-history, 50 credits ($0.01)): Use when a person asks how a product's price moved, whether now is a good time to buy, or what it cost before. Returns up to 90 days, one point a day per shop (that day's last proved price), each with its proof. Send the product and the country; add a shop for one shop only. Prices come from Agorantis, a neutral price index: shops are ordered by price, then check time, and nothing else; no shop can pay to rank. Every price carries: price (amount and currency), currency, shipping (free, paid with its amount, or unknown), stock, shop (the store: name, domain, country) and store (the branch, when the shop prices by branch), checked_at, proof (the listing and its fingerprint), receipt_url (a public page with the price's proof, no key needed), match_confidence (0 to 1: how sure it is the product asked for; 1 when sent by product_id) and ranked_for_money: false. When you tell a person a price, give its shop, its check time and its receipt_url. A price that was not read right comes back as an honest state instead (unsure, not_sold_here, no_public_price or could_not_check), never a guess: tell the person the state and its reason. If the answer is not_sure with candidates, ask the person which product they mean and call again with its product_id. An error says its code (error), and most say their cause and fix apart: follow fix; on too_many_requests wait retry_after seconds; on payment_needed or cap_reached tell the person the fix, never pay for them.
- live_check (POST /v1/live-check, 50 credits ($0.01) plain site, 150 credits ($0.03) protected, 400 credits ($0.08) heavily protected): Use only when the person needs the price this minute and the saved reading (price_at) is not fresh enough. Checks one product at one shop again now and answers when the reading is back (up to about 20 seconds), as "done". If it is not back in time it answers "queued" with a job_id and no reading (call price_at for the saved one): call live_check again with only that job_id a minute later for the result. Its price is held from the balance when you ask and charged once, when you collect a price: in the call, or later by job_id. A check that fails, or that you do not collect within 7 days, costs nothing and its hold is released; asking again by job_id after paying gives that check's own reading again for 24 hours (then 410), for nothing more. To give up a check the engine has not started, send its job_id with cancel: true: its hold is released, for nothing. A key may have 5 checks open at once, a business 20. It needs an agent key and bought or plan credits: free credits and x402 without a key do not pay for it. Its price depends on the shop's site type, given in the answer. Send the product and the shop's website, or a shop link from an earlier answer. Prices come from Agorantis, a neutral price index: shops are ordered by price, then check time, and nothing else; no shop can pay to rank. Every price carries: price (amount and currency), currency, shipping (free, paid with its amount, or unknown), stock, shop (the store: name, domain, country) and store (the branch, when the shop prices by branch), checked_at, proof (the listing and its fingerprint), receipt_url (a public page with the price's proof, no key needed), match_confidence (0 to 1: how sure it is the product asked for; 1 when sent by product_id) and ranked_for_money: false. When you tell a person a price, give its shop, its check time and its receipt_url. A price that was not read right comes back as an honest state instead (unsure, not_sold_here, no_public_price or could_not_check), never a guess: tell the person the state and its reason. If the answer is not_sure with candidates, ask the person which product they mean and call again with its product_id. An error says its code (error), and most say their cause and fix apart: follow fix; on too_many_requests wait retry_after seconds; on payment_needed or cap_reached tell the person the fix, never pay for them.
- market_scan (POST /v1/market-scan, 1,250 credits ($0.25) for up to 25 sellers, plus 50 credits ($0.01) per seller past 25): Use when a person wants the whole market for a kind of product in a country ("every price for instant coffee in Egypt"), across the products it may be. Returns every shop's reading for each, cheapest first, each with its product. It costs more than cheapest: for one known product, call cheapest instead. It needs an agent key and bought or plan credits: free credits and x402 without a key do not pay for it. Prices come from Agorantis, a neutral price index: shops are ordered by price, then check time, and nothing else; no shop can pay to rank. Every price carries: price (amount and currency), currency, shipping (free, paid with its amount, or unknown), stock, shop (the store: name, domain, country) and store (the branch, when the shop prices by branch), checked_at, proof (the listing and its fingerprint), receipt_url (a public page with the price's proof, no key needed), match_confidence (0 to 1: how sure it is the product asked for; 1 when sent by product_id) and ranked_for_money: false. When you tell a person a price, give its shop, its check time and its receipt_url. A price that was not read right comes back as an honest state instead (unsure, not_sold_here, no_public_price or could_not_check), never a guess: tell the person the state and its reason. If the answer is not_sure with candidates, ask the person which product they mean and call again with its product_id. An error says its code (error), and most say their cause and fix apart: follow fix; on too_many_requests wait retry_after seconds; on payment_needed or cap_reached tell the person the fix, never pay for them.
- get_proof (POST /v1/proof, free): Use when a person asks how a price is known, or to show its evidence. Send a price's proof.fingerprint, copied whole. Returns the shop's page it was read from, the saved price snippet, a screenshot when one was kept, and when it was checked. Free.
- account_usage (POST /v1/usage, free): Use to see this key's month: requests made, the account's free credits left, credits and money spent, the account's credit balance, and the key's monthly spending cap and what is left of it. Free.

## Countries

- Covered countries: EG, AE, SA, KW, QA, BH, OM, JO, MA, US, GB, DE. Prices are read at shops in these countries only; a country not listed finds nothing and costs nothing.

## Limits

Rate limits, shared by every Worker instance: each key 10 a second unless raised, and all keys of one business 20 a second together; calls with no key 300 a minute from one address, at most 30 in a second. Unknown agent keys: 300 a minute from one address, and only they are held back: a key that worked in the last 30 days, or that sign-in gave, is never refused for the address it comes from. Sign-in: the pages a person's browser opens (/authorize) 30 a minute from one address and 10 failed sign-ins a minute per account; /token 120 accepted calls a minute per assistant's client and 300 refused calls a minute from one address; /register 1,000 an hour from one address. Open live checks: 5 a key, 20 a business. The public files (llms.txt, openapi.json, the receipt keys, the OAuth metadata, health) count against no limit. A call past a limit gets 429 with Retry-After and the RateLimit headers; its body names the limit met and the seconds to wait. Nothing is charged for it.
Each paying wallet (x402): 10 a second and 300 a minute.

## Honest states

- priced: the price any shopper pays now for one unit, with proof
- unsure: readings did not agree or carry no proof, so no price is shown
- not_sold_here: the shop's own catalog or search shows it does not sell this product
- no_public_price: the shop shows no price to a logged-out shopper
- could_not_check: the shop turned the check away, or was not checked yet

## Receipts

- Every price shown carries a signed receipt beside its proof: Ed25519 over the canonical JSON of the values shown (shop, listing, product, price, currency, stock, check time, proof), with its key_id, issued_at and how it was read. It holds nothing about who asked, so it can be handed on.
- Our public keys, every one ever used: /.well-known/agorantis-receipt-keys.json. The open format, a 10-line check, and a page that checks a receipt in your browser: https://agorantis.com/receipts

## Addresses

- MCP (streamable HTTP): https://mcp.agorantis.com/mcp (also at https://mcp.agorantis.com), with a key or by signing in (OAuth 2.1: /.well-known/oauth-protected-resource)
- MCP paying per call with x402, no account: https://mcp.agorantis.com/x402
- Plain HTTP: POST https://api.agorantis.com/v1/<tool>, a JSON body
- OpenAPI: /openapi.json