Block: ---₿ ---
Read ratings and reviews with the Public API, or collect and manage reviews with the Business API. Built for integrators, wallets, and service owners.
Every review on Nod City is a signed Nostr event (kind 31986) published to open relays. The data is decentralized, censorship-resistant, and cryptographically verifiable. Anyone can read it directly from relays using the Nostr protocol.
So why use this API?
Think of this API as a convenience layer on top of Nostr, not a replacement. Every event_id in our responses is a real Nostr event you can verify on any relay.
https://nod.city/api/v1Authorization: Bearer <api-key>. Create invitation links, reply to reviews, and embed widgets.60 requests per minute per IP (public) or per API key (business). When exceeded, the API returns 429 with a Retry-After header.
// All errors return JSON with an "error" field:
{
"error": "Rate limit exceeded. Try again in 60 seconds."
}
// Common status codes:
// 400 Bad Request — invalid parameters or malformed body
// 401 Unauthorized — missing or invalid API key / session
// 403 Forbidden — you don't own this resource
// 404 Not Found — service, review, or invitation not found
// 409 Conflict — invitation already used
// 429 Too Many Requests — rate limit exceededBuilding something that needs higher limits? Let us know. We're happy to help.
No authentication required. Read-only access to services and reviews.
/api/v1/servicesList all services with ratings. Supports search and category filtering. Ordered by review count.
qstringSearch by name, slug, or descriptioncategorystringFilter by category slug (e.g. "wallets", "exchanges")limitintegerResults per page (default 30, max 100)offsetintegerPagination offset (default 0)curl https://nod.city/api/v1/services?category=wallets&limit=3
{
"services": [
{
"slug": "phoenix",
"name": "Phoenix",
"description": "...",
"website": "https://phoenix.acinq.co",
"category": "wallets",
"tags": ["Lightning", "Non-custodial"],
"logo_url": "https://nod.city/logos/phoenix.png",
"x_handle": "PhoenixWallet",
"average_rating": 4.2,
"review_count": 15,
"url": "https://nod.city/service/phoenix"
}
],
"total": 45,
"limit": 3,
"offset": 0
}/api/v1/services/:slugGet full details for a single service, including founders and the 5 most recent reviews. A single call gives integrators everything they need.
curl https://nod.city/api/v1/services/phoenix
{
"slug": "phoenix",
"name": "Phoenix",
"description": "...",
"website": "https://phoenix.acinq.co",
"category": "wallets",
"tags": ["Lightning", "Non-custodial"],
"logo_url": "https://nod.city/logos/phoenix.png",
"x_handle": "PhoenixWallet",
"nostr_pubkey": "abc123...",
"average_rating": 4.2,
"review_count": 15,
"url": "https://nod.city/service/phoenix",
"founders": [
{ "x_handle": "aaborrell", "nostr_pubkey": "def456..." }
],
"recent_reviews": [
{
"event_id": "...",
"content": "Great wallet for Lightning payments.",
"rating": 5,
"author": {
"pubkey": "...",
"display_name": "Alice",
"picture": "https://..."
},
"created_at": "2026-04-01T12:00:00Z"
}
]
}/api/v1/services/:slug/reviewsPaginated reviews for a specific service with full author profiles including NIP-05 verification.
limitintegerResults per page (default 30, max 100)offsetintegerPagination offset (default 0)curl https://nod.city/api/v1/services/phoenix/reviews?limit=5
{
"reviews": [
{
"event_id": "...",
"content": "...",
"rating": 4,
"author": {
"pubkey": "...",
"display_name": "Alice",
"picture": "https://...",
"nip05": "alice@example.com"
},
"created_at": "2026-04-01T12:00:00Z",
"url": "https://nod.city/review/..."
}
],
"total": 15,
"limit": 5,
"offset": 0,
"service": {
"slug": "phoenix",
"name": "Phoenix",
"average_rating": 4.2
}
}/api/v1/reviewsRecent reviews across all services. The since parameter is useful for incremental sync. Poll periodically and only fetch new reviews.
categorystringFilter by service categorysincestringISO 8601 datetime. Only returns reviews after this time.limitintegerResults per page (default 30, max 100)offsetintegerPagination offset (default 0)curl https://nod.city/api/v1/reviews?category=wallets&limit=5
{
"reviews": [
{
"event_id": "...",
"content": "...",
"rating": 4,
"author": {
"pubkey": "...",
"display_name": "Alice",
"picture": "https://...",
"nip05": "alice@example.com"
},
"created_at": "2026-04-01T12:00:00Z",
"url": "https://nod.city/review/...",
"service": {
"slug": "phoenix",
"name": "Phoenix",
"category": "wallets"
}
}
],
"total": 312,
"limit": 5,
"offset": 0
}Tools for service owners to collect reviews, reply to feedback, and embed ratings. All endpoints require an API key.
POST /api/v1/business/api-keys with your session cookie. Save the key — it's shown only once.Authorization: Bearer YOUR_KEY on every business endpoint./api/v1/business/api-keysCreate a new API key for a service you own. Requires an active X session cookie. The full key is returned only once — store it securely.
service_slugstringrequiredThe slug of the service you ownnamestringA label for this key (e.g. "Production")curl -X POST https://nod.city/api/v1/business/api-keys \
-H "Cookie: x_session=YOUR_SESSION" \
-H "Content-Type: application/json" \
-d '{"service_slug": "phoenix", "name": "Production"}'{
"id": 1,
"key": "a1b2c3d4e5f6...full-64-char-hex-key...",
"key_prefix": "a1b2c3d4",
"service_slug": "phoenix",
"name": "Production",
"created_at": "2026-04-06T12:00:00.000Z"
}/api/v1/business/api-keysList all API keys you've created. Returns masked keys (prefix only, never the full key). Requires X session cookie.
curl https://nod.city/api/v1/business/api-keys \ -H "Cookie: x_session=YOUR_SESSION"
{
"api_keys": [
{
"id": 1,
"key_prefix": "a1b2c3d4",
"service_slug": "phoenix",
"name": "Production",
"created_at": "2026-04-06T12:00:00.000Z",
"last_used_at": "2026-04-06T14:30:00.000Z",
"revoked_at": null
}
]
}/api/v1/business/api-keys/:idRevoke an API key. The key immediately stops working. This cannot be undone. Requires X session cookie.
curl -X DELETE https://nod.city/api/v1/business/api-keys/1 \ -H "Cookie: x_session=YOUR_SESSION"
{ "ok": true }/api/v1/business/invitationsGenerate a unique review invitation link. Embed this URL in your own emails or order confirmations. Customers still must log in (X or Nostr) to submit a review — no customer PII is shared with Nod City.
reference_idstringYour internal reference (e.g. order ID). Optional, for your tracking.redirect_uristringURL to show a "Return to business" link after review. Optional.curl -X POST https://nod.city/api/v1/business/invitations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reference_id": "order-123", "redirect_uri": "https://example.com/thanks"}'{
"id": 42,
"url": "https://nod.city/service/phoenix/review?invite=abc123...",
"token": "abc123def456789012345678abcdef00",
"service_slug": "phoenix",
"reference_id": "order-123",
"redirect_uri": "https://example.com/thanks",
"created_at": "2026-04-06T12:00:00.000Z"
}/api/v1/business/invitationsList invitation links for your service with their status. Use this to track which invitations have been used.
limitintegerResults per page (default 30, max 100)offsetintegerPagination offset (default 0)curl https://nod.city/api/v1/business/invitations?limit=10 \ -H "Authorization: Bearer YOUR_API_KEY"
{
"invitations": [
{
"id": 42,
"token": "abc123...",
"reference_id": "order-123",
"redirect_uri": "https://example.com/thanks",
"status": "used",
"created_at": "2026-04-06T12:00:00.000Z",
"reviewed_at": "2026-04-06T15:30:00.000Z"
},
{
"id": 43,
"token": "def456...",
"reference_id": "order-124",
"redirect_uri": null,
"status": "pending",
"created_at": "2026-04-06T13:00:00.000Z",
"reviewed_at": null
}
],
"limit": 10,
"offset": 0
}Add a rating badge to any website with two lines of HTML. No API key required — the widget uses the public API.
<div data-nod-slug="phoenix"></div> <script src="https://nod.city/widget.js" async defer></script>
For dark backgrounds, add data-nod-theme="dark" to the div.
Preview
/api/v1/business/reviews/:eventId/replyReply to a review as the business owner. You sign the Nostr event (kind 1111) yourself and send it to us. We verify the signature, publish to relays, and cache the reply. The review must belong to your service.
signed_eventobjectrequiredA fully signed Nostr kind 1111 event. Must include an E tag referencing the review's event ID.curl -X POST https://nod.city/api/v1/business/reviews/REVIEW_EVENT_ID/reply \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"signed_event": {
"id": "...",
"pubkey": "your-nostr-pubkey",
"kind": 1111,
"created_at": 1712400000,
"content": "Thank you for the review!",
"tags": [["K", "31986"], ["E", "REVIEW_EVENT_ID", "", ""]],
"sig": "..."
}
}'{
"event_id": "...",
"created_at": "2026-04-06T12:00:00.000Z"
}If you display Nod City ratings in your app or website, please include a visible attribution: "Powered by Nod City" with a link back to the service page.
Questions about the API or want to discuss an integration? Reach out on X @nodcity or via Nostr.