Provider Management API

This document describes the Provider Management endpoints for configuring market data providers that supply digital asset rates.

Endpoints

• Create Provider - POST /providers
• List Providers - GET /providers
• Get Provider - GET /providers/:id
• Update Provider - PUT /providers/:id
• Delete Provider - DELETE /providers/:id

---

Create Provider

Creates a new market data provider configuration.

Endpoint: POST /providers

Request Body

{
  "name": "string",
  "slug": "string",
  "isDefault": boolean,
  "config": {}
}

Field	Type	Required	Description
name	string	Yes	Provider display name (e.g., "CoinMarketCap")
slug	string	Yes	Unique provider identifier slug (e.g., "coinmarketcap")
isDefault	boolean	No	Whether this is a default provider (default: false)
config	object	No	Provider-specific configuration (API keys, settings, etc.)

Response

Status: 201 Created

{
  "id": "456e8400-e29b-41d4-a716-446655440000",
  "name": "CoinMarketCap",
  "slug": "coinmarketcap",
  "isDefault": true,
  "config": {
    "apiKey": "***",
    "priority": 1
  },
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z"
}

Examples

Create Default Provider

curl -X POST "https://api.ledgerlink.ai/v1/providers" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CoinMarketCap",
    "slug": "coinmarketcap",
    "isDefault": true,
    "config": {
      "apiKey": "your-api-key-here",
      "priority": 1
    }
  }'

Response:

{
  "id": "456e8400-e29b-41d4-a716-446655440000",
  "name": "CoinMarketCap",
  "slug": "coinmarketcap",
  "isDefault": true,
  "config": {
    "apiKey": "***",
    "priority": 1
  },
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z"
}

Create Non-Default Provider

curl -X POST "https://api.ledgerlink.ai/v1/providers" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pyth Network",
    "slug": "pyth",
    "isDefault": false
  }'

Error Responses

400 Bad Request

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

Causes:

• Missing required fields (name or slug)
• Invalid data types
• Slug already exists (must be unique)

500 Internal Server Error

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

---

List Providers

Retrieves a paginated list of all configured providers.

Endpoint: GET /providers

Query Parameters

Parameter	Type	Required	Description
name	string	No	Filter by name (case-insensitive, partial match)
slug	string	No	Filter by slug (exact match)
isDefault	boolean	No	Filter by default status
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, slug, createdAt, updatedAt (default: createdAt)
sortOrder	string	No	Sort direction: asc or desc (default: asc)

Response

Status: 200 OK

{
  "data": [
    {
      "id": "456e8400-e29b-41d4-a716-446655440000",
      "name": "CoinMarketCap",
      "slug": "coinmarketcap",
      "isDefault": true,
      "config": {
        "apiKey": "***",
        "priority": 1
      },
      "createdAt": "2025-11-20T10:30:00.000Z",
      "updatedAt": "2025-11-20T10:30:00.000Z",
      "assetProviders": [],
      "categoryProviders": []
    },
    {
      "id": "567e8400-e29b-41d4-a716-446655440001",
      "name": "Pyth Network",
      "slug": "pyth",
      "isDefault": true,
      "config": {},
      "createdAt": "2025-11-20T11:00:00.000Z",
      "updatedAt": "2025-11-20T11:00:00.000Z",
      "assetProviders": [],
      "categoryProviders": []
    }
  ],
  "pageInfo": {
    "limit": 10,
    "offset": 0,
    "total": 2
  }
}

Examples

List All Providers

curl -X GET "https://api.ledgerlink.ai/v1/providers"

List Default Providers Only

curl -X GET "https://api.ledgerlink.ai/v1/providers?isDefault=true"

Filter by Name

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

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid query parameters",
  "error": "Bad Request"
}

500 Internal Server Error

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

---

Get Provider

Retrieves a specific provider by ID with full relationship data.

Endpoint: GET /providers/:id

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Provider UUID

Response

Status: 200 OK

{
  "id": "456e8400-e29b-41d4-a716-446655440000",
  "name": "CoinMarketCap",
  "slug": "coinmarketcap",
  "isDefault": true,
  "config": {
    "apiKey": "***",
    "priority": 1
  },
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z",
  "assetProviders": [
    {
      "assetId": "123e4567-e89b-12d3-a456-426614174000",
      "providerId": "456e8400-e29b-41d4-a716-446655440000",
      "asset": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Bitcoin",
        "code": "BTC"
      }
    }
  ],
  "categoryProviders": [
    {
      "categoryId": "789e4567-e89b-12d3-a456-426614174000",
      "providerId": "456e8400-e29b-41d4-a716-446655440000",
      "category": {
        "id": "789e4567-e89b-12d3-a456-426614174000",
        "name": "Cryptocurrency"
      }
    }
  ]
}

Example

curl -X GET "https://api.ledgerlink.ai/v1/providers/456e8400-e29b-41d4-a716-446655440000"

Error Responses

404 Not Found

{
  "statusCode": 404,
  "message": "Provider not found",
  "error": "Not Found"
}

500 Internal Server Error

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

---

Update Provider

Updates an existing provider's configuration.

Endpoint: PUT /providers/:id

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Provider UUID

Request Body

{
  "name": "string",
  "slug": "string",
  "isDefault": boolean,
  "config": {}
}

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

Response

Status: 200 OK

{
  "id": "456e8400-e29b-41d4-a716-446655440000",
  "name": "CoinMarketCap Pro",
  "slug": "coinmarketcap",
  "isDefault": true,
  "config": {
    "apiKey": "***",
    "priority": 1,
    "timeout": 5000
  },
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T15:45:00.000Z"
}

Example

curl -X PUT "https://api.ledgerlink.ai/v1/providers/456e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CoinMarketCap Pro",
    "config": {
      "apiKey": "new-api-key",
      "priority": 1,
      "timeout": 5000
    }
  }'

Error Responses

404 Not Found

{
  "statusCode": 404,
  "message": "Provider not found",
  "error": "Not Found"
}

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid input data",
  "error": "Bad Request"
}

---

Delete Provider

Soft deletes a provider from the system.

Endpoint: DELETE /providers/:id

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Provider UUID

Response

Status: 200 OK

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

Example

curl -X DELETE "https://api.ledgerlink.ai/v1/providers/456e8400-e29b-41d4-a716-446655440000"

Error Responses

404 Not Found

{
  "statusCode": 404,
  "message": "Provider not found",
  "error": "Not Found"
}

400 Bad Request

{
  "statusCode": 400,
  "message": "Cannot delete provider with active mappings",
  "error": "Bad Request"
}

Causes:

• Provider has active asset or category mappings
• Provider is currently in use

Notes

• This is a soft delete - the provider is marked as deleted but remains in the database
• Deleted providers are excluded from list queries
• Consider removing asset and category mappings before deleting
• Deleting a provider may impact rate fetching for associated assets

---

Provider Fields Reference

Field	Type	Description
id	string (UUID)	Unique provider identifier
name	string	Provider display name
slug	string	Unique provider slug (used in code)
isDefault	boolean	Whether this provider is used by default
config	object	Provider-specific configuration
createdAt	string (ISO 8601)	Creation timestamp
updatedAt	string (ISO 8601)	Last update timestamp
assetProviders	array	Asset mappings (when included)
categoryProviders	array	Category mappings (when included)

---

Supported Providers

Link Quote currently supports the following market data providers:

CoinMarketCap

Slug: coinmarketcap

Description: Professional cryptocurrency market data provider with comprehensive coverage.

Configuration:

{
  "config": {
    "apiKey": "your-cmc-api-key",
    "priority": 1
  }
}

Features:

• Real-time pricing for thousands of digital assets
• Historical data access
• High reliability and uptime
• Professional-grade API

Requirements:

• CoinMarketCap API key (Basic, Hobbyist, Startup, Standard, or Enterprise plan)

Pyth Network (Hermes)

Slug: pyth

Description: Decentralized oracle network providing real-time on-chain price feeds.

Configuration:

{
  "config": {
    "priority": 2
  }
}

Features:

• Sub-second price updates
• Decentralized data sources
• On-chain verification
• High-frequency trading support

Requirements:

• No API key required
• Connects to Hermes price service

---

Default Providers

Providers marked with isDefault: true are used when:

1. An asset does not exist in the database
2. An asset has no specific provider mappings
3. An asset's category has no provider mappings

Example Provider Selection Logic:

Rate Request for "BTC"
  ↓
1. Check if asset "BTC" exists
  ↓
2. If exists → Use asset-specific providers (if any)
  ↓
3. If no asset providers → Use category providers (if any)
  ↓
4. If no category providers → Use default providers
  ↓
5. Fetch rates from all selected providers in parallel
  ↓
6. Return average of successful responses

---

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