lthn.io/app/Website/Docs/Content/api/overview.md

API Overview

The Lethean REST API provides programmatic access to name registration, DNS management, blockchain data, and proxy services. All endpoints return JSON.

Base URL

https://api.lthn.io/v1

Authentication

Read endpoints (GET) are public. Write endpoints (POST) require a Bearer token:

curl -H 'Authorization: Bearer YOUR_TOKEN' \
     -H 'Accept: application/json' \
     https://api.lthn.io/v1/names/register

Get your API token by purchasing a service at order.lthn.ai.

Request Headers

Header	Required	Description
Accept	Yes	Must be application/json
Content-Type	For POST	Must be application/json
Authorization	For POST	Bearer {token}

Endpoint Groups

Names (13 endpoints)

Method	Endpoint	Description
GET	/v1/names/available/{name}	Check if a name is available
GET	/v1/names/lookup/{name}	Look up a registered name
GET	/v1/names/directory	All names grouped by type
GET	/v1/names/search?q={query}	Search names
POST	/v1/names/register	Register a new name
POST	/v1/names/claim	Pre-register a name claim
GET	/v1/names/claims	List all claims (admin)
GET	/v1/names/records/{name}	DNS records from sidechain
POST	/v1/names/records/{name}	Update DNS records
GET	/v1/names/ticket/{id}	Check DNS change ticket
GET	/v1/names/health	Registrar health + wallet balance
GET	/v1/names/sunrise/verify/{name}	Get verification token
GET	/v1/names/sunrise/check/{name}	Check DNS TXT verification

Explorer (7 endpoints)

Method	Endpoint	Description
GET	/v1/explorer/info	Chain info
GET	/v1/explorer/stats	Chain statistics
GET	/v1/explorer/block/{id}	Block by height or hash
GET	/v1/explorer/tx/{hash}	Transaction details
GET	/v1/explorer/aliases	All chain aliases
GET	/v1/explorer/alias/{name}	Single alias details
GET	/v1/explorer/search/{query}	Search blocks, txs, aliases

Proxy (5 endpoints)

Method	Endpoint	Description
GET	/v1/proxy/status	Network availability + pricing
GET	/v1/proxy/nodes	List nodes by capability
POST	/v1/proxy/connect	Get a gateway connection
GET	/v1/proxy/usage	Your usage (bytes, requests)
GET	/v1/proxy/billing/{key}	Billing data per API key

Gateway (4 endpoints)

Method	Endpoint	Description
POST	/v1/gateway/pair	Pair a gateway node
POST	/v1/gateway/heartbeat	Report alive + stats
GET	/v1/gateway/live	List live paired gateways
POST	/v1/gateway/dispatch	Select best gateway

Error Responses

All errors return JSON with an error field:

{
    "error": "Name already registered.",
    "name": "example"
}

Status	Meaning
200	Success
201	Created (new resource)
401	Unauthorised (missing/invalid token)
404	Not found
409	Conflict (already exists, locked)
422	Validation error
429	Rate limited

Rate Limiting

Write endpoints are rate-limited:

Endpoint	Limit
POST /v1/names/register	10/minute
POST /v1/names/records/{name}	20/minute
POST /v1/proxy/connect	60/minute
POST /v1/names/claim	10/minute

Examples

Check Name Availability

curl -s -H 'Accept: application/json' \
  'https://api.lthn.io/v1/names/available/mybrand'

{
    "name": "mybrand",
    "available": true,
    "reserved": false,
    "fqdn": "mybrand.lthn"
}

Look Up a Name

curl -s -H 'Accept: application/json' \
  'https://api.lthn.io/v1/names/lookup/charon'

Check System Health

curl -s -H 'Accept: application/json' \
  'https://api.lthn.io/v1/names/health'

{
    "status": "healthy",
    "registrar": {
        "balance": 137.66,
        "registrations_remaining": 13765,
        "low_funds": false,
        "wallet_online": true
    },
    "chain": {
        "height": 13300,
        "aliases": 140,
        "synced": true,
        "daemon_online": true
    }
}

Embeddable Widget

Add a .lthn name search to any website:

<div id="lthn-search"></div>
<script src="https://lthn.io/widget.js"></script>

The widget supports dark/light themes and custom API URLs via data attributes.