# Auth.md

## Listing Roast x402 Auth

Listing Roast x402 does not use accounts, API keys, OAuth login, browser sign-up, or agent registration.

Access is HTTP-native:

1. Fetch free discovery documents.
2. Choose a route.
3. If the buyer explicitly intends to pay, call the paid route with x402.
4. The server returns HTTP 402 with payment requirements until a valid x402 payment is provided.
5. After payment, retry the same route with the payment header and read the JSON response.

## Supported Auth Method

- Type: x402 payment
- Network: eip155:8453
- Asset: USDC
- Receiver: available in the HTTP 402 payment challenge
- API keys: not required
- OAuth/OIDC: not supported
- Agent registration: not supported
- User account: not required

## Agent Registration

Agent registration is not supported and is not required for Listing Roast x402.

- Registration endpoint: none
- Identity endpoint: none
- Claim endpoint: none
- Token endpoint: none
- Authorization server: none
- Supported identity types: none
- Supported scopes: none

Agents authorize each paid API call by completing the x402 payment challenge for that exact request. There are no long-lived credentials to register, issue, refresh, or revoke.

## Free Discovery

- Homepage: https://listing-roast-x402-service-production.up.railway.app/
- x402 manifest: https://listing-roast-x402-service-production.up.railway.app/x402.json
- OpenAPI: https://listing-roast-x402-service-production.up.railway.app/.well-known/openapi.json
- API catalog: https://listing-roast-x402-service-production.up.railway.app/.well-known/api-catalog
- Agent card: https://listing-roast-x402-service-production.up.railway.app/.well-known/agent-card.json
- Agent Skills: https://listing-roast-x402-service-production.up.railway.app/.well-known/agent-skills/index.json
- MCP metadata: https://listing-roast-x402-service-production.up.railway.app/.well-known/mcp.json
- MCP server card: https://listing-roast-x402-service-production.up.railway.app/.well-known/mcp/server-card.json
- llms.txt: https://listing-roast-x402-service-production.up.railway.app/llms.txt
- Full Markdown guide: https://listing-roast-x402-service-production.up.railway.app/llms-full.txt
- Pay-now handoff: https://listing-roast-x402-service-production.up.railway.app/api/pay-now?intent=buyer-agent%20skip%20reasons
- Pricing catalog: https://listing-roast-x402-service-production.up.railway.app/api/pricing
- Route finder: https://listing-roast-x402-service-production.up.railway.app/api/find?q=x402%20discovery%20audit
- Local route router: https://listing-roast-x402-service-production.up.railway.app/api/route?query=x402%20discovery%20audit&top=3
- WebMCP handoff: load https://listing-roast-x402-service-production.up.railway.app/ in a WebMCP-capable browser and call `listing_roast_x402_handoff`.

## Preferred First Paid Action

Use the already-indexed GET route first when the buyer wants a quick listing quality score:

```bash
npx awal@2.8.0 x402 pay https://listing-roast-x402-service-production.up.railway.app/api/listing-roast \
  -X GET \
  --max-amount 1000
```

Expected price: $0.001. Max amount: 1000 USDC units.

## Recommended Paid Sequence

1. Start with GET https://listing-roast-x402-service-production.up.railway.app/api/listing-roast for $0.001, max 1000 USDC units. This is the already-indexed quick score route and the lowest-friction paid test.
2. Upgrade to POST https://listing-roast-x402-service-production.up.railway.app/api/listing-roast for $0.01, max 10000 USDC units only when the quick score is promising and the buyer wants the full rewrite, top fixes, and stop-or-upgrade guidance.

Full roast command:

```bash
npx awal@2.8.0 x402 pay https://listing-roast-x402-service-production.up.railway.app/api/listing-roast \
  -X POST \
  -d '{"agentName":"Example x402 API","listingText":"A paid x402 API that helps builders check whether buyer agents understand the offer before paying. It returns JSON with skip reasons, top fixes, a rewritten listing, and a stop-or-upgrade recommendation. Example payloads are included for quick testing.","targetBuyer":"x402 and MCP builders","currentPrice":"$1.00","currentCheckoutPath":"/api/listing-roast","goal":"Increase first paid conversion"}' \
  --max-amount 10000
```

## Paid Routes

- GET https://listing-roast-x402-service-production.up.railway.app/api — $0.001, max 1000; generic paid x402 navigation route map plus fallback quick score for agents that start at /api first.
- GET https://listing-roast-x402-service-production.up.railway.app/api/v1 — $0.001, max 1000; versioned paid x402 navigation route map plus fallback quick score for agents that start at /api/v1 first.
- GET https://listing-roast-x402-service-production.up.railway.app/v1 — $0.001, max 1000; short versioned paid x402 navigation route map plus fallback quick score for agents that start at /v1 first.
- GET https://listing-roast-x402-service-production.up.railway.app/api/listing-roast — $0.001, max 1000; already-indexed quick score.
- GET https://listing-roast-x402-service-production.up.railway.app/api/agent-listing-conversion — $0.001, max 1000; buyer-agent skip reasons and listing clarity.
- GET https://listing-roast-x402-service-production.up.railway.app/api/x402-site-audit — $0.001, max 1000; x402 route and discovery preflight.
- POST https://listing-roast-x402-service-production.up.railway.app/api/listing-score — $0.005, max 5000; structured listing quality score.
- POST https://listing-roast-x402-service-production.up.railway.app/api/x402-discovery-audit — $0.01, max 10000; full x402 discovery audit.
- POST https://listing-roast-x402-service-production.up.railway.app/api/listing-roast — $0.01, max 10000; full listing roast and rewrite.

## Guardrails For Agents

- Do not make a paid call unless the buyer explicitly intends to spend USDC.
- Do not use this document as an OAuth promise. OAuth is not available for this service.
- Do not ask the buyer for an API key or login. There is no account setup.
- Use the 402 payment challenge as the source of truth for the receiver, network, and amount.
- Use live wallet/register evidence before claiming revenue has settled.