Grails API Documentation

POST /api/v1/cart

Add a single ENS name to the cart. If the item is already in the cart with the same type, the request succeeds silently without creating a duplicate.

Authentication: Required

Cache: None

Request Body

Field	Type	Required	Description
`ensNameId`	number	Yes	Database ID of the ENS name
`cartType`	string	Yes	Cart type name (e.g. `buy`, `register`)

Sample Request


curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.grails.app/api/v1/cart \
  -d '{ "ensNameId": 42, "cartType": "buy" }'

Response


// 200 OK — newly added
{
  "success": true,
  "data": {
    "message": "Added to cart",
    "cartItemId": 1,
    "ensNameId": 42,
    "ensName": "example.eth",
    "cartType": "buy"
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}

When the item already exists in the cart with the same type, cartItemId is null:


// 200 OK — duplicate (no-op)
{
  "success": true,
  "data": {
    "message": "Item already in cart",
    "cartItemId": null,
    "ensNameId": 42,
    "ensName": "example.eth",
    "cartType": "buy"
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}

Error Responses

Status	Code	Description
400	`VALIDATION_ERROR`	Invalid request body
400	`INVALID_CART_TYPE`	Cart type does not exist
401	`UNAUTHORIZED`	Missing or invalid token
404	`ENS_NAME_NOT_FOUND`	ENS name ID not found
500	`INTERNAL_ERROR`	Failed to add to cart