Livre blanc

FireScrap — Traducteur live HTML → JSONL

Structuration à la volée pour agents autonomes. Version 1.0 — 03/11/2026. Service en ligne, sans modèle, sans navigateur, cache partagé.

EN LIGNE — BÊTA TECHNIQUE x402 v2 · USDC · Base Gratuit 100/jour · 1,00 USDC / 1k

Résumé en une page

Problème : un agent qui navigue le web reçoit du HTML — verbeux, profondément imbriqué, écrit pour un navigateur, pas pour une machine. Chaque agent réinvente sa propre extraction : lente, fragile, inconsistante.

Solution : FireScrap propose un service de structuration partagé : une URL entre, un document JSONL par sections sémantiques sort. La page est traduite une fois, puis servie à tous les agents qui la demandent (cache partagé). Aucun modèle de langage, aucun navigateur intégré — juste une classification déterministe du DOM.

Promesse : pas de boîte noire. Chaque section porte son raw_html_snippet d'origine pour vérification sans retour au site source. Erreurs typées explicites (400/415/502/503/504), jamais document vide présenté comme succès.

1. Pourquoi ce service existe

FireScrap poursuit un seul objectif : donner aux agents un accès structuré au web, sans qu'ils n'aient à réécrire l'extraction.

Objectifs mesurables pour l'agent client :

  1. Économiser le contexte : ~30 k tokens épargnés par appel médian (le HTML brut n'entre pas dans la fenêtre de contexte).
  2. Garantir la vérifiabilité : chaque section cite son extrait source (raw_html_snippet). L'agent n'a pas besoin de re-fetch pour valider.
  3. Uniformiser l'entrée : mêmes types de sections, même schéma, quel que soit le site source.
  4. Être courtois envers le web : cache partagé = une seule récupération HTTP par page, respect robots.txt, entêtes politesse.
Ce que le service ne promet PAS : il n'interprète pas le JavaScript (page pure JS = erreur 503 explicite), ne génère pas de résumé (sortie = sections brutes), ne fait pas d'inférence sémantique (classification structurelle uniquement). La feuille de route V2 (JavaScript) est en cours.

2. Architecture — trois principes

Principe I — Déterminisme

Même URL + mêmes entêtes = même document. Pas de modèle, pas d'aléa. La classification DOM est purement structurelle (sélecteurs CSS, heuristiques de densité texte).

Principe II — Cache partagé

Clé de cache = URL normalisée + entêtes pertinentes (Accept-Language, etc.). Une page traduite = servie à tous. TTL adaptatif selon fréquence de changement détectée.

Principe III — Transparence

Chaque section : _type, position_in_document, raw_html_snippet. L'agent reconstruit, vérifie, filtre sans dépendre du service.

Pas de navigateur, pas de modèle — c'est ce qui rend le service déployable sur CPU, rapide (~80 ms médian), et prévisible en coût. L'étape suivante (V2) interprétera le JS côté serveur, toujours sans navigateur headless.

3. Types de sections (schéma v1)

TypeDescriptionChamps clés
article_headerTitres h1–h6heading_text, level
article_paragraphParagraphes de textetext_normalized
article_listListes ul/olitems[], ordered
article_code_blockBlocs <pre><code>language, code
article_tableTableaux HTMLheaders[], rows[][]
article_mediaImages, vidéos, iframessrc, alt, type
article_blockquoteCitationstext_normalized, cite
article_separatorhr, sauts thématiques—

Chaque section porte position_in_document (ordre global) et raw_html_snippet (extrait source tronqué à 500 caractères).

4. Formats de sortie dérivés

Un seul objet interne → cinq formats, sans divergence :

jsonl (défaut)
Une ligne JSON par section, streaming-friendly.
yaml
Document YAML unique, lisible humain.
toml
Configuration TOML, sections = tables.
markdown
Reconstitution Markdown sémantique.
ndjson_md
JSONL + champ markdown par section.

5. API & économie

Endpoint principal : POST /api/v1/translate

curl -X POST https://firescrap.services4agents.fyi/api/v1/translate \ -H 'Content-Type: application/json' \ -d '{"url":"https://exemple.fr","format":"jsonl"}'

En-têtes de réponse utiles : X-Cache-Hit (bool), X-Quota-Remaining (int), X-FireScrap-Session (session payée, 90 j).

Tarification x402 (USDC sur Base) :

  • Gratuit : 100 traductions / jour, sans compte, sans clé.
  • Payant : 1,00 USDC les 1 000 traductions. Paiement par session (EIP-3009), règlement on-chain groupé. Session = 90 jours.
Coût machine mesuré : ≈ 0,42 € / million d'appels (CPU seul, pas de GPU). Le tarif couvre l'infrastructure + marge pour R&D V2 (JavaScript).

6. Erreurs typées — contrat de fiabilité

CodeSignificationAction agent
400URL invalide (schéma, encodage)Corriger l'URL, réessayer
415Contenu non-HTML (PDF, image, binaire)Ignorer, pas réessayable
502Hôte injoignable (DNS, TCP, TLS)Réessayer plus tard (backoff)
503Non exploitable (JS pur, vide, erreur HTTP)Ignorer, raison dans detail
504Timeout (>>10 s ou >2 Mo)Réessayer ou marquer comme lent

Un défaut de conformité du document de sortie au schéma = 500 incident serveur, jamais réponse partielle envoyée au client.

7. Feuille de route

  1. V1 — HTML · livrée : une URL, un document structuré, cache, erreurs typées, quota gratuit, paiement x402. En ligne
  2. V2 — JavaScript : interpréter le code des pages pour l'agent, sans navigateur et sans modèle. C'est le cœur de la valeur : ce qui est compliqué à décrypter pour un agent, nous le décryptons à sa place. En cours
  3. V3 — Enrichissement : formats de documents supplémentaires (PDF, EPUB), correction et enrichissement du contenu signalés dans la réponse (entités, faits vérifiables, contradictions). Prévu
White paper

FireScrap — Live HTML → JSONL Translator

On-the-fly structuring for autonomous agents. Version 1.0 — 03/11/2026. Live service, no model, no browser, shared cache.

LIVE — TECHNICAL BETA x402 v2 · USDC · Base Free 100/day · 1.00 USDC / 1k

One-page summary

Problem: an agent browsing the web receives HTML — verbose, deeply nested, written for a browser, not a machine. Every agent reinvents its own extraction: slow, brittle, inconsistent.

Solution: FireScrap offers a shared structuring service: a URL goes in, a JSONL document of semantic sections comes out. The page is translated once, then served to every agent that asks for it (shared cache). No language model, no built-in browser — just deterministic DOM classification.

Promise: no black box. Every section carries its original raw_html_snippet for verification without re-fetching the source site. Explicit typed errors (400/415/502/503/504), never an empty document passed off as success.

1. Why this service exists

FireScrap pursues a single objective: give agents structured access to the web without them having to rewrite extraction.

Measurable objectives for the client agent:

  1. Save context: ~30k tokens saved per median call (raw HTML doesn't enter the context window).
  2. Guarantee verifiability: each section cites its source excerpt (raw_html_snippet). The agent doesn't need to re-fetch to validate.
  3. Uniform input: same section types, same schema, regardless of source site.
  4. Be courteous to the web: shared cache = one HTTP fetch per page, respects robots.txt, polite headers.
What the service does NOT promise: it does not interpret JavaScript (pure JS page = explicit 503 error), does not generate summaries (output = raw sections), does not do semantic inference (structural classification only). The V2 roadmap (JavaScript) is in progress.

2. Architecture — three principles

Principle I — Determinism

Same URL + same headers = same document. No model, no randomness. DOM classification is purely structural (CSS selectors, text-density heuristics).

Principle II — Shared cache

Cache key = normalized URL + relevant headers (Accept-Language, etc.). A translated page = served to all. Adaptive TTL based on detected change frequency.

Principle III — Transparency

Every section: _type, position_in_document, raw_html_snippet. The agent rebuilds, verifies, filters without depending on the service.

No browser, no model — that's what makes the service deployable on CPU, fast (~80 ms median), and predictable in cost. The next step (V2) will interpret JS server-side, still without a headless browser.

3. Section types (schema v1)

TypeDescriptionKey fields
article_headerHeadings h1–h6heading_text, level
article_paragraphText paragraphstext_normalized
article_listul/ol listsitems[], ordered
article_code_blockPre/code blockslanguage, code
article_tableHTML tablesheaders[], rows[][]
article_mediaImages, videos, iframessrc, alt, type
article_blockquoteBlockquotestext_normalized, cite
article_separatorhr, thematic breaks—

Each section carries position_in_document (global order) and raw_html_snippet (source excerpt truncated to 500 chars).

4. Derived output formats

One internal object → five formats, no divergence:

jsonl (default)
One JSON line per section, streaming-friendly.
yaml
Single YAML document, human-readable.
toml
TOML config, sections = tables.
markdown
Semantic Markdown reconstruction.
ndjson_md
JSONL + markdown field per section.

5. API & economics

Main endpoint: POST /api/v1/translate

curl -X POST https://firescrap.services4agents.fyi/api/v1/translate \ -H 'Content-Type: application/json' \ -d '{"url":"https://example.com","format":"jsonl"}'

Useful response headers: X-Cache-Hit (bool), X-Quota-Remaining (int), X-FireScrap-Session (paid session, 90 days).

x402 pricing (USDC on Base):

  • Free: 100 translations / day, no account, no key.
  • Paid: 1.00 USDC per 1,000 translations. Per-session payment (EIP-3009), batched on-chain settlement. Session = 90 days.
Measured machine cost: ≈ €0.42 / million calls (CPU only, no GPU). Pricing covers infrastructure + R&D margin for V2 (JavaScript).

6. Typed errors — reliability contract

CodeMeaningAgent action
400Invalid URL (scheme, encoding)Fix URL, retry
415Non-HTML content (PDF, image, binary)Ignore, not retryable
502Host unreachable (DNS, TCP, TLS)Retry later (backoff)
503Not usable (pure JS, empty, HTTP error)Ignore, reason in detail
504Timeout (>10 s or >2 MB)Retry or mark as slow

Output document schema non-conformance = 500 server incident, never partial response sent to client.

7. Roadmap

  1. V1 — HTML · delivered: one URL, one structured document, cache, typed errors, free quota, x402 payment. Live
  2. V2 — JavaScript: interpret page code for the agent, without a browser and without a model. That's the core value: what's hard for an agent to decipher, we decipher for it. In progress
  3. V3 — Enrichment: additional document formats (PDF, EPUB), correction and enrichment signaled in response (entities, verifiable facts, contradictions). Planned