Grails

https://grails.app
Admin
Grails is an ENS name manager and marketplace providing a RESTful API for programmatic access to ENS...
Tokens:167,276
Snippets:813
Trust Score:7.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Response Example

Source: https://docs.grails.app/docs/api/watchlist/get-lists

This is an example of a successful response (200 OK) when retrieving watchlists. It includes a list of watchlists, each with its ID, name, default status, item count, and creation/update timestamps.

```json
// 200 OK
{
  "success": true,
  "data": {
    "lists": [
      {
        "id": 1,
        "name": "Watchlist",
        "isDefault": true,
        "itemCount": 15,
        "createdAt": "2026-01-15T00:00:00.000Z",
        "updatedAt": "2026-04-07T12:00:00.000Z"
      },
      {
        "id": 2,
        "name": "Favorites",
        "isDefault": false,
        "itemCount": 5,
        "createdAt": "2026-03-01T00:00:00.000Z",
        "updatedAt": "2026-04-05T00:00:00.000Z"
      }
    ]
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Successful Response Example

Source: https://docs.grails.app/docs/api/auth/me

This is an example of a successful 200 OK response, detailing the structure of the user profile data returned by the API.

```json
{
  "success": true,
  "data": {
    "id": 1,
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "email": "user@example.com",
    "emailVerified": true,
    "telegram": "@username",
    "discord": "user#1234",
    "notifyOnOfferReceived": true,
    "notifyOnListingSold": true,
    "minOfferThreshold": 0.1,
    "createdAt": "2026-01-15T00:00:00.000Z",
    "updatedAt": "2026-04-01T00:00:00.000Z",
    "lastSignIn": "2026-04-07T12:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-04-07T12:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Successful Response Example

Source: https://docs.grails.app/docs/api/listings/get-by-name

This is an example of a successful response (200 OK) when retrieving listings by ENS name. It includes listing details and associated ENS name information.

```json
// 200 OK
{
  "success": true,
  "data": [
    {
      "id": 42,
      "ens_name_id": 1,
      "seller_address": "0xabcd...",
      "price_wei": "100000000000000000",
      "currency_address": "0x0000000000000000000000000000000000000000",
      "order_hash": "0x1234...",
      "order_data": { ... },
      "status": "active",
      "source": "grails",
      "created_at": "2026-04-01T00:00:00.000Z",
      "updated_at": "2026-04-01T00:00:00.000Z",
      "expires_at": null,
      "last_validated_at": null,
      "unfunded_at": null,
      "unfunded_reason": null,
      "broker_address": null,
      "broker_fee_bps": null,
      // Joined from ens_names
      "ens_name": "example.eth",
      "token_id": "12345...",
      "current_owner": "0xabcd...",
      "name_expiry_date": "2027-01-15T00:00:00.000Z",
      "registration_date": "2023-01-15T00:00:00.000Z",
      "last_sale_date": null
    }
  ],
  "meta": {
    "timestamp": "2026-04-07T12:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Successful Response Example

Source: https://docs.grails.app/docs/api/watchlist/remove-item

This is an example of a successful response (200 OK) when an item is removed from the watchlist.

```json
// 200 OK
{
  "success": true,
  "data": {
    "message": "Removed from watchlist"
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Get User Balances (cURL)

Source: https://docs.grails.app/docs/api/users/balances

Example of how to request token balances for a user's address using cURL. Replace '0x1234.../balances' with the actual address.

```bash
curl https://api.grails.app/api/v1/users/0x1234.../balances
```

--------------------------------

### Successful Response Example

Source: https://docs.grails.app/docs/api/votes/get-votes

This is an example of a successful 200 OK response, showing vote counts and the current user's vote if authenticated.

```json
{
  "success": true,
  "data": {
    "ensName": "example.eth",
    "upvotes": 15,
    "downvotes": 3,
    "netScore": 12,
    "userVote": 1
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Volume Distribution Response Example

Source: https://docs.grails.app/docs/api/analytics/volume

This is an example of a successful response (200 OK) from the volume distribution API. It includes the sales volume distribution broken down by price range, along with metadata.

```json
// 200 OK
{
  "success": true,
  "data": {
    "period": "7d",
    "distribution": [
      { "price_range": "< 0.01 ETH", "sales_count": 50, "total_volume_wei": "250000000000000000" },
      { "price_range": "0.01-0.1 ETH", "sales_count": 80, "total_volume_wei": "4000000000000000000" },
      { "price_range": "0.1-0.5 ETH", "sales_count": 30, "total_volume_wei": "7500000000000000000" },
      { "price_range": "0.5-1 ETH", "sales_count": 15, "total_volume_wei": "10000000000000000000" },
      { "price_range": "1-5 ETH", "sales_count": 10, "total_volume_wei": "25000000000000000000" },
      { "price_range": "5-10 ETH", "sales_count": 3, "total_volume_wei": "20000000000000000000" },
      { "price_range": "10-50 ETH", "sales_count": 2, "total_volume_wei": "50000000000000000000" },
      { "price_range": "50+ ETH", "sales_count": 1, "total_volume_wei": "75000000000000000000" }
    ]
  },
  "meta": {
    "timestamp": "2026-04-09T00:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Service Readiness Response (All Services Reachable)

Source: https://docs.grails.app/docs/api/health

Example response when all dependent services (PostgreSQL, Elasticsearch) are reachable.

```json
{
  "status": "ready",
  "checks": {
    "postgres": true,
    "elasticsearch": true
  },
  "timestamp": "2026-04-07T12:00:00.000Z"
}
```

--------------------------------

### Sample Response for Get Listing by ID

Source: https://docs.grails.app/docs/api/listings/get-by-id

This is a successful response (200 OK) for a GET request to retrieve a listing. It includes detailed information about the listing and associated ENS name data.

```json
// 200 OK
{
  "success": true,
  "data": {
    "id": 42,
    "ens_name_id": 1,
    "seller_address": "0xabcd...",
    "price_wei": "100000000000000000",
    "currency_address": "0x0000000000000000000000000000000000000000",
    "order_hash": "0x1234...",
    "order_data": { ... },
    "status": "active",
    "source": "grails",
    "created_at": "2026-04-01T00:00:00.000Z",
    "updated_at": "2026-04-01T00:00:00.000Z",
    "expires_at": null,
    "last_validated_at": null,
    "unfunded_at": null,
    "unfunded_reason": null,
    "broker_address": null,
    "broker_fee_bps": null,
    // Joined from ens_names
    "ens_name": "example.eth",
    "token_id": "12345...",
    "current_owner": "0xabcd...",
    "name_expiry_date": "2027-01-15T00:00:00.000Z",
    "registration_date": "2023-01-15T00:00:00.000Z",
    "last_sale_date": null
  },
  "meta": {
    "timestamp": "2026-04-07T12:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Successful Response Example

Source: https://docs.grails.app/docs/api/ens-roles/can-manage

This is an example of a successful response (200 OK) from the API, indicating that the address can manage the ENS name.

```json
// 200 OK
{
  "success": true,
  "data": {
    "canManage": true,
    "role": "both",
    "isWrapped": true,
    "fuses": {
      "canUnwrap": false,
      "canBurnFuses": true,
      "canTransfer": true,
      "canSetResolver": true,
      "canSetTTL": true,
      "canCreateSubdomain": true,
      "parentCanControl": false,
      "canExtendExpiry": true,
      "raw": 65537
    }
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Successful Leaderboard Response Example

Source: https://docs.grails.app/docs/api/leaderboard

This is an example of a successful 200 OK response from the leaderboard API, showing user data, pagination, and metadata.

```json
// 200 OK
{
  "success": true,
  "data": {
    "users": [
      {
        "address": "0x1234...",
        "names_owned": 150,
        "names_in_clubs": 42,
        "expired_names": 5,
        "names_listed": 12,
        "names_sold": 25,
        "sales_volume": "15000000000000000000",
        "clubs": ["999", "10k", "100k"]
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5000,
    "pages": 500
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0",
    "sort": { "by": "names_owned", "order": "desc" }
  }
}
```

--------------------------------

### GET /health/ready

Source: https://docs.grails.app/docs/api/health

Checks the readiness of the service by verifying connectivity to its dependencies.

```APIDOC
## GET /health/ready

### Description
Checks connectivity to PostgreSQL and Elasticsearch. Returns `200` if all dependencies are reachable, `503` if any check fails.

### Method
GET

### Endpoint
/health/ready

### Response
#### Success Response (200)
- **status** (string) - The readiness status of the service (e.g., "ready").
- **checks** (object) - An object detailing the status of individual dependency checks.
  - **postgres** (boolean) - Indicates if PostgreSQL is reachable.
  - **elasticsearch** (boolean) - Indicates if Elasticsearch is reachable.
- **timestamp** (string) - The timestamp when the readiness check was performed.

#### Response Example (All Services Reachable)
```json
{
  "status": "ready",
  "checks": {
    "postgres": true,
    "elasticsearch": true
  },
  "timestamp": "2026-04-07T12:00:00.000Z"
}
```

#### Error Response (503 Service Unavailable)
- **status** (string) - The readiness status of the service (e.g., "not ready").
- **checks** (object) - An object detailing the status of individual dependency checks.
  - **postgres** (boolean) - Indicates if PostgreSQL is reachable.
  - **elasticsearch** (boolean) - Indicates if Elasticsearch is reachable.
- **timestamp** (string) - The timestamp when the readiness check was performed.

#### Response Example (One or More Services Down)
```json
{
  "status": "not ready",
  "checks": {
    "postgres": true,
    "elasticsearch": false
  },
  "timestamp": "2026-04-07T12:00:00.000Z"
}
```
```

--------------------------------

### Service Readiness Response (One or More Services Down)

Source: https://docs.grails.app/docs/api/health

Example response when one or more dependent services are not reachable.

```json
{
  "status": "not ready",
  "checks": {
    "postgres": true,
    "elasticsearch": false
  },
  "timestamp": "2026-04-07T12:00:00.000Z"
}
```

--------------------------------

### Successful Response for Get Badges

Source: https://docs.grails.app/docs/api/users/badges

This is an example of a successful response (200 OK) when retrieving POAP badges. It includes the address, a list of badges with event details, and metadata.

```json
// 200 OK
{
  "success": true,
  "data": {
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "badges": [
      {
        "event": { "id": 12345, "name": "Grails Early Adopter", ... },
        "tokenId": "6789",
        "owner": "0x1234...",
        "created": "2025-06-15T00:00:00.000Z"
      }
    ]
  },
  "meta": {
    "timestamp": "2026-04-07T12:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Sample Response for Recommendations

Source: https://docs.grails.app/docs/api/recommendations/based-on-votes

This is an example of a successful response (200 OK) containing recommended names and associated metrics. The data includes a list of names, each with recommendation scores and similar voter counts.

```json
// 200 OK
{
  "success": true,
  "data": {
    "names": [
      {
        "name": "recommended.eth",
        // ... standard search result fields
        "recommendation_metrics": {
          "type": "based-on-votes",
          "recommendation_score": 12,
          "similar_voters": 6
        }
      }
    ],
    "meta": {
      "type": "based-on-votes",
      "limit": 10
    }
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Sample Response for Recommendations

Source: https://docs.grails.app/docs/api/recommendations/for-you

This is an example of a successful response (200 OK) from the recommendations endpoint. It includes a list of recommended names with their associated personalized scores and metadata about the request.

```json
// 200 OK
{
  "success": true,
  "data": {
    "names": [
      {
        "name": "recommended.eth",
        // ... standard search result fields
        "recommendation_metrics": {
          "type": "for-you",
          "personalized_score": 45
        }
      }
    ],
    "meta": {
      "type": "for-you",
      "limit": 20,
      "score_weights": {
        "watchlist_similarity": 3,
        "vote_similarity": 2
      }
    }
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Get Awards Leaderboard

Source: https://docs.grails.app/docs/api/awards-leaderboard

Ranks users by ENS registration and renewal activity through the Grails referral program. Points are earned based on total duration — 1 point per year of registration/renewal duration. The program started on April 1, 2026.

```APIDOC
## GET /api/v1/awards-leaderboard

### Description
Ranks users by ENS registration and renewal activity through the Grails referral program. Points are earned based on total duration — 1 point per year of registration/renewal duration. The program started on April 1, 2026.

### Method
GET

### Endpoint
/api/v1/awards-leaderboard

### Query Parameters
- **page** (number) - Optional - Page number. Default: `1`
- **limit** (number) - Optional - Results per page (1–100). Default: `20`
- **sortBy** (string) - Optional - Sort field. Default: `points`. Available fields: `points`, `registration_duration`, `renewal_duration`, `total_duration`, `total_eth_spend`, `base_cost_usd`, `base_cost_eth`
- **sortOrder** (string) - Optional - Sort order. Default: `desc`. Available values: `asc`, `desc`

### Request Example
```curl
https://api.grails.app/api/v1/awards-leaderboard?sortBy=points&limit=10
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the leaderboard data.
  - **users** (array) - List of users with their ranking details.
    - **rank** (number) - Position in the leaderboard.
    - **address** (string) - User’s Ethereum address.
    - **points** (number) - Total points (1 per year of duration).
    - **registration_duration_seconds** (number) - Total registration duration.
    - **renewal_duration_seconds** (number) - Total renewal duration.
    - **total_duration_seconds** (number) - Combined registration + renewal duration.
    - **total_duration_years** (number) - Duration in years.
    - **total_eth_spend_wei** (string) - Total ETH spent (wei).
    - **base_cost_usd** (number) - Estimated base cost in USD ($5/year).
    - **base_cost_eth** (number) - Estimated base cost in ETH (at time of transaction).
    - **registration_count** (number) - Number of registrations.
    - **renewal_count** (number) - Number of renewals.
- **pagination** (object) - Pagination details.
  - **page** (number) - Current page number.
  - **limit** (number) - Results per page.
  - **total** (number) - Total number of results.
  - **pages** (number) - Total number of pages.
- **meta** (object) - Metadata about the leaderboard.
  - **timestamp** (string) - Timestamp of the response.
  - **version** (string) - API version.
  - **program_start** (string) - The start date of the awards program.
  - **seconds_per_year** (number) - The number of seconds in a year used for calculation.
  - **sort** (object) - Information about the current sort order.
    - **by** (string) - The field by which the data is sorted.
    - **order** (string) - The order of sorting (`asc` or `desc`).

#### Response Example
```json
{
  "success": true,
  "data": {
    "users": [
      {
        "rank": 1,
        "address": "0x1234...",
        "points": 12,
        "registration_duration_seconds": 252455616,
        "renewal_duration_seconds": 126227808,
        "total_duration_seconds": 378683424,
        "total_duration_years": 12.0,
        "total_eth_spend_wei": "500000000000000000",
        "base_cost_usd": 60.0,
        "base_cost_eth": 0.03,
        "registration_count": 8,
        "renewal_count": 4
      }
    ]
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 250,
    "pages": 25
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0",
    "program_start": "2026-04-01T00:00:00Z",
    "seconds_per_year": 31556952,
    "sort": { "by": "points", "order": "desc" }
  }
}
```

#### Error Responses
- **500** - Failed to fetch awards leaderboard.
```

--------------------------------

### Get Order by ID or Hash

Source: https://docs.grails.app/docs/api/orders

Get an order by its ID or order hash.

```APIDOC
## GET /:id

### Description
Get an order by ID or order hash.

### Method
GET

### Endpoint
/api/v1/orders/:id

### Auth
None
```

--------------------------------

### Sample Request for Registrations

Source: https://docs.grails.app/docs/api/charts/registrations

Demonstrates how to call the API to get registration data for a specific period. Ensure to replace placeholder values with actual parameters.

```curl
curl "https://api.grails.app/api/v1/charts/registrations?period=30d"
```

--------------------------------

### Sample Response (200 OK)

Source: https://docs.grails.app/docs/api/offers/by-owner

This is a successful response structure containing a list of offers and pagination details. The 'data' object includes an array of 'offers' and 'pagination' information.

```json
// 200 OK
{
  "success": true,
  "data": {
    "offers": [
      {
        "id": 99,
        "ens_name_id": 1,
        "buyer_address": "0x5678...",
        "offer_amount_wei": "50000000000000000",
        "currency_address": "0x0000000000000000000000000000000000000000",
        "order_hash": "0xabc123...",
        "order_data": { ... },
        "status": "pending",
        "created_at": "2026-04-07T12:00:00.000Z",
        "expires_at": "2026-05-01T00:00:00.000Z",
        "source": "grails",
        "last_validated_at": "2026-04-07T13:00:00.000Z",
        "unfunded_at": null,
        "unfunded_reason": null,
        "name": "example.eth",
        "token_id": "12345..."
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 8,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  },
  "meta": {
    "timestamp": "2026-04-07T12:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Get POAP Stats

Source: https://docs.grails.app/docs/api/poap/stats

Make a GET request to the POAP stats endpoint to retrieve aggregate data. No authentication is required.

```bash
curl "https://api.grails.app/api/v1/poap/stats"
```

```json
{
  "success": true,
  "data": {
    "total": 1000,
    "claimed": 750,
    "remaining": 250
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Sample Request for User Activity

Source: https://docs.grails.app/docs/api/analytics/user-me

Use this cURL command to request the activity summary and portfolio overview for the authenticated user. Replace YOUR_TOKEN with your actual API token.

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.grails.app/api/v1/analytics/user/me"
```

--------------------------------

### Sample Request for Similar to Watchlist

Source: https://docs.grails.app/docs/api/recommendations/similar-to-watchlist

Demonstrates how to make a request to the similar-to-watchlist endpoint using cURL. Ensure you replace YOUR_TOKEN with your actual authentication token.

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.grails.app/api/v1/recommendations/similar-to-watchlist?limit=10"
```

--------------------------------

### Sample Request for Recommendations

Source: https://docs.grails.app/docs/api/recommendations/for-you

Use this cURL command to fetch personalized recommendations. Replace YOUR_TOKEN with your actual API token. The 'limit' parameter can be adjusted to control the number of results.

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.grails.app/api/v1/recommendations/for-you?limit=20"
```

--------------------------------

### Sample API Response (200 OK)

Source: https://docs.grails.app/docs/api/offers/by-buyer

This is a successful response structure for the 'Get Offers by Buyer Address' endpoint. It includes offer details and pagination information.

```json
// 200 OK
{
  "success": true,
  "data": {
    "offers": [
      {
        "id": 99,
        "ens_name_id": 1,
        "buyer_address": "0x1234...",
        "offer_amount_wei": "50000000000000000",
        "currency_address": "0x0000000000000000000000000000000000000000",
        "order_hash": "0xabc123...",
        "order_data": { ... },
        "status": "pending",
        "created_at": "2026-04-07T12:00:00.000Z",
        "expires_at": "2026-05-01T00:00:00.000Z",
        "source": "grails",
        "last_validated_at": "2026-04-07T13:00:00.000Z",
        "unfunded_at": null,
        "unfunded_reason": null,
        "name": "example.eth",
        "token_id": "12345..."
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 5,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  },
  "meta": {
    "timestamp": "2026-04-07T12:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Get Offer by ID using cURL

Source: https://docs.grails.app/docs/api/offers/get-by-id

Use this cURL command to make a GET request to retrieve a specific offer by its ID. Replace '99' with the actual offer ID.

```bash
curl https://api.grails.app/api/v1/offers/99
```

--------------------------------

### Connect to Activity WebSocket

Source: https://docs.grails.app/docs/api/websocket/activity

Use this command to establish a WebSocket connection to the activity stream. The server will send a 'connected' message upon successful connection.

```bash
wscat -c "wss://api.grails.app/ws/activity"
```

--------------------------------

### API Response Example

Source: https://docs.grails.app/docs/api/analytics/registrations-by-length

A successful 200 OK response from the Registrations by Length API, showing a breakdown of registration costs by name length for a 7-day period.

```json
{
  "success": true,
  "data": {
    "period": "7d",
    "breakdown": [
      {
        "name_length": 3,
        "count": 15,
        "total_cost_wei": "750000000000000000",
        "avg_cost_wei": "50000000000000000",
        "avg_base_cost_wei": "45000000000000000",
        "avg_premium_wei": "5000000000000000",
        "min_cost_wei": "10000000000000000",
        "max_cost_wei": "200000000000000000",
        "median_cost_wei": "40000000000000000",
        "premium_count": 3
      },
      {
        "name_length": 4,
        "count": 45,
        "total_cost_wei": "225000000000000000",
        "avg_cost_wei": "5000000000000000",
        "avg_base_cost_wei": "4500000000000000",
        "avg_premium_wei": "500000000000000",
        "min_cost_wei": "1000000000000000",
        "max_cost_wei": "50000000000000000",
        "median_cost_wei": "4000000000000000",
        "premium_count": 5
      }
    ]
  },
  "meta": {
    "timestamp": "2026-04-09T00:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Sample Response for Similar to Watchlist

Source: https://docs.grails.app/docs/api/recommendations/similar-to-watchlist

Illustrates a successful response from the similar-to-watchlist endpoint. The data includes recommended names, their similarity metrics, and metadata about the recommendation type and limit.

```json
// 200 OK
{
  "success": true,
  "data": {
    "names": [
      {
        "name": "recommended.eth",
        // ... standard search result fields
        "recommendation_metrics": {
          "type": "similar-to-watchlist",
          "similarity_score": 15,
          "common_watchers": 8
        }
      }
    ],
    "meta": {
      "type": "similar-to-watchlist",
      "limit": 10
    }
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Get Listing by ID using cURL

Source: https://docs.grails.app/docs/api/listings/get-by-id

Use this command to make a GET request to the listings API to retrieve a specific listing by its ID. Replace `42` with the desired listing ID.

```bash
curl https://api.grails.app/api/v1/listings/42
```

--------------------------------

### Sample Request for Recommendations

Source: https://docs.grails.app/docs/api/recommendations/based-on-votes

Use this cURL command to request recommendations based on votes. Include your authentication token and optionally specify the number of results.

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.grails.app/api/v1/recommendations/based-on-votes?limit=10"
```

--------------------------------

### Sample Request using cURL

Source: https://docs.grails.app/docs/api/clubs/get-club

Demonstrates how to make a GET request to the API to retrieve club details. Replace '10k' with the desired club name.

```curl
curl "https://api.grails.app/api/v1/clubs/10k"
```

--------------------------------

### Persona Response Example

Source: https://docs.grails.app/docs/api/personas/list

This is an example of a successful response when listing personas. It includes a list of persona objects, each with its unique identifier, display name, descriptive text, icon, and predefined filter configurations.

```json
// 200 OK
{
  "success": true,
  "data": [
    {
      "slug": "collector",
      "name": "Collector",
      "description": "Focused on accumulating ENS names",
      "icon": "🏆",
      "defaultFilters": {
        "allNames": { "sortBy": "price", "sortOrder": "asc" },
        "listings": { "sortBy": "price", "sortOrder": "asc" },
        "sales": { "sortBy": "date", "sortOrder": "desc" },
        "registrations": { "sortBy": "date", "sortOrder": "desc" },
        "offers": { "sortBy": "price", "sortOrder": "desc" }
      }
    }
  ],
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z"
  }
}
```

--------------------------------

### GET /health

Source: https://docs.grails.app/docs/api/health

Retrieves the current status and version of the service.

```APIDOC
## GET /health

### Description
Returns the current service status and version.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the service (e.g., "healthy").
- **timestamp** (string) - The timestamp when the health check was performed.
- **version** (string) - The current version of the service.

### Response Example
```json
{
  "status": "healthy",
  "timestamp": "2026-04-07T12:00:00.000Z",
  "version": "1.0.0"
}
```
```

--------------------------------

### Get Listing by ID

Source: https://docs.grails.app/docs/api/listings

Retrieves a single listing by its unique identifier.

```APIDOC
## GET /:id

### Description
Get a single listing by ID.

### Method
GET

### Endpoint
/api/v1/listings/:id
```

--------------------------------

### Sample API Request

Source: https://docs.grails.app/docs/api/analytics/offers

Demonstrates how to make a request to the offers feed API.

```curl
curl "https://api.grails.app/api/v1/analytics/offers"
```

--------------------------------

### Create Listing

Source: https://docs.grails.app/docs/api/listings/create

Creates a new marketplace listing. The seller address must match the authenticated user. On creation, background jobs are queued for expiry scheduling, ENS metadata sync, and club floor price updates.

```APIDOC
## POST /api/v1/listings

### Description
Create a new marketplace listing. The seller address must match the authenticated user. On creation, background jobs are queued for expiry scheduling, ENS metadata sync, and club floor price updates.

### Method
POST

### Endpoint
/api/v1/listings

### Parameters
#### Request Body
- **ensNameId** (number) - Required - Database ID of the ENS name
- **sellerAddress** (string) - Required - Seller’s Ethereum address (must match authenticated user)
- **priceWei** (string) - Required - Listing price in wei
- **currencyAddress** (string) - Optional - Payment token address (defaults to ETH zero address)
- **orderData** (any) - Required - Seaport order data for on-chain fulfillment
- **expiresAt** (string) - Optional - Listing expiration date (ISO string)

### Request Example
```json
{
  "ensNameId": 1,
  "sellerAddress": "0xabcd...",
  "priceWei": "100000000000000000",
  "orderData": { ... }
}
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the details of the created listing.
  - **id** (number) - The unique identifier for the listing.
  - **ens_name_id** (number) - The database ID of the ENS name associated with the listing.
  - **seller_address** (string) - The Ethereum address of the seller.
  - **price_wei** (string) - The listing price in wei.
  - **currency_address** (string) - The address of the payment token.
  - **order_hash** (string|null) - The hash of the order.
  - **order_data** (any) - The Seaport order data.
  - **status** (string) - The current status of the listing.
  - **source** (string|null) - The source of the listing.
  - **created_at** (string) - The timestamp when the listing was created.
  - **updated_at** (string) - The timestamp when the listing was last updated.
  - **expires_at** (string|null) - The expiration date of the listing.
  - **broker_address** (string|null) - The address of the broker.
  - **broker_fee_bps** (number|null) - The broker fee in basis points.
- **meta** (object) - Metadata about the response.
  - **timestamp** (string) - The timestamp of the response.
  - **version** (string) - The API version.

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": 43,
    "ens_name_id": 1,
    "seller_address": "0xabcd...",
    "price_wei": "100000000000000000",
    "currency_address": "0x0000000000000000000000000000000000000000",
    "order_hash": null,
    "order_data": { ... },
    "status": "active",
    "source": null,
    "created_at": "2026-04-07T12:00:00.000Z",
    "updated_at": "2026-04-07T12:00:00.000Z",
    "expires_at": null,
    "broker_address": null,
    "broker_fee_bps": null
  },
  "meta": {
    "timestamp": "2026-04-07T12:00:00.000Z",
    "version": "1.0.0"
  }
}
```

#### Error Responses
- **400 VALIDATION_ERROR**: Invalid request body
- **401 UNAUTHORIZED**: Missing or invalid token
- **403 FORBIDDEN**: Seller address does not match authenticated user
- **404 ENS_NAME_NOT_FOUND**: ENS name ID does not exist
```

--------------------------------

### Connect to WebSocket Events Channel

Source: https://docs.grails.app/docs/api/websocket/events

Use this command to establish a WebSocket connection to the events channel. Ensure the URL is correct for your deployment.

```bash
wscat -c "wss://api.grails.app/ws/events"
```

--------------------------------

### Get User Balances

Source: https://docs.grails.app/docs/api/users/balances

Fetches the token balances for a specified Ethereum address.

```APIDOC
## GET /api/v1/users/:address/balances

### Description
Returns token balances for the given address: ETH, WETH, USDC, and ENS.

### Method
GET

### Endpoint
/api/v1/users/:address/balances

### Parameters
#### Path Parameters
- **address** (string) - Required - Ethereum address (`0x` + 40 hex chars)

### Request Example
```curl
https://api.grails.app/api/v1/users/0x1234.../balances
```

### Response
#### Success Response (200)
- **success** (boolean)
- **data** (object)
  - **address** (string)
  - **balances** (object)
    - **eth** (object)
      - **symbol** (string)
      - **address** (string | null)
      - **wei** (string)
      - **formatted** (string)
      - **decimals** (integer)
    - **weth** (object)
      - **symbol** (string)
      - **address** (string)
      - **wei** (string)
      - **formatted** (string)
      - **decimals** (integer)
    - **usdc** (object)
      - **symbol** (string)
      - **address** (string)
      - **wei** (string)
      - **formatted** (string)
      - **decimals** (integer)
    - **ens** (object)
      - **symbol** (string)
      - **address** (string)
      - **wei** (string)
      - **formatted** (string)
      - **decimals** (integer)
- **meta** (object)
  - **timestamp** (string)
  - **version** (string)

#### Response Example
```json
{
  "success": true,
  "data": {
    "address": "0x983110309620d911731ac0932219af06091b6744",
    "balances": {
      "eth": {
        "symbol": "ETH",
        "address": null,
        "wei": "1500000000000000000",
        "formatted": "1.5",
        "decimals": 18
      },
      "weth": {
        "symbol": "WETH",
        "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
        "wei": "250000000000000000",
        "formatted": "0.25",
        "decimals": 18
      },
      "usdc": {
        "symbol": "USDC",
        "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "wei": "1000000000",
        "formatted": "1000.0",
        "decimals": 6
      },
      "ens": {
        "symbol": "ENS",
        "address": "0xC18360217D8F7Ab5e7c516566761Ea12Ce7F9D72",
        "wei": "50000000000000000000",
        "formatted": "50.0",
        "decimals": 18
      }
    }
  },
  "meta": {
    "timestamp": "2026-04-07T12:00:00.000Z",
    "version": "1.0.0"
  }
}
```

#### Error Responses
- **400** `VALIDATION_ERROR`: Invalid address format
- **500** `INTERNAL_ERROR`: Failed to fetch balances
```

--------------------------------

### Get Personalized Recommendations

Source: https://docs.grails.app/docs/api/recommendations/for-you

Fetches personalized recommendations for the user. Authentication is required.

```APIDOC
## GET /api/v1/recommendations/for-you

### Description
Personalized recommendations combining watchlist similarity (3x weight) and vote similarity (2x weight). Fetches candidates from both sources, scores them by weighted sum, and returns the top results.

### Method
GET

### Endpoint
/api/v1/recommendations/for-you

### Parameters
#### Query Parameters
- **limit** (number) - Optional - Max results (1–50). Defaults to 10.

### Request Example
```curl
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.grails.app/api/v1/recommendations/for-you?limit=20"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the recommendation results.
  - **names** (array) - List of recommended items.
    - **name** (string) - The name of the recommended item.
    - **recommendation_metrics** (object) - Metrics for the recommendation.
      - **type** (string) - Type of recommendation ('for-you').
      - **personalized_score** (number) - The personalized score for this recommendation.
  - **meta** (object) - Metadata about the recommendations.
    - **type** (string) - Type of metadata ('for-you').
    - **limit** (number) - The limit applied to the results.
    - **score_weights** (object) - The weights used for scoring.
      - **watchlist_similarity** (number) - Weight for watchlist similarity.
      - **vote_similarity** (number) - Weight for vote similarity.
- **meta** (object) - General metadata about the response.
  - **timestamp** (string) - The timestamp of the response.
  - **version** (string) - The API version.
```

--------------------------------

### Sample API Response (200 OK)

Source: https://docs.grails.app/docs/api/analytics/offers

Illustrates the structure of a successful response from the offers feed API, including offer details and pagination information.

```json
// 200 OK
{
  "success": true,
  "data": {
    "results": [
      {
        "name": "example.eth",
        "token_id": "12345",
        "offer_amount_wei": "100000000000000000",
        "currency_address": "0x0000000000000000000000000000000000000000",
        "buyer_address": "0x1234...abcd",
        "status": "active",
        "source": "grails",
        "created_at": "2026-04-07T12:00:00.000Z",
        "clubs": ["999"]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 200,
      "totalPages": 10,
      "hasNext": true,
      "hasPrev": false
    }
  },
  "meta": {
    "timestamp": "2026-04-09T00:00:00.000Z",
    "version": "1.0.0"
  }
}
```

--------------------------------

### Get Listing by Name

Source: https://docs.grails.app/docs/api/listings

Retrieves active listings for a specific ENS name.

```APIDOC
## GET /name/:name

### Description
Get active listings for an ENS name.

### Method
GET

### Endpoint
/api/v1/listings/name/:name
```

--------------------------------

### Bulk Create Listings Request

Source: https://docs.grails.app/docs/api/orders/bulk

Use this cURL command to send a bulk request for creating listings. Ensure you replace YOUR_TOKEN with your actual authentication token and populate the listing details accurately.

```curl
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.grails.app/api/v1/orders/bulk \
  -d '{
    "listings": [
      {
        "type": "listing",
        "token_id": "111",
        "price_wei": "100000000000000000",
        "order_data": "{...}",
        "order_hash": "0xabc...",
        "seller_address": "0xabcd..."
      },
      {
        "type": "listing",
        "token_id": "222",
        "price_wei": "200000000000000000",
        "order_data": "{...}",
        "order_hash": "0xdef...",
        "seller_address": "0xabcd..."
      }
    ]
  }'
```

--------------------------------

### Get all roles for a name

Source: https://docs.grails.app/docs/api/ens-roles

Retrieves all roles associated with a specific ENS name.

```APIDOC
## GET /names/:name/roles

### Description
Get all roles for a name.

### Method
GET

### Endpoint
/api/v1/ens-roles/names/:name/roles

### Parameters
#### Path Parameters
- **name** (string) - Required - The ENS name to query roles for.
```
Tokens:
Raw