Category Management API

This document describes the Category Management endpoints for organizing digital assets into groups.

Endpoints

• Create Category - POST /categories
• List Categories - GET /categories
• Get Category - GET /categories/:id
• Update Category - PUT /categories/:id
• Delete Category - DELETE /categories/:id

---

Create Category

Creates a new asset category for organizing digital assets.

Endpoint: POST /categories

Request Body

{
  "name": "string",
  "description": "string"
}

Field	Type	Required	Description
name	string	Yes	Category name (e.g., "Cryptocurrency", "Stablecoins")
description	string	No	Category description

Response

Status: 201 Created

{
  "id": "789e4567-e89b-12d3-a456-426614174000",
  "name": "Cryptocurrency",
  "description": "Digital currencies using blockchain technology",
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z"
}

Examples

Create Basic Category

curl -X POST "https://api.ledgerlink.ai/v1/categories" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stablecoins"
  }'

Response:

{
  "id": "789e4567-e89b-12d3-a456-426614174000",
  "name": "Stablecoins",
  "description": null,
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z"
}

Create Category with Description

curl -X POST "https://api.ledgerlink.ai/v1/categories" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DeFi Tokens",
    "description": "Tokens from decentralized finance protocols"
  }'

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": ["name must be a string", "name should not be empty"],
  "error": "Bad Request"
}

Causes:

• Missing required name field
• Invalid data types
• Empty name value

409 Conflict

{
  "statusCode": 409,
  "message": "Category with this name already exists",
  "error": "Conflict"
}

500 Internal Server Error

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

---

List Categories

Retrieves a paginated list of categories with optional filtering and sorting.

Endpoint: GET /categories

Query Parameters

Parameter	Type	Required	Description
name	string	No	Filter by name (case-insensitive, partial match)
limit	number	No	Maximum results per page (default: 10)
offset	number	No	Number of results to skip (default: 0)
sortBy	string	No	Sort field: name, createdAt, updatedAt (default: createdAt)
sortOrder	string	No	Sort direction: asc or desc (default: asc)

Response

Status: 200 OK

{
  "data": [
    {
      "id": "789e4567-e89b-12d3-a456-426614174000",
      "name": "Cryptocurrency",
      "description": "Digital currencies using blockchain technology",
      "createdAt": "2025-11-20T10:30:00.000Z",
      "updatedAt": "2025-11-20T10:30:00.000Z",
      "assets": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "Bitcoin",
          "code": "BTC"
        },
        {
          "id": "234e4567-e89b-12d3-a456-426614174001",
          "name": "Ethereum",
          "code": "ETH"
        }
      ],
      "categoryProviders": [
        {
          "providerId": "456e8400-e29b-41d4-a716-446655440000",
          "provider": {
            "id": "456e8400-e29b-41d4-a716-446655440000",
            "name": "CoinMarketCap",
            "slug": "coinmarketcap"
          }
        }
      ]
    }
  ],
  "pageInfo": {
    "limit": 10,
    "offset": 0,
    "total": 5
  }
}

Response Fields

Data Array

Field	Type	Description
id	string (UUID)	Category identifier
name	string	Category name
description	string	Category description
createdAt	string	Creation timestamp (ISO 8601)
updatedAt	string	Last update timestamp (ISO 8601)
assets	array	Assets in this category (when included)
categoryProviders	array	Providers mapped to this category (when included)

Page Info

Field	Type	Description
limit	number	Requested limit
offset	number	Requested offset
total	number	Total matching records

Examples

List All Categories

curl -X GET "https://api.ledgerlink.ai/v1/categories?limit=20&offset=0"

Filter by Name

curl -X GET "https://api.ledgerlink.ai/v1/categories?name=crypto"

Response:

{
  "data": [
    {
      "id": "789e4567-e89b-12d3-a456-426614174000",
      "name": "Cryptocurrency",
      "description": "Digital currencies"
    }
  ],
  "pageInfo": {
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}

Sort by Name Alphabetically

curl -X GET "https://api.ledgerlink.ai/v1/categories?sortBy=name&sortOrder=asc"

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid sortBy value",
  "error": "Bad Request"
}

Causes:

• Invalid sortBy field
• Invalid sortOrder value
• Negative limit or offset

500 Internal Server Error

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

---

Get Category

Retrieves a specific category by ID with full relationship data.

Endpoint: GET /categories/:id

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Category UUID

Response

Status: 200 OK

{
  "id": "789e4567-e89b-12d3-a456-426614174000",
  "name": "Cryptocurrency",
  "description": "Digital currencies using blockchain technology",
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z",
  "assets": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Bitcoin",
      "code": "BTC",
      "description": "Leading cryptocurrency"
    },
    {
      "id": "234e4567-e89b-12d3-a456-426614174001",
      "name": "Ethereum",
      "code": "ETH",
      "description": "Smart contract platform"
    }
  ],
  "categoryProviders": [
    {
      "categoryId": "789e4567-e89b-12d3-a456-426614174000",
      "providerId": "456e8400-e29b-41d4-a716-446655440000",
      "provider": {
        "id": "456e8400-e29b-41d4-a716-446655440000",
        "name": "CoinMarketCap",
        "slug": "coinmarketcap",
        "isDefault": true
      }
    }
  ]
}

Example

curl -X GET "https://api.ledgerlink.ai/v1/categories/789e4567-e89b-12d3-a456-426614174000"

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "The category does not exist",
  "error": "Bad Request"
}

Causes:

• Category ID not found
• Invalid UUID format

500 Internal Server Error

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

---

Update Category

Updates an existing category's details.

Endpoint: PUT /categories/:id

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Category UUID

Request Body

{
  "name": "string",
  "description": "string"
}

All fields are optional. Only provided fields will be updated.

Response

Status: 200 OK

{
  "id": "789e4567-e89b-12d3-a456-426614174000",
  "name": "Cryptocurrencies",
  "description": "Updated description for digital currencies",
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T15:45:00.000Z"
}

Example

curl -X PUT "https://api.ledgerlink.ai/v1/categories/789e4567-e89b-12d3-a456-426614174000" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cryptocurrencies",
    "description": "Major digital currencies and tokens"
  }'

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "The category does not exist",
  "error": "Bad Request"
}

Causes:

• Category not found
• Invalid input data
• Name conflict with existing category

500 Internal Server Error

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

---

Delete Category

Soft deletes a category from the system.

Endpoint: DELETE /categories/:id

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Category UUID

Response

Status: 200 OK

{
  "success": true,
  "message": "Category successfully deleted"
}

Example

curl -X DELETE "https://api.ledgerlink.ai/v1/categories/789e4567-e89b-12d3-a456-426614174000"

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "The category does not exist",
  "error": "Bad Request"
}

Causes:

• Category not found
• Category has active assets (implementation-dependent)

500 Internal Server Error

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

Notes

• This is a soft delete - the category is marked as deleted but remains in the database
• Deleted categories are excluded from list queries
• Consider the impact on associated assets before deleting
• Assets in deleted categories may default to having no category

---

Category Use Cases

Provider Selection by Category

Categories enable efficient provider selection for rate fetching:

1. Category-Level Providers: Map providers to categories (e.g., "CoinMarketCap" → "Cryptocurrency")
2. Asset-Level Override: Individual assets can override category providers
3. Fallback Strategy: If no asset-specific providers, use category providers
4. Default Providers: If no category providers, use default providers

Organization and Filtering

Categories help organize assets:

• Group similar assets (Stablecoins, DeFi Tokens, NFTs, etc.)
• Filter asset lists by category
• Apply category-wide configurations
• Simplify bulk operations

Example Category Structure

Categories:
├── Cryptocurrency
│   ├── Bitcoin (BTC)
│   ├── Ethereum (ETH)
│   └── Solana (SOL)
├── Stablecoins
│   ├── USD Coin (USDC)
│   ├── Tether (USDT)
│   └── DAI (DAI)
└── DeFi Tokens
    ├── Uniswap (UNI)
    ├── Aave (AAVE)
    └── Compound (COMP)

---

Need Help? Contact helpdesk@ledgerlink.ai for assistance.