Grails API Documentation

GET /api/v1/watchlist

Get watchlist items with ENS name details and listing status. Defaults to the user’s default list if no listId is specified.

Authentication: Required

Cache: None

Query Parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number (min 1)
`limit`	number	`20`	Results per page (1–100)
`listId`	number	—	Filter by list ID (defaults to user’s default list)

Sample Request


curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.grails.app/api/v1/watchlist?page=1&limit=20"

Response


// 200 OK
{
  "success": true,
  "data": {
    "watchlist": [
      {
        "id": 1,
        "userId": 42,
        "ensNameId": 100,
        "ensName": "example.eth",
        "listId": 1,
        "listName": "Watchlist",
        "notifyOnSale": true,
        "notifyOnOffer": true,
        "notifyOnListing": true,
        "notifyOnPriceChange": false,
        "minOfferThreshold": null,
        "addedAt": "2026-04-01T00:00:00.000Z",
        "nameData": {
          "name": "example.eth",
          "tokenId": "12345...",
          "ownerAddress": "0xabcd...",
          "expiryDate": "2027-01-15T00:00:00.000Z",
          "hasActiveListing": true,
          "activeListing": {
            "id": 42,
            "price_wei": "100000000000000000",
            "currency_address": "0x0000...0000",
            "source": "grails",
            "created_at": "2026-04-01T00:00:00.000Z"
          }
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 15,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}