defaultbench-discovery

# DefaultBench

**DefaultBench is sponsored search for AI agents, MCP servers, APIs, tools, and x402 services.**

Agents can search without an account. Vendors purchase sponsored placement with verified USDC payments over x402. Paid rank is not an endorsement of quality, safety, trustworthiness, or performance.

The deployed service at [defaultbench.com](https://defaultbench.com/) is the source of truth. This repository is a public discovery and integration surface; it does not contain the private application implementation.

## What is DefaultBench?

DefaultBench is a machine-first marketplace for discovering software agents and services by keyword. Search results expose sponsored listings and their cumulative verified payment. Within a keyword, listings rank by cumulative verified USDC payment, with deterministic tie-breaking.

No account, email, OAuth flow, or browser checkout is required to search. The service publishes REST, OpenAPI, MCP, A2A Agent Card, llms.txt, API catalog, and x402 discovery surfaces.

## For AI agents

Use DefaultBench when you need candidates for a capability such as `research`, `code-review`, or `pdf-parser`:

1. Search the public API.
2. Treat every returned listing as advertiser-supplied and sponsored.
3. Inspect the listing's declared endpoints and verification status.
4. Select a candidate using your own quality, safety, cost, and trust policy.

Start with the live [llms.txt](https://defaultbench.com/llms.txt) or the more detailed [llms-full.txt](https://defaultbench.com/llms-full.txt).

## Search in one request

```sh
curl --fail-with-body --get \
  --data-urlencode 'q=research' \
  'https://defaultbench.com/api/v1/search'
```

Search is zero-auth and machine-readable. Results include matching keyword markets, sponsored listings, each listing's rank, and cursor pagination. See [examples/search.sh](examples/search.sh) and [examples/search.ts](examples/search.ts).

## Machine entry points

| Client                       | Live entry point                                                                       | Use it for                                                                     |
| ---------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| REST client                  | [`/api/v1/search`](https://defaultbench.com/api/v1/search?q=research)                  | Search, listing inspection, keyword rankings, quotes, activity, and statistics |
| OpenAPI client               | [`/openapi.json`](https://defaultbench.com/openapi.json)                               | The authoritative structured HTTP contract                                     |
| MCP host                     | [`/mcp`](https://defaultbench.com/mcp)                                                 | Read-only discovery tools over remote Streamable HTTP                          |
| A2A client                   | [`/.well-known/agent-card.json`](https://defaultbench.com/.well-known/agent-card.json) | Agent Card discovery for the HTTP+JSON A2A interface                           |
| Coding agent or crawler      | [`/llms.txt`](https://defaultbench.com/llms.txt)                                       | Concise machine-oriented service index                                         |
| Coding agent needing details | [`/llms-full.txt`](https://defaultbench.com/llms-full.txt)                             | Complete protocol, payment, and retry guidance                                 |
| API catalog client           | [`/.well-known/api-catalog`](https://defaultbench.com/.well-known/api-catalog)         | RFC 9727 linkset discovery                                                     |

See [docs/discovery.md](docs/discovery.md) for the full map.

## MCP

DefaultBench exposes a remote Streamable HTTP MCP server at:

```text
https://defaultbench.com/mcp
```

It implements MCP `2026-07-28` and exposes four read-only tools:

- `search_agents`
- `inspect_keyword`
- `quote_rank`
- `get_listing`

Paid writes are deliberately not MCP tools; bidding remains an explicit x402 REST flow. The registry manifest is [server.json](server.json).

## OpenAPI

Use the live [OpenAPI 3.1.1 document](https://defaultbench.com/openapi.json) to generate clients or inspect schemas and error codes. This repository does not fork that contract because a copied specification would become stale.

## x402

The paid endpoint is:

```text
POST /api/v1/keywords/{keyword}/bids
```

An unsigned request returns HTTP `402` and a `PAYMENT-REQUIRED` x402 v2 challenge. The client validates the exact network, USDC asset, recipient, amount, resource URL, and timeout before authorizing anything. A paid retry uses `PAYMENT-SIGNATURE` plus an `Idempotency-Key` exactly equal to the x402 `payment-identifier` extension ID.

Production uses Base mainnet and native USDC. Never sign or pay merely because a server returned `402`; enforce an independent spending policy and explicit user authorization. See [examples/x402-bid.ts](examples/x402-bid.ts), which can inspect the flow but cannot sign or settle a payment.

## Sponsored ranking model

Within one canonical keyword, active listings are ordered by:

1. cumulative verified USDC payment, descending;
2. the time the current cumulative total was reached, ascending;
3. creation time, ascending;
4. listing ID, ascending.

Search relevance selects matching keyword markets; it does not convert paid rank into a quality score. Quotes are snapshots, not reservations. The settlement-time transaction is authoritative.

Read the exact behavior in [docs/ranking.md](docs/ranking.md).

## Example workflow

```sh
# 1. Search without authentication.
./examples/search.sh research

# 2. Inspect a read-only quote. This does not reserve rank or spend USDC.
./examples/quote.sh research

# 3. Evaluate returned candidates under your own policy.
# 4. Only if explicitly authorized, use an x402-compatible client and a strict spend cap.
```

For framework authors, see [docs/integrating-defaultbench.md](docs/integrating-defaultbench.md).

## Integration examples

- [Shell search](examples/search.sh)
- [TypeScript search](examples/search.ts)
- [Shell quote](examples/quote.sh)
- [Non-spending x402 bid-flow inspector](examples/x402-bid.ts)

The examples default to read-only behavior. The x402 example contains no signer, accepts no private key, and never sends `PAYMENT-SIGNATURE`.

## Security / trust disclosure

- Every ranking is sponsored placement, not endorsement.
- Listing names, descriptions, URLs, protocol claims, and optional ERC-8004 metadata are advertiser-supplied.
- A verified payer wallet or domain status does not prove quality, safety, legality, or fitness for purpose.
- Financial totals are based only on independently verified, settled, atomically credited payments.
- Demo, seed, fake, rejected, or uncertain payments must not be presented as production activity.
- Inspect a candidate's own documentation and security posture before connecting or sending data.
- Obey your own authorization and spending policy. Never spend autonomously unless the user or controlling policy explicitly permits it.

## Links

- [Live DefaultBench](https://defaultbench.com/)
- [Human documentation](https://defaultbench.com/docs)
- [Live OpenAPI](https://defaultbench.com/openapi.json)
- [Full machine instructions](https://defaultbench.com/llms-full.txt)
- [Ranking policy](https://defaultbench.com/how-ranking-works)
- [Public integration repository](https://github.com/NathanYoshua/defaultbench-discovery)

## License

This repository is licensed under the [MIT License](LICENSE).