Well-Known Fetch API

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

{
  "domain": "example.com"
}

200 OK
payment-response: <base64 settlement receipt>

{
  "domain": "example.com",
  "files_requested": [
    "security.txt",
    "ads.txt",
    "humans.txt"
  ],
  "security_txt": {
    "requested": true,
    "present": true,
    "status": 200,
    "url": "https://example.com/.well-known/security.txt",
    "contact": [
      "mailto:[email protected]",
      "https://example.com/security-contact"
    ],
    "expires": "2027-01-01T00:00:00.000Z",
    "is_expired": false,
    "encryption": [
      "https://example.com/pgp-key.txt"
    ],
    "acknowledgments": [
      "https://example.com/hall-of-fame"
    ],
    "preferred_languages": "en, fr",
    "canonical": [
      "https://example.com/.well-known/security.txt"
    ],
    "policy": [
      "https://example.com/security-policy"
    ],
    "hiring": [
      "https://example.com/jobs"
    ],
    "signed": false,
    "field_count": 9
  },
  "ads_txt": {
    "requested": true,
    "present": true,
    "status": 200,
    "url": "https://example.com/ads.txt",
    "records": [
      {
        "advertising_system": "greenadexchange.com",
        "publisher_id": "12345",
        "relationship": "DIRECT",
        "certification_authority_id": "d75815a79",
        "line": 4
      },
      {
        "advertising_system": "blueadexchange.com",
        "publisher_id": "xf7",
        "relationship": "RESELLER",
        "certification_authority_id": null,
        "line": 5
      },
      {
        "advertising_system": "silverssp.com",
        "publisher_id": "9675",
        "relationship": "DIRECT",
        "certification_authority_id": null,
        "line": 6
      }
    ],
    "records_total": 3,
    "records_truncated": false,
    "direct_count": 2,
    "reseller_count": 1,
    "variables": [
      {
        "name": "CONTACT",
        "value": "[email protected]"
      }
    ],
    "variables_truncated": false,
    "invalid_lines": 0
  },
  "humans_txt": {
    "requested": true,
    "present": true,
    "status": 200,
    "url": "https://example.com/humans.txt",
    "text": "/* TEAM */\nWebmaster: Jane Doe\nSite: example.com\n\n/* THANKS */\nEveryone.\n",
    "truncated": false,
    "bytes": 73
  },
  "normalised": {
    "files_present": [
      "ads.txt",
      "humans.txt",
      "security.txt"
    ],
    "security_contacts": [
      "mailto:[email protected]",
      "https://example.com/security-contact"
    ],
    "security_expires": "2027-01-01T00:00:00.000Z",
    "security_expired": false,
    "security_signed": false,
    "ads_sellers": 3,
    "ads_direct": 2,
    "ads_reseller": 1
  },
  "fetched_at": "2026-08-26T18:00:00.000Z"
}

// wellknown-fetch: $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 = {
  "domain": "example.com"
}

const res = await fetchWithPayment('https://grist.tools/v1/wellknown-fetch', {
  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)

# wellknown-fetch: $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 = {
    "domain": "example.com"
}

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

# wellknown-fetch: $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/wellknown-fetch' -H 'content-type: application/json' -d '{"domain":"example.com"}'

# 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/wellknown-fetch' -H 'content-type: application/json' -H 'payment-signature: <base64 x402 payload>' -d '{"domain":"example.com"}'