Rate Management API

This document describes the Rate Management endpoints for creating and retrieving digital asset rates.

Endpoints

Create Rate - POST /rates
List Rates - GET /rates

Create Rate

Creates a new rate for a digital asset by fetching current pricing from configured market data providers.

Endpoint: POST /rates

Request Headers

Header	Type	Required	Description
`x-request-id`	string	No	Request identifier for tracing (UUID format)
`Content-Type`	string	Yes	Must be `application/json`

Request Body

{
  "assetCode": "string"
}

Field	Type	Required	Description
`assetCode`	string	Yes	Asset code (e.g., "BTC", "ETH", "SOL")

Note: Currency is currently hardcoded to USD. Future versions may support additional currencies.

Response

Status: 201 Created

{
  "rate": 67543.50,
  "currency": "USD",
  "isStatic": false
}

Field	Type	Description
`rate`	number	Current rate value for the asset
`currency`	string	Currency in which the rate is denominated
`isStatic`	boolean	Whether the rate is static (true for stablecoins like USDC/USDT)

Examples

Basic Rate Request

curl -X POST "https://api.ledgerlink.ai/v1/rates" \
  -H "Content-Type: application/json" \
  -d '{
    "assetCode": "BTC"
  }'

Response:

{
  "rate": 67543.50,
  "currency": "USD",
  "isStatic": false
}

Rate with Request ID

curl -X POST "https://api.ledgerlink.ai/v1/rates" \
  -H "Content-Type: application/json" \
  -H "x-request-id: 123e4567-e89b-12d3-a456-426614174000" \
  -d '{
    "assetCode": "ETH"
  }'

Response:

{
  "rate": 3124.80,
  "currency": "USD",
  "isStatic": false
}

Stablecoin Rate

curl -X POST "https://api.ledgerlink.ai/v1/rates" \
  -H "Content-Type: application/json" \
  -d '{
    "assetCode": "USDC"
  }'

Response:

{
  "rate": 1.0,
  "currency": "USD",
  "isStatic": true
}

Error Responses

400 Bad Request - Invalid Input

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

Causes:

Missing assetCode field
Invalid data type for assetCode

503 Service Unavailable - Provider Unavailable

{
  "statusCode": 503,
  "message": "No providers available to fetch rate for BTC",
  "error": "Service Unavailable"
}

Causes:

All configured providers are down or unreachable
No providers configured for the requested asset
Provider API rate limits exceeded

500 Internal Server Error

{
  "statusCode": 500,
  "message": "Failed to create rate",
  "error": "Internal Server Error"
}

Causes:

Database connection failure
ActiveMQ publishing failure
Unexpected service error

Rate Calculation Process

Stablecoin Check: If asset is USDC or USDT, returns static rate of 1.0 USD
Static Value Check: If asset has a configured staticValue, returns that value
Asset Lookup: Searches for asset in database by code (case-insensitive)
Provider Selection:
- If asset found: Uses asset-specific providers or category providers
- If asset not found: Uses default providers (where isDefault = true)
Multi-Provider Fetch: Queries all selected providers in parallel
Average Calculation: Computes average from all successful provider responses
Data Persistence: Stores rate in database with timestamp and provider details
Event Publishing: Publishes VALUATION_PROCESSED event to ActiveMQ
Response: Returns aggregated rate to client

Provider Data

The rate response includes aggregated data from multiple providers. The actual provider-specific rates are stored in the database data field but not returned in the API response. Example stored data:

{
  "assetCode": "BTC",
  "providers": {
    "coinmarketcap": 67550.00,
    "pyth": 67537.00
  }
}

List Rates

Retrieves historical rates from the database with filtering, sorting, and pagination capabilities.

Endpoint: GET /rates

Query Parameters

Parameter	Type	Required	Description
`name`	string	No	Filter by asset name (case-insensitive, partial match)
`fromTime`	string	No	Start date/time (ISO 8601 format)
`toTime`	string	No	End date/time (ISO 8601 format)
`limit`	number	No	Maximum number of results (default: 10)
`offset`	number	No	Number of results to skip (default: 0)
`sortBy`	string	No	Field to sort by: `timestamp`, `rate` (default: `timestamp`)
`sortOrder`	string	No	Sort direction: `asc` or `desc` (default: `desc`)

Response

Status: 200 OK

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "assetId": "123e4567-e89b-12d3-a456-426614174000",
      "rate": 67543.50,
      "currency": "USD",
      "timestamp": "2025-11-20T17:00:00.000Z",
      "data": {
        "assetCode": "BTC",
        "providers": {
          "coinmarketcap": 67550.00,
          "pyth": 67537.00
        }
      },
      "asset": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Bitcoin",
        "code": "BTC",
        "categoryId": "789e4567-e89b-12d3-a456-426614174000"
      }
    }
  ],
  "pageInfo": {
    "limit": 10,
    "offset": 0,
    "total": 1547
  }
}

Response Fields

Data Array

Field	Type	Description
`id`	string	Unique rate record ID (UUID)
`assetId`	string	Associated asset ID
`rate`	number	Rate value
`currency`	string	Currency denomination
`timestamp`	string	When the rate was created (ISO 8601)
`data`	object	Provider-specific rate details
`asset`	object	Associated asset details

Page Info

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

Examples

Get Latest Rates for Bitcoin

curl -X GET "https://api.ledgerlink.ai/v1/rates?name=bitcoin&limit=10&sortBy=timestamp&sortOrder=desc"

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "assetId": "123e4567-e89b-12d3-a456-426614174000",
      "rate": 67543.50,
      "currency": "USD",
      "timestamp": "2025-11-20T17:00:00.000Z",
      "data": {
        "assetCode": "BTC",
        "providers": {
          "coinmarketcap": 67550.00,
          "pyth": 67537.00
        }
      },
      "asset": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Bitcoin",
        "code": "BTC",
        "categoryId": "789e4567-e89b-12d3-a456-426614174000"
      }
    }
  ],
  "pageInfo": {
    "limit": 10,
    "offset": 0,
    "total": 1547
  }
}

Get Rates Within Date Range

curl -X GET "https://api.ledgerlink.ai/v1/rates?name=ethereum&fromTime=2025-11-01T00:00:00Z&toTime=2025-11-20T23:59:59Z&limit=100&sortBy=timestamp&sortOrder=asc"

Get All Rates with Pagination

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

# Second page
curl -X GET "https://api.ledgerlink.ai/v1/rates?limit=20&offset=20"

Error Responses

400 Bad Request - Invalid Parameters

{
  "statusCode": 400,
  "message": "Invalid sortBy value. Allowed values: timestamp, rate",
  "error": "Bad Request"
}

Causes:

Invalid sortBy value
Invalid sortOrder value
Invalid date format for fromTime or toTime
Negative limit or offset

500 Internal Server Error

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

Causes:

Database connection failure
Query execution error

Use Cases

Real-time Pricing: Use POST /rates to get current market rates on-demand
Historical Analysis: Use GET /rates to retrieve stored rates for charting and analysis
Price Tracking: Query rates within date ranges to track price movements
Audit Trail: Review historical rates with provider details for compliance

Notes

POST creates new rates by fetching from providers (real-time)
GET retrieves historical rates stored in the database
Rates are automatically persisted when created via POST
Provider-specific rates are included in the data field
Asset relationships are automatically resolved and included
Use pagination for large result sets to avoid performance issues
Timestamps are in UTC (ISO 8601 format)

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

Endpoints​

Create Rate​

Request Headers​

Request Body​

Response​

Examples​

Basic Rate Request​

Rate with Request ID​

Stablecoin Rate​

Error Responses​

400 Bad Request - Invalid Input​

503 Service Unavailable - Provider Unavailable​

500 Internal Server Error​

Rate Calculation Process​

Provider Data​

List Rates​

Query Parameters​

Response​

Response Fields​

Data Array​

Page Info​

Examples​

Get Latest Rates for Bitcoin​

Get Rates Within Date Range​

Get All Rates with Pagination​

Error Responses​

400 Bad Request - Invalid Parameters​

500 Internal Server Error​

Use Cases​

Notes​

Endpoints

Create Rate

Request Headers

Request Body

Response

Examples

Basic Rate Request

Rate with Request ID

Stablecoin Rate

Error Responses

400 Bad Request - Invalid Input

503 Service Unavailable - Provider Unavailable

500 Internal Server Error

Rate Calculation Process

Provider Data

List Rates

Query Parameters

Response

Response Fields

Data Array

Page Info

Examples

Get Latest Rates for Bitcoin

Get Rates Within Date Range

Get All Rates with Pagination

Error Responses

400 Bad Request - Invalid Parameters

500 Internal Server Error

Use Cases

Notes