API Documentation

Integrate NameSniper into your apps, agents, and workflows

Authentication

Two authentication methods are supported. Every request must include one of them.

API Key

Pass your key in the Authorization header. API access requires a Pro ($7/mo) or Business ($24/mo) plan.

Header

Authorization: Bearer ns_sk_...

Generate and manage keys in your Dashboard → API Keys.

x402 Pay-Per-Call

Coming Soon

Pay per request with USDC micropayments. No account or API key needed — ideal for agents and one-off integrations.

See the x402 pricing table below for per-endpoint costs.

Base URL

https://namesniper.pro/api/v1

All endpoint paths below are relative to this base URL.

Endpoints

POST/api/v1/check

Full Check (Flagship)

The all-in-one endpoint. Checks domains, social media, brand score, and trademark in a single call.

Request body

{
  "name": "coolbrand",
  "platforms": ["github", "twitter", "youtube"],   // optional
  "domains": ["com", "io", "dev"],                 // optional
  "brandScore": true,                              // optional
  "trademark": true                                // optional
}

Response

{
  "success": true,
  "data": {
    "name": "coolbrand",
    "domains": {
      "results": [ ... ],
      "summary": { "available": 15, "taken": 4 }
    },
    "social": {
      "results": [ ... ],
      "summary": { "available": 10, "taken": 4 }
    },
    "brandScore": { "overall": 82, ... },
    "trademark": { "riskLevel": "low", ... }
  },
  "meta": {
    "plan": "pro",
    "duration": 3200,
    "timestamp": "2026-02-11T12:00:00Z"
  }
}

POST/api/v1/check/domains

Domain Check

Check domain availability across specific TLDs using the 3-tier verification system.

Request body

{
  "name": "coolbrand",
  "tlds": ["com", "io", "dev"]
}

POST/api/v1/check/social

Social Media Check

Check username availability across specific social platforms with parallel processing.

Request body

{
  "name": "coolbrand",
  "platforms": ["github", "twitter", "youtube"]
}

POST/api/v1/brand-score

Brand Score

Get a comprehensive brand analysis covering memorability, SEO potential, and professional appeal.

Request body

{
  "name": "coolbrand"
}

POST/api/v1/trademark

Trademark Check

Screen for USPTO trademark conflicts with risk assessment and legal guidance.

Request body

{
  "name": "coolbrand",
  "includeVariations": true
}

POST/api/v1/alternatives

Smart Alternatives

Generate professional brand name variations using prefixes, suffixes, and creative patterns.

Request body

{
  "name": "coolbrand",
  "count": 8
}

POST/api/v1/generate

AI Name Generation

Generate creative brand names from a business description using AI.

Request body

{
  "description": "productivity tool for remote teams",
  "count": 10,
  "style": "modern"
}

GET/api/v1/usage

Usage Stats

Returns your current plan, rate limits, and API usage statistics. No request body required.

Monitoring API

Watch taken usernames and get notified when they become available. Monitoring requires a Free plan or above.

POST/api/v1/watch

Create Watch

Start monitoring a username across one or more platforms. Get notified when it becomes available.

Request body

{
  "username": "coolbrand",
  "platforms": ["github", "twitter", "instagram"]
}

Response

{
  "success": true,
  "data": {
    "created": 3,
    "watches": [
      { "id": "clx...", "username": "coolbrand", "platform": "github", "status": "watching", "createdAt": "..." }
    ]
  }
}

GET/api/v1/watch

List Watches

List all monitored handles with status, last check time, and slot usage.

PATCH/api/v1/watch/:id

Pause / Resume Watch

Pause or resume monitoring for a specific watch.

Request body

{
  "status": "paused"   // or "watching"
}

DELETE/api/v1/watch/:id

Remove Watch

Stop monitoring and delete a watch. Frees up a slot.

GET/api/v1/notifications

List Notifications

Retrieve in-app notifications with pagination. Use ?unread=true to filter.

Query params: unread (bool), limit (max 100), offset

PATCH/api/v1/notifications/:id

Mark Notification Read

Mark a single notification as read.

POST/api/v1/notifications/read-all

Mark All Read

Mark all unread in-app notifications as read.

POST/api/v1/webhooks

Register Webhook

Create a webhook endpoint for real-time notifications. The signing secret is returned only on creation.

Request body

{
  "url": "https://example.com/hook",
  "events": ["handle_available", "handle_change"]
}

Response

{
  "success": true,
  "data": {
    "id": "clx...",
    "url": "https://example.com/hook",
    "secret": "abc123...",
    "events": ["handle_available", "handle_change"],
    "active": true
  }
}

GET/api/v1/webhooks

List Webhooks

List all registered webhook endpoints with status and failure info.

DELETE/api/v1/webhooks/:id

Remove Webhook

Delete a webhook endpoint.

Monitoring Limits

Plan	Watch Slots	Check Frequency	Notifications	Webhooks	History
Free	2	12h	In-app	0	7 days
Day Pass	5	6h	In-app, Email	0	7 days
Pro	15	1h	All	2	30 days
Business	50	15min	All	10	90 days

15 platforms are monitorable (all except LinkedIn). Tier C platforms (Instagram, TikTok, Twitter/X, Threads, Snapchat) are checked via proxy for reliability.

Webhook Payload

When a monitored handle changes status, webhooks receive a signed POST request.

Payload

{
  "event": "handle_available",
  "timestamp": "2026-02-12T10:30:00Z",
  "data": {
    "username": "coolbrand",
    "platform": "instagram",
    "previousStatus": "taken",
    "profileUrl": "https://instagram.com/coolbrand",
    "watchId": "clx..."
  }
}

The request includes an X-NameSniper-Signature header with an HMAC-SHA256 signature of the body using your webhook secret. Verify this to ensure authenticity.

Verification (Node.js)

const crypto = require('crypto');

function verifySignature(body, secret, signature) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(body).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature)
  );
}

Webhooks are auto-disabled after 10 consecutive delivery failures. Re-enable from the dashboard or via PATCH /api/v1/webhooks/:id with {"active": true}.

Rate Limits

Plan	Requests / min	Requests / hr	Daily limit
Pro	20	300	1,000
Business	40	800	3,000

When a limit is exceeded the API returns 429 with a Retry-After header indicating how many seconds to wait.

MCP Server

Connect NameSniper to any MCP-compatible AI agent or IDE with a single config block.

Remote MCP (recommended)

mcp.json

{
  "namesniper": {
    "type": "url",
    "url": "https://namesniper.pro/mcp",
    "headers": {
      "Authorization": "Bearer ns_sk_..."
    }
  }
}

Via npm

Terminal

npx @namesniper/mcp

The npm package reads your API key from the NAMESNIPER_API_KEY environment variable.

Available MCP Tools

Tool	Description
namesniper_check	All-in-one: domains + social + brand score + trademark
namesniper_check_domains	Domain availability across TLDs
namesniper_check_social	Username availability across platforms
namesniper_generate	AI brand name generation
namesniper_trademark	USPTO trademark screening
namesniper_alternatives	Smart name variations
namesniper_watch	Start monitoring a handle
namesniper_watches	List monitored handles and status

x402 Pay-Per-Call Pricing

With x402 you pay per request in USDC. No account, no API key, no monthly commitment.

Endpoint	Price (USDC)
/check (full)	$0.08
/check/domains	$0.03
/check/social	$0.05
/generate	$0.04
/brand-score	$0.02
/trademark	$0.03
/alternatives	$0.03

x402 support is coming soon. Prices are subject to change before launch.

Code Examples

curl

curl -X POST https://namesniper.pro/api/v1/check \
  -H "Authorization: Bearer ns_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"coolbrand"}'

JavaScript (fetch)

const res = await fetch('https://namesniper.pro/api/v1/check', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ns_sk_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'coolbrand' }),
});
const data = await res.json();

Python (requests)

import requests

r = requests.post(
    'https://namesniper.pro/api/v1/check',
    headers={'Authorization': 'Bearer ns_sk_...'},
    json={'name': 'coolbrand'},
)
data = r.json()

Error Handling

All errors follow a consistent JSON shape:

{
  "success": false,
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Try again in 12 seconds."
  }
}

Status	Meaning	What to do
400 Bad Request	Invalid request body — missing name, bad format, or invalid parameters.
401 Unauthorized	Missing or malformed Authorization header.
402 Payment Required	x402 payment required. Include USDC micropayment to proceed.
403 Forbidden	Invalid or revoked API key, or your plan does not include API access.
429 Too Many Requests	Rate limit or daily limit exceeded. Check the Retry-After header for when to retry.
500 Server Error	Something went wrong on our end. Retry after a short delay or contact support.

Ready to integrate?

Grab your API key and start checking brand names programmatically in minutes.

Get Your API Key View Plans