# Explorer API

Everything the explorer shows, as JSON. Ask who operates a wallet, look up an agent, or page through the registry. No key, no sign-in.

## The basics

-   Every call is a plain `GET` that answers JSON. CORS is open, so a web page can call it too.
-   The base is `https://adapterscan.com/api`. It covers every mainnet (Robinhood Chain, Base and Ethereum), and each row says which chain it's on. Add `?chain=base` to any call to narrow it to one chain, or a comma-separated few.
-   The testnet is separate: `https://testnet.adapterscan.com/api`, same calls, Sepolia only.
-   Everything comes from what the indexer has already read. A call never waits on the chain.

## Who operates this wallet?

The question most callers have. Give it the address an agent is talking to:

```bash
curl "https://adapterscan.com/api/wallet/<address>"
```

```json
{
  "chain": "base",
  "verified": true,
  "self": null,
  "designation": { "account": "0x7099…79c8", "ubid": "0x5e63…c565", "setBy": "0x7099…79c8", "order": { … } },
  "identity": { "ubid": "0x5e63…c565", "boundAddress": "0xcf7e…0fc9", "tokenId": "7", "agentWallet": "0x7099…79c8", … },
  "chains": [ … ]
}
```

-   **verified: true** means both sides agree: the wallet says it works for the profile, and the profile names the wallet back. Only then is the link real.
-   **verified: false** is one side's claim alone. Treat it as unconfirmed.
-   **self** is set when the address is itself the agent (an account-bound profile).
-   The answer is `null` when nobody claims the address. An address can be claimed on more than one chain: `chains` has each answer, and the fields above are the first.
-   **identity** is the bare record. For its name, picture and reputation, ask `/identity/<ubid>`.

For everything about an address - its own profile, what it operates, the profiles it holds the deed to, the statements it has made - use `/address/<address>`.

## Look up an agent

| Call | Answers |
| --- | --- |
| /search?q=<text> | Profiles matching a name, a UBID, an address, a token or an ERC-8004 id. What the explorer's search box asks. |
| /identity/<ubid> | One profile: its name and card, what it's bound to and who holds that, its operating wallet, and its reputation (stars, ratings, reviews, transaction records). 404 if there's no such UBID. |
| /history/<ubid> | Every event behind a profile, in order, with what each one did. Events that failed their checks are there too, marked. |
| /attestations?ubid=<ubid> | The statements made about a profile, newest first. |
| /attestation/<id> | One statement, with the fields its id is hashed from, so you can check it yourself. |

```bash
curl "https://adapterscan.com/api/search?q=normie"
curl "https://adapterscan.com/api/identity/0xfd7d1b959d39a1871fa1794a5aab9f224fa93e8954185803dfc5352b4be1e655"
```

## Lists and paging

Lists answer a page, newest first: `{ items, total, offset, limit }`. 25 rows unless you ask for more with `limit` (up to 200). Walk through with `offset`.

| Call | Filters |
| --- | --- |
| /identities | `q` (a name), `registration` (registered, counterfactual), `standard` (ERC721, ACCOUNT, …), `bound` (a contract), `tokenId` |
| /attestations | `type` (STAR, RATING, REVIEW, INTERACTION, CONFIRM\_ACCOUNT), `standard`, `attester`, `ubid` |
| /collections | The collections profiles are bound to, the most profiles first. `sort=newest`, `q` (a name or address) |
| /collection/<contract> | One collection on each chain it's on. Its profiles: `/identities?bound=<contract>` |
| /overview | Totals, and each chain's figures and how its indexer is doing |

```bash
# every on-chain agent in a collection, 100 at a time
curl "https://adapterscan.com/api/identities?bound=0x9eb6e2025b64f340691e424b7fe7022ffde12438&registration=registered&limit=100&offset=0"
```

## Fair use

The API is free and open, with a limit per caller so one script can't slow it down for everyone. You get **300 requests a minute**, in bursts of up to 60. Social card images and CSV exports have their own, smaller allowance of 20 a minute.

-   Every answer says where you stand: `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds).
-   Over the limit you get a `429` with `Retry-After` in seconds. Wait that long and carry on.
-   Paging through the whole registry fits comfortably: at 200 rows a request, 25,000 profiles is 125 requests.

> Building something that needs more? Get in touch rather than spreading requests across addresses.

## For agents

`https://adapterscan.com/llms.txt` describes all of this in plain text, for an agent to read before it calls. The explorer's pages also answer a plain fetch with a short text summary of what's on them, and these docs are Markdown at the same path with `.md` on the end.
