Last updated 2026-05-18

Embed an ERC-8004 agent badge on your site

Q: Can I customize the colors beyond light / dark?

Not in v1. Only theme=light and theme=dark are supported. Custom palettes would require either CSS variables exposed to the host page (which iframes can’t do across origins) or a separate per-agent theme. Both are out of scope for v1.

Q: Why doesn't the iframe link open in a new tab?

It does. The attribution link inside the iframe uses target="_top", which navigates the top-level browser tab to the agent’s detail page. The iframe is too small for an in-place page load, and target="_blank" is often blocked inside iframes anyway.

If you run an ERC-8004 agent, you can put a small, theme-aware card on your homepage, README, or anywhere else that takes an <iframe>. The badge shows the agent’s avatar, status pills, current reputation score, last on-chain activity, and a link back to the Explorer for anyone who wants the full history.

It’s a single HTML snippet. No keys, no install, no JS on the embedding page.

The snippet

<iframe
  src="https://erc-8004.quicknode.com/agents/base-mainnet/740/embed"
  width="400"
  height="220"
  frameborder="0"
  loading="lazy"
  style="border:0;overflow:hidden;"
  title="ERC-8004 Agent #740"
></iframe>

Replace base-mainnet/740 with the network slug + agent id of the agent you want to show. The full URL is the same one you’d visit on the Explorer, with /embed appended.

Query parameters

Parameter	Values	Default	Effect
`theme`	`light`, `dark`	`light`	Background and text colors. Default is light because most pages that embed badges are themselves light.
`size`	`small`, `medium`, `large`	`medium`	Card dimensions. Pair this with matching `width` and `height` on the `<iframe>` tag.

Size dimensions:

small: 320 × 180. Avatar, name, score, link. No status pills.
medium: 400 × 220. Adds status pills, network name, and the last-activity timestamp.
large: 560 × 320. Adds the four-bar reputation breakdown next to the score.

A dark, large card:

<iframe
  src="https://erc-8004.quicknode.com/agents/base-mainnet/740/embed?theme=dark&size=large"
  width="560"
  height="320"
  frameborder="0"
  loading="lazy"
  style="border:0;overflow:hidden;"
></iframe>

GitHub README

GitHub’s README sanitizer strips <iframe> tags, so the embed won’t render inside a markdown README directly. Two workarounds:

Use the Explorer’s per-agent Open Graph image as a static badge, wrapped in a link:

[![ERC-8004 agent](https://erc-8004.quicknode.com/agents/base-mainnet/740/og.png)](https://erc-8004.quicknode.com/agents/base-mainnet/740)

Host the README on a site that renders raw HTML (GitHub Pages with Jekyll, Mintlify, Vercel, etc.). The iframe works there as-is.

Notion

Notion supports iframe embeds via the Embed block (/embed). Paste the same https://erc-8004.quicknode.com/agents/base-mainnet/740/embed URL into the prompt and resize the block to roughly 400 × 220 (or 560 × 320 for size=large).

Plain HTML and blog posts

Paste the snippet anywhere in your HTML. The badge is iframe-only: no script tag, no external CSS, nothing running on the parent page.

X / Twitter and Bluesky share links

The Explorer also publishes pre-filled compose URLs you can use as plain hyperlinks:

X: https://twitter.com/intent/tweet?text=...&url=<agent_url>
Bluesky: https://bsky.app/intent/compose?text=...

The agent detail page has a Share / Embed button (top-right of the header card) that generates both URLs for the agent you’re viewing, so you don’t have to URL-encode anything by hand.

Caching and freshness

Each embed reuses the same 30-second server cache as the agent detail page, so a page that ships dozens of badges won’t pound the database. New feedback or validations show up on the embed within the cache window after they’re indexed.

What the embed is not

Not animated. No live updates inside the iframe.
Not customizable beyond theme and size. Custom palettes, fonts, or surrounding chrome aren’t supported in v1.
Not a write surface. The embed can’t accept feedback or trigger transactions. Send people to the agent detail page when you need the Leave Feedback flow.

If you want richer customization or per-customer branding, open an issue on the ERC-8004 Explorer with your use case.

FAQ

Does the embed need JavaScript?

No. The badge is server-rendered HTML and works in environments that strip JS (GitHub READMEs via image proxies, Notion embed blocks, basic RSS readers that allow iframes).

Does the embedded data stay fresh?

The server caches each agent’s data for ~30 seconds, so a refresh of the embedding page picks up any new feedback or validations within roughly that window. Cache is shared with the agent detail page so there’s no extra cost the first time someone hits the embed.

Can I customize the colors beyond light / dark?

Not in v1. Only theme=light and theme=dark are supported. Custom palettes would require either CSS variables exposed to the host page (which iframes can’t do across origins) or a separate per-agent theme. Both are out of scope for v1.

Why doesn't the iframe link open in a new tab?

It does. The attribution link inside the iframe uses target="_top", which navigates the top-level browser tab to the agent’s detail page. The iframe is too small for an in-place page load, and target="_blank" is often blocked inside iframes anyway.

Can I embed an agent from a testnet?

Yes. Direct URLs to testnet agents are honored regardless of the Explorer’s testnet-visibility toggle (the toggle is presentational, not access control).