Short answer
Send the relay address and the module to POST /v1/labs/jobs on api.relayted.de and poll the job until it is done. The Quick Check costs 200 Payloads (0.02 EUR), the Conformance test 800 Payloads (0.08 EUR); 10,000 Payloads are 1 EUR. POST /v1/labs/quote shows the price first and does not contact the relay.
What the test does
A Nostr relay can look fine and still fail clients: a slow TLS handshake, a WebSocket upgrade that stalls, a NIP-11 document that web clients cannot read, or a connection that drops when the phone changes network. The labs service of relayted runs these checks against a relay you name and returns a JSON report. You call it from a script, a CI job or an agent, and you pay per test from the same prepaid balance as the other relayted services.
There are two ready-made tests and a free selection of single checks:
| Test | What it covers | Price |
|---|---|---|
quick | DNS, TLS, WebSocket upgrade, NIP-11, publish and query, latency, stability | 200 Payloads (0.02 EUR) |
conformance | NIP-01, every filter, event semantics, advertised versus observed limits; the test dataset is included | 800 Payloads (0.08 EUR) |
| single checks | Pick checks by id | 20 Payloads each, never more than the bundle that contains them; a one-time 400 Payloads once per balance if a check needs the known test dataset |
10,000 Payloads are 1 EUR. The current numbers are always at /v1/pricing.
Ask for the price first
A quote is free and the relay is not contacted:
export RELAYTED_KEY="RAPI-XXXX-XXXX-XXXX-XXXX-XXXX"
curl -s https://api.relayted.de/v1/labs/quote \
-H "Authorization: Bearer $RELAYTED_KEY" \
-H "Content-Type: application/json" \
-d '{"relay":"wss://relay.example.com","modules":["quick"]}'
The answer contains cost in Payloads, eur, your balance and sufficient, so a script can stop before it spends anything.
Run the Quick Check
The same body, sent to the jobs endpoint, orders the test:
curl -s "https://api.relayted.de/v1/labs/jobs?wait=25" \
-H "Authorization: Bearer $RELAYTED_KEY" \
-H "Content-Type: application/json" \
-d '{"relay":"wss://relay.example.com","modules":["quick"]}' > job.json
jq '.job | {id, status, cost}' job.json
relay accepts wss://host[:port][/path], ws:// or a bare host, which is treated as wss. A real connection test takes a while, so the job is often still processing after the first call. Poll it with long polling until it is done:
JOB=$(jq -r '.job.id' job.json)
while :; do
STATUS=$(curl -s "https://api.relayted.de/v1/jobs/$JOB?wait=25" \
-H "Authorization: Bearer $RELAYTED_KEY" | jq -r '.job.status')
case "$STATUS" in queued|processing) ;; *) break ;; esac
done
Every delivered result in job.results has a download url, fetched with the same Authorization header. The job also reports cost, refunded and charged.
Single checks and a webhook
If you only care about one thing, GET https://api.relayted.de/v1/services/labs lists the selectable checks without a key. Send their ids in checks instead of modules; the result then has the key custom. If you would rather not poll, add "webhook":"https://example.com/hook" (an https URL) and the finished reports are sent there.
What labs does not do
Requests are limited to public targets. labs publishes test events with throwaway keys and does not run load tests against third-party relays. If the relay is unreachable or answers like something other than a Nostr relay, the amount for that test is refunded.
When to use which test
Use quick after a deployment, after a certificate change or on a schedule, to see within seconds whether the relay is reachable and answers sensibly. Use conformance when you changed relay software, filters or limits, or when clients report odd behaviour such as missing notes. The three guides that follow in this series go through what the checks look at: NIP-11, NIP-01 and NIP-42.
You can try the same tests in the browser at labs.relayted.de. The API documentation for labs is at api.relayted.de/docs/labs.
FAQ
How much does a relay test cost?
The Quick Check costs 200 Payloads (0.02 EUR) and the Conformance test 800 Payloads (0.08 EUR). Single checks cost 20 Payloads each, never more than the bundle that contains them. 10,000 Payloads are 1 EUR.
Can I see the price before I pay?
Yes. POST /v1/labs/quote returns the cost in Payloads and EUR and whether your balance is sufficient. It is free and does not contact the relay.
Do I need a subscription?
No. All relayted services draw from one prepaid balance and every test is priced per use.
How do I get the result without polling?
Add a webhook (an https URL) to the request and the finished reports are sent there.
What if the relay cannot be tested?
If the relay is unreachable or does not answer like a Nostr relay, the amount for that test is refunded. The job reports cost, refunded and charged.
