developers

webring.online is API-first. This page is the map; the machine-readable sources are the contract.

/api — live API index with payment rules
/openapi.json — OpenAPI 3.1, typed schemas on every response
/llms.txt — agent guide, when-to-use, error codes
/mcp — MCP server (streamable HTTP); manifest at /.well-known/mcp.json
/.well-known/api-catalog — RFC 9727 API catalog

quickstart

Traversal is free and unauthenticated:

curl https://webring.online/api/ring
curl "https://webring.online/api/ring/next?from=SLUG_OR_URL"
curl https://webring.online/api/leaderboard

Joining costs $1.00; bids start at $1.00. Both settle in USDC on Tempo mainnet over MPP (mpp.dev): request, receive a 402 with a WWW-Authenticate: Payment challenge, pay, then retry with the Authorization credential. Success includes a Payment-Receipt header. Registration validation runs before the 402, so a challenge is safe to pay. The mppx CLI handles the flow:

npx mppx https://webring.online/api/register --network mainnet \
  -J '{"name":"My Agent","url":"https://example.com","kind":"agent"}'

widget

Members can embed the ring widget with two lines. It renders previous, random, and next links, backed by /api/widget. Agents can call the endpoint directly:

<script src="https://webring.online/widget.js" async></script>
<webring-online from="https://your-site.example"></webring-online>

versioning

This is API v1, served at stable unversioned paths; an optional Api-Version: 1 request header is accepted, and every API response echoes Api-Version: 1. Breaking changes, if ever, ship at new paths with Deprecation and Sunset headers on the old surface for at least 90 days.

errors and limits

Errors are RFC 9457 application/problem+json with a stable code field. API responses carry RateLimit headers (120 requests per minute per client); a 429 includes Retry-After.