HTTP API

LNS exposes a JSON API on the HTTP port (default 5553). All responses have Content-Type: application/json.

Endpoints

`GET /resolve`

Resolve a .lthn name to its DNS records.

Parameters:

Parameter	Required	Description
`name`	Yes	The name to resolve (e.g., `charon`, `charon.lthn`, or `charon.lthn.`)
`type`	No	Record type filter: `A` or `TXT`. Omit for all types.

Examples:

# Resolve all record types
curl http://localhost:5553/resolve?name=charon

# Resolve A records only
curl http://localhost:5553/resolve?name=charon&type=A

# Resolve TXT records only
curl http://localhost:5553/resolve?name=charon.lthn&type=TXT

Success response (200):

{
  "name": "charon.lthn",
  "found": true,
  "A": ["10.69.69.165"],
  "TXT": ["v=lthn1;type=gateway;cap=vpn,dns"]
}

Not found response (404):

{
  "name": "unknown.lthn",
  "found": false
}

Missing name parameter:

{
  "error": "?name= required"
}

The name parameter accepts any of these formats -- the .lthn suffix is stripped automatically:

charon
charon.lthn
charon.lthn.

`GET /names`

List all cached names and their records.

Example:

curl http://localhost:5553/names

Response (200):

{
  "mode": "light",
  "count": 14,
  "root": "abc123def456...",
  "names": [
    {
      "name": "charon.lthn",
      "A": ["10.69.69.165"],
      "TXT": ["v=lthn1;type=gateway;cap=vpn,dns"]
    },
    {
      "name": "trade.lthn",
      "A": ["10.69.69.200"],
      "TXT": []
    }
  ]
}

Fields:

mode -- current LNS operating mode
count -- total number of cached names
root -- current HSD tree root hash (changes when sidechain state updates)
names -- array of all cached name records

`GET /health`

Health check endpoint. Returns the current status of the LNS instance.

Example:

curl http://localhost:5553/health

Healthy response (200):

{
  "status": "ok",
  "mode": "light",
  "names": 14,
  "tree_root": "abc123def456..."
}

Degraded response (503):

{
  "status": "degraded",
  "mode": "light",
  "names": 0,
  "tree_root": ""
}

The health endpoint returns "degraded" (HTTP 503) when either:

The tree root has not been fetched (daemon/HSD unreachable)
The cache is empty (no names resolved)

Use this endpoint for Docker health checks or load balancer probes.

`GET /`

Root endpoint. Returns a plain-text usage hint.

curl http://localhost:5553/

Response:

LNS light mode -- /resolve?name=charon&type=A -- /names -- /health