---
title: "Cited Validate — JSON API response vs JSON Schema, signed pass/fail + per-field errors (keyless x402)"
method: GET
path: "/buy/validate"
tags: ["json-schema-validation", "api-response-validation", "schema-validate", "contract-testing", "data-validation-api", "url-to-validation", "json-validator", "verifiable-validation", "attestation", "provenance", "keyless", "agent-native", "data-quality"]
---

# Cited Validate — JSON API response vs JSON Schema, signed pass/fail + per-field errors (keyless x402)

`GET /buy/validate`

## Request

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

URL (a JSON/API endpoint) + a JSON Schema in → a deterministic pass/fail with per-field errors (missing/wrong-type/enum/range/pattern), plus a signed provenance receipt binding the verdict to the exact response bytes AND the exact schema. Deterministic, keyless, no LLM — x402, USDC on Base mainnet.

## Query parameters

- `url` string, required: the JSON/API endpoint to fetch + validate (http/https)
- `schema` string, required: the JSON Schema to validate against. THREE accepted forms: (1) COMPACT URL-native comma list of field[:type] (type in string|number|integer|boolean|array|object|null; default string), e.g. id:integer,name,price:number,inStock:boolean — every field becomes a REQUIRED typed property; (2) a JSON-Schema string (Draft-07 core subset: type/required/properties/items/enum/const/min*/max*/pattern/format/additionalProperties/nullable/anyOf/oneOf/allOf/not); (3) a shorthand-map string {"id":"integer","name":"string"}.
- `pointer` string: optional JSON-Pointer (e.g. /data or /result/0) to validate a SUB-DOCUMENT of the response instead of the whole body (for APIs that wrap the payload).

## Response `200`

Delivered after the x402 payment settles on Base mainnet.

- object
  - `ok` boolean, required: true when the validation RAN (delivered); false on an honest undeliverable (503-before-charge)
  - `url` string, required: final URL after redirects
  - `status` integer: upstream HTTP status of the fetched JSON
  - `text` string: the canonical signed string: JSON.stringify(report, sorted-keys) — the exact bytes the provenance receipt covers (embeds documentHash + schemaHash + verdict)
  - `fetchedAt` string: ISO timestamp of the fetch (also in the signed attestation)
  - `data` object: the validation report the buyer consumes
    - `valid` boolean: true iff the fetched JSON conforms to the schema with zero errors
    - `errorCount` integer: number of validation errors found
    - `errors` object[]: per-field errors in document order (empty when valid)
      - `path` string: JSON-Pointer path to the offending value
      - `keyword` string: the schema keyword that failed (type, required, enum, minimum, pattern, …)
      - `message` string: human-readable reason
    - `truncated` boolean: true if the error cap clipped the list (still honest about more existing)
    - `documentHash` string: 0x… sha256 of the canonical JSON document that was validated
    - `schemaHash` string: 0x… sha256 of the canonical (normalised) schema that was applied
    - `schemaForm` string: which input form was used: compact | json-schema | shorthand
    - `pointer` string: the JSON-Pointer applied (empty for whole-body validation)
    - `validatedType` string: the JSON type of the validated (sub-)document
  - `attestation` object: EIP-191 provenance receipt over `text` (the canonical sorted-key JSON of the report, which embeds documentHash + schemaHash + verdict), ecrecoverable OFFLINE (key at /.well-known/mercury-attestation). Proves: which schema was checked, which bytes were checked, and the verdict — all at fetchedAt.
    - `keyId` string
    - `alg` string
    - `address` string
    - `contentHash` string
    - `nonce` string
    - `signedAt` string
    - `signature` string
    - `verify` object
      - `message` string
      - `howTo` string
  - `error` string: present only when ok:false (undeliverable, not charged)

## 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)