Subdomain Eligibility

Eligibility lets parent name owners hand out ENS subnames only to people who meet your rules—instead of letting anyone register freely.

In practice: you paste a link (URL) to a small program you control—usually a simple web endpoint on your server. When someone tries to claim a subname under your parent name, Lime calls that link and passes the visitor’s wallet address to your server, then reads back a clear yes or no: allowed to register, or not. You decide what “yes” means (staking, allowlist, completed task, and so on); Lime only needs that answer to allow or block the claim.

Why use it?

Typical patterns:

Rewards — grant a subname after a user completes an action (e.g. stake tokens, bridge assets to an L2, hold a balance).
Growth / marketing — tie registration to verifiable steps (e.g. follow on X, join a community, complete a quest). Your backend decides what “done” means and returns eligible or not.
Access control — allowlist, tiers, seasonal campaigns, or limits per wallet.

The ENS subname is the on-brand identity layer; your backend is the source of truth for who may register at a given time.

How it fits together

You run (or integrate) a small backend that answers yes or no for a given wallet (see Response format below).
The parent name’s owner configures an eligibility_url in Lime (name Manage settings) pointing to that service. Before saving for real users, you can test the URL from the web UI or via the API.
When a wallet tries to reserve a subdomain under that parent, the Lime backend calls your URL with the wallet address and uses the JSON response to set can_register in GET /api/v1/names/check.
Registration still completes through the usual EIP-712 POST /api/v1/names/reserve flow once the wallet is eligible.

So: your backend encodes the “task” or policy; Lime encodes ENS records and signatures.

For every HTTP method, path, and field on the Lime side, see API Overview. This page explains eligibility in plain terms; the overview has the full endpoint reference.

Response format (your server and Lime)

This has nothing to do with an onchain smart contract. No Solidity, no deployment step for “the eligibility contract.” Your piece is a normal web address that returns JSON—the same way any REST-style service works.

What Lime expects: when eligibility is checked, Lime GETs your URL and adds wallet_address=0x… to the query string. Your server answers with JSON in this shape:


{ "result": true }


{ "result": false }

That is the whole request/response convention between Lime and your server—plain HTTP, not a blockchain contract.

Details, security constraints (SSRF protection, schemes, timeouts), and the verify endpoint below are documented in the API reference.

Testing your eligibility URL

After you enter an eligibility URL (or before you sign to save it), you can run the same check Lime uses in production—so you know the URL is reachable and returns the right JSON.

From the Lime website (owner only)

Open your name’s Manage page (settings where you edit managers and the eligibility URL).
Paste your eligibility URL in the Eligibility URL field.
Click Test next to the field.
In the dialog (Test eligibility API), enter a wallet address to simulate (you can use your connected wallet or any 0x… test address).
Run the test: you’ll see eligible / not eligible, or an error message if the URL failed validation, timed out, or returned invalid data.

The UI calls Lime’s backend, which then calls your URL the same way as during a real registration check.

From the API

Integrators and scripts can call POST /api/v1/eligibility/verify with a JSON body:


{
  "api_url": "https://your-service.example/api/check-eligibility",
  "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
}

The response includes eligible: true | false and echoes the URL and wallet. Use the same base URL as the rest of the Lime ENS API for your network.

POST /api/v1/eligibility/verify — ask Lime’s backend to call your URL with a test wallet (used by the Test button and by scripts).
GET /api/v1/names/records — includes eligibility_url for the name’s node.
POST /api/v1/names/manage — owner-signed update of eligibility_url (and managers).
GET /api/v1/names/check — can_register reflects your eligibility rules when configured.

Example minimal backend

Lime eligibility backend example is a small Go service that exposes GET /api/check-eligibility?wallet_address=0x… and returns {"result": true} for any valid EVM address (and false for invalid input). Use it as a starting point—replace the logic with staking checks, database allowlists, indexer queries, OAuth-linked accounts, or any policy you need.