# Agorantis

> The truth layer for AI shopping. Agorantis gives people, businesses and their AI agents the price and stock of a product at a shop, each with the page it came from and the time it was checked.

The rule: no one can pay to rank higher, and no one gets hidden.

Who it is for: businesses that sell anything and want to see the whole market, people who shop with an AI assistant, and the builders of AI agents.

What it costs: free to start. Store plans from USD 19.99 a month. For agents, an answer costs from half a cent, and a failed one costs nothing.

## 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.

## Pages

- [Agorantis](https://agorantis-app.eyad-172.workers.dev/): the home page
- [For AI agents](https://agorantis-app.eyad-172.workers.dev/agents): what an agent can ask, and how to connect it
- [Connect your AI](https://agorantis-app.eyad-172.workers.dev/connect): one address for Claude, ChatGPT, Cursor, VS Code or any MCP client
- [Pricing](https://agorantis-app.eyad-172.workers.dev/pricing): store plans and what an answer costs
- [Product prices](https://agorantis-app.eyad-172.workers.dev/price): the saved prices of a product at real shops, each with its check time
- [Price receipts](https://agorantis-app.eyad-172.workers.dev/receipts): the open receipt format, and a check that runs in your browser
- [Trust and security](https://agorantis-app.eyad-172.workers.dev/trust): the neutral rule and how data is kept
- [About Agorantis](https://agorantis-app.eyad-172.workers.dev/about): who we are

## For AI agents

- [Agent service llms.txt](https://mcp.agorantis.com/llms.txt): the agent service's own file, with its tools and terms
- [MCP address](https://mcp.agorantis.com/mcp): add it to any MCP client
- [Your first call](https://agorantis-app.eyad-172.workers.dev/agents/first-call): a free key, one command and a real answer
- [llms-full.txt](https://agorantis-app.eyad-172.workers.dev/llms-full.txt): every field, price and error, a first call and a real answer

## Your first call

- Get a free key at https://agorantis-app.eyad-172.workers.dev/agents#key (sign up free). Put it in AGORANTIS_KEY, then run:

```
curl -X POST https://api.agorantis.com/v1/cheapest \
  -H "Authorization: Bearer $AGORANTIS_KEY" \
  -H "content-type: application/json" \
  -d '{"product":"Nescafe Gold 200g","country":"EG"}'
```

- Or connect over MCP at https://mcp.agorantis.com/mcp: Claude and ChatGPT sign in with an Agorantis account; any other MCP client takes these settings:

```json
{
  "mcpServers": {
    "agorantis": {
      "type": "http",
      "url": "https://mcp.agorantis.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AGORANTIS_KEY"
      }
    }
  }
}
```

## What an answer looks like

```json
{
  "ok": true,
  "product": {
    "id": 1042,
    "name": "Nescafe Gold Instant Coffee 200g",
    "brand": "Nescafe",
    "size": "200g"
  },
  "results": [
    {
      "state": "priced",
      "shop": {
        "name": "Shop A",
        "domain": "shop-a.example",
        "country": "EG"
      },
      "address": "https://shop-a.example/nescafe-gold-200g",
      "price": {
        "minor": 39500,
        "amount": "395.00",
        "currency": "EGP",
        "was_minor": 42000,
        "from": false
      },
      "currency": "EGP",
      "shipping": {
        "state": "free",
        "minor": 0,
        "amount": "0.00"
      },
      "stock": "in_stock",
      "checked_at": "2026-11-15T07:41:00.000Z",
      "proof": {
        "listing": "https://shop-a.example/nescafe-gold-200g",
        "fingerprint": "pf_8c41e2",
        "snippet": "EGP 395.00",
        "checked_at": "2026-11-15T07:41:00.000Z"
      },
      "receipt": {
        "v": "0.1",
        "key_id": "21fe31dfa154a261",
        "issued_at": "2026-11-15T09:12:03.000Z",
        "read": "page",
        "sig": "kOiq03shA3BWL9XCt0m26hHYS68zfzVI5YyHpJXLHXUS3mSA86vP_vaTX1dx9W-oTCfm85zsof5aKoBqLw5tBA"
      },
      "receipt_url": "https://api.agorantis.com/receipt/pf_8c41e2",
      "match_confidence": 0.9,
      "ranked_for_money": false,
      "store": null,
      "fresh": false,
      "fresh_check": "not_available",
      "why": "read from the shop's own page; last checked 2026-11-15T07:41:00.000Z; call live_check for a fresh check of this shop"
    },
    {
      "state": "not_sold_here",
      "shop": {
        "name": "Shop B",
        "domain": "shop-b.example",
        "country": "EG"
      },
      "address": "https://shop-b.example/search?q=nescafe+gold",
      "price": null,
      "currency": null,
      "shipping": {
        "state": "unknown",
        "minor": null,
        "amount": null
      },
      "stock": "not_shown",
      "checked_at": "2026-11-15T06:58:00.000Z",
      "proof": null,
      "receipt_url": null,
      "match_confidence": 0.9,
      "ranked_for_money": false,
      "store": null,
      "fresh": false,
      "fresh_check": "not_available",
      "why": "the shop's own search does not list it; last checked 2026-11-15T06:58:00.000Z; call live_check for a fresh check of this shop"
    }
  ],
  "cheapest": {
    "state": "priced",
    "shop": {
      "name": "Shop A",
      "domain": "shop-a.example",
      "country": "EG"
    },
    "address": "https://shop-a.example/nescafe-gold-200g",
    "price": {
      "minor": 39500,
      "amount": "395.00",
      "currency": "EGP",
      "was_minor": 42000,
      "from": false
    },
    "currency": "EGP",
    "shipping": {
      "state": "free",
      "minor": 0,
      "amount": "0.00"
    },
    "stock": "in_stock",
    "checked_at": "2026-11-15T07:41:00.000Z",
    "proof": {
      "listing": "https://shop-a.example/nescafe-gold-200g",
      "fingerprint": "pf_8c41e2",
      "snippet": "EGP 395.00",
      "checked_at": "2026-11-15T07:41:00.000Z"
    },
    "receipt": {
      "v": "0.1",
      "key_id": "21fe31dfa154a261",
      "issued_at": "2026-11-15T09:12:03.000Z",
      "read": "page",
      "sig": "kOiq03shA3BWL9XCt0m26hHYS68zfzVI5YyHpJXLHXUS3mSA86vP_vaTX1dx9W-oTCfm85zsof5aKoBqLw5tBA"
    },
    "receipt_url": "https://api.agorantis.com/receipt/pf_8c41e2",
    "match_confidence": 0.9,
    "ranked_for_money": false,
    "store": null,
    "fresh": false,
    "fresh_check": "not_available",
    "why": "read from the shop's own page; last checked 2026-11-15T07:41:00.000Z; call live_check for a fresh check of this shop"
  },
  "ranked_for_money": false,
  "usage": {
    "free": true,
    "price_credits": 25,
    "price_usd": "0.005",
    "credits": 25,
    "charged": true
  }
}
```

## Prices in plain units

- One saved price = USD 0.005 = 25 credits. USD 1 buys 5,000 credits. A call that finds nothing costs nothing.
- price_at: 25 credits, USD 0.005, by x402 too
- cheapest: 25 credits, USD 0.005, by x402 too
- find: 50 credits, USD 0.01, by x402 too
- match_products: 50 credits, USD 0.01, by x402 too
- price_history: 50 credits, USD 0.01, by x402 too
- live_check: 50+ credits, USD 0.01+, key only
- market_scan: 1,250+ credits, USD 0.25+, key only
- get_proof: free, no key needed
- account_usage: free, key only
- live_check costs 50, 150 or 400 credits, by how hard the shop's site is to read. market_scan costs 1,250 credits for up to 25 sellers, then 50 credits a seller.

## Errors

- too_many_requests: A rate limit. Wait retry_after seconds (also the Retry-After header), then send the same call.
- payment_needed: Out of credits. Add credits at agorantis.com/connections; the answer names the price.
- cap_reached: The key's monthly spending cap is met. Raise it at agorantis.com/connections, or wait for next month.
- payment_required: No key, paying by x402: pay the price in accepts and send the same call again.
- bad_input: The request is not right. cause says what, fix says what to send.

## Each tool's inputs

- [The agent service's llms-full.txt](https://mcp.agorantis.com/llms-full.txt): every tool's inputs and every error code, from the service itself