Namerate Public API

The Namerate API lets you get an estimated value (score) of a nickname in $NMRT using the same algorithm as the in‑app rating.

• Base URL (prod): https://namerate.tech
• API version prefix: /api/v1
• Authentication: API key (header or query param)

Quick start

1. Open Namerate mini‑app → B2B section → create your API key.
2. Keep the key safe. It is shown in full only once, when created.
3. Call the endpoint:

curl -X POST \
  -H "X-API-Key: nmrt-***your_key***" \
  -H "Content-Type: application/json" \
  -d '{"name":"testuser"}' \
  https://namerate.tech/api/v1/public/rate

---

Endpoints

Rate a nickname

• POST https://namerate.tech/api/v1/public/rate
• GET https://namerate.tech/api/v1/public/rate?api_key=<key>&name=<nickname>

Authenticate with your API key:

• Preferred: header X-API-Key: <key>
• Alternative: query api_key=<key>

Nickname input rules:

• Length: 5–32 characters
• Allowed characters: A–Z, a–z, 0–9, _ (underscore)
• Invalid input returns 400 Bad Request

Request

=== "POST (recommended)"

curl -X POST \
  -H "X-API-Key: nmrt-******your_key******" \
  -H "Content-Type: application/json" \
  -d '{"name":"testuser"}' \
  https://namerate.tech/api/v1/public/rate

POST /api/v1/public/rate HTTP/1.1
Host: namerate.tech
Content-Type: application/json
X-API-Key: nmrt-******your_key******

{
  "name": "testuser"
}

=== "GET"

curl "https://namerate.tech/api/v1/public/rate?api_key=nmrt-******your_key******&name=testuser"

Response

{
  "name": "testuser",
  "rate": 965
}

Errors

HTTP	Code	When
400	invalid name: 5-32 chars, only A-Z a-z 0-9 _ allowed	Fails validation
400	name is required	Empty/absent name
401	unauthorized	Missing/invalid API key
429	rate limit exceeded	Daily limit reached (if configured)
500	internal	Unexpected server error

---

Authentication

Pass your API key in one of two ways:

• Header (recommended): X-API-Key: nmrt-...
• Query: ?api_key=nmrt-...

Key visibility

Your API key is shown in full only once (at creation/rotation) in the mini‑app B2B section.
Afterwards, it is masked (e.g., nmrt-d44b…e43b). Store it securely when you first see it.

Key format:

• Always starts with nmrt-
• Example full key: nmrt-7c1ba0a8c2… (SHA‑like random)

---

Rate limits & pricing

• Each successful call may deduct $NMRT from your account (your plan defines price per call).
• Rate limits may apply per API key (private usage only, you’ll receive 429 Too Many Requests if exceeded).
• If you need higher limits or custom pricing, contact support.

Current plan & usage

• The API may respond with 429 if daily limit is reached (limit for private usage only).
• You can see total spend inside the B2B section in the Telegram mini‑app (“Spent”).

---

Validation rules

• Trimmed nickname must match: ^[A-Za-z0-9_]{5,32}$
• Examples:
• Valid: test_user_01, Alice_123, abcde
• Invalid: ab (too short), this_name_is_way_too_long_over_32 (too long), abra-cadabra (dash not allowed)

Response on invalid:

{
  "error": "invalid name: 5-32 chars, only A-Z a-z 0-9 _ allowed"
}

---

Examples

cURL

# POST
curl -X POST \
  -H "X-API-Key: nmrt-******your_key******" \
  -H "Content-Type: application/json" \
  -d '{"name":"alice_123"}' \
  https://namerate.tech/api/v1/public/rate

JavaScript (fetch)

const API_URL = 'https://namerate.tech/api/v1/public/rate';
const API_KEY = 'nmrt-******your_key******';

async function rateName(name) {
  const res = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(err.error || `HTTP ${res.status}`);
  }
  return res.json();
}

rateName('alice_123')
  .then(console.log)
  .catch(console.error);

Python (requests)

import requests

API_URL = 'https://namerate.tech/api/v1/public/rate'
API_KEY = 'nmrt-******your_key******'

resp = requests.post(
    API_URL,
    headers={'X-API-Key': API_KEY, 'Content-Type': 'application/json'},
    json={'name': 'alice_123'}
)
if resp.ok:
    print(resp.json())
else:
    print('Error', resp.status_code, resp.json())

---

Response schema

{
  "name": "string", // validated nickname
  "rate": 965       // integer score in $NMRT units
}

Error schema:

{ "error": "string" }

---

Best practices

• Prefer POST with header X-API-Key over query auth.
• Validate nickname client‑side using the same regex to avoid extra roundtrips.
• Handle 429 (retry later or reduce frequency).
• Cache popular results if your use case allows.
• Keep your API key in a secure vault (don’t commit to VCS, don’t embed in public apps).

---

Changelog

• 2025‑10: Public API launched; B2B key management; masking keys; nickname validation.
• Future: Additional endpoints, pagination, and webhooks may be added without breaking changes.

---

Contact & support

• App: Open Namerate → B2B section for key management and usage overview.
• Support: Use the in‑app menu or contact your Namerate admin.