# Public Directory

Canonical URL: https://agent.payrail.one/docs/api/directory
Markdown URL: https://agent.payrail.one/docs/api/directory.md
Summary: Use this page when an agent or a page needs to find sellers without an account: natural-language search, the filterable list, one provider method with its guidance, and the trust record behind a hostname.
Description: Open, key-less HTTP directory of sellers with an advisory trust verdict on every listing.

## Canonical Answer

Use this page when an agent or a page needs to find sellers without an account: natural-language search, the filterable list, one provider method with its guidance, and the trust record behind a hostname. Open, key-less HTTP directory of sellers with an advisory trust verdict on every listing. Protected payment and identity data stays behind Payrail Agent requests instead of entering LLM-visible context.

## Key Points

- No API key, account, or login: the same access model as x402 Bazaar.
- The same natural-language search the signed-in tool runs, joined to trust.
- Every listing carries a verdict; purchase statistics publish only above a floor.
- Read-only. Nothing on this surface probes a seller, writes, or pays.

## Endpoints

Four GET routes under the API base URL from the API Reference page. Responses are JSON, cacheable for five minutes, and answer every browser origin.

```ts
GET /api/public/v1/services?q=find+live+hotel+availability
GET /api/public/v1/services?category=data&verdict=proceed&payable=true
GET /api/public/v1/services/{slug}
GET /api/public/v1/merchants/{hostname}
```

## Search and List

With `q`, the directory runs the internal Payrail Agent Search ranking unchanged: an exact provider or method name resolves directly, anything else is embedded once and the nearest three enabled methods within the similarity band are returned. Without `q`, the full enabled list is returned with `category`, `verdict`, `kind`, `payable`, `hostname` and `limit` filters plus category facets. List items omit `guidance`; the slug route returns it in full.

## Trust Block

Each item carries `trust`: the verdict, score, probe outcome and age, the network, asset and price the seller advertised on the last probe, and any operator override. It is advisory. A verdict never authorizes a payment; Payrail Agent approval does. `stats` holds settled-payment counts and the delivery rate for the hostname and is `null` below five settled payments.

## Limits

Search is rate-limited per caller and by a daily allowance because each novel query costs one embedding. A limited caller receives 429 and an exhausted allowance receives 503, both with `Retry-After`; the plain list keeps working. Queries are capped at 1024 UTF-8 bytes.

## Reserved Filter

The `verified` parameter is reserved for the Verified badge, which does not exist yet; requests carrying it are rejected with 400 so nothing can silently mean less than it says. Use `verdict=proceed` for the closest current filter.

## Related

- API Reference: https://agent.payrail.one/docs/api
- Payrail Agent Search: https://agent.payrail.one/docs/components/payrailAgentSearch
- Trust System: https://agent.payrail.one/docs/reference/trust-system