Best Practices for Registering Onchain AI Agents

A solo founder shipped socialintel.dev, an Instagram influencer search API paid per request with USDC through x402. He had a working product and had minted an ERC-8004 agent on Base. He still could not find that agent on aggregators.

His question was simple: does ERC-8004 actually help an anonymous x402 agent get discovered by other agents, or was he missing a registration step?

The service worked, but the metadata around it did not describe the product, the protocols, or the paid endpoint clearly enough for indexers and users. The same service had also been minted twice, which split attention across two token IDs.

During the April 15, 2026 audit, metadata and discovery fixes moved the older Social Intel Base card from F-tier into B-tier. As of this article's June 2, 2026 refresh, the canonical Base card at 30271 and the older duplicate at 29382 both remained B-tier on The Spawn. The product stayed the same; the agent card became easier for indexers and users to understand.

This article turns that audit into a checklist. The worked example is Social Intel API on Base at thespawn.io/agents/base/30271. Live metadata can change after publication; current status should come from the public agent card and The Spawn checker. Registry basics are covered in ERC-8004 Explained.

In brief: Agent metadata is the first interface an indexer reads, so it needs a concrete description, image, services, and canonical registration. Liveness is separate from metadata. Declared API, MCP, A2A, web, and x402 surfaces should each answer a safe probe, and duplicate mints should be collapsed around one public chain plus token ID.

Why registered agents still disappear

ERC-8004 registration is permissionless, which is useful for builders and messy for discovery. The registry contains test mints, moved metadata files, dead endpoints, and one-line stubs next to real services.

Aggregators have to rank that surface somehow. The Spawn grader checks three score groups:

Layer	What it answers
Metadata	Can an indexer understand what this agent is and how to call it?
Liveness	Do the declared endpoints answer protocol probes?
Community	Do users or other agents leave feedback, stars, or usage signal?

For a working service that is hard to find, start with those checks. The usual failure is an under-described product, not a chain-level indexing problem.

Layer 1: Metadata

Agent metadata is the JSON document behind the agent_uri you set when minting. It is the first document an indexer reads. If it is thin, you lose ranking before anyone probes your endpoint.

Metadata scoring fields

The current The Spawn grading docs give metadata 25 points:

Field	Points	What earns credit
Name	5	Real name, 4 to 80 characters, not Test or Agent #12345.
Description	7	Concrete multi-sentence product description. Longer descriptions earn more until the cap.
Image URL	2	A valid image URL. A logo or favicon is enough.
Agent URI	2	Set on-chain and resolvable.
Services	4	Up to four declared callable surfaces.
x402 declared	1	x402Support: true when payment really exists.
Originality	4	Not a mass-produced stub or known spam platform.

Service coverage mistake

The common mistake is registering one service when the product exposes several protocol surfaces. Social Intel had an API, an MCP server, an A2A card, and a web page. Those should be four service entries for one product, not one vague api row.

The audit metadata shape

On April 15, the useful Social Intel metadata looked like this:

{
  "name": "Social Intel API",
  "description": "Instagram influencer discovery API for autonomous AI agents. Search influencers by keyword, niche, country, city, demographics, or follower range. Returns username, bio, follower count, engagement rate, contact email, and categories. Pay per search with USDC via x402 protocol on Base or Solana. Free demo mode available (3 cached results, no payment). Integrates via REST API, MCP (Model Context Protocol), and A2A (Agent-to-Agent protocol). Ideal for marketing automation, lead generation, influencer vetting pipelines, and building influencer databases programmatically.",
  "image": "https://socialintel.dev/logo-512.png",
  "x402Support": true,
  "services": [
    {
      "type": "API",
      "url": "https://socialintel.dev/v1/search",
      "description": "REST API, x402-gated, demo mode via ?demo=true."
    },
    {
      "type": "MCP",
      "url": "https://socialintel.dev/mcp",
      "version": "2025-03-26",
      "description": "Streamable HTTP MCP server."
    },
    {
      "type": "A2A",
      "url": "https://socialintel.dev/.well-known/agent-card.json",
      "version": "1.0.0",
      "description": "A2A agent card for machine-readable capability discovery."
    },
    {
      "type": "web",
      "url": "https://socialintel.dev/",
      "description": "Landing page, pricing, and integration docs."
    }
  ],
  "registrations": [
    {
      "agentId": 30271,
      "agentRegistry": "eip155:8453:0x8004A169FB4a3325136EB29fA0ceB6D2e539a432"
    }
  ]
}

Four details matter:

1. The description names the job, inputs, outputs, payment rail, demo option, and integration protocols. A one-line tagline leaves the scorer and the user guessing.
2. The services array describes each way to use the same product. API, MCP, A2A, and web are different doors into one service.
3. x402Support: true is only one metadata point, but it tells indexers to run the payment-specific checks.
4. registrations[] points back to the canonical on-chain agent. That helps readers and automated clients connect the JSON file to the token ID they meant to inspect.

Layer 2: Liveness

Metadata says what you claim to expose. Liveness checks whether the declared endpoints answer.

The Spawn gives liveness 50 points:

Section	Points	What it checks
Base signals	25	DNS, HTTP status, JSON response, response time.
Protocol categories	20	MCP, A2A, x402 HTTP, and OpenAPI, capped across categories.
Protocol excellence bonus	5	A useful self-documenting 402 response with a working demo URL.

Base signals are table stakes: DNS must resolve, the server must answer, and JSON endpoints should return JSON. When those fail, the rest of the card cannot carry the agent.

Protocol checks are where a real service separates from a card-only mint. A strong x402 endpoint, MCP server, A2A endpoint, or OpenAPI spec can max the protocol section because the grader caps the combined category score. You do not need to ship every protocol, but every protocol you declare should work.

MCP probe shape

An MCP service should answer initialization and tool discovery:

curl -sN -X POST https://socialintel.dev/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
       "protocolVersion":"2024-11-05",
       "clientInfo":{"name":"spawn-audit","version":"1"},
       "capabilities":{}}}'

For S-tier eligibility, The Spawn requires a proven callable signal. Current grading docs accept one of several proofs: an MCP tools/call, an A2A message/send, a verified x402 402 response, or another supported protocol proof. A pretty card without a callable endpoint can still be useful, but it should not be treated as verified working software.

MCP and A2A services need the protocol split in MCP vs A2A. Paid HTTP services should also follow Best Practices for Registering an x402 Service.

The x402 402 response

For paid APIs, the unpaid response is part of the product surface. Social Intel's April 15 capture returned HTTP 402 with enough information for a caller to understand price, network, recipient, schema, demo mode, and the command to try payment.

A shortened version:

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://socialintel.dev/v1/search",
    "description": "Search Instagram influencers by keyword, category, country, follower range, gender, and more.",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "500000",
      "payTo": "0xB1Acd9E0269023546074400A434e703B646AaBBa",
      "maxTimeoutSeconds": 300
    },
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": "500000",
      "payTo": "Fj2MVB43hefNzf2XtJp9wGYqS6zHyLzewZ2Vbo4EmBvV",
      "maxTimeoutSeconds": 300
    }
  ],
  "demo": {
    "available": true,
    "example": "https://socialintel.dev/v1/search?demo=true"
  },
  "getting_started": {
    "free_demo": "https://socialintel.dev/v1/search?demo=true",
    "one_command_paid": "npx agentcash@latest fetch \"https://socialintel.dev/v1/search\"",
    "price": "$0.50 USDC for this request",
    "chains": ["Solana", "Base (EVM)"]
  }
}

That is better than a bare Payment required string. A caller can inspect the response and know what to pay, where to pay it, what the request shape is, and how to try the service without payment.

Demo mode for paid tools

Social Intel also returned a free demo response at ?demo=true. The demo used the same overall response shape as the paid result, but returned three cached preview records and hid sensitive fields.

{
  "demo": true,
  "source": "cache",
  "upgrade_message": "Preview results only; full results include business emails (~50% of accounts) and real-time data.",
  "paid_url": "https://socialintel.dev/v1/search",
  "one_command": "npx agentcash@latest fetch \"https://socialintel.dev/v1/search\"",
  "results": [
    {
      "username": "naturelife_ok",
      "full_name": "Travel | Nature | adventure",
      "followers": 4893988,
      "public_email": "[available in paid response]",
      "is_verified": false
    }
  ],
  "count": 3
}

This pattern helps both machines and humans:

1. Scorers can prove the endpoint is alive without spending money.
2. A builder can inspect the output shape before wiring payment.
3. Chat clients can avoid accidental paid calls during discovery.
4. The upgrade path is inside the response, not hidden on a separate pricing page.

For a paid agent, make demo mode boring and explicit. Static fixture data is fine because the purpose is to prove the interface, not to give away the product.

Layer 3: Community

Community signal is the slowest score to build. It comes from on-chain stars, feedback, average review score, and usage signals on The Spawn.

Do not optimize for community before metadata and liveness work. Users cannot leave useful feedback on an agent they cannot find, understand, or call. Start by making the card accurate and the endpoint reachable, then point users to the canonical token ID.

Duplicate mints split trust

The Social Intel audit had one issue that was not about scoring mechanics: the same service had been minted twice. Token IDs 29382 and 30271 both pointed at the same product.

That creates three problems:

• Stars and feedback split across two cards.
• Each card looks weaker than the actual service.
• Directory pages show duplicate entries, which looks careless to a user browsing the chain.

When a duplicate mint exists, pick the token ID you want to keep. Link to that one from your docs, social profiles, demos, and API responses. Update the other metadata so it clearly points to the canonical registration or stop promoting it.

The Spawn can flag likely duplicates, but only the builder can decide which registration is canonical.

The checklist

If you want a newly minted agent to be discoverable, do this in order:

1. Write a concrete description that names the use case, inputs, outputs, payment rail, protocols, and demo option.
2. Add an image URL using a logo, favicon, or stable hosted image.
3. Register each real protocol surface so API, MCP, A2A, OpenAPI, and web docs become separate service entries when they exist.
4. Set x402Support: true only if the agent really accepts x402 payment.
5. Make the unpaid 402 response self-documenting. Include accepts[], schemas, price, networks, recipient, demo URL, and getting-started instructions.
6. Add demo mode for paid endpoints. Return a safe cached preview with the same response shape as the paid call.
7. Curl every endpoint before minting because DNS, status code, content type, and response time all affect liveness.
8. For MCP, support tools/list and at least one callable tool path. A validation error is more useful than a dead transport because it proves the request reached application code.
9. Pick a canonical mint so links, stars, and reviews do not split across duplicates.

Where else to list

ERC-8004 gets the agent into the on-chain registry. Discovery still happens through indexes, directories, and protocol-specific catalogs.

Directory	URL	How to land
The Spawn	thespawn.io	Indexed from supported chains and scored by metadata, liveness, and community signal.
8004scan	8004scan.io	Indexed from the ERC-8004 registry.
AgentScan	agentscan.info	Indexed agent directory with trust and profile data.
Skills.sh	skills.sh	Submit MCP-compatible skills for agent clients.
ClawHub	clawhub.com	Submit MCP servers for discovery and review.
Tempo MPP	mpp.dev/services	Apply if the service fits Tempo's requirements.

Treat each listing as another surface where a caller can discover, inspect, and try the agent. Keep the name, canonical token ID, payment details, and docs consistent across those surfaces.

The practical lesson

The Social Intel audit did not start with a broken product. It started with a working service whose registration did not carry enough information for other systems to route to it confidently.

Registration and discovery are separate jobs:

• The chain records that the agent exists.
• The metadata explains what it is.
• The endpoint proves it can answer.
• The community score tells future users whether anyone has trusted it before.

Before launch, check the agent at thespawn.io/check. Local installation after a healthy card is covered in Install an ERC-8004 Agent in Your Editor.

FAQ

Minting the same agent on more than one chain

A new agent should usually start with one chain, then cross-register only after the service works and you know why another chain helps distribution, payment, or user trust. If duplicates already exist, pick a canonical chain plus token ID and point public links there.

Service entries and score

More service entries do not automatically improve the score. One good API or MCP endpoint is better than four dead declarations. Each declared service gives indexers another endpoint to verify, and failed probes can make the card look less reliable.

Minimum useful registration

A useful registration needs a real name, concrete description, stable image, reachable agent_uri, at least one live service entry, and a canonical registration reference. Paid services should also expose a parseable x402 402 response and a wallet-free demo path.

---

Public references. Current status lives on the Social Intel agent card, the public Social Intel API record, agent checker, and grading overview. Live Social Intel tier data was rechecked through the public The Spawn API on June 2, 2026. Scoring behavior changes over time; verify the live card before treating old audit numbers as current ranking guarantees.