Documentation · How-to

How do I check if an ERC-8004 agent is reachable and payable?

Check four things in order: the agent’s on-chain registration, whether its endpoint answers, whether that endpoint returns a valid x402 402 Payment Required challenge with a payTo address and a price, and finally whether a small test payment actually settles and returns a response. The first three are free read-only checks; only the last proves an agent is payable. For market-wide numbers see /v1/public/stats and the adoption stats.

The four checks

  1. Registration. Read tokenURI(agentId) from the ERC-8004 IdentityRegistry on the agent’s chain and fetch the registration document. It should be valid JSON listing at least one service endpoint. See ERC-8004 explained for the registry addresses and document format.
  2. Reachability. Request each listed endpoint. The host should resolve, the TLS certificate should be valid, and the server should return an HTTP response. Any status code counts as “the host answered”; it does not yet mean the endpoint is usable.
  3. x402 challenge. Call the paid endpoint with no payment header. A payable endpoint replies 402 with an accepts array. Each entry should carry a scheme, a network, an asset, a payTo address and a price. Check that the address is a well-formed 0x address and the price is a plausible per-call amount. The cycle is described in x402 explained.
  4. Settled test payment. Sign one of the offers with a wallet holding a small amount, retry, and confirm that the payment settles on-chain to the advertised payTo and that the server then returns a substantive response. This is the only step that demonstrates the full path works. Use a small amount and a dedicated wallet.

Free per-agent lookup

Our public agent-detail endpoint summarises the observable signals for one indexed agent — host reachability and HTTP status, TLS validity, advertised x402 support, and whether any on-chain payment has been received — with no payment and no authentication: 

GET https://api.onchainagentintel.io/v1/public/agent/{chain}/{agent_id}

Use base or ethereum as the chain and the numeric agentId. The response reflects our most recent probe, not the present moment. The full catalog, including which endpoints are free and which are paid, is in agent.json; the schema is in the OpenAPI document.

Common failure signs

  • The registration document is missing, malformed, or points at a host that no longer resolves.
  • The host answers but the paid path returns 401 or 403 (an auth wall) or 405 (wrong method) instead of 402.
  • The 402 body has no accepts entries, or none with a valid payTo.
  • The challenge is valid but uses a payment format or protocol version a stock client cannot parse. Our interop field test documents this on a small sample.
  • Payment settles but no usable response follows.

We measured how agents fall off along this path in the payability funnel dataset and the endpoint probe write-up; read their method notes for exact stage definitions and caveats.

What these checks don’t prove

Reachable and payable describes plumbing at one moment in time. It does not show that the agent’s work is correct, that its owner is trustworthy, or that it will behave the same tomorrow. Combine it with ownership and reputation evidence, as in how to verify an ERC-8004 agent, and keep first payments small.

FAQ

How do I check if an ERC-8004 agent is reachable?

Read the agent’s tokenURI from the IdentityRegistry, fetch the registration document, and request each service endpoint it lists. An endpoint is reachable if the host resolves, the TLS handshake succeeds, and it returns an HTTP response. Reachability is a point-in-time observation: it says nothing about whether the agent will still answer later or will accept payment.

How do I check if an ERC-8004 agent can accept an x402 payment?

Call its paid endpoint without a payment header. A payable x402 endpoint answers HTTP 402 with a machine-readable list of payment options that includes a payTo address, a token, and a price. Missing options, an auth wall (401/403), or a method mismatch (405) are signs the endpoint cannot be paid by a generic x402 client. Only a test payment that settles on-chain and returns a response proves the full path.

Is advertising x402 support in the registration the same as being payable?

No. Registrations are self-declared and unverified. An agent can claim payment support while its endpoint is down, returns no 402 challenge, or uses a payment format a stock client cannot parse. Our published payability funnel treats these as separate stages for that reason.

Is there a free way to look up an agent’s reachability signals?

Yes. The public agent-detail endpoint returns a neutral summary for one agent, including host reachability, advertised x402 support, and whether any on-chain payment has been received. It is free and needs no authentication. Fill in the chain (base or ethereum) and the numeric agentId.

Does a reachable, payable agent deliver good work?

Not necessarily. These checks cover plumbing, not quality or honesty. Reputation feedback, ownership, and a small paid trial are separate evidence. Treat every check as one signal, and pay small amounts first.