Mohammad Mudassir

Posted on Jul 28

Branding Your x402 Merchant on the GoPlausible Dashboard

#ai #agents #web3 #x402

"Your merchant name, logo, and description aren't read from your x402 config they're scraped from your website. Here's how to make your merchant look right in the dashboard."

If you've deployed an x402-enabled API and noticed your merchant shows up in the GoPlausible dashboard with a missing logo or a generic name, this guide is for you.

The key thing to understand: your merchant name, logo, and description are not read from your x402 config. They're scraped from your website's root HTML or, if you don't have a website, from your Algorand NFD.

How Merchant Enrichment Works

The facilitator enriches your merchant profile from the following sources, in priority order:

Dashboard Field	Source
Merchant Name	`og:site_name` → `og:title` → `<title>`
Description	`og:description` → meta description
Logo	`og:image` (public HTTPS URL)
Endpoint Description	`description` in `paymentMiddleware()`

So the only piece of branding that comes from your code is the endpoint description. Everything else comes from your domain's root page.

Prerequisites

Before enrichment can happen at all, make sure you have:

A real HTTPS domain. Localhost and tunnels won't be scraped.
Bazaar discovery enabled, along with the x402-global-challenge tag.
At least one settlement completed through the GoPlausible facilitator enrichment is triggered by settlement activity.

Step 1: Add Website Metadata

Add standard Open Graph tags to the <head> of your site's root page:

<title>YourName</title>
<meta name="description" content="Your one-line pitch">
<meta property="og:site_name" content="YourName">
<meta property="og:title" content="YourName">
<meta property="og:description" content="Your one-line pitch">
<meta property="og:image" content="https://your-domain/logo.png">

That's the whole trick. If these tags exist and are reachable at your domain root, the dashboard picks them up.

Step 2: Content-Negotiate if Your Root Returns JSON

Many x402 merchants are pure APIs, so hitting / returns JSON. That gives the scraper nothing to work with. The fix is simple content negotiation:

Serve JSON to API clients (e.g. Accept: application/json).
Serve HTML containing your metadata to browsers and crawlers.

Your API consumers never notice, and the scraper gets what it needs.

Step 3: Host Your Logo

Host your logo at a stable URL like https://your-domain/logo.png.
Make sure it's publicly accessible over HTTPS no auth walls, no redirects to login pages.

Step 4: Trigger Re-enrichment

Already deployed with the old (or missing) metadata? Enrichment doesn't refresh instantly. To pick up your changes:

Make another settlement through the facilitator, or
Wait for the facilitator to rescrape your domain on its own schedule.

Verification Checklist

Before assuming something is broken, verify each link in the chain:

# 1. Metadata is actually served at the root
curl -H "Accept: text/html" https://your-domain/ | grep og:

# 2. Logo returns HTTP 200
curl -I https://your-domain/logo.png

# 3. Your merchant appears in facilitator discovery

If all three check out and you've made a fresh settlement, your branding should appear on the dashboard.

No Website? Use an Algorand NFD

If you're running a headless service with no web presence, you can still get branded: register an Algorand NFD for your payTo address. The Bazaar can enrich your merchant profile directly from the NFD, pulling your name and avatar from there instead of a website.

That's it a few meta tags, a public logo, and one settlement, and your x402 merchant goes from anonymous endpoint to a properly branded listing.

DEV Community