Skip to content
ENSRainbow Docs

Using ENSRainbow

Client SDK

ENSRainbow provides an official TypeScript client SDK to simplify integrations with the API. You can find the SDK package at @ensnode/ensrainbow-sdk.

The SDK provides a simple, type-safe interface for all API endpoints and handles proper formatting of labelhashes and error handling.

Heal Label

Terminal window
curl https://api.ensrainbow.io/v1/heal/0x[labelhash]

The labelhash parameter must be strictly formatted as a “normalized labelhash” according to these requirements:

  • Must start with ‘0x’
  • Must be exactly 66 characters long (including ‘0x’ prefix)
  • Must be lowercase
  • Must be a valid hex string that converts to exactly 32 bytes

For example, this is a valid “normalized labelhash”:

0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc

These would be invalid:

# Too short
0xaf2c
# Not lowercase
0xAF2CAA1C2CA1D027F1AC823B529D0A67CD144264B2789FA2EA4D63A67C7103CC
# Missing 0x prefix
af2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc

Examples:

  1. Successful request:

    Terminal window
    curl https://api.ensrainbow.io/v1/heal/0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc

    Response:

    {
      "status": "success",
      "label": "vitalik"
    }

  2. Invalid labelhash format:

    Terminal window
    curl https://api.ensrainbow.io/v1/heal/0xinvalid

    Response:

    {
      "status": "error",
      "error": "Invalid labelhash - must be a valid hex string",
      "errorCode": 400
    }

  3. Label not found:

    Terminal window
    curl https://api.ensrainbow.io/v1/heal/0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff

    Response:

    {
      "status": "error",
      "error": "Label not found",
      "errorCode": 404
    }

Note on returned labels: The service returns labels exactly as they appear in the source data. This means:

  • Labels may or may not be ENS-normalized
  • Labels can contain any valid string, including dots, null bytes, or be empty
  • Clients should handle all possible string values appropriately

Error Responses:

  • 400 Bad Request: When the labelhash parameter is missing or invalid

    {
      "status": "error",
      "error": "Invalid labelhash - must be a valid hex string",
      "errorCode": 400
    }

  • 404 Not Found: When no label is found for the given labelhash

    {
      "status": "error",
      "error": "Label not found",
      "errorCode": 404
    }

Get Count of Healable Labels

Terminal window
curl https://api.ensrainbow.io/v1/labels/count

Success Response:

{
  "status": "success",
  "count": 133856894,
  "timestamp": "2024-01-30T11:18:56Z"
}

Health Check

Terminal window
curl https://api.ensrainbow.io/health

Response: {"status":"ok"}

NameHash Labs Hosted Instance

Important: While we provide a freely available hosted instance for the ENS community, we strongly recommend running your own ENSRainbow instance alongside ENSNode in your infrastructure. Co-locating these services on the same local network significantly improves indexing performance.