Grails API Documentation

GET /api/v1/listings

List marketplace listings with filtering, sorting, and pagination. Defaults to active listings only. Names past their 90-day grace period are excluded.

Authentication: None

Cache: None

Query Parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number (min 1)
`limit`	number	`20`	Results per page (1–100)
`status`	string	`active`	Filter: `active`, `sold`, `cancelled`, `expired`, `unfunded`
`seller`	string	—	Filter by seller address
`minPrice`	string	—	Minimum price (wei)
`maxPrice`	string	—	Maximum price (wei)
`sort`	string	`created`	Sort by: `price`, `created`, `expiry`, `name`
`order`	string	`desc`	Sort direction: `asc` or `desc`

Sample Request


curl "https://api.grails.app/api/v1/listings?status=active&sort=price&order=asc&limit=10"

Response


// 200 OK
{
  "success": true,
  "data": {
    "listings": [
      {
        "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
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 500,
      "totalPages": 50,
      "hasNext": true,
      "hasPrev": false
    }
  },
  "meta": {
    "timestamp": "2026-04-07T12:00:00.000Z",
    "version": "1.0.0"
  }
}