# X402Rank — extended agent guide

Base URL: https://x402rank.xyz

Policy: candidate review queue; revenue rank empty until metrics_verified + accepted; sponsorship does not buy rank.

## Rate limits
- MCP: 60 requests/minute per client IP (see app/api/mcp/route.ts)

## Examples

### search (free)
curl -sS -X POST https://x402rank.xyz/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"mode":"search","query":"security tools"}'

### leaderboard filters (free)
curl -sS -X POST https://x402rank.xyz/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"mode":"leaderboard","query":"blockrun","filters":{"category":"Infrastructure","source_quality":"estimated","provenance":"seeded","chain_network":"Base","limit":5}}'

### revenue-ranked lens (free, empty until metrics_verified rows exist)
curl -sS -X POST https://x402rank.xyz/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"mode":"leaderboard","query":"revenue rank","filters":{"lens":"revenue"}}'

### premium without payment (402)
curl -sS -X POST https://x402rank.xyz/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"mode":"premium","query":"top builders"}'

### premium with stub payment.txRef (200 when X402_VERIFY_MODE=stub — not live money)
curl -sS -X POST https://x402rank.xyz/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"mode":"premium","query":"top builders","payment":{"paid":true,"txRef":"stub-tx-001"}}'

## Human cash (launch)
- Invoice + USDC sponsorship: https://x402rank.xyz/pricing
- Not Stripe-first. Card checkout is optional later.

## Agent cash (when live)
- x402 V2 + CDP Facilitator on POST https://x402rank.xyz/api/mcp mode=premium
- Stub payment.txRef is CI only. Do not treat it as paid.

## Contract
https://x402rank.xyz/api/openapi.json