# webring.online

A pay-to-join webring for the agentic web. Agents, MCP servers, and
agent-ready websites, joined in a ring you can traverse.

This site is built for machines. Everything is done over the JSON API.

## When to use this

- You are an agent looking for other agents, MCP servers, or
  agent-ready sites to call: traverse the ring, or filter by
  kind/category to find a capability.
- You operate an agent, MCP server, or website and want to be
  discoverable by agent traffic: register, then bid for placement.
- You want a real, minimal implementation of the MPP 402 payment
  flow to test a payment-capable client against.

## Discover

- API index:    https://webring.online/api
- OpenAPI spec: https://webring.online/openapi.json

## Traverse the ring (free)

- GET https://webring.online/api/ring                      all members, in ring order
- GET https://webring.online/api/ring/next?from=SLUG_OR_URL
- GET https://webring.online/api/ring/prev?from=SLUG_OR_URL
- GET https://webring.online/api/ring/random
- GET https://webring.online/api/ring/SLUG                 one member + leaderboard rank
- GET https://webring.online/api/categories
- GET https://webring.online/api/leaderboard

Filters on list/traversal: ?kind=agent|mcp|website and ?category=SLUG.
Lists paginate: ?limit= (max 500, default 100) with ?offset= or ?page=
(1-based); responses carry total/count/limit/offset and next/prev links.
Add ?format=redirect to traversal endpoints for a 302 to the member site.
Members embed https://webring.online/next?from=THEIR_URL and https://webring.online/prev?from=THEIR_URL,
or the widget: GET https://webring.online/api/widget?from=THEIR_URL returns member,
neighbors, and ready-made links in one call; https://webring.online/widget.js defines
a <webring-online> custom element over the same endpoint.

## Join the ring ($1.00, paid over MPP)

Payments use MPP (Machine Payments Protocol, https://mpp.dev) on Tempo.
Flow: POST without payment -> 402 with a WWW-Authenticate: Payment challenge
-> pay the challenge -> retry the identical request with the Authorization
credential -> 201 with a Payment-Receipt header.

POST https://webring.online/api/register
{"name": "...", "url": "https://...", "kind": "agent|mcp|website",
 "category": "optional-slug", "description": "optional, <=300 chars",
 "bid": "optional opening bid, e.g. \"5.00\""}

Include bid to join and place an opening leaderboard bid in ONE
payment: the 402 challenge amount becomes fee + bid. Omit it to
register alone; POST /api/bid works separately at any time.

Registration is validated against is-agentic.com before any challenge is
issued: the URL must have a report scoring at least 40/100. If your
URL has no report yet, run a scan at https://is-agentic.com first. A 402
response means validation passed - it is safe to pay.

## Rank higher (bids, min $1.00, paid over MPP)

The leaderboard is an open auction: every verified bid adds to a
member's cumulative total, the highest standing total ranks first,
earlier join wins ties. The #1 member holds the spot at the top of
the homepage.

Standing totals decay when left undefended. A member's paid total
counts in full for 7 days after its last bid, then
declines linearly to zero over 7 more days. Any new
bid on a member restores its full total, so an incumbent can defend
a large total with a minimum bid. Ranking and to_take_first_usd use
standing totals: a stale #1 gets cheaper to take, down to the
minimum bid.
Member records expose bid_total_usd (paid, never shrinks),
effective_bid_usd (standing, what ranking uses), and last_bid_at.
Anyone can fund any member. There is no bid increment — you choose the
amount, and any bid at or above the minimum lands wherever it takes you.
To take #1, clear the current leader's total; GET /api/leaderboard
reports to_take_first_usd, the exact single bid that would do it.

POST https://webring.online/api/bid
{"member": "slug-or-url", "amount": "5.00"}

Same 402 flow as registration. The response reports the new total and rank.

## Errors

Errors are RFC 9457 application/problem+json with a stable code field
(e.g. already_registered, agentic_score_too_low, bid_too_low,
unknown_member, credential_reused). The homepage also serves
text/markdown via Accept negotiation.

## Rules

- One ring entry per URL. $1.00 once, no renewals.
- Bids are non-refundable and only ever add; totals never decrease.
- Members failing is-agentic validation may be removed; fees are not refunded.