AI Recommendations

GET /api/v1/ai-recommendations/:name

Returns AI-generated similar name suggestions for an ENS name. Uses OpenAI with the name’s club memberships as context.

Two-tier caching:

Redis (via cacheHandler): 15s
PostgreSQL (ai_recommendations table): 60 days

Cached results are served to all users. Generating new recommendations (cache miss) requires authentication — unauthenticated users receive a 401 on cache miss. Rate limited to 60 requests/minute per IP.

Authentication: Optional (required to generate new recommendations on cache miss)

Cache: 15s (Redis) + 60 days (DB)

Path Parameters

Parameter	Type	Required	Description
`name`	string	Yes	ENS name or label (1–40 chars). `.eth` suffix is stripped automatically.

Sample Request


curl https://api.grails.app/api/v1/ai-recommendations/example.eth

Response


// 200 OK — cache hit
{
  "success": true,
  "data": {
    "suggestions": [
      "similar1.eth",
      "similar2.eth",
      "similar3.eth"
    ]
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z"
  }
}

The X-Cache header indicates HIT (from DB cache) or MISS (freshly generated).

Behavior

Scenario	Result
DB cache hit	Returns cached suggestions (any user)
Cache miss + authenticated	Generates via OpenAI, caches 60 days, returns suggestions
Cache miss + unauthenticated	Returns `401 UNAUTHORIZED`
Name not in database	Returns empty suggestions `[]` (cached briefly for 5 min)
OpenAI failure	Returns empty suggestions `[]` (not cached)

Error Responses

Status	Code	Description
400	`INVALID_NAME`	Invalid ENS name or fewer than 3 characters
401	`UNAUTHORIZED`	Authentication required to generate new recommendations
500	`INTERNAL_ERROR`	Failed to fetch AI recommendations