---
title: "MERCURY Cited Sitemap"
method: GET
path: "/buy/sitemap"
tags: ["cited-sitemap", "sitemap", "sitemap-xml", "crawl-frontier", "url-inventory", "seo", "indexability", "site-coverage", "verifiable-data-record", "attestation", "provenance", "keyless", "agent-native", "scraping", "rag"]
---

# MERCURY Cited Sitemap

`GET /buy/sitemap`

## Request

- Base URL: `https://network.mercury-hq.com`
- URL: `https://network.mercury-hq.com/buy/sitemap`
- Auth: none declared
- TypeScript: <https://skmtc.dev/mercury-hq/apis/mercury-x402-storefront/docs/buy/sitemap/get.ts> (a function with typed inputs; its response is checked against the schema)

Domain/URL → a SIGNED snapshot of the site's PUBLISHED sitemap: discovers the sitemap via robots.txt Sitemap: lines then /sitemap.xml fallback, parses <urlset> + <sitemapindex> (follows up to 5 child sitemaps), returns a deduped, bounded (≤2000) URL inventory with lastmod/changefreq/priority. The receipt signs the DECLARED URL list (deterministic — same sitemap bytes ⇒ byte-identical list). Optional ?fetch=N (≤10) adds a HARD-BOUNDED same-domain liveness probe (title+status+bytes per URL) — that probe is the ONLY non-deterministic part and is NOT covered by the signature. SSRF-guarded; the crawl is bounded at every axis.

## Query parameters

- `url` string, required: a domain (example.com) or any URL on the site — only its origin is used
- `fetch` string: optional N (0–10): also shallow-fetch the first N same-domain sitemap URLs and report each one's live title + HTTP status + byte size (liveness sample). NOT covered by the signed receipt (it can change between calls). Default 0 = off.
- `limit` string: optional cap on URLs returned (1–2000); default returns all up to 2000

## Response `200`

Delivered after the x402 payment settles on Base mainnet.

- object
  - `ok` boolean, required: true on success; false on an honest failure (still delivered)
  - `url` string, required: the sitemap URL that was fetched + parsed
  - `status` integer: upstream HTTP status of the sitemap fetch
  - `data` object: the structured sitemap snapshot (the product the buyer consumes)
    - `origin` string: scheme://host the sitemap was discovered for
    - `sitemapUrl` string: the sitemap that was parsed
    - `discoveredVia` 'robots.txt' | 'sitemap.xml' | 'input': how the sitemap was located (robots Sitemap: line / conventional path / direct input)
    - `robotsSitemaps` string[]: all Sitemap: URLs robots.txt declared (may be > the one parsed)
    - `kind` 'urlset' | 'sitemapindex' | 'unknown': which sitemap schema was parsed
    - `childSitemaps` string[]: child sitemaps followed from a <sitemapindex> (bounded to 5)
    - `total` integer: number of unique page URLs returned
    - `truncated` boolean: true if the site declared more URLs than the 2000 cap / requested limit
    - `urls` object[]: the published URL inventory (deduped, origin-then-loc sorted)
      - `loc` string: absolute page URL
      - `lastmod` string: declared last-modified (only if present)
      - `changefreq` string: declared change frequency (only if present)
      - `priority` string: declared crawl priority (only if present)
    - `probe` object[]: OPTIONAL liveness sample (?fetch=N): first N same-domain URLs shallow-fetched. NOT covered by the signed receipt — live status can change between calls.
      - `url` string
      - `ok` boolean
      - `status` integer
      - `title` string
      - `bytes` integer
      - `error` string: present only when that URL failed
  - `text` string: canonical newline string the signed receipt covers: one URL per line, origin-then-loc sorted (the DECLARED inventory only — never the live-probe sample, so it is reproducible)
  - `contentType` string
  - `fetchedAt` string: ISO8601 fetch time (in the signed payload)
  - `error` string: present only when ok:false

## Other responses

- `402`: Payment Required — retry with an x402-signed payment (e.g. x402-fetch). Terms are in the challenge body (x402 v1).

---

[API](https://skmtc.dev/mercury-hq/apis/mercury-x402-storefront.md) - [All operations](https://skmtc.dev/mercury-hq/apis/mercury-x402-storefront/llms.txt) - [OpenAPI document](https://skmtc.dev/mercury-hq/apis/mercury-x402-storefront/revisions/211aa7db24ae?raw)