# agents.md - AgentShoppable

AgentShoppable tests whether AI shopping agents can find, understand, recommend
and buy from an online store. This file tells an agent how to use us.

## Identify yourself

We verify **RFC 9421 HTTP Message Signatures** (Web Bot Auth, signature tag
`web-bot-auth`, Ed25519). Sign at least `@method @authority @path
signature-agent` and send:

```
signature-agent: "https://your-agent.example"
signature-input: sig1=("@method" "@authority" "@path" "signature-agent");created=..;expires=..;keyid="<JWK thumbprint>";alg="ed25519";tag="web-bot-auth"
signature: sig1=:<base64>:
```

Publish your public key at `/.well-known/http-message-signatures-directory` so we
can verify it. Ours is at
<https://agentshoppable.com/.well-known/http-message-signatures-directory>; we
sign our own requests to merchants with that key, so a merchant seeing
`Signature-Agent: "https://agentshoppable.com"` can confirm the request was ours.

An unsigned agent is still served every path `robots.txt` allows. A signature
buys a higher rate limit, not access.

## Discovery

- Agent profile (UCP): <https://agentshoppable.com/.well-known/ucp>
- Key directory: <https://agentshoppable.com/.well-known/http-message-signatures-directory>
- Summary for models: <https://agentshoppable.com/llms.txt>
- Research and public data: <https://agentshoppable.com/research>, <https://agentshoppable.com/data/>

## Scanning a store on a shopper's behalf

`POST https://agentshoppable.com/v1/public/scans` with
`{"storefrontUrl":"https://example.com"}` returns `{"reportId":"..."}`. Read it at
`GET /v1/public/reports/{reportId}`. Three per hour per visitor. Non-passing
findings unlock with the merchant's email.

A scan reads public endpoints and creates one test cart that it cancels.
**Nothing is ever purchased.** Do not estimate a store's result: run the scan or
ask the merchant for their report link.

## Rate limits and human approval

Three free scans per hour per visitor. Plans and billing are a human decision:
do not subscribe a merchant to a paid plan on their behalf. Send billing and
agency questions to <hello@agentshoppable.com>.