DEV Community: Eyvind Barthelemy

The API promised industry keywords. Modern sites kept returning [].

Eyvind Barthelemy — Sat, 08 Aug 2026 04:46:14 +0000

This is a submission for DEV's Summer Bug Smash: Smash Stories powered by Sentry.

The quietest kind of production bug

The endpoint was healthy. Payment gating worked. The response matched its JSON schema. Nothing crashed, timed out, or lit up a red dashboard.

It was still broken.

I had launched a pay-per-call /enrich endpoint for AI agents. Give it a domain and it returns structured public company intelligence: identity, contact surfaces, technology signals, DNS and email infrastructure, social profiles, AI-search readiness—and company.keywords, advertised as industry keywords an agent could use for routing or qualification.

For modern sites, that last field kept coming back as this:

{
  "company": {
    "name": "...",
    "keywords": []
  }
}

The API had returned a successful, paid, structurally valid answer that omitted one of the signals it promised.

That made this bug more interesting than a 500 error. Every shallow health check passed. Only checking whether the output was useful revealed the failure.

Root cause: a legacy assumption hiding behind a modern schema

The original implementation populated the field from one HTML tag:

const keywords = (meta.keywords || "")
  .split(",")
  .map((value) => clean(value))
  .filter(Boolean)
  .slice(0, 15);

That means the entire field depended on:

<meta name="keywords" content="payments, infrastructure, fintech">

Many contemporary sites do not publish that legacy tag. They express topics elsewhere: JSON-LD keywords, knowsAbout, applicationCategory, article tags, titles, and descriptions.

My parser had confused one old representation with the underlying concept. The schema said “industry keywords”; the code actually meant “the value of this one optional meta tag.”

The first tempting fix was the wrong one

The easy patch would have been to split the page title and return the first few long words. That would make the array non-empty, but it would blur together two different kinds of evidence:

topics the publisher explicitly declared; and
terms the service derived from public copy.

For an autonomous buyer, that distinction matters. A derived label should not masquerade as a company-authored claim.

So the fix needed to improve coverage and preserve provenance.

The repair: declared first, deterministic fallback second

The corrected pipeline has three stages.

1. Collect declared signals

It reads:

meta[name="keywords"];
news_keywords;
article:tag;
JSON-LD keywords;
JSON-LD knowsAbout; and
JSON-LD applicationCategory.

The JSON-LD walk handles nested graphs, arrays, strings, and { "name": "..." } objects.

2. Normalize without laundering the evidence

Declared values are cleaned, capped at 40 characters, deduplicated case-insensitively, and limited to 15 public response items.

If fewer than six declared topics exist, the service deterministically derives a top-up from title and description text. It removes stopwords and numeric noise, ranks by frequency, and preserves first-appearance order as the tie-breaker.

There is no model call and no random generation. The same public input produces the same result.

3. Label the provenance

The response now states where its list came from:

{
  "company": {
    "keywords": [
      "stripe",
      "financial",
      "infrastructure",
      "grow",
      "revenue",
      "services",
      "platform",
      "types"
    ],
    "keywordsSource": "derived"
  }
}

The label is one of:

declared: the page provided a complete set;
mixed: declared topics plus a deterministic top-up; or
derived: no declared topics were available.

That small field keeps the improvement honest. A consuming agent can accept derived signals for discovery, or require declared signals for a higher-stakes decision.

Before and after

BEFORE
legacy meta keywords absent
        └─ company.keywords = []
             └─ HTTP 200, schema valid, weak answer

AFTER
declared meta + JSON-LD topics
        ├─ enough signals ──────────────> declared
        └─ sparse or absent
             └─ deterministic top-up ──> mixed / derived

all paths: case-insensitive dedupe + 15-item cap + provenance label

The endpoint still uses only public page data. The payment rail, input contract, URL security guard, and all unrelated response fields are unchanged.

Locking the semantic contract down

The original repair shipped on June 24. While preparing this retrospective, I noticed the lesson had not been encoded in a focused test. That is exactly how a quiet semantic bug can return during a later refactor.

I extracted the keyword pipeline behind a pure keywordSignals(...) seam and added four deterministic regression cases:

No legacy metadata still produces a non-empty derived set.
Meta and nested JSON-LD topics merge and deduplicate before a top-up.
Six declared topics remain purely declared; marketing copy is not appended.
The public response cap remains 15 after normalization.

The full current suite also preserves the gateway's referral safety tests:

$ npm test
tests 8
pass 8
fail 0

A live keyless CLI probe against stripe.com now returns eight keywords and keywordsSource: "derived" rather than the empty field that exposed the bug.

Code and evidence

What I learned

A valid payload can still violate the product promise

Status codes, JSON parsing, and schema validation prove transport and shape. They do not prove that the signal a customer is buying is present or useful.

For data products, a test should assert semantic invariants: the advertised field is populated for representative modern inputs, its provenance is visible, and its bounds remain stable.

Prefer concepts over historical representations

“Industry topics” can appear in several public formats. Binding the concept to one legacy tag made the implementation brittle even though the code looked reasonable in isolation.

Derived data needs an honesty label

Filling an empty field is not enough. The consumer should know whether a value was declared, inferred deterministically, or generated. Provenance turns a fallback from a hidden guess into a usable choice.

The lasting fix was not merely making [] non-empty. It was making the endpoint say what it knows, how it knows it, and keeping that contract executable in tests.

The RPC said Base was healthy. The first contract read still failed.

Eyvind Barthelemy — Sat, 08 Aug 2026 04:26:59 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

Agent Bounties is an open-source, payment-first bounty network. One of its GitHub Actions turns an exact GitHub identity and wallet into a participant record on Base before that participant can enter certain funded bounty flows.

That registration path is deliberately fail-closed: if the action cannot prove the right chain, registry, attester, identity, transaction receipt, and final eligibility state, it must stop rather than pretending registration succeeded.

While using the real registration workflow, I found a narrower but consequential reliability bug. The action considered an RPC endpoint healthy after only an eth_chainId check. The endpoint correctly reported Base mainnet, but refused the first participant-registry archive read with HTTP 403. Because selection had already committed to that endpoint, the ordered fallbacks were never tried.

The result was not a cosmetic error. Two exact GitHub-hosted runs, from different runner regions, failed before broadcasting a transaction, blocking the participant registration that the bounty path required.

Bug Fix or Performance Improvement

The old health check answered only this question:

Does this endpoint say it is Base mainnet?

The workflow actually needed a stronger answer:

Does this endpoint say it is Base mainnet and successfully perform the immutable registry read that registration depends on?

That difference matters because an RPC can serve a cheap chain-ID response while rate-limiting, gating, or rejecting historical contract reads.

The failure looked like this:

configured RPC
    └─ eth_chainId == 8453       ✓ selected
         └─ registry attester()  ✗ HTTP 403
              └─ registration   ✗ fail closed

fallback RPCs                    never reached

I changed endpoint selection to probe the real capability before committing:

def select_base_rpc(cast: str, configured: str, registry: str) -> str:
    """Probe ordered RPC fallbacks and commit to one usable Base endpoint."""

    endpoints = parse_rpc_urls(configured)
    for endpoint in endpoints:
        try:
            if run([cast, "chain-id", "--rpc-url", endpoint]) != BASE_CHAIN_ID:
                continue
            attester = run(
                [cast, "call", "--rpc-url", endpoint, registry, "attester()(address)"]
            ).lower()
            if ADDRESS.fullmatch(attester):
                return endpoint
        except RegistrationError:
            continue
    raise RegistrationError("no usable Base mainnet RPC endpoint")

The workflow now has three ordered candidates:

The operator-configured endpoint, preserving the existing preference.
https://mainnet.base.org.
https://base.drpc.org.

An endpoint is selected only after it returns Base chain ID 8453 and a valid address from the registry's attester() call. If none can do both, the workflow still fails closed.

I also fixed a related consistency error: the final eligibleAt(...) confirmation had been passed the original comma-separated configuration rather than the single endpoint selected by the probe. Every chain operation now uses the same proven endpoint.

Code

The PR changes three files:

.github/workflows/participant-registration.yml |   2 +-
scripts/register_participant.py                |  20 +++-
scripts/test_register_participant.py           | 133 +++++++++++++++++++++++--
3 files changed, 141 insertions(+), 14 deletions(-)

The upstream PR is open and currently mergeable, with its automated claimed-work check green. The challenge FAQ says an OSS contribution does not need to be merged upstream, so the public fork commit above is the stable, reviewable implementation while maintainer review proceeds independently.

My Improvements

1. I reproduced the failure in the real workflow

This was not inferred from a synthetic timeout. Two authorized registration attempts failed on the same provider from different GitHub runner regions:

ORD runner: the endpoint passed chain ID, then rejected the registry read.
SJC runner: the same sequence failed again on a later retry.

Direct workstation probes between the two attempts showed that all three candidates could answer both calls at that moment. That contrast isolated the issue: a developer-side smoke test was not a reliable proxy for the GitHub runner's ability to perform the actual contract read.

Both workflow attempts stopped before a transaction. That is the correct safety outcome, but the wrong availability outcome when healthy fallbacks exist.

2. I made the probe match the operation

The core fix is intentionally small: test the cheapest real dependency before selecting a provider. attester() is read-only, stable, inexpensive, and exercises the same registry access class the registration flow requires.

This avoids a dangerous overcorrection. The change does not weaken receipt checks, bypass eligibility, retry a transaction blindly, or alter any signing authority. It improves endpoint selection while preserving every existing payment and identity invariant.

3. I added deterministic regression coverage

The focused suite now covers:

an unavailable endpoint;
an endpoint on the wrong chain;
an endpoint that passes chain-id but refuses the registry read;
ordered fallback selection;
safe parsing of the endpoint list;
an end-to-end fixture proving every chain operation uses the selected endpoint;
preservation of transaction evidence after a post-receipt error;
strict identity, repository, PR, registration-record, and eligibility checks.

Current verification:

$ python3 scripts/test_register_participant.py -v
Ran 10 tests in 0.002s
OK

$ bash scripts/preflight.sh core
preflight=core ok

$ git diff --check
# clean

4. I preserved the failure boundary

If no endpoint both reports Base mainnet and reads the expected registry, the action stops. No transaction is attempted. The change does not modify the contract, registry address, attester or keeper authority, participant identity derivation, validity window, or settlement behavior.

That was the most important design constraint: failover should improve availability without turning uncertainty into an on-chain side effect.

Result

The fixed path now distinguishes "this server knows Base's chain ID" from "this server can actually support participant registration." A degraded configured provider no longer prevents the workflow from trying its healthy fallbacks, and the selected endpoint is used consistently through the final eligibility check.

The broader lesson is simple: health checks should prove the capability the next operation needs, not merely the cheapest fact a service can return.

Give your AI agent company + on-chain wallet enrichment in 30 seconds (x402, pay-per-call USDC)

Eyvind Barthelemy — Thu, 25 Jun 2026 03:34:35 +0000

If you're building autonomous agents, you've hit this wall: your agent needs to enrich a company by domain or size up a wallet before it sends funds, but every good data source (Clearbit, Apollo, Nansen) is signup- and KYC-gated. An autonomous agent can't click "Sign up," verify an email, and paste an API key.

So I put a small data gateway behind x402 — HTTP 402 + pay-per-call USDC on Base. No account, no API key, no subscription. Your agent does a GET, gets a 402 with the price, pays a couple cents of USDC, and replays the request. That's it.

30-second install (Claude / Cursor / any MCP agent)

npx skills add epistemedeus/x402-data-gateway-skills --all

That drops in Agent Skills that teach your agent when to call each endpoint — so "enrich this company" or "profile this wallet" just works.

The two I actually built this for

company-enrich — a domain → clean firmographics (name, description, tech stack, socials, contact), plus two layers generic enrichment APIs don't return:

DNS / email-infra (MX, SPF, DMARC — great for outreach validation)
an AI-search-readiness score (JSON-LD, OpenGraph, robots/sitemap/llms.txt) — "can an AI assistant actually read and cite this site?"

wallet-enrich — a Base/EVM 0x address → on-chain profile: EOA vs contract, native + token holdings, ERC-20/721/1155 metadata, EIP-1967 proxy detection, activity, and the Basename (e.g. jesse.base.eth), forward-confirmed so it's never wrong. The crypto-native counterpart for sizing up a counterparty before you transact.

Calling it from code (x402-fetch)

import { wrapFetchWithPayment } from "x402-fetch";
// walletClient = a viem wallet funded with a little USDC on Base
const fetchPaid = wrapFetchWithPayment(fetch, walletClient);

const res = await fetchPaid(
  "https://x402-url-extractor-production.up.railway.app/wallet-enrich?address=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
);
console.log(await res.json());
// -> { type: "contract", contract: { standard: "ERC-20 (token)", token: { symbol: "USDC", ... } }, profile: "token-contract:USDC" }

Settlement is non-custodial: the facilitator verifies your signed EIP-3009 authorization and the USDC moves straight to the service wallet. Nobody holds your funds.

Also exposed as an MCP server

Prefer MCP? The same tools are an x402-gated MCP server (tools/list is free, tools/call is paid), listed in the official MCP Registry as io.github.epistemedeus/x402-data-gateway. tools/list to see all six; pay-per-call on the ones you use.

What's in the gateway

Skill	Does	Price
company-enrich	domain → company intel + AI-readiness + DNS	$0.02
wallet-enrich	0x address → on-chain profile + Basename	$0.02
web-extract	URL → structured JSON or LLM-ready Markdown	$0.05
repo-security-scan	static supply-chain scan of a GitHub repo before you install it	$0.20
schema-generate	business site → paste-ready JSON-LD bundle	$0.25

Public data only, deterministic, pay-per-call. Repo + full docs: https://github.com/epistemedeus/x402-data-gateway-skills

If you wire it into an agent, I'd genuinely like to hear what task you used it for.

I checked the structured data on 61 med-spa sites AI assistants surface. Only 8% have FAQ markup.

Eyvind Barthelemy — Wed, 24 Jun 2026 19:57:30 +0000

I run a small AI-search readiness tool, so I got curious about a concrete question: when someone asks ChatGPT or Perplexity "best med spa near me for Botox," what structured data do the businesses that surface actually have?

So I checked. I took the high-intent queries a real patient would run — "best med spa in [city]", "Botox [city]", "laser hair removal [city]" — across 8 US metros (Austin, Scottsdale, Miami, Dallas, Nashville, Los Angeles, Chicago, Denver), collected the individual-clinic pages that surfaced, fetched each one, and parsed its JSON-LD. 62 clinic URLs, 61 reachable.

The result surprised me.

The basics are common. The quotable fields are not.

Of the 61 reachable clinic pages:

77% have some JSON-LD structured data
59% have a LocalBusiness / MedicalBusiness block
59% have a telephone, 57% a postal address
…but only 31% have AggregateRating
only 25% have priceRange
only 11% mark up their services (Service / OfferCatalog)
only 8% have FAQPage markup
only 2% have Review markup

So clinics nail the identity basics (name, address, phone) and skip the answer-rich markup — the exact fields an assistant uses to quote a business rather than just list it.

Why the distinction matters

When an LLM answers a local "best X near me" question, it's assembling facts: which businesses exist, what they offer, what it costs, how they're rated, and what people ask. A page with a bare LocalBusiness block can be named. A page that also carries Service + priceRange, FAQPage, and real Review/AggregateRating markup gives the model the actual sentences and numbers to cite.

The data says the second kind of page barely exists in this category. That's not a doom stat — it's the cheapest competitive edge in the space right now, and it's a one-time paste into your <head>.

What "good" looks like

A complete bundle for a local business is a @graph with the business entity, its services as an OfferCatalog, an FAQPage, and real ratings:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": ["MedicalBusiness", "HealthAndBeautyBusiness"],
      "name": "Example Aesthetics",
      "telephone": "+1-512-555-0100",
      "priceRange": "$$",
      "address": { "@type": "PostalAddress", "addressLocality": "Austin", "addressRegion": "TX", "addressCountry": "US" },
      "hasOfferCatalog": {
        "@type": "OfferCatalog",
        "itemListElement": [
          { "@type": "Offer", "itemOffered": { "@type": "Service", "name": "Botox" } },
          { "@type": "Offer", "itemOffered": { "@type": "Service", "name": "Dermal Fillers" } }
        ]
      },
      "aggregateRating": { "@type": "AggregateRating", "ratingValue": "4.9", "reviewCount": "214" }
    },
    {
      "@type": "FAQPage",
      "mainEntity": [
        { "@type": "Question", "name": "How much does Botox cost?",
          "acceptedAnswer": { "@type": "Answer", "text": "Botox is priced per unit; most treatments range from $10–$18 per unit." } }
      ]
    }
  ]
}

One honest caveat: put your real ratings and reviews in there. The structure is the easy part; fabricated ratings are both against Google's guidelines and pointless.

Method + caveats

This is a structured-data census of the surfaced set — it measures what makes a page eligible to be cited, not a live count of any single engine's citations (I don't have ChatGPT/Perplexity API access at scale, and I'd rather report what I can verify first-party than guess). I excluded aggregators and listicles (Yelp, etc.) from the clinic tally. Full data, the metro list, and the methodology are in the report below. I refresh it monthly.

Check your own site

Free, open-source:

npx github:epistemedeus/ai-readiness yoursite.com

Full data + a free starter-block generator (and, if you want the complete bundle generated against your live site with a gap diff, a paid option): the med-spa AI-citation schema gap report — linked as the canonical source below.

If you've measured this for another vertical, I'd love to compare notes.

I scanned 136 companies to see if AI search can actually read their sites - the data (and how to fix yours)

Eyvind Barthelemy — Wed, 24 Jun 2026 06:13:47 +0000

AI answer engines (ChatGPT, Perplexity, Google AI Overviews, Claude) are turning into a real referral source. But they can only cite pages they can actually crawl and parse. So I built a tiny, open-source checker and ran it against the homepages of 136 well-known companies across 7 industries to see how AI-ready the web really is.

The results weren't what I expected.

What I measured

Each homepage scored 0-100 across six things AI crawlers and answer-engines rely on:

AI-crawler access - does robots.txt allow GPTBot, OAI-SearchBot, PerplexityBot, Google-Extended, ClaudeBot?
Structured data - JSON-LD (Organization, WebSite, FAQPage)
Title + meta description
Open Graph tags
XML sitemap
llms.txt

The findings

Average score by industry (higher = easier for AI to read):

Industry	Avg score
Marketing agencies	92
SaaS	88
Dev tools	86
E-commerce	85
AI startups	83
Fintech	74
Healthtech	63

What jumped out:

Structured data is the #1 gap. A large share of sites ship no Organization or FAQPage JSON-LD - which is exactly the format AI answers like to quote.
Plenty of well-known tech companies score in the C/D range, almost always because of missing schema, not anything hard.
The bar is low. A deliberate, clean setup puts a tiny site ahead of companies a thousand times its size in how readable it is to AI search.

How to fix yours (copy-paste)

1. Let the AI crawlers in - robots.txt:

User-agent: GPTBot
Allow: /
User-agent: OAI-SearchBot
Allow: /
User-agent: PerplexityBot
Allow: /
User-agent: Google-Extended
Allow: /
User-agent: *
Allow: /
Sitemap: https://yourdomain.com/sitemap.xml

2. Tell engines who you are - Organization JSON-LD in your <head>:

<script type="application/ld+json">
{"@context":"https://schema.org","@type":"Organization","name":"YOUR COMPANY","url":"https://yourdomain.com","sameAs":["https://www.linkedin.com/company/yourco","https://x.com/yourco"]}
</script>

3. Add FAQPage JSON-LD to any page with Q&A - it's the structure AI answers quote most.

Check your own site (free, open source)

I open-sourced the checker. No install needed:

npx github:epistemedeus/ai-readiness https://yourdomain.com

It prints a 0-100 score plus the exact gaps and fixes. Browser version (no install): https://samedaydesk.com/tools/ai-readiness

If you'd rather grab every template ready to paste (robots.txt, all the JSON-LD, sitemap, meta/OG) in one file, I bundled them into a $9 kit: https://buy.stripe.com/9B66oI1BEdTV6116oieZ20j - but the free checker plus the snippets above honestly get most sites 80% of the way there.

What does your site score? The thing that surprised me most: a bunch of AI companies can't be read by AI. 🤔