Searching a term tells you who ranks for it. The useful question runs the other way — given a domain, which terms does it win, and where? Answering that by hand means thousands of searches. Here’s how an agent asks it once.
POST a domain and the ranked-keywords stall returns the terms it currently ranks for in organic search — each with its position, search volume, CPC, competition, and the exact URL and title that rank. That last part matters: knowing a domain ranks for a term is half an answer; knowing which page does is what an agent can act on. Pay-per-call over x402, no key.
# Every keyword a domain already ranks for, with position.
curl -s -X POST https://true402.dev/api/v1/ranked-keywords \
-H 'content-type: application/json' \
-d '{"target": "x402.org", "limit": 5}'
# → { target, observed, totalRanked, returned,
# keywords: [ { keyword, position, searchVolume, cpc,
# competition, url, title } ],
# location, language, limits: [...] }The endpoint works the same on any domain, which is what makes it competitor research rather than self-reporting. Anyone can search a term and see who appears; this just answers the question at scale. Run it on a rival to see the terms they own, then run keyword-volume on the ones you do not — demand you are not capturing is the gap worth writing for.
This is a crawl snapshot for one search engine, one location, one language — not a query issued the moment you ask. Positions move, and personalisation means two people can see different results for the same term. Every response carries that in a limits[] field rather than leaving an agent to infer it. A domain the index holds nothing for returns observed: false with a note — never zero keywords, which would be a claim about the domain rather than about our data.
An unpaid request returns HTTP 402 with payment requirements; the agent pays USDC on Base and retries — no subscription, no dashboard login. Want who links to a domain instead? Backlinks. Looking for terms to target? Keyword ideas. New to the protocol? What is x402? Full reference: API docs.
It calls a ranked-keywords endpoint that already holds the positions. true402’s ranked-keywords stall does this: POST a domain to /api/v1/ranked-keywords and it returns the keywords that domain currently ranks for in organic search, each with its position, search volume, CPC, competition, and the exact URL and title that rank. No account, no seat, no API key — the agent pays per call over x402.
Yes — that is the common use. Rankings are public: anyone can search a term and see who appears. This endpoint simply answers the reverse question at scale, turning "which terms does this domain win?" into one call instead of thousands of manual searches. It works identically on your own domain and on anyone else’s.
Keyword research asks what demand exists; ranked keywords asks what a domain already captures. They answer different halves of the same question. An agent typically runs both: keyword-volume to size demand for terms it is considering, and ranked-keywords to see which of those a domain already owns and which are still open.
No, and the response says so. It is a crawl snapshot for one search engine, one location and one language — not a live query issued at the moment you ask. Positions move, and personalisation means two people can see different results for the same term. That caveat ships inside every response in a limits[] field so an agent consuming the data sees it.
It comes back as observed: false with a note, never as "0 keywords". A brand-new or very small site may hold no rankings the index has crawled, and reporting that as zero would assert the domain ranks for nothing — a claim about the world rather than about our data. The service reports what it holds and declines to dress an absence up as a finding.