# How to test a Nostr relay with one API call

URL: https://blog.relayted.de/test-nostr-relay-api-quick-check/
Published: 2026-11-10
Service: relayted labs

## 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](https://api.relayted.de/v1/pricing).

## Ask for the price first

A quote is free and the relay is not contacted:

```bash
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:

```bash
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:

```bash
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-11-relay-information-document-check/), [NIP-01](/nip-01-relay-conformance-check/) and [NIP-42](/nip-42-relay-authentication-check/).

You can try the same tests in the browser at [labs.relayted.de](https://labs.relayted.de/). The API documentation for labs is at [api.relayted.de/docs/labs](https://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.
