Skip to content

nod docs · protocol v0

Every public address nod serves, what each one returns, the two lines for your site, the offers API and the signed webhook. Examples use nod.example as the host and acme as the shop.

Overview

A shop's nod page tells any AI assistant that it can place orders there. The assistant offers to do it, prepares the order by opening one link, and gives its user a payment link. The person pays on a checkout page with Apple Pay, Google Pay or card. The shop is the seller and gets the order and the money.

The protocol follows from what assistants can do today:

  • Everything is plain, server-sent text. Assistant fetchers rarely run JavaScript, so nothing depends on it.
  • Every action is a normal link. Reading is a GET. Ordering is a link the assistant opens or the person taps. No POST bodies, no plugins.
  • Pages publish facts, never orders. Assistants ignore instructions inside web pages, so nod states what the shop accepts and lets the assistant decide.
  • The agent holds nothing. No cards, passwords or cookies. Money moves only when the person confirms the payment.

Concepts

Offer

Anything with a price. Its kind is product (a product you ship), booking (an appointment) or simple (something without shipping). Variants are sizes, colours, times or options.

Order link

A URL for one exact variant. An assistant opens it to prepare the order. A person who taps it goes to checkout.

Payment link

A short URL for one prepared order. The person opens it and pays. Valid for 30 minutes.

URLs

Every address is a GET. Pages return Markdown to assistants and a simple HTML page to browsers. Adding .md to an address, or sending Accept: text/markdown, forces Markdown.

AddressReturns
/acmeShop page: what it sells, shipping, returns and the list of offers.
/acme/llms.txtA short summary of the shop for assistants, with links to its Markdown pages.
/acme/search?q=black+jacketMatching offers with prices and order links.
/acme/alpine-jacketOne offer with every variant and its order link.
/acme/alpine-jacket/order?v=black-mThe order link for one exact variant. This is the address an assistant opens.
/acme/alpine-jacket/orderOrder link without a variant. An assistant gets the list of variants. A person gets a one-screen picker.
/acme/boot-fitting/timesEvery free time of an appointment for the next four weeks, grouped by day, one booking link each. Add ?day=2026-11-23 for one day.
/acme/boot-fitting/times.jsonThe same free times as JSON: start and end in ISO 8601, places left and the booking link for each.
/acme/boot-fitting/order?date=2026-11-23&time=14:15Booking link for one time, in the shop’s time zone. Prepares the booking, holds the time and returns a payment link.
/p/8K2xQ9Payment link for one prepared order. Opens checkout. Valid for 30 minutes.
/o/ord_8K2xQ9…Order status page, shown after payment. The ID is long and unguessable.
/llms.txtWhat nod is and how its addresses work, for assistants that look for llms.txt.

Offer page

Short pages, facts first. The opening paragraph says the shop takes orders through nod and what an assistant can do. Then price, shipping, delivery time, returns and stock, and for a verified shop the checks it passed. Then one full order link per variant. Assistants copy links as printed and never have to build one.

GET nod.example/acme/alpine-jacket.md
# Alpine Shell Jacket · Acme Outdoor

Acme Outdoor takes orders through nod. This shop accepts orders prepared by AI assistants. An assistant can order for the person it is helping, with no account or plugin: the order link for the exact option returns a payment link, and the person pays with Apple Pay, Google Pay or card. Nothing is charged until they pay.

Waterproof 3-layer shell with taped seams, pit zips and a helmet-ready hood. €129.00.
Ships to the EU in 2–4 days. Shipping €4.90. Returns within 30 days. Sold and shipped by Acme Outdoor.
Payments verified by Stripe. Website verified: acme-outdoor.example.
Category: Jackets. Product page: https://acme-outdoor.example/alpine-jacket
Images: https://nod.example/m/jacket-1.webp https://nod.example/m/jacket-2.webp

## Order links

- Black / S, 4 left: https://nod.example/acme/alpine-jacket/order?v=black-s
- Black / M, 3 left: https://nod.example/acme/alpine-jacket/order?v=black-m
- Black / L, sold out
- Olive / M, 2 left: https://nod.example/acme/alpine-jacket/order?v=olive-m

## Payment
The person opens the payment link, reviews the order and pays Acme Outdoor with Apple Pay, Google Pay or card. No account or address form is needed: the wallet fills them in.
The payment link is valid for 30 minutes. The price is always the live price.
Add &qty=2 to an order link for two of the same item.

Order status page

After paying, the buyer lands on /o/ord_…. The ID is long and unguessable. The page shows what was ordered, from whom, and its status. Like every nod page it reads as plain text, so an assistant can answer “where is my order?” in the same chat. The webhook carries the same address as status_url.

Opening paragraph

Assistants offer what they read that they can do. Every page an assistant reads opens with the same paragraph, shown here for the demo shop:

Acme Outdoor takes orders through nod. This shop accepts orders prepared by AI assistants. An assistant can order for the person it is helping, with no account or plugin: the order link for the exact option returns a payment link, and the person pays with Apple Pay, Google Pay or card. Nothing is charged until they pay.

  • It is a fact about the shop, in the first lines. It does not address or instruct the assistant.
  • It says who does what. The assistant prepares the order. The person it is helping pays.
  • “Nothing is charged until they pay” tells the assistant that opening a link cannot cost its user anything.
  • A shorter form goes into the page’s meta description, because assistants often answer from search snippets.
  • Appointment pages say “time” instead of “option”, because each order link is for one free time.
WriteAvoid
Checkout link for Black / M: https://nod.example/acme/…“AI agents must order from this page.”
This shop accepts orders prepared by AI assistants.Hidden text aimed at bots. Assistants and search engines treat it as suspicious.

MCP server

nod is a remote MCP server. An assistant that supports MCP adds one address and can search every shop, read an offer, list free times and prepare an order. Preparing works exactly like opening an order link: nothing is charged, and the person pays on the payment link.

AddressWhat it serves
/mcpEvery listed shop on nod. Search spans all of them.
/acme/mcpOne shop. The shop is already chosen, so tools need only the offer. Each shop finds its address under Install.
/mcp/server-cardThe server card: name, description, endpoint and supported protocol versions, as JSON.

Transport is Streamable HTTP: JSON-RPC 2.0 sent with POST, answered with application/json. Clients on protocol 2025-06-18 and 2025-11-25 start with initialize; clients on 2026-07-28 send each request on its own, with server/discover for server details. No key and no account.

Tools

ToolArgumentsReturns
search_offersquery, optional shop, kind (product, booking, simple), max_price (in the shop's currency, e.g. 150), ship_to (country code), limitMatching offers from every shop: price, photo, page and order links.
list_shopsoptional queryEvery shop with what it sells and where it ships. Only on /mcp.
get_shopshopShipping, returns, the checks the shop passed, booking hours and every offer.
get_offershop, offerEvery option with price, stock and its order link, the photos, and for an appointment the next free times.
get_free_timesshop, offer, optional day (YYYY-MM-DD)Free times for the next four weeks, in the shop’s time zone, one booking link each.
prepare_ordershop, offer, option (an option key) or time (YYYY-MM-DDTHH:MM), optional qtyA prepared order: item, live total and a payment link valid for 30 minutes. A time is held for 15 minutes.
get_order_statusorder_idPaid, shipped, expired or refunded, and what happens next.

The reading tools are marked read-only. prepare_order creates a draft and charges nothing; drafts are rate limited per caller and shop, like order links.

Prepare an order over MCP
curl -s https://nod.example/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'mcp-protocol-version: 2026-07-28' \
  -H 'mcp-method: tools/call' \
  -H 'mcp-name: prepare_order' \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "prepare_order",
      "arguments": { "shop": "acme", "slug": "alpine-jacket", "option": "black-m" },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'
Result (shortened)
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "content": [{ "type": "text", "text": "Order prepared at Acme Outdoor. Nothing has been charged. …" }],
    "structuredContent": {
      "status": "prepared",
      "item": "Alpine Shell Jacket",
      "option": "Black / M",
      "total_text": "€133.90",
      "pay_url": "https://nod.example/p/8K2xQ9",
      "pay_url_expires_at": "2026-11-19T14:32:00.000Z",
      "status_url": "https://nod.example/o/ord_8K2xQ9…"
    }
  }
}
In Claude, add a custom connector with the address. In ChatGPT, create a connector with it (some plans need developer mode). Any other MCP client: add a remote server over Streamable HTTP.

Public JSON API

The same data as plain JSON over HTTPS, for agents and tool runners that call REST endpoints. No key. The OpenAPI 3.1 description is at /openapi.json, ready to import as a GPT Action or into any tool runner.

RequestReturns
GET /v1/search?q=…Offers across every shop. Filters: kind, max_price, ship_to, shop, limit.
GET /v1/shopsEvery listed shop with its categories and number of offers.
GET /v1/shops/acmeOne shop: shipping, returns, checks passed and its offers.
GET /v1/shops/acme/offers/alpine-jacketOne offer with every option, its stock and order link.
GET /v1/shops/acme/offers/boot-fitting/timesFree times of an appointment. Add ?day=2026-11-23 for one day.
POST /v1/ordersPrepares an order from { shop, offer, option?, time?, qty? } and returns its payment link.
GET /v1/orders/ord_…Status of one order.
Search (shortened)
GET /v1/search?q=rain+jacket&ship_to=RO&max_price=150

200 OK
{
  "query": "rain jacket",
  "results": [
    {
      "shop": { "slug": "acme", "name": "Acme Outdoor", "url": "https://nod.example/acme" },
      "offer": "alpine-jacket",
      "title": "Alpine Shell Jacket",
      "price_text": "€129.00",
      "url": "https://nod.example/acme/alpine-jacket",
      "image": "https://nod.example/m/…",
      "options": [
        { "key": "black-m", "label": "Black / M", "stock": "3 left", "order_url": "https://nod.example/acme/alpine-jacket/order?v=black-m" }
      ]
    }
  ]
}
Prepare a booking
POST /v1/orders
Content-Type: application/json

{ "shop": "acme", "offer": "boot-fitting", "time": "2026-11-23T14:15", "qty": 1 }

201 Created
{ "status": "prepared", "total_text": "€20.00", "pay_url": "https://nod.example/p/Q7mW2c", "time_held_until": "…", … }

Preparing an order is a POST, so crawlers never trigger it. Prices are always live. Amounts in answers are in cents with a ready …_text form next to each one; the max_price filter takes the plain price, such as 150.

Discovery files

Files assistants, agents and search engines look for, all generated from live data.

AddressWhat it is
/llms.txtWhat nod is, how its addresses work, and where to search and browse.
/llms-full.txtEvery listed shop and its offers in one Markdown file.
/acme/llms.txtOne shop’s summary, with links to its Markdown pages.
/sitemap.xmlSitemap index: nod’s own pages and one sitemap per shop.
/acme/sitemap.xmlThe shop page and every offer, with their photos and last change.
/.well-known/ai-catalog.jsonAI Catalog listing nod’s MCP server and API.
/.well-known/api-catalogAPI catalog (RFC 9727) linking the OpenAPI description and these docs.
/openapi.jsonOpenAPI 3.1 description of the public JSON API.
/indexnow.txtnod’s IndexNow key.

How new pages reach search engines

  • When a shop goes live, or an offer is added, changed, paused or removed, nod sends those addresses to IndexNow. Bing and the other IndexNow engines can show the change within minutes, and so can the assistants that search with them.
  • Google and every other crawler read the sitemaps, which list each page’s last change and photos.
  • Every shop and offer page carries structured data (schema.org) with live price, stock, shipping, returns and an order action.
  • On a shop's own website, the install script adds the same structured data to a matching product page that has none, and links each page to the shop's Markdown and llms.txt with <link rel="alternate">.

Examples use nod.example. Listed means live and, with real payments, verified by Stripe; imported products also need a verified website or listing.

Install snippet

The shop pastes two lines once, into the footer or the site-wide template. It works on WordPress, Shopify, Wix, Squarespace, Webflow, Framer, Next.js and any HTML site. Each shop finds its own snippet under Install in the dashboard.

Site-wide footer
<a href="https://nod.example/acme">This shop accepts orders prepared by AI assistants: catalog and order links</a>
<script async src="https://nod.example/h.js" data-shop="acme"></script>
LineForWhat it does
The linkAssistants that only read the server’s HTMLAppears on every page. The assistant follows it to the hosted catalog and finds the order links there.
The scriptAgents that drive a real browser, and search enginesOn a page that matches an offer, adds the folded order block and, when the page has none, the product data search engines read. On every page, links to the shop’s Markdown catalog and llms.txt. About 2 KB compressed, loads after the page, no dependencies.

The script matches a page to an offer by its address, which is why each offer stores the page_url of the product page it came from.

The snippet also proves that you own the site. nod asks for that proof before products imported from a website go live. A meta tag or a DNS record works too, and the dashboard shows yours under Install.

Install guides

Paste both lines from your own snippet. Menu names can differ slightly between plan versions. After saving, run Check my site under Install in the dashboard.

WordPress

Use your theme's footer code setting or a header and footer code plugin, so both lines print on every page just before </body>. On a block theme you can add a Custom HTML block to the footer template part.

Shopify

Online Store, Themes, then Edit code. Open layout/theme.liquid, paste both lines just before </body> and save.

Wix

Settings, then Custom code. Add custom code, paste both lines, choose all pages and place it at the end of the body.

Squarespace

Open Code injection in your site settings, paste both lines into the Footer field and save.

Webflow

Site settings, then Custom code. Paste both lines into Footer code, save and publish the site.

Framer

Site settings, then Custom code. Paste both lines into the end of the <body> tag field and publish.

Next.js

Put the link in your site-wide footer component and the script tag in the root layout, inside <body>. A plain <script async> tag or next/script both work.

Any HTML site

Paste both lines just before </body> in your site-wide template, or on every page if your site has no template.

Platform names and logos belong to their owners.

Folded block

The strongest placement: the order links inside the product page's own HTML, so an assistant that opens the page has them in one step. Use Copy HTML next to any offer in the dashboard and paste it into that product's description.

Product description
<details class="nod-order">
  <summary>Order through an AI assistant</summary>
  <p>This shop accepts orders prepared by AI assistants. Each link prepares the order and returns a payment link; nothing is charged until the customer pays.</p>
  <p><a href="https://nod.example/acme/alpine-jacket/order?v=black-m" rel="nofollow">Black / M</a> · <a href="https://nod.example/acme/alpine-jacket/order?v=olive-m" rel="nofollow">Olive / M</a> · <a href="https://nod.example/acme/alpine-jacket/order?v=olive-l" rel="nofollow">Olive / L</a></p>
</details>
  • It is one folded line any visitor can open, so it is never hidden text.
  • It does not replace or touch the shop’s Add to cart button.
  • A visitor who opens it and taps a link is sent to the shop’s normal product page. The shop’s own customers never become nod orders.

Offers API

Push offers instead of adding them in the dashboard. Create an API key under Settings and send it as a bearer token. Offers are upserted by slug, so the same request is safe to repeat.

Request
PUT /v1/offers
Authorization: Bearer nod_sk_…
Content-Type: application/json

{
  "offers": [{
    "slug": "alpine-jacket",
    "kind": "product",
    "title": "Alpine Shell Jacket",
    "description": "Waterproof 3-layer shell.",
    "images": [
      "https://acme-outdoor.example/jacket.jpg",
      "https://acme-outdoor.example/jacket-hood.jpg"
    ],
    "category": "Jackets",
    "page_url": "https://acme-outdoor.example/alpine-jacket",
    "price": 12900,
    "variants": [
      { "key": "black-m", "label": "Black / M", "stock": 3 }
    ]
  }]
}
Response
200 OK
Content-Type: application/json

{
  "offers": [
    {
      "slug": "alpine-jacket",
      "kind": "product",
      "title": "Alpine Shell Jacket",
      "image": "https://acme-outdoor.example/jacket.jpg",
      "images": [
        "https://acme-outdoor.example/jacket.jpg",
        "https://acme-outdoor.example/jacket-hood.jpg"
      ],
      "category": "Jackets",
      "price": 12900,
      "currency": "eur",
      "status": "active",
      "url": "https://nod.example/acme/alpine-jacket",
      "variants": [
        { "key": "black-m", "label": "Black / M", "price": null, "stock": 3 }
      ],
      "order_links": {
        "black-m": "https://nod.example/acme/alpine-jacket/order?v=black-m"
      }
    }
  ]
}

Offer fields

FieldTypeNotes
slugstringa–z, 0–9 and dashes. The key for upserts. Defaults to a slug of the title.
kindstringproduct, booking or simple. Defaults to product.
titlestringRequired.
descriptionstringOptional. Short and factual reads best.
imagesarrayAbsolute addresses of the photos, in order, up to 12. The first is the main photo.
imageURLOne photo, used when you send no images.
categorystringOptional, for example “Jackets”. Shown to assistants and used for filters.
page_urlURLThe product page on your site. Used to match pages to offers.
priceintegerRequired. In cents: 12900 is €129.00.
statusstringactive (default) or paused.
variantsarrayEach has key, label, optional price in cents and optional stock. Omit stock for unlimited. Sending variants replaces the list; leaving it out keeps the current one.
duration_minintegerBookings only, with capacity (places per slot) and deposit in cents. Time slots come from the shop's weekly hours.

Listing offers

GET /v1/offers returns every offer in the same shape, with its url and order_links.

GET /v1/offers
Authorization: Bearer nod_sk_…

Errors

401 for a missing or invalid key, 400 when the body is not JSON or has no offers (1 to 500 per request), 422 with a list of problems when an offer is not valid. Nothing is saved unless every offer is valid.

422 Unprocessable Entity

{
  "error": {
    "message": "Some offers are not valid.",
    "details": ["offers[0].price must be an integer number of cents"]
  }
}

Webhooks

Set a webhook address under Settings. nod POSTs JSON to it when an order is paid (order.paid) and when it is refunded (order.refunded). Answer with any 2xx status within 8 seconds. Use order as your idempotency key: the same order can arrive more than once.

Request
POST https://acme-outdoor.example/hooks/nod
Content-Type: application/json
User-Agent: nod-webhooks/1.0
Nod-Signature: t=1763457400,v1=5f2b7c0e9a41d3…
Body · order.paid
{
  "type": "order.paid",
  "id": "evt_4hQ2mZ8xT1aVb7Kc9LpR",
  "created": "2026-11-18T09:16:40.000Z",
  "shop": "acme",
  "order": "ord_8K2xQ9vT4mW7pL2nR5sY1c",
  "status": "paid",
  "items": [
    { "offer": "alpine-jacket", "variant": "black-m", "title": "Alpine Shell Jacket",
      "label": "Black / M", "qty": 1, "unit": 12900 }
  ],
  "currency": "eur",
  "subtotal": 12900,
  "shipping": 490,
  "total": 13390,
  "charged": 13390,
  "fee": 645,
  "slot": null,
  "buyer": { "name": "Sam Lee", "email": "sam@example.com", "phone": "+33 6 12 34 56 78" },
  "ship_to": { "name": "Sam Lee", "line1": "12 Rue des Lilas", "city": "Lyon",
               "postal_code": "69003", "country": "FR" },
  "source": { "kind": "agent", "agent": "chatgpt", "first_seen": "2026-11-18T09:14:02.000Z" },
  "status_url": "https://nod.example/o/ord_8K2xQ9vT4mW7pL2nR5sY1c"
}
FieldMeaning
typeorder.paid or order.refunded.
orderThe order ID. Stable across events for the same order.
itemsOne entry per line: offer slug, variant key, qty and unit price in cents.
currencyThree-letter code, lowercase.
totalWhat the order costs, shipping included, in cents.
chargedWhat was charged now. Equals total, or the deposit for a booking paid by deposit.
feenod’s fee in cents: 5% of item prices, never of shipping.
buyername, email, phone from checkout.
ship_toline1, city, postal_code, country. null when nothing is shipped.
slotBookings: the booked start time in ISO 8601. Otherwise null.
sourceagent is the assistant that brought the order (chatgpt, claude, perplexity, gemini…), or null for a direct link. first_seen is when the order was prepared.

Verifying signatures

Every webhook carries Nod-Signature: t=<unix>,v1=<hex>. v1 is the HMAC-SHA256 of ${t}.${rawBody}, keyed with your webhook secret from Settings. Compute it over the raw body, before parsing, and compare in constant time.

verify-nod.js
import crypto from 'node:crypto'

// rawBody is the exact request body as text, before JSON.parse.
export function verifyNod(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  if (!parts.t || !parts.v1) return false
  // Reject events older than five minutes.
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex')
  return expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
}

// Example: a Next.js route handler
export async function POST(req) {
  const raw = await req.text()
  const ok = verifyNod(raw, req.headers.get('nod-signature') ?? '', process.env.NOD_WEBHOOK_SECRET)
  if (!ok) return new Response('Invalid signature', { status: 400 })
  const event = JSON.parse(raw)
  if (event.type === 'order.paid') {
    // Fulfil the order. Use event.order as the idempotency key.
  }
  return new Response('ok')
}
You can rotate the secret in Settings. Events are signed with the new secret from that moment, so update your endpoint at the same time.

Ready to try it on a real shop?

Create a shop, connect Stripe and paste two lines. It takes minutes.