Sitemap Parse API

POST /v1/sitemap-parse
content-type: application/json
payment-signature: <base64 x402 payload>

{
  "url": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml",
  "limit": 100,
  "include_metadata": true
}

200 OK
payment-response: <base64 settlement receipt>

{
  "requested_url": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml",
  "entry_url": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml",
  "source_url": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml",
  "discovery": "direct",
  "kind": "mixed",
  "format": "xml",
  "urls": [
    {
      "loc": "https://grist.tools/samples/web/fieldnotes/index.html",
      "lastmod": "2026-08-25T00:00:00Z",
      "changefreq": "daily",
      "priority": 1
    },
    {
      "loc": "https://grist.tools/samples/web/fieldnotes/about.html",
      "lastmod": "2026-08-20T00:00:00Z",
      "changefreq": "yearly",
      "priority": 0.3
    },
    {
      "loc": "https://grist.tools/samples/web/fieldnotes/notes/first-frost.html",
      "lastmod": "2026-08-24T06:30:00Z",
      "changefreq": "monthly",
      "priority": 0.6
    },
    {
      "loc": "https://grist.tools/samples/web/fieldnotes/notes/rain-gauge.html",
      "lastmod": "2026-08-25T06:15:00Z",
      "changefreq": null,
      "priority": 0.6
    }
  ],
  "count": 4,
  "total_seen": 4,
  "truncated": false,
  "stopped_reason": null,
  "sitemap_count": 3,
  "sitemaps_visited": [
    {
      "url": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml",
      "kind": "sitemapindex",
      "url_count": 0,
      "http_status": 200,
      "bytes": 407,
      "gzip": false,
      "depth": 0
    },
    {
      "url": "https://grist.tools/samples/web/fieldnotes/sitemap-pages.xml",
      "kind": "urlset",
      "url_count": 2,
      "http_status": 200,
      "bytes": 479,
      "gzip": false,
      "depth": 1
    },
    {
      "url": "https://grist.tools/samples/web/fieldnotes/sitemap-notes.xml",
      "kind": "urlset",
      "url_count": 2,
      "http_status": 200,
      "bytes": 493,
      "gzip": false,
      "depth": 1
    }
  ],
  "sitemaps_skipped": [],
  "sitemaps_skipped_total": 0,
  "sitemaps_skipped_by_reason": {
    "depth_limit": 0,
    "sitemap_limit": 0,
    "cross_host": 0,
    "too_large": 0,
    "malformed": 0,
    "duplicate": 0,
    "time_budget": 0,
    "not_fetchable": 0
  },
  "invalid_loc_count": 0,
  "invalid_lastmod_count": 0,
  "robots_sitemaps": null,
  "fetched_at": "2026-09-01T12:00:00.000Z"
}

// sitemap-parse: $0.002 per call, paid in USD Coin on eip155:8453 via x402
// Install: npm install @x402/fetch@2 @x402/evm@2 viem@2
// Save as client.mjs (ES module, Node 18+), export EVM_PRIVATE_KEY with the paying wallet's key in your shell, then run: node client.mjs
// The wrapper reads the 402 (payment-required), signs and retries with payment-signature.
import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from '@x402/fetch'
import { ExactEvmScheme } from '@x402/evm/exact/client'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY)
const client = new x402Client().register('eip155:8453', new ExactEvmScheme(account))
const fetchWithPayment = wrapFetchWithPayment(fetch, client)

const body = {
  "url": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml",
  "limit": 100,
  "include_metadata": true
}

const res = await fetchWithPayment('https://grist.tools/v1/sitemap-parse', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(body),
})
console.log(res.status, await res.json())
const settle = res.headers.get('payment-response')
if (settle) console.log(decodePaymentResponseHeader(settle).transaction)

# sitemap-parse: $0.002 per call, paid in USD Coin on eip155:8453 via x402
# Install: pip install "x402[requests,evm]>=2.24,<3"
# The session reads the 402 (payment-required), signs and retries with payment-signature.
import os
from eth_account import Account
from x402 import x402ClientSync
from x402.http import decode_payment_response_header
from x402.http.clients.requests import x402_requests
from x402.mechanisms.evm.exact import register_exact_evm_client
from x402.mechanisms.evm.signers import EthAccountSigner

account = Account.from_key(os.environ["EVM_PRIVATE_KEY"])
client = x402ClientSync()
register_exact_evm_client(client, EthAccountSigner(account), networks="eip155:8453")
session = x402_requests(client)

payload = {
    "url": "https://grist.tools/samples/web/fieldnotes/sitemap-index.xml",
    "limit": 100,
    "include_metadata": True
}

res = session.post("https://grist.tools/v1/sitemap-parse", json=payload)
print(res.status_code, res.json())
settle = res.headers.get("payment-response")
if settle:
    print(decode_payment_response_header(settle).transaction)

# sitemap-parse: $0.002 per call, paid in USD Coin on eip155:8453 via x402
# 1. Unpaid call: HTTP 402, the requirements in the payment-required header (base64 JSON) and in the body.
curl -i -X POST 'https://grist.tools/v1/sitemap-parse' -H 'content-type: application/json' -d '{"url":"https://grist.tools/samples/web/fieldnotes/sitemap-index.xml","limit":100,"include_metadata":true}'

# 2. Same call with the signed payment (an EIP-3009 authorization, EIP-712 signed: it cannot be
#    typed by hand). x-payment is accepted as the v1 alternative. HTTP 200 carries payment-response.
curl -i -X POST 'https://grist.tools/v1/sitemap-parse' -H 'content-type: application/json' -H 'payment-signature: <base64 x402 payload>' -d '{"url":"https://grist.tools/samples/web/fieldnotes/sitemap-index.xml","limit":100,"include_metadata":true}'