{"openapi":"3.1.0","info":{"title":"graded.sh API","version":"1.0.0","summary":"Graded index of x402 services and a prepaid gateway that pays them for you.","description":"Discovery is free and needs no key. Calling services needs a self-provisioned gwk_ key with prepaid credits. Full guide: https://graded.sh/llms-full.txt","contact":{"email":"hello@graded.sh","url":"https://graded.sh/about"}},"servers":[{"url":"https://graded.sh"}],"externalDocs":{"url":"https://graded.sh/llms-full.txt"},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"gwk_ agent key from POST /v1/accounts (or gwo_ owner key where noted). See /auth.md."}}},"paths":{"/v1/services":{"get":{"operationId":"listServices","summary":"Search the graded catalog (free)","parameters":[{"name":"query","in":"query","schema":{"type":"string"},"description":"Substring match on name, description, id or URL (alias q)"},{"name":"grade","in":"query","schema":{"type":"string"},"description":"Comma list, e.g. A,B"},{"name":"callable","in":"query","schema":{"type":"string","enum":["1","true"]},"description":"Only services the gateway can execute"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Matching services, callable first, then 30-day demand, then score","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}}}}},"/v1/services/{id}":{"get":{"operationId":"getService","summary":"Service detail: grade breakdown, prices, input schema, output example (free)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Service id, e.g. bz_8b5918356e66"}],"responses":{"200":{"description":"Service","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/services/{id}/history":{"get":{"operationId":"getServiceHistory","summary":"Daily uptime, 402/2xx rate, latency, grade and price history (free)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Service id, e.g. bz_8b5918356e66"},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}}],"responses":{"200":{"description":"History with summary and daily buckets","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/services/{id}/demand":{"get":{"operationId":"getServiceDemand","summary":"On-chain payment facts for the service's payTo address (free)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Service id, e.g. bz_8b5918356e66"}],"responses":{"200":{"description":"Payment facts","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/stats":{"get":{"operationId":"getStats","summary":"Live catalog counts and grade distribution (free)","responses":{"200":{"description":"Stats","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/accounts":{"post":{"operationId":"createAccount","summary":"Create an account and get a gwk_ key, shown once (free, no email)","responses":{"200":{"description":"New key","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"balance_usd":{"type":"string"}}}}}}}}},"/v1/account":{"get":{"operationId":"getAccount","summary":"Balance, totals, limits and recent calls","security":[{"bearer":[]}],"responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/account/limits":{"post":{"operationId":"setLimits","summary":"Set spending guardrails; null clears a field. After an owner key exists the agent key can only tighten.","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"max_call_usd":{"type":["number","null"],"exclusiveMinimum":0,"maximum":100},"daily_usd":{"type":["number","null"],"exclusiveMinimum":0,"maximum":1000},"min_grade":{"type":["string","null"],"enum":["A","B","C","D",null]},"allow":{"type":["array","null"],"items":{"type":"string"},"maxItems":200}}}}}},"responses":{"200":{"description":"Stored limits","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Only the owner key can loosen or clear this limit","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/account/owner-key":{"post":{"operationId":"createOwnerKey","summary":"One time: mint a gwo_ owner key for the human supervisor","security":[{"bearer":[]}],"responses":{"200":{"description":"Owner key, shown once","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"Owner key already exists","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/call/{id}":{"post":{"operationId":"callService","summary":"Call a service through the gateway; charges upstream price + 25% (min $0.005), refunds failures","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Service id, e.g. bz_8b5918356e66"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"object","description":"URL query params for the upstream service"},"body":{"type":"object","description":"JSON body for the upstream service"}}}}}},"responses":{"200":{"description":"Upstream result with charged_usd and balance_usd","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Service not callable through the gateway","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Insufficient credits, with top-up instructions","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Blocked by your account limits","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Daily spend cap reached","content":{"application/json":{"schema":{"type":"object"}}}},"502":{"description":"Upstream failed; not charged","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Gateway-wide daily cap reached","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/topup":{"get":{"operationId":"topUpInfo","summary":"How to add credits (free)","responses":{"200":{"description":"Instructions","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"topUp","summary":"Add credits with USDC on Base (x402-gated, credited 1:1). Unpaid requests get the 402 quote with or without a key; a paid request needs the key.","security":[{},{"bearer":[]}],"responses":{"200":{"description":"Credited","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Paid without a valid account key","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"x402 payment quote","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/stripe/checkout":{"post":{"operationId":"cardCheckout","summary":"Card top-up: returns a hosted checkout URL to hand to a human","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["pack"],"properties":{"pack":{"type":"integer","enum":[5,10,20]}}}}}},"responses":{"200":{"description":"Checkout URL","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"type":"object"}}}},"422":{"description":"Unknown pack","content":{"application/json":{"schema":{"type":"object"}}}},"502":{"description":"Checkout could not be created","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Card top-ups disabled","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/claims":{"get":{"operationId":"listClaims","summary":"Your service claims","security":[{"bearer":[]}],"responses":{"200":{"description":"Claims","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"createClaim","summary":"Start claiming a service you operate; returns a verification token","security":[{"bearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["service_id"],"properties":{"service_id":{"type":"string"}}}}}},"responses":{"200":{"description":"Claim with how_to_verify","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/claims/{id}/verify":{"post":{"operationId":"verifyClaim","summary":"Check the token at /.well-known/graded.txt or the X-Graded-Verify header","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Claim id"}],"responses":{"200":{"description":"Claim","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid key","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Checked a moment ago","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/badge/{file}":{"get":{"operationId":"getBadge","summary":"SVG status badge: current grade and 30-day uptime (free)","parameters":[{"name":"file","in":"path","required":true,"schema":{"type":"string"},"description":"{service id}.svg"}],"responses":{"200":{"description":"Badge","content":{"image/svg+xml":{}}}}}}}}