Provider Mapping API

This document describes the Provider Mapping endpoints for associating market data providers with specific assets or categories.

Endpoints

Asset-Provider Mappings

Create Asset-Provider Mapping - POST /asset-providers
Delete Asset-Provider Mapping - DELETE /asset-providers/:assetId/providers/:providerId

Category-Provider Mappings

Create Category-Provider Mapping - POST /category-providers
Delete Category-Provider Mapping - DELETE /category-providers/:id/category/:categoryId

Asset-Provider Mappings

Asset-provider mappings allow you to specify which providers should be used to fetch rates for specific assets. These mappings take precedence over category-level mappings.

Create Asset-Provider Mapping

Associates a provider with a specific asset.

Endpoint: POST /asset-providers

Request Body

{
  "assetId": "string",
  "providerId": "string",
  "config": {}
}

Field	Type	Required	Description
`assetId`	string (UUID)	Yes	Asset UUID to map
`providerId`	string (UUID)	Yes	Provider UUID to map
`config`	object	No	Mapping-specific configuration (e.g., priority)

Response

Status: 201 Created

{
  "assetId": "123e4567-e89b-12d3-a456-426614174000",
  "providerId": "456e8400-e29b-41d4-a716-446655440000",
  "config": {
    "priority": 1
  },
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z"
}

Examples

Map CoinMarketCap to Bitcoin

curl -X POST "https://api.ledgerlink.ai/v1/asset-providers" \
  -H "Content-Type: application/json" \
  -d '{
    "assetId": "123e4567-e89b-12d3-a456-426614174000",
    "providerId": "456e8400-e29b-41d4-a716-446655440000"
  }'

Response:

{
  "assetId": "123e4567-e89b-12d3-a456-426614174000",
  "providerId": "456e8400-e29b-41d4-a716-446655440000",
  "config": null,
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z"
}

Map with Priority Configuration

curl -X POST "https://api.ledgerlink.ai/v1/asset-providers" \
  -H "Content-Type: application/json" \
  -d '{
    "assetId": "123e4567-e89b-12d3-a456-426614174000",
    "providerId": "567e8400-e29b-41d4-a716-446655440001",
    "config": {
      "priority": 2
    }
  }'

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": ["assetId must be a UUID", "providerId must be a UUID"],
  "error": "Bad Request"
}

Causes:

Missing assetId or providerId
Invalid UUID format
Asset or provider does not exist
Mapping already exists

500 Internal Server Error

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

Delete Asset-Provider Mapping

Removes the association between an asset and a provider.

Endpoint: DELETE /asset-providers/:assetId/providers/:providerId

Path Parameters

Parameter	Type	Required	Description
`assetId`	string (UUID)	Yes	Asset UUID
`providerId`	string (UUID)	Yes	Provider UUID

Response

Status: 200 OK

{
  "success": true,
  "message": "Asset-provider relationship successfully deleted"
}

Example

curl -X DELETE "https://api.ledgerlink.ai/v1/asset-providers/123e4567-e89b-12d3-a456-426614174000/providers/456e8400-e29b-41d4-a716-446655440000"

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid UUID format",
  "error": "Bad Request"
}

Causes:

Invalid UUID format
Mapping does not exist

500 Internal Server Error

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

Category-Provider Mappings

Category-provider mappings allow you to specify which providers should be used for all assets within a category. Assets without specific provider mappings will inherit their category's providers.

Create Category-Provider Mapping

Associates a provider with a category.

Endpoint: POST /category-providers

Request Body

{
  "categoryId": "string",
  "providerId": "string",
  "config": {}
}

Field	Type	Required	Description
`categoryId`	string (UUID)	Yes	Category UUID to map
`providerId`	string (UUID)	Yes	Provider UUID to map
`config`	object	No	Mapping-specific configuration

Response

Status: 201 Created

{
  "id": "890e4567-e89b-12d3-a456-426614174002",
  "categoryId": "789e4567-e89b-12d3-a456-426614174000",
  "providerId": "456e8400-e29b-41d4-a716-446655440000",
  "config": {
    "priority": 1
  },
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z"
}

Examples

Map CoinMarketCap to Cryptocurrency Category

curl -X POST "https://api.ledgerlink.ai/v1/category-providers" \
  -H "Content-Type: application/json" \
  -d '{
    "categoryId": "789e4567-e89b-12d3-a456-426614174000",
    "providerId": "456e8400-e29b-41d4-a716-446655440000"
  }'

Response:

{
  "id": "890e4567-e89b-12d3-a456-426614174002",
  "categoryId": "789e4567-e89b-12d3-a456-426614174000",
  "providerId": "456e8400-e29b-41d4-a716-446655440000",
  "config": null,
  "createdAt": "2025-11-20T10:30:00.000Z",
  "updatedAt": "2025-11-20T10:30:00.000Z"
}

Map Multiple Providers to Category

# Map CoinMarketCap
curl -X POST "https://api.ledgerlink.ai/v1/category-providers" \
  -H "Content-Type: application/json" \
  -d '{
    "categoryId": "789e4567-e89b-12d3-a456-426614174000",
    "providerId": "456e8400-e29b-41d4-a716-446655440000",
    "config": { "priority": 1 }
  }'

# Map Pyth Network
curl -X POST "https://api.ledgerlink.ai/v1/category-providers" \
  -H "Content-Type: application/json" \
  -d '{
    "categoryId": "789e4567-e89b-12d3-a456-426614174000",
    "providerId": "567e8400-e29b-41d4-a716-446655440001",
    "config": { "priority": 2 }
  }'

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": ["categoryId must be a UUID", "providerId must be a UUID"],
  "error": "Bad Request"
}

Causes:

Missing categoryId or providerId
Invalid UUID format
Category or provider does not exist
Mapping already exists

500 Internal Server Error

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

Delete Category-Provider Mapping

Removes the association between a category and a provider.

Endpoint: DELETE /category-providers/:id/category/:categoryId

Path Parameters

Parameter	Type	Required	Description
`id`	string (UUID)	Yes	Provider UUID
`categoryId`	string (UUID)	Yes	Category UUID

Response

Status: 200 OK

{
  "success": true,
  "message": "Category-provider relationship successfully deleted"
}

Example

curl -X DELETE "https://api.ledgerlink.ai/v1/category-providers/456e8400-e29b-41d4-a716-446655440000/category/789e4567-e89b-12d3-a456-426614174000"

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid UUID format",
  "error": "Bad Request"
}

Causes:

Invalid UUID format
Mapping does not exist

500 Internal Server Error

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

Querying Existing Mappings

Note: There are currently no dedicated GET endpoints to list mappings. To view existing mappings:

View Asset Mappings

Use the asset endpoints:

# Get specific asset with providers
GET /assets/:id

# List assets with providers
GET /assets

Response includes assetProviders array:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Bitcoin",
  "code": "BTC",
  "assetProviders": [
    {
      "providerId": "456e8400-e29b-41d4-a716-446655440000",
      "provider": {
        "id": "456e8400-e29b-41d4-a716-446655440000",
        "name": "CoinMarketCap",
        "slug": "coinmarketcap"
      }
    }
  ]
}

View Category Mappings

Use the category endpoints:

# Get specific category with providers
GET /categories/:id

# List categories with providers
GET /categories

Response includes categoryProviders array:

{
  "id": "789e4567-e89b-12d3-a456-426614174000",
  "name": "Cryptocurrency",
  "categoryProviders": [
    {
      "providerId": "456e8400-e29b-41d4-a716-446655440000",
      "provider": {
        "id": "456e8400-e29b-41d4-a716-446655440000",
        "name": "CoinMarketCap",
        "slug": "coinmarketcap"
      }
    }
  ]
}

Provider Selection Logic

When fetching a rate via POST /rates, the system determines which providers to query using the following priority:

1. Asset-Specific Providers (Highest Priority)

If the asset has direct provider mappings, use only those providers.

Asset: Bitcoin (BTC)
Asset Providers: [CoinMarketCap, Pyth]
→ Use CoinMarketCap and Pyth

2. Category-Level Providers

If no asset-specific providers, use category providers.

Asset: Ethereum (ETH)
Asset Providers: []
Category: Cryptocurrency
Category Providers: [CoinMarketCap]
→ Use CoinMarketCap

3. Default Providers (Fallback)

If no asset or category providers, use default providers (where isDefault = true).

Asset: New Token (NEW)
Asset Providers: []
Category Providers: []
Default Providers: [CoinMarketCap, Pyth]
→ Use CoinMarketCap and Pyth

4. Asset Not Found

If the asset doesn't exist in the database, use default providers.

Asset: Unknown (XYZ) - Not in database
→ Use default providers

Mapping Strategy Examples

Example 1: Major Cryptocurrency

# Bitcoin uses both CoinMarketCap and Pyth
POST /asset-providers
{
  "assetId": "btc-asset-id",
  "providerId": "coinmarketcap-provider-id"
}

POST /asset-providers
{
  "assetId": "btc-asset-id",
  "providerId": "pyth-provider-id"
}

# Result: POST /rates { "assetCode": "BTC" }
# → Queries both providers, returns average

Example 2: Category-Wide Mapping

# All stablecoins use CoinMarketCap
POST /category-providers
{
  "categoryId": "stablecoins-category-id",
  "providerId": "coinmarketcap-provider-id"
}

# Assets: USDC, USDT, DAI (all in Stablecoins category)
# → All use CoinMarketCap unless overridden at asset level

Example 3: Override Category Mapping

# Category: DeFi Tokens → Provider: CoinMarketCap
POST /category-providers
{
  "categoryId": "defi-category-id",
  "providerId": "coinmarketcap-provider-id"
}

# But UNI uses Pyth specifically
POST /asset-providers
{
  "assetId": "uni-asset-id",
  "providerId": "pyth-provider-id"
}

# Result:
# - POST /rates { "assetCode": "UNI" } → Uses Pyth only
# - POST /rates { "assetCode": "AAVE" } → Uses CoinMarketCap (category)

Best Practices

1. Use Category Mappings for Scalability

Map providers at the category level to automatically cover all assets in that category:

# Good: One mapping covers all cryptocurrencies
POST /category-providers { categoryId: "crypto", providerId: "cmc" }

2. Override for Special Cases

Use asset-specific mappings only when an asset requires different providers:

# Override for specific asset that needs Pyth
POST /asset-providers { assetId: "sol", providerId: "pyth" }

3. Configure Multiple Providers

Map multiple providers to get averaged rates and improve reliability:

POST /asset-providers { assetId: "btc", providerId: "cmc" }
POST /asset-providers { assetId: "btc", providerId: "pyth" }
# → Rate is average of both providers

4. Use Priority Configuration

Use the config field to set provider priority:

{
  "config": {
    "priority": 1,
    "weight": 0.6
  }
}

5. Set Default Providers

Ensure at least one provider is marked as default for fallback:

POST /providers {
  "name": "CoinMarketCap",
  "slug": "coinmarketcap",
  "isDefault": true
}

Troubleshooting

No Providers Available Error

Error: 503 Service Unavailable - No providers available to fetch rate

Causes:

Asset has no provider mappings
Category has no provider mappings
No default providers configured
All configured providers are failing

Solution:

Add provider mappings at asset or category level
Ensure at least one provider is marked as default
Check provider health and configuration

Rate Fetching Fails

Error: 503 Service Unavailable - All providers failed to fetch rate

Causes:

Provider API keys invalid or expired
Provider services down
Network connectivity issues
Asset not supported by providers

Solution:

Verify provider API keys in provider config
Check provider service status
Add alternative providers as backup
Verify asset codes match provider requirements

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

Endpoints​

Asset-Provider Mappings​

Category-Provider Mappings​

Asset-Provider Mappings​

Create Asset-Provider Mapping​

Request Body​

Response​

Examples​

Map CoinMarketCap to Bitcoin​

Map with Priority Configuration​

Error Responses​

400 Bad Request​

500 Internal Server Error​

Delete Asset-Provider Mapping​

Path Parameters​

Response​

Example​

Error Responses​

400 Bad Request​

500 Internal Server Error​

Category-Provider Mappings​

Create Category-Provider Mapping​

Request Body​

Response​

Examples​

Map CoinMarketCap to Cryptocurrency Category​

Map Multiple Providers to Category​

Error Responses​

400 Bad Request​

500 Internal Server Error​

Delete Category-Provider Mapping​

Path Parameters​

Response​

Example​

Error Responses​

400 Bad Request​

500 Internal Server Error​

Querying Existing Mappings​

View Asset Mappings​

View Category Mappings​

Provider Selection Logic​

1. Asset-Specific Providers (Highest Priority)​

2. Category-Level Providers​

3. Default Providers (Fallback)​

4. Asset Not Found​

Mapping Strategy Examples​

Example 1: Major Cryptocurrency​

Example 2: Category-Wide Mapping​

Example 3: Override Category Mapping​

Best Practices​

1. Use Category Mappings for Scalability​

2. Override for Special Cases​

3. Configure Multiple Providers​

4. Use Priority Configuration​

5. Set Default Providers​

Troubleshooting​

No Providers Available Error​

Rate Fetching Fails​

Endpoints

Asset-Provider Mappings

Category-Provider Mappings

Asset-Provider Mappings

Create Asset-Provider Mapping

Request Body

Response

Examples

Map CoinMarketCap to Bitcoin

Map with Priority Configuration

Error Responses

400 Bad Request

500 Internal Server Error

Delete Asset-Provider Mapping

Path Parameters

Response

Example

Error Responses

400 Bad Request

500 Internal Server Error

Category-Provider Mappings

Create Category-Provider Mapping

Request Body

Response

Examples

Map CoinMarketCap to Cryptocurrency Category

Map Multiple Providers to Category

Error Responses

400 Bad Request

500 Internal Server Error

Delete Category-Provider Mapping

Path Parameters

Response

Example

Error Responses

400 Bad Request

500 Internal Server Error

Querying Existing Mappings

View Asset Mappings

View Category Mappings

Provider Selection Logic

1. Asset-Specific Providers (Highest Priority)

2. Category-Level Providers

3. Default Providers (Fallback)

4. Asset Not Found

Mapping Strategy Examples

Example 1: Major Cryptocurrency

Example 2: Category-Wide Mapping

Example 3: Override Category Mapping

Best Practices

1. Use Category Mappings for Scalability

2. Override for Special Cases

3. Configure Multiple Providers

4. Use Priority Configuration

5. Set Default Providers

Troubleshooting

No Providers Available Error

Rate Fetching Fails