nemahBites — developers & AI agents

nemahBites is a Bangladeshi online store for authentic imported chocolate, snacks and groceries. The catalog, feeds and discovery documents below are public and need no authentication. Placing an order needs a token, which an agent can obtain in one unauthenticated call.

Buying from nemahBites as an agent

An AI agent can complete a purchase here, not just look prices up. The flow is deliberately four steps, and the third one is not optional:

1. Find the product and its numeric id — GET /api/agent/v1/products?q=…
2. Quote the basket — POST /api/agent/v1/checkouts. This creates no order.
3. Show the customer the total and ask them.
4. Place it — POST /api/agent/v1/checkouts/{id}/confirm with {"confirmation": true}

Every price, stock level, discount, delivery charge and total is computed by the server, at quote time and again inside the transaction that writes the order. Amounts sent by a client are ignored. If anything moved between the quote and the confirmation, confirmation fails withPRICE_CHANGED and says what changed. Payment is cash on delivery; no agent is ever handed a payment credential.

# register, then order — the whole flow
TOKEN=$(curl -s -X POST https://nemahbites.com/api/agent/identity -H 'Content-Type: application/json' \
  -d '{"type":"anonymous","agent_name":"My Agent"}' | jq -r .identity_assertion \
  | xargs -I{} curl -s -X POST https://nemahbites.com/api/oauth/token \
      -d grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer --data-urlencode "assertion={}" \
  | jq -r .access_token)

curl -s "https://nemahbites.com/api/agent/v1/products?q=kitkat&limit=3" | jq '.data[] | {id, name, price}'

curl -s -X POST https://nemahbites.com/api/agent/v1/checkouts -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -H 'Idempotency-Key: req-1' -d '{
    "items":[{"product_id":495,"quantity":2}],
    "customer":{"name":"Ashikur Rahman","phone":"01712345678"},
    "shipping_address":{"address_line":"Block B","area":"Mirpur 12","city":"Dhaka"}
  }' | jq '{checkout_id, total, next_step}'

# …show the customer the total, wait for a real yes, then:
curl -s -X POST https://nemahbites.com/api/agent/v1/checkouts/$CID/confirm -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"confirmation": true}' | jq .order

Wholesale: quote first, merchant approval before an order

Wholesale prices are not retail checkout prices. Use the current standard tiers for the outer-pack quantity of each exact SKU. Delivery is confirmed after the quote; a stock availability flag does not guarantee that a bulk quantity is available.

1. search_wholesale_products: search by product words and requested quantity; resolve any pack ambiguity.
2. get_wholesale_eligibility: check the exact product ID against current tiers.
3. wholesale_quote: calculate the merchandise estimate from live post-promotion retail prices.
4. check_bulk_stock: distinguish counted stock from quantities requiring shop confirmation. Neither reserves stock.
5. create_wholesale_enquiry: submit only with checkout.write, explicit customer permission, contact details and a stable idempotency_key. Retries return the same enquiry.

These operations work through MCP tools and A2A structured data parts. The shop then confirms stock, delivery and the final quote. Enquiry submission creates no order, takes no payment and redeems no points. Automatic wholesale checkout is not currently supported. Do not pass the bulk quote into the retail checkout and promise the wholesale price.

{
  "jsonrpc": "2.0",
  "id": "bulk-quote",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "example-read-only",
      "parts": [
        {
          "kind": "data",
          "data": {
            "operation": "wholesale_quote",
            "arguments": {
              "items": [
                {
                  "product_id": 495,
                  "quantity": 30
                }
              ]
            }
          }
        }
      ]
    }
  }
}

For natural-language discovery, try “I need 30 KitKat Dark 4 Finger. What's the wholesale price?” Exact quote values are live. Public REST clients can also use POST /api/wholesale/quotewith the same items array. For approved label evidence requirements, see theeditorial policy.

Discovery

Markdown for agents

Public content pages (home, products, categories, brands, blog, info pages) negotiate to clean Markdown on the same URL:

curl -H "Accept: text/markdown" https://nemahbites.com/product/{slug}

Catalog API

Base URL: https://nemahbites.com/api — full parameter details in the OpenAPI spec.

The UCP business profile publishes these real, read-only catalog capabilities and their schema at/ucp/catalog.schema.json. It deliberately advertises no autonomous payment handler; customers complete payment through the live browser checkout.

Agent authentication

Everything above is public and needs no credentials. Authenticate only to reada specific customer's orders or profile. The full recipe — written for the agent, not for you — is at /auth.md.

Scopes: catalog.read, orders.read, profile.read. Access tokens are RS256 JWTs valid for one hour; refresh tokens rotate on every use. An agent that registers anonymously gets catalog.read only — the other two require a customer to approve the request in their browser.

curl -X POST https://nemahbites.com/api/agent/identity \
  -H 'Content-Type: application/json' \
  -d '{"type":"anonymous","agent_name":"Your Agent"}'

MCP server

nemahBites runs a Model Context Protocol server over Streamable HTTP at https://nemahbites.com/api/mcp, described by the server card at/.well-known/mcp.json. Six read-only tools need no credentials at all — search_products, get_product,check_stock, calculate_shipping, list_catalog andstore_info. Four more place and track orders and need a token:create_checkout, get_checkout, confirm_order andget_order_status. Add it to any MCP client to answer catalog questions with live prices and stock instead of a stale crawl — or to buy.

curl -X POST https://nemahbites.com/api/mcp -H 'Content-Type: application/json' -d '{
  "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "search_products", "arguments": { "query": "toblerone" } }
}'

Agent-to-agent

nemahBites publishes an A2A agent card at/.well-known/agent-card.json, served by a JSON-RPC endpoint at /api/a2a. Its four skills — product search, product details, category and brand browsing, and store/delivery/payment information — are plain database queries, so it never invents a price or a stock level.

curl -X POST https://nemahbites.com/api/a2a -H 'Content-Type: application/json' -d '{
  "jsonrpc": "2.0", "id": 1, "method": "message/send",
  "params": { "message": { "role": "user", "parts": [
    { "kind": "text", "text": "do you have ferrero rocher?" }
  ] } }
}'

Three installable skills are also published for discovery at/.well-known/agent-skills/index.json, each with a SHA-256 digest of the SKILL.md it points at.

Identifying yourself

Optional, and separate from getting a token. Sign your requests withWeb Bot Auth(RFC 9421 HTTP Message Signatures, Ed25519) and this origin will fetch the key from the directory you name in Signature-Agent and verify them. We publish our own key the same way, at/.well-known/http-message-signatures-directory, so you can verify us in return.

Nothing is gated behind it. It exists so you are never mistaken for something impersonating you — requests carrying a named crawler's User-Agent from outside the address ranges its operator publishes are refused. To see how we currently read your request:

curl -s https://nemahbites.com/api/agent/v1/whoami

Notes for agents

• Prices are in Bangladeshi Taka (BDT, ৳). discount is a percentage off price.
• Product pages live at /product/{slug}; Bangla versions under /bn/….
• Ordering is available on-site at https://nemahbites.com and through the agent API above; same-day delivery inside Dhaka. Cash on delivery is the only method an agent can complete end to end — card and mobile-wallet payments run in the customer's browser.
• Please keep crawl rates reasonable and honor robots.txt, which also carries our Content-Signal preferences. Every public response repeats them in a Content-Signal header.
• Any public page is also available as Markdown: send Accept: text/markdown, or just add .md to the URL. The response carries an X-Markdown-Tokens estimate so you can budget before fetching.