---
title: "Structured Data Extraction API — URL to typed JSON (schema extract, keyless x402)"
method: GET
path: "/buy/extract"
tags: ["structured-data-extraction", "structured-extract", "schema-extract", "json-mode", "url-to-json", "typed-extract", "product-data-extraction", "web-scraping-api", "data-extraction-api", "llm-ready-data", "verifiable-extract"]
---

# Structured Data Extraction API — URL to typed JSON (schema extract, keyless x402)

`GET /buy/extract`

## Request

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

TYPED structured extract for autonomous agents — URL + schema → a clean, type-safe JSON record. Where /buy/fetch returns page TEXT (and ?extract= returns string-only fields), THIS returns the schema-conformant object an LLM/RAG/trading pipeline actually consumes: pass ?url=…&schema=title,price:number,rating:number,inStock:boolean and get back { title:"…", price:19.99, rating:4.5, inStock:true } — numbers as numbers, booleans as booleans, absent fields null (honest). `schema` accepts the URL-friendly compact form (field[:type], type in string|number|integer|boolean) OR a Firecrawl/OpenAI-style JSON-Schema object ({"properties":{"price":{"type":"number"}}}). That is Firecrawl's paid 'JSON mode' headline guarantee — type-safety, 'numbers as numbers not strings' — done DETERMINISTICALLY from the page's own JSON-LD/OpenGraph/meta/microdata: keyless, NO LLM call, NO API key, NO signup, $0.004/call, paid in-band over HTTP 402 (x402, USDC on Base mainnet). The typed record is folded into the SIGNED provenance attestation too (EIP-191, ecrecoverable OFFLINE), so a buyer can prove the EXTRACTED FIELDS — not just raw bytes — are exactly what MERCURY resolved. Honest charge-per-ATTEMPT: every call returns a structured result (success OR an ok:false reason). Same SSRF guard, 5s timeout, 10MB cap, no mint.

## Query parameters

- `url` string, required: the page to extract from (http/https)
- `schema` string, required: fields to extract. COMPACT: comma list of field[:type] (type in string|number|integer|boolean, default string), e.g. title,price:number,rating:number,inStock:boolean. OR a JSON-Schema string ({"properties":{"price":{"type":"number"}}}). Resolved from JSON-LD/OpenGraph/meta/microdata.
- `format` 'text' | 'markdown': optional: text (default) or markdown for the page-text field

## 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: final URL after redirects
  - `status` integer: upstream HTTP status
  - `extract` object: the TYPED record: each requested field resolved + coerced to its declared type (numbers as numbers, booleans as booleans), absent fields null. Deterministic, keyless, no LLM.
  - `schema` object: echo of the resolved field->type map that was applied
  - `coerced` string[]: names of the fields that were actually type-cast (present only when non-empty)
  - `title` string: page <title>
  - `text` string: cleaned page text (also returned; markdown if ?format=markdown)
  - `bytes` integer: raw body size
  - `contentType` string
  - `truncated` boolean
  - `redirects` string[]: redirect chain followed
  - `fetchedAt` string: ISO timestamp of the fetch (also in the signed attestation)
  - `metered` boolean
  - `delivered` string
  - `kind` string
  - `error` string: present only when ok:false
  - `attestation` object: EIP-191 provenance receipt over the page text + the typed extract record (canonical key order), ecrecoverable OFFLINE (key at /.well-known/mercury-attestation). Proves the FIELDS are genuine + untampered.
    - `keyId` string
    - `alg` string
    - `address` string
    - `contentHash` string
    - `nonce` string
    - `signedAt` string
    - `signature` string
    - `verify` object
      - `message` string
      - `howTo` string

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