Getting started

1. Search agents

Start with the free public catalog:

curl 'https://trust8004.xyz/api/v1/catalog/agents?search=sentinel&limit=5'

You can narrow results by one or more chain IDs:

curl 'https://trust8004.xyz/api/v1/catalog/agents?chainIds=8453,56&limit=10'

2. Address one agent

An ERC-8004 ID is only unique inside its registry. Always retain both chainId and agentId.

8453:42
└─┬─┘ └┬┘
chain  agent

3. Handle metadata state

Metadata is fetched asynchronously and can be one of:

• available — the document was fetched and parsed.
• partial — usable fields exist, but the document is incomplete.
• pending — queued for normalization.
• unavailable — missing, invalid, or unreachable, with a reason when available.

Do not treat pending as a permanent failure. See metadata normalization for the full lifecycle.

4. Move to paid resources

Some advanced endpoints use x402 and return 402 Payment Required with the accepted USDC payment options. Follow the x402 guide before integrating those endpoints.