# graded.sh: the graded x402 gateway

> A graded index of about 4,900 x402 (HTTP-402, machine-payable) services, each scored A to F for agent usability, plus a payment gateway: one API key pays for any passing service with prepaid credits. Fund with USDC on Base or a credit card; no crypto wallet required. An agent can create its own account and start calling services with no email and no human in the loop.

Everything here is built for autonomous agents. Discovery (search, service detail, grades) is free. You only pay when you successfully call a service through the gateway: the upstream x402 price plus a 25% markup (minimum $0.005). Failed and errored calls are auto-refunded. Data includes x402 service listings from x402-list.com, used under CC BY 4.0.

## Start here (for agents)
- [Full agent guide](https://graded.sh/llms-full.txt): complete REST + MCP contract with copy-pasteable examples, self-onboarding flow, and pricing.
- [MCP endpoint](https://graded.sh/mcp): streamable HTTP MCP server. Tools: list_services, get_service, get_service_history, call_service, create_account, account, top_up_info.
- [Machine discovery doc](https://graded.sh/.well-known/x402): x402 resource descriptor (JSON) for directory crawlers.

## REST API (no key needed to browse)
- [Search the catalog](https://graded.sh/v1/services): `GET /v1/services?query=&grade=A,B&callable=1&offset=0&limit=25`. Free. Ranked by real 30-day demand and grade.
- [Service detail](https://graded.sh/v1/services): `GET /v1/services/:id`: grade breakdown, live price, your price, input schema, output example. Free.
- [Service history](https://graded.sh/v1/services): `GET /v1/services/:id/history?days=30` (1 to 90). Daily UTC buckets from our 6-hourly probes: uptime %, 402/2xx %, p50/p95 latency, grade per day, price changes, probe counts. Free. Also the MCP tool get_service_history.
- [Status badge](https://graded.sh/methodology): `https://graded.sh/badge/:id.svg` shows the current grade and 30-day uptime; it links to the service page `https://graded.sh/s/:id`. Free to embed.
- [Catalog stats](https://graded.sh/v1/stats): `GET /v1/stats`: live service counts, grade distribution, last probe time. This is the source of truth for any number.
- [Create an account](https://graded.sh/v1/accounts): `POST /v1/accounts`: returns a secret gwk_ key. No email, no human. Free.
- [Account balance & history](https://graded.sh/v1/account): `GET /v1/account` with `Authorization: Bearer gwk_...`.
- [Call a service](https://graded.sh/v1/services): `POST /v1/call/:id` with your Bearer key: the gateway pays the upstream service from its own wallet and deducts your credits.

## Fund an account
- [x402 top-up (USDC on Base)](https://graded.sh/v1/topup): `POST /v1/topup`, x402-gated, credited 1:1.
- [Card top-up (Stripe)](https://graded.sh/v1/stripe/checkout): `POST /v1/stripe/checkout` with a Bearer key and `{"pack": 5 | 10 | 20}` (USD): returns a hosted card-checkout URL. Live now.

## About
- [Grading methodology](https://graded.sh/methodology): how the A to F agent-usability grade is computed.
- [About graded.sh](https://graded.sh/about): what this is and who runs it.