Profiles

Aggregated profile data for any Ethereum address or ENS name.

Base path: /api/v1/profiles

GET /api/v1/profiles/:addressOrName

Returns a comprehensive profile for the given address or ENS name, including ENS records, owned names with listing status, activity stats, persona classification, and various timestamps.

If the input is an ENS name not found in the database, the API attempts to fetch it from The Graph subgraph. For wrapped ENS names, the API resolves the actual owner through the Name Wrapper contract.

Profile views are tracked asynchronously after the response is sent.

Authentication: Optional (enhances response with user-specific context)

Cache: None

Path Parameters

Parameter	Type	Required	Description
`addressOrName`	string	Yes	Ethereum address (`0x...`) or ENS name (e.g. `vitalik.eth`)

Sample Request


curl https://api.grails.app/api/v1/profiles/vitalik.eth


curl https://api.grails.app/api/v1/profiles/0x1234567890abcdef1234567890abcdef12345678

Response


// 200 OK
{
  "success": true,
  "data": {
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "primaryName": "example.eth",
    "ensRecords": {
      "avatar": "https://...",
      "name": "Example User",
      "description": "ENS enthusiast",
      "email": "user@example.com",
      "url": "https://example.com",
      "location": "Ethereum",
      "twitter": "example",
      "github": "example",
      "header": "https://...",
      "address": "0x1234...",
      "records": { /* full ENS text records */ }
    },
    "persona": {
      "slug": "collector",
      "name": "Collector",
      "icon": "🏆"
    },
    "lastSeenAt": "2026-04-07T10:00:00.000Z",
    "lastSeenOnchain": "2026-04-06T18:30:00.000Z",
    "lastRenewedAt": "2026-03-15T12:00:00.000Z",
    "lastTransferInAt": "2026-02-20T09:00:00.000Z",
    "lastTransferOutAt": null,
    "ownedNames": [
      {
        "id": 1,
        "token_id": "12345678901234567890",
        "name": "example.eth",
        "expiry_date": "2027-01-15T00:00:00.000Z",
        "registration_date": "2023-01-15T00:00:00.000Z",
        "created_at": "2025-06-01T00:00:00.000Z",
        "is_listed": true,
        "active_listing": {
          "id": 42,
          "price_wei": "100000000000000000",
          "currency_address": "0x0000000000000000000000000000000000000000",
          "source": "grails",
          "created_at": "2026-04-01T00:00:00.000Z"
        }
      }
    ],
    "stats": {
      "totalNames": 15,
      "listedNames": 3,
      "totalActivity": 128,
      "viewCount": 42
    }
  },
  "meta": {
    "timestamp": "2026-04-07T12:00:00.000Z",
    "version": "1.0.0"
  }
}

Response Fields

Field	Type	Description
`address`	string	Resolved Ethereum address (lowercase)
`primaryName`	string \| null	Primary ENS name for this address (from EFP API)
`ensRecords`	object \| null	ENS text records (avatar, name, description, socials, etc.)
`persona`	object \| null	User’s persona classification (`slug`, `name`, `icon`)
`lastSeenAt`	string \| null	Last time user was active on the platform
`lastSeenOnchain`	string \| null	Last on-chain transaction (cached, refreshed every 6 hours)
`lastRenewedAt`	string \| null	Last ENS renewal transaction
`lastTransferInAt`	string \| null	Last inbound ENS transfer
`lastTransferOutAt`	string \| null	Last outbound ENS transfer
`ownedNames`	array	ENS names owned, with listing status and active listing details
`stats`	object	Aggregated counts: total names, listed names, activity count, profile views

Error Responses

Status	Code	Description
404	`PROFILE_NOT_FOUND`	No profile found for the given address or ENS name
404	`INVALID_ADDRESS`	ENS name exists but has no valid owner (stuck in Name Wrapper)
500	`INTERNAL_ERROR`	Failed to fetch profile