Pagination and filtering

Agent collection operations accept limit and offset. The free catalog returns at most 100 agents per request; use consecutive pages instead of requesting an unbounded export.

curl 'https://trust8004.xyz/api/v1/catalog/agents?limit=100&offset=0'

The response includes items, total, limit, and offset. Continue with offsets 100, 200, and so on until offset + items.length >= total.

offset is for shallow browsing: the database has to read and discard every skipped row, so a page at offset 150000 sorts the whole registry to return 100 agents. The free catalog therefore accepts offsets up to 10000 and answers 400 beyond it. To read the whole catalog, use the cursor below.

Enumerating every agent

afterId is a keyset cursor and the supported way to walk the full catalog. It returns agents whose id is greater than the value you pass, ordered by id ascending, and costs the same at any depth. Start at 0 and pass the id of the last item of each page:

curl 'https://trust8004.xyz/api/v1/catalog/agents?afterId=0&limit=100'
# ...then, with the id of the last item returned:
curl 'https://trust8004.xyz/api/v1/catalog/agents?afterId=41300&limit=100'

Stop when a page returns fewer than limit items. Cursor responses have no total field at all — the short page is the end of the walk, and counting the remainder on every page would cost as much as the scan the cursor avoids. Every indexed agent is reachable this way, on the free tier, with no payment and no depth limit.

The cursor defines its own ordering, so it cannot be combined with search, sortBy, or sortOrder; each returns 400 rather than being ignored. Note that sortBy=id without a cursor sorts by the on-chain agentId string, which is a different column from the numeric id the cursor pages on. Filters such as chainIds, owner, and active compose with the cursor normally, so you can enumerate one chain or the whole registry.

afterId must be between 0 and 2147483647; anything else returns 400.

Agents by chain

Use chainIds for one or multiple registries:

# Base only
curl 'https://trust8004.xyz/api/v1/catalog/agents?chainIds=8453&limit=100&offset=0'

# Ethereum, Base, and BNB Chain
curl 'https://trust8004.xyz/api/v1/catalog/agents?chainIds=1,8453,56&limit=100&offset=0'

The returned total reflects the selected chains, so the same stopping rule works when traversing one chain or a group of chains.

Latest 100 agents

Registration time descending is the default. Specify it explicitly when the ordering is part of an integration contract:

# Across every indexed chain
curl 'https://trust8004.xyz/api/v1/catalog/agents?limit=100&sortBy=registered&sortOrder=desc'

# Latest 100 on BNB Chain
curl 'https://trust8004.xyz/api/v1/catalog/agents?chainIds=56&limit=100&sortBy=registered&sortOrder=desc'

“Latest” uses the indexed on-chain registration timestamp. Rows whose timestamp is still being repaired are placed after rows with confirmed timestamps.

Filters are applied inside PostgreSQL before ranking and pagination. This keeps totals and displayed results aligned, including when full-text search is active.

Search forms

The search parameter supports:

• text, such as sentinel;
• an agent ID, such as 42;
• a chain-qualified ID, such as 8453:42.

Text input is bounded to prevent excessively broad database work. Invalid input returns 400 before paid settlement.