1 of 3

Kaiko Portfolio Risk & Performance

Analyze and report portfolio performance and measure potential investment losses.

Value at risk calculation

What is this endpoint for?

Thuis endpoints helps you calculate value at risk. Computed by a proprietary and thoroughly backtested methodology that accounts for the idiosyncrasies of crypto market structure. By convention it's a forecasting VaR, i.e. the prediction of the potential loss for the next day.

Endpoint

https://us.market-api.kaiko.io/v2/data/analytics.v2/value_at_risk

Parameters

Parameter

Required

Description

bases

Yes

Total must match quantities below. The order of bases and their respective quantities must match in the request.

quote

Yes

quantities

Yes

Quantities list of base asset in the portfolio. Must match the number of bases. The order of quantities and their respective bases must match in the request.

risk_level

Yes

The Value at Risk confidence level. Min: 0.90 (included) Max: 1 (excluded)

start_time

Yes

First fixing of the calculation in ISO 8601 (inclusive).

end_time

Yes

Last fixing of the calculation in ISO 8601 (inclusive).

sources

boolean. If true, returns all pair prices which were used to compute the Value at Risk. Default: false

Fields

Parameter

Description

var_time

The time at which the VaR is computed.

value_at_risk

Composed of two fields: value and risk_level (the Value at Risk estimator at the specified risk_level.)

additional_vars

List of additional VaRs for standard risk levels.

pair

The constituent pair. (showing only when sources is set to be true)

ref_price

The reference price per asset. (showing only when sources is set to be true)

date

The date of the reference price. (showing only when sources is set to be true)

Request examples

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
'https://us.market-api.kaiko.io/v2/data/analytics.v2/value_at_risk?bases=eth,btc,ltc&quantities=3,2,5&quote=usd&risk_level=0.95&start_time=2021-12-01T00:00:00.000Z&end_time=2022-01-31T00:00:00.000Z&sources=true'

##### 1. Import dependencies #####
import requests
import pandas as pd

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
bases = "btc,eth"
quote = "usd"
quantities = "1,10"
risk_level = "0.95"
start_time = "2021-12-01T00:00:00.000Z"
end_time = "2022-01-31T00:00:00.000Z"

# ---- Optional parameters ---- #
sources = None

# ---- API key configuration ---- #
api_key = "YOUR_API_KEY"

##### 3. Get the data #####
# ---- Function to run an API call ---- # 
# Get the data in a dataframe --------- # 

def get_kaiko_data(api_key: str, bases: str, quote: str, quantities: str, risk_level: str, start_time: str, end_time: str, sources: bool = None):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/analytics.v2/value_at_risk'
    params = {
        "bases": bases,
        "quote": quote,
        "quantities": quantities,
        "risk_level": risk_level,
        "start_time": start_time,
        "end_time": end_time,
        "sources": sources
    }

    try:
        res = requests.get(url, headers=headers, params=params)
        res.raise_for_status() 
        data = res.json()
        if 'data' not in data:
            print("No data returned.")
            return pd.DataFrame() 
        df = pd.DataFrame(data['data'])

        # Handle pagination with continuation token
        while 'next_url' in data:
            next_url = data['next_url']
            if next_url is None:
                break
            res = requests.get(next_url, headers=headers)
            res.raise_for_status()
            data = res.json()
            if 'data' in data:
                df = pd.concat([df, pd.DataFrame(data['data'])], ignore_index=True)
        return df

    except requests.exceptions.RequestException as e:
        print(f"API request error: {e}")
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_data(api_key=api_key, bases=bases, quote=quote, quantities=quantities, risk_level=risk_level, start_time=start_time, end_time=end_time, sources=sources)
print (df)

Response example

{"query": {
        "bases": "eth,btc,ltc",
        "quote": "usd",
        "quantities": "3,2,5",
        "risk_level": "0.95",
        "sources": true,
        "data_version": "v2",
        "commodity": "analytics",
        "request_time": "2024-12-02T14:57:10.523Z"
    },
    "time": "2024-12-02T14:57:11.037Z",
    "timestamp": 1733151431037,
    "data": [
        {
            "var_time": 1638316800000,
            "value_at_risk": {
                "value": 7348.431318368653,
                "risk_level": 0.95
            },
            "additional_vars": [
                {
                    "value": 6283.239075888689,
                    "risk_level": 0.9
                },
                {
                    "value": 7348.431318368653,
                    "risk_level": 0.95
                },
                {
                    "value": 10285.468412415725,
                    "risk_level": 0.975
                },
                {
                    "value": 10711.839781569755,
                    "risk_level": 0.99
                }
            ]
        },
        {
            "var_time": 1638403200000,
            "value_at_risk": {
                "value": 7300.740323399054,
                "risk_level": 0.95
            },
            "additional_vars": [
                {
                    "value": 6243.422441930624,
                    "risk_level": 0.9
                },
                /*...*/ 
            ]
        },,
    /*...*/ 
    ]
 "sources": {
        "prices": [
            {
                "pair": "eth-usd",
                "prices": [
                    {
                        "ref_price": 611.8140773650796,
                        "date": {
                            "seconds": 1606780800
                        }
                    },
                    /*...*/ 
                ]
            },
            {
                "pair": "btc-usd",
                "prices": [
                    {
                        "ref_price": 19588.910928118505,
                        "date": {
                            "seconds": 1606780800
                        }
                    },
                    /*...*/ 
                ]
            },
            /*...*/ 
        ]
    }
  "quantities": [3, 2, 5],
  "start_date": {"seconds": 1638403200},
  "end_date": {"seconds": 1643673600},
  "risk_level": 0.95,
  "additional_risk_levels": [0.9, 0.95, 0.975, 0.99],
  "decay": 30,
  "bases": ["eth", "btc", "ltc"]}

Custom valuation

This endpoint is in Alpha. Changes to the format or data constraints might change without prior notice.

What is this endpoint for?

The Custom Valuation endpoint allows you to build completely customizable single-asset or multi-asset price feeds for NAV calculations, portfolio valuation, asset allocation strategies, and indices.

Endpoint

https://us.market-api.kaiko.io/v2/data/trades.v1/valuation

Parameters

Parameter

Required

Description

bases

Yes

quote

Yes

The fiat pricing currency.

percentages

Yes

List of percentages for outlier management. Min: 1 Max: 5 To not enforce any outlier management, use 1

semi_length_window

Yes

The time interval to compute the transaction.

weights

Yes

Weighting list of base assets. The order and length of bases and their respective weights must match in the request. Weights must sum up to 1. For single-asset price feeds use an asset weighting of 1

continuation_token

end_time

Last fixing of the calculation in ISO 8601 (exclusive).

exchanges

interval

Frequency in time unit after the first fixing. Must be greater than twice the semi_length_window Default: 1d.

start_time

First fixing of the calculation in ISO 8601 (inclusive).

sources

boolean. If true, returns all prices and volumes which were used to calculate valuation price. Default: false

Fields

Field

Description

timestamp

Timestamp at which the interval begins.

percentage

Percent of the price distribution centered around the median price.

price

The composite price, with a base of 100.

pair

The constituent pair.

contribution

The asset contribution to the composite price.

ref_price

The reference price per asset.

weight

The weight per asset.

Request example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/trades.v1/valuation?start_time=2021-04-01T16:00:00.000Z&end_time=2021-04-15T16:00:00.000Z&interval=1d&semi_length_window=30m&exchanges=cbse,stmp,bfnx,gmni&bases=btc,ltc,pdot,eth,ada&weights=0.4,0.2,0.1,0.2,0.1&percentages=0.9&quote=usd&sources=true'

##### 1. Import dependencies #####
import requests
import pandas as pd

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
bases = "btc,eth"
quote = "usd"
percentages = "0.99"
semi_length_window = "30m"
weights = "0.7,0.3"

# ---- Optional parameters ---- #
continuation_token = None
start_time = "2021-04-01T16:00:00.000Z"
end_time = "2021-04-01T17:00:00.000Z"
exchanges = None
interval = "1h"
sources = None

# ---- API key configuration ---- #
api_key = "YOUR_API_KEY"

##### 3. Get the data #####
# ---- Function to run an API call ---- # 
# Get the data in a dataframe --------- # 

def get_kaiko_data(api_key: str, bases: str, quote: str, percentages: str, semi_length_window: str, weights: str, continuation_token: str = None, end_time: str = None, exchanges: str = None, interval: str = None, start_time: str = None, sources: bool = None):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/trades.v1/valuation'
    params = {
        "bases": bases,
        "quote": quote,
        "percentages": percentages,
        "semi_length_window": semi_length_window,
        "weights": weights,
        "continuation_token": continuation_token,
        "end_time": end_time,
        "exchanges": exchanges,
        "interval": interval,
        "start_time": start_time,
        "sources": sources
    }

    try:
        res = requests.get(url, headers=headers, params=params)
        res.raise_for_status() 
        data = res.json()
        if 'data' not in data:
            print("No data returned.")
            return pd.DataFrame() 
        df = pd.DataFrame(data['data'])

        # Handle pagination with continuation token
        while 'next_url' in data:
            next_url = data['next_url']
            if next_url is None:
                break
            res = requests.get(next_url, headers=headers)
            res.raise_for_status()
            data = res.json()
            if 'data' in data:
                df = pd.concat([df, pd.DataFrame(data['data'])], ignore_index=True)
        return df

    except requests.exceptions.RequestException as e:
        print(f"API request error: {e}")
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_data(api_key=api_key, bases=bases, quote=quote, percentages=percentages, semi_length_window=semi_length_window, weights=weights, continuation_token=continuation_token, end_time=end_time, exchanges=exchanges, interval=interval, start_time=start_time, sources=sources)
print (df)

message = "hello world"
puts message

Response example

{
  "query": {
    "start_time": "2021-04-01T16:00:00.000Z",
    "end_time": "2021-04-15T16:00:00.000Z",
    "page_size": 100,
    "interval": "1d",
    "semi_length_window": "30m",
    "exchanges": [
      "cbse",
      "stmp",
      "bfnx",
      "gmni"
    ],
    "sources": true,
    "bases": [
      "btc",
      "ltc",
      "pdot",
      "eth",
      "ada"
    ],
    "weights": [
      "0.4",
      "0.2",
      "0.1",
      "0.2",
      "0.1"
    ],
    "percentages": [
      "0.9"
    ],
    "quote": "usd",
    "reporting_currency": "usd",
    "data_version": "v1",
    "commodity": "trades",
    "request_time": "2024-07-11T08:57:23.063Z",
    "start_timestamp": 1617292800000,
    "end_timestamp": 1618502400000
  },
  "time": "2024-07-11T08:57:23.196Z",
  "timestamp": 1720688243196,
  "data": [
    {
      "datetime": "2021-04-01 16:00:00 UTC",
      "timestamp": 1617292800000,
      "response_by_percentages": [
        {
          "percentage": 0.9,
          "price": "90.0",
          "response_by_pairs": [
            {
              "pair": "ada-usd",
              "contribution": "10.0",
              "ref_price": "1.1952953546487899",
              "weight": 0.1,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "1.1922063859615473",
                  "volume": "49092.65228160001"
                },
                {
                  "exchange": "cbse",
                  "price": "1.1953795367859443",
                  "volume": "1801399.5699999994"
                },
                {
                  "exchange": "stmp",
                  "price": "0.0",
                  "volume": "0.0"
                }
              ]
            },
            {
              "pair": "btc-usd",
              "contribution": "40.0",
              "ref_price": "58975.26519568534",
              "weight": 0.4,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "58966.37653591877",
                  "volume": "108.71255996999984"
                },
                {
                  "exchange": "stmp",
                  "price": "58976.48063086188",
                  "volume": "123.44333201"
                },
                {
                  "exchange": "cbse",
                  "price": "58976.49990471515",
                  "volume": "643.5522803799886"
                },
                {
                  "exchange": "gmni",
                  "price": "58975.66262303746",
                  "volume": "54.53016263210016"
                }
              ]
            },
            {
              "pair": "eth-usd",
              "contribution": "20.0",
              "ref_price": "1944.7174052029602",
              "weight": 0.2,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "1945.7164477717267",
                  "volume": "1721.0945157499918"
                },
                {
                  "exchange": "stmp",
                  "price": "1943.0465962793976",
                  "volume": "1569.1804287999996"
                },
                {
                  "exchange": "cbse",
                  "price": "1944.7179352862468",
                  "volume": "7742.478813930065"
                },
                {
                  "exchange": "gmni",
                  "price": "1946.2500402590074",
                  "volume": "586.0819996599986"
                }
              ]
            },
            {
              "pair": "ltc-usd",
              "contribution": "20.0",
              "ref_price": "203.41030791068565",
              "weight": 0.2,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "203.84776792550193",
                  "volume": "3868.5610560399973"
                },
                {
                  "exchange": "stmp",
                  "price": "203.42655125349268",
                  "volume": "4009.0371638699994"
                },
                {
                  "exchange": "cbse",
                  "price": "203.3196206193",
                  "volume": "17346.437634749967"
                },
                {
                  "exchange": "gmni",
                  "price": "203.26188467749023",
                  "volume": "1242.1202100000007"
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "datetime": "2021-04-02 16:00:00 UTC",
      "timestamp": 1617379200000,
      "response_by_percentages": [
        {
          "percentage": 0.9,
          "price": "92.13188514508228",
          "response_by_pairs": [
            {
              "pair": "ada-usd",
              "contribution": "10.157886022869157",
              "ref_price": "1.2141673976187375",
              "weight": 0.1,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "1.2128093063448417",
                  "volume": "107143.38469117999"
                },
                {
                  "exchange": "cbse",
                  "price": "1.2142086749468801",
                  "volume": "3525191.7300000032"
                },
                {
                  "exchange": "stmp",
                  "price": "0.0",
                  "volume": "0.0"
                }
              ]
            },
            {
              "pair": "btc-usd",
              "contribution": "40.30999169598328",
              "ref_price": "59432.31125766219",
              "weight": 0.4,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "59427.12972653533",
                  "volume": "193.30433213000433"
                },
                {
                  "exchange": "stmp",
                  "price": "59425.8954255416",
                  "volume": "49.357525309999936"
                },
                {
                  "exchange": "cbse",
                  "price": "59435.46776704534",
                  "volume": "275.4378068199984"
                },
                {
                  "exchange": "gmni",
                  "price": "59453.40333572798",
                  "volume": "21.280975116099974"
                }
              ]
            },
            {
              "pair": "eth-usd",
              "contribution": "21.25300137809248",
              "ref_price": "2066.5540846389476",
              "weight": 0.2,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "2067.3615848735412",
                  "volume": "5101.355564200053"
                },
                {
                  "exchange": "stmp",
                  "price": "2065.2429517064065",
                  "volume": "2345.690675829999"
                },
                {
                  "exchange": "cbse",
                  "price": "2066.4390961104596",
                  "volume": "13570.961299999917"
                },
                {
                  "exchange": "gmni",
                  "price": "2066.992539862674",
                  "volume": "1178.3902252700013"
                }
              ]
            },
            {
              "pair": "ltc-usd",
              "contribution": "20.41100604813737",
              "ref_price": "207.59045125092447",
              "weight": 0.2,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "208.16900230011748",
                  "volume": "2373.9750840599995"
                },
                {
                  "exchange": "stmp",
                  "price": "207.94761364569408",
                  "volume": "2709.4314194299986"
                },
                {
                  "exchange": "cbse",
                  "price": "207.49248995319408",
                  "volume": "30287.91699937994"
                },
                {
                  "exchange": "gmni",
                  "price": "208.16066650838093",
                  "volume": "1097.6045568000002"
                }
              ]
            }
          ]
        }
      ]
    },
		/*...*/
	],
  "result": "success",
  "continuation_token": "312usdfiuwJx9B8tjXrkviUbsvNHKm9fsJmDabmQYrA4rn8eg3DP3S5P1XaRLt8gk4wy3vLWiV9KDDdt9vgjkkH4FY2KTYZqfgwZBrj2Ss2Qtzm6bxSnj6RFxs6NLDdXxShES2bsTuyLgU2ETkJgKPWLGQjCNNv3iuU22kCHSo7s7uN6XY1hLozkST5BX3gR4wywE2TVqQ6erNubvr9sLnvKSHbnqdxdcbyXVT71J5piyGym8aXpkFpqoPsVaF36p7Wg1bN9yZgFALQbP7m21egNHy1Fdz5wiP5UXCUTG9Q1xTqR9QhHu3ouBYsRZ7n9EnD91NGYZxRpQ3wLqncwUFUDHwAPV4Zo8vK29RthQEscBB8qZgiKGEhSNGtbXE7xxHdMQHDG2FvxQrLBdqKf8JizRgYpVr6Qrz9p82Z8qZtK97Gpm8uhfk5RrxHgE59MhgHTMxfDviY7j8dNByrQPB9uQ3HmXZUxcC2KJ4aNJGQSXk3ciH9NH2MaVMVauHGRXeFMc74LczksqwiB9xvtZwMZ777yvRrfdp2H6NFDnUnVBjdGfC5XURf2k8jDX4Ax2",
  "next_url": "https://us.market-api.kaiko.io/v2/data/trades.v1/valuation?continuation_token=312usdfiuwJx9B8tjXrkviUbsvNHKm9fsJmDabmQYrA4rn8eg3DP3S5P1XaRLt8gk4wy3vLWiV9KDDdt9vgjkkH4FY2KTYZqfgwZBrj2Ss2Qtzm6bxSnj6RFxs6NLDdXxShES2bsTuyLgU2ETkJgKPWLGQjCNNv3iuU22kCHSo7s7uN6XY1hLozkST5BX3gR4wywE2TVqQ6erNubvr9sLnvKSHbnqdxdcbyXVT71J5piyGym8aXpkFpqoPsVaF36p7Wg1bN9yZgFALQbP7m21egNHy1Fdz5wiP5UXCUTG9Q1xTqR9QhHu3ouBYsRZ7n9EnD91NGYZxRpQ3wLqncwUFUDHwAPV4Zo8vK29RthQEscBB8qZgiKGEhSNGtbXE7xxHdMQHDG2FvxQrLBdqKf8JizRgYpVr6Qrz9p82Z8qZtK97Gpm8uhfk5RrxHgE59MhgHTMxfDviY7j8dNByrQPB9uQ3HmXZUxcC2KJ4aNJGQSXk3ciH9NH2MaVMVauHGRXeFMc74LczksqwiB9xvtZwMZ777yvRrfdp2H6NFDnUnVBjdGfC5XURf2k8jDX4Ax2",
  "access": {
    "access_range": {
      "start_timestamp": 1262995200000,
      "end_timestamp": 2186006399000
    },
    "data_range": {
      "start_timestamp": null,
      "end_timestamp": null
    }
  }
}

Value at risk calculation

What is this endpoint for?

Endpoint

https://us.market-api.kaiko.io/v2/data/analytics.v2/value_at_risk

Parameters

Parameter

Required

Description

bases

Yes

List of portfolio base components. See

Total must match quantities below. The order of bases and their respective quantities must match in the request.

quote

Yes

The fiat currency.

quantities

Yes

Quantities list of base asset in the portfolio. Must match the number of bases. The order of quantities and their respective bases must match in the request.

risk_level

Yes

The Value at Risk confidence level. Min: 0.90 (included) Max: 1 (excluded)

start_time

Yes

First fixing of the calculation in ISO 8601 (inclusive).

end_time

Yes

Last fixing of the calculation in ISO 8601 (inclusive).

sources

boolean. If true, returns all pair prices which were used to compute the Value at Risk. Default: false

Fields

Parameter

Description

var_time

The time at which the VaR is computed.

value_at_risk

Composed of two fields: value and risk_level (the Value at Risk estimator at the specified risk_level.)

additional_vars

List of additional VaRs for standard risk levels.

pair

The constituent pair. (showing only when sources is set to be true)

ref_price

The reference price per asset. (showing only when sources is set to be true)

date

The date of the reference price. (showing only when sources is set to be true)

Request examples

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
'https://us.market-api.kaiko.io/v2/data/analytics.v2/value_at_risk?bases=eth,btc,ltc&quantities=3,2,5&quote=usd&risk_level=0.95&start_time=2021-12-01T00:00:00.000Z&end_time=2022-01-31T00:00:00.000Z&sources=true'

##### 1. Import dependencies #####
import requests
import pandas as pd

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
bases = "btc,eth"
quote = "usd"
quantities = "1,10"
risk_level = "0.95"
start_time = "2021-12-01T00:00:00.000Z"
end_time = "2022-01-31T00:00:00.000Z"

# ---- Optional parameters ---- #
sources = None

# ---- API key configuration ---- #
api_key = "YOUR_API_KEY"

##### 3. Get the data #####
# ---- Function to run an API call ---- # 
# Get the data in a dataframe --------- # 

def get_kaiko_data(api_key: str, bases: str, quote: str, quantities: str, risk_level: str, start_time: str, end_time: str, sources: bool = None):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/analytics.v2/value_at_risk'
    params = {
        "bases": bases,
        "quote": quote,
        "quantities": quantities,
        "risk_level": risk_level,
        "start_time": start_time,
        "end_time": end_time,
        "sources": sources
    }

    try:
        res = requests.get(url, headers=headers, params=params)
        res.raise_for_status() 
        data = res.json()
        if 'data' not in data:
            print("No data returned.")
            return pd.DataFrame() 
        df = pd.DataFrame(data['data'])

        # Handle pagination with continuation token
        while 'next_url' in data:
            next_url = data['next_url']
            if next_url is None:
                break
            res = requests.get(next_url, headers=headers)
            res.raise_for_status()
            data = res.json()
            if 'data' in data:
                df = pd.concat([df, pd.DataFrame(data['data'])], ignore_index=True)
        return df

    except requests.exceptions.RequestException as e:
        print(f"API request error: {e}")
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_data(api_key=api_key, bases=bases, quote=quote, quantities=quantities, risk_level=risk_level, start_time=start_time, end_time=end_time, sources=sources)
print (df)

Response example

{"query": {
        "bases": "eth,btc,ltc",
        "quote": "usd",
        "quantities": "3,2,5",
        "risk_level": "0.95",
        "sources": true,
        "data_version": "v2",
        "commodity": "analytics",
        "request_time": "2024-12-02T14:57:10.523Z"
    },
    "time": "2024-12-02T14:57:11.037Z",
    "timestamp": 1733151431037,
    "data": [
        {
            "var_time": 1638316800000,
            "value_at_risk": {
                "value": 7348.431318368653,
                "risk_level": 0.95
            },
            "additional_vars": [
                {
                    "value": 6283.239075888689,
                    "risk_level": 0.9
                },
                {
                    "value": 7348.431318368653,
                    "risk_level": 0.95
                },
                {
                    "value": 10285.468412415725,
                    "risk_level": 0.975
                },
                {
                    "value": 10711.839781569755,
                    "risk_level": 0.99
                }
            ]
        },
        {
            "var_time": 1638403200000,
            "value_at_risk": {
                "value": 7300.740323399054,
                "risk_level": 0.95
            },
            "additional_vars": [
                {
                    "value": 6243.422441930624,
                    "risk_level": 0.9
                },
                /*...*/ 
            ]
        },,
    /*...*/ 
    ]
 "sources": {
        "prices": [
            {
                "pair": "eth-usd",
                "prices": [
                    {
                        "ref_price": 611.8140773650796,
                        "date": {
                            "seconds": 1606780800
                        }
                    },
                    /*...*/ 
                ]
            },
            {
                "pair": "btc-usd",
                "prices": [
                    {
                        "ref_price": 19588.910928118505,
                        "date": {
                            "seconds": 1606780800
                        }
                    },
                    /*...*/ 
                ]
            },
            /*...*/ 
        ]
    }
  "quantities": [3, 2, 5],
  "start_date": {"seconds": 1638403200},
  "end_date": {"seconds": 1643673600},
  "risk_level": 0.95,
  "additional_risk_levels": [0.9, 0.95, 0.975, 0.99],
  "decay": 30,
  "bases": ["eth", "btc", "ltc"]}

Custom valuation

This endpoint is in Alpha. Changes to the format or data constraints might change without prior notice.

What is this endpoint for?

The Custom Valuation endpoint allows you to build completely customizable single-asset or multi-asset price feeds for NAV calculations, portfolio valuation, asset allocation strategies, and indices.

Endpoint

https://us.market-api.kaiko.io/v2/data/trades.v1/valuation

Parameters

Parameter

Required

Description

bases

Yes

List of portfolio base components. Min: 1 Max: 5 See The order and length of bases and their respective weights must match in the request.

quote

Yes

The fiat pricing currency.

percentages

Yes

List of percentages for outlier management. Min: 1 Max: 5 To not enforce any outlier management, use 1

semi_length_window

Yes

The time interval to compute the transaction.

weights

Yes

continuation_token

See Each response will only contain maximum 7 days of data. To get more data, the continuation_token should be used.

end_time

Last fixing of the calculation in ISO 8601 (exclusive).

exchanges

List of exchanges to source data from. See Default: All exchanges

interval

Frequency in time unit after the first fixing. Must be greater than twice the semi_length_window Default: 1d.

start_time

First fixing of the calculation in ISO 8601 (inclusive).

sources

boolean. If true, returns all prices and volumes which were used to calculate valuation price. Default: false

Fields

Field

Description

timestamp

Timestamp at which the interval begins.

percentage

Percent of the price distribution centered around the median price.

price

The composite price, with a base of 100.

pair

The constituent pair.

contribution

The asset contribution to the composite price.

ref_price

The reference price per asset.

weight

The weight per asset.

Request example

curl --compressed -H 'Accept: application/json' -H 'X-Api-Key: <client-api-key>' \
  'https://us.market-api.kaiko.io/v2/data/trades.v1/valuation?start_time=2021-04-01T16:00:00.000Z&end_time=2021-04-15T16:00:00.000Z&interval=1d&semi_length_window=30m&exchanges=cbse,stmp,bfnx,gmni&bases=btc,ltc,pdot,eth,ada&weights=0.4,0.2,0.1,0.2,0.1&percentages=0.9&quote=usd&sources=true'

##### 1. Import dependencies #####
import requests
import pandas as pd

##### 2. Choose the value of the query's parameters #####
# ---- Required parameters ---- #
bases = "btc,eth"
quote = "usd"
percentages = "0.99"
semi_length_window = "30m"
weights = "0.7,0.3"

# ---- Optional parameters ---- #
continuation_token = None
start_time = "2021-04-01T16:00:00.000Z"
end_time = "2021-04-01T17:00:00.000Z"
exchanges = None
interval = "1h"
sources = None

# ---- API key configuration ---- #
api_key = "YOUR_API_KEY"

##### 3. Get the data #####
# ---- Function to run an API call ---- # 
# Get the data in a dataframe --------- # 

def get_kaiko_data(api_key: str, bases: str, quote: str, percentages: str, semi_length_window: str, weights: str, continuation_token: str = None, end_time: str = None, exchanges: str = None, interval: str = None, start_time: str = None, sources: bool = None):
    headers = {'Accept': 'application/json', 'X-Api-Key': api_key}
    
    url = f'https://us.market-api.kaiko.io/v2/data/trades.v1/valuation'
    params = {
        "bases": bases,
        "quote": quote,
        "percentages": percentages,
        "semi_length_window": semi_length_window,
        "weights": weights,
        "continuation_token": continuation_token,
        "end_time": end_time,
        "exchanges": exchanges,
        "interval": interval,
        "start_time": start_time,
        "sources": sources
    }

    try:
        res = requests.get(url, headers=headers, params=params)
        res.raise_for_status() 
        data = res.json()
        if 'data' not in data:
            print("No data returned.")
            return pd.DataFrame() 
        df = pd.DataFrame(data['data'])

        # Handle pagination with continuation token
        while 'next_url' in data:
            next_url = data['next_url']
            if next_url is None:
                break
            res = requests.get(next_url, headers=headers)
            res.raise_for_status()
            data = res.json()
            if 'data' in data:
                df = pd.concat([df, pd.DataFrame(data['data'])], ignore_index=True)
        return df

    except requests.exceptions.RequestException as e:
        print(f"API request error: {e}")
        return pd.DataFrame() 

# ---- Get the data ---- #
df = get_kaiko_data(api_key=api_key, bases=bases, quote=quote, percentages=percentages, semi_length_window=semi_length_window, weights=weights, continuation_token=continuation_token, end_time=end_time, exchanges=exchanges, interval=interval, start_time=start_time, sources=sources)
print (df)

message = "hello world"
puts message

Response example

{
  "query": {
    "start_time": "2021-04-01T16:00:00.000Z",
    "end_time": "2021-04-15T16:00:00.000Z",
    "page_size": 100,
    "interval": "1d",
    "semi_length_window": "30m",
    "exchanges": [
      "cbse",
      "stmp",
      "bfnx",
      "gmni"
    ],
    "sources": true,
    "bases": [
      "btc",
      "ltc",
      "pdot",
      "eth",
      "ada"
    ],
    "weights": [
      "0.4",
      "0.2",
      "0.1",
      "0.2",
      "0.1"
    ],
    "percentages": [
      "0.9"
    ],
    "quote": "usd",
    "reporting_currency": "usd",
    "data_version": "v1",
    "commodity": "trades",
    "request_time": "2024-07-11T08:57:23.063Z",
    "start_timestamp": 1617292800000,
    "end_timestamp": 1618502400000
  },
  "time": "2024-07-11T08:57:23.196Z",
  "timestamp": 1720688243196,
  "data": [
    {
      "datetime": "2021-04-01 16:00:00 UTC",
      "timestamp": 1617292800000,
      "response_by_percentages": [
        {
          "percentage": 0.9,
          "price": "90.0",
          "response_by_pairs": [
            {
              "pair": "ada-usd",
              "contribution": "10.0",
              "ref_price": "1.1952953546487899",
              "weight": 0.1,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "1.1922063859615473",
                  "volume": "49092.65228160001"
                },
                {
                  "exchange": "cbse",
                  "price": "1.1953795367859443",
                  "volume": "1801399.5699999994"
                },
                {
                  "exchange": "stmp",
                  "price": "0.0",
                  "volume": "0.0"
                }
              ]
            },
            {
              "pair": "btc-usd",
              "contribution": "40.0",
              "ref_price": "58975.26519568534",
              "weight": 0.4,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "58966.37653591877",
                  "volume": "108.71255996999984"
                },
                {
                  "exchange": "stmp",
                  "price": "58976.48063086188",
                  "volume": "123.44333201"
                },
                {
                  "exchange": "cbse",
                  "price": "58976.49990471515",
                  "volume": "643.5522803799886"
                },
                {
                  "exchange": "gmni",
                  "price": "58975.66262303746",
                  "volume": "54.53016263210016"
                }
              ]
            },
            {
              "pair": "eth-usd",
              "contribution": "20.0",
              "ref_price": "1944.7174052029602",
              "weight": 0.2,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "1945.7164477717267",
                  "volume": "1721.0945157499918"
                },
                {
                  "exchange": "stmp",
                  "price": "1943.0465962793976",
                  "volume": "1569.1804287999996"
                },
                {
                  "exchange": "cbse",
                  "price": "1944.7179352862468",
                  "volume": "7742.478813930065"
                },
                {
                  "exchange": "gmni",
                  "price": "1946.2500402590074",
                  "volume": "586.0819996599986"
                }
              ]
            },
            {
              "pair": "ltc-usd",
              "contribution": "20.0",
              "ref_price": "203.41030791068565",
              "weight": 0.2,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "203.84776792550193",
                  "volume": "3868.5610560399973"
                },
                {
                  "exchange": "stmp",
                  "price": "203.42655125349268",
                  "volume": "4009.0371638699994"
                },
                {
                  "exchange": "cbse",
                  "price": "203.3196206193",
                  "volume": "17346.437634749967"
                },
                {
                  "exchange": "gmni",
                  "price": "203.26188467749023",
                  "volume": "1242.1202100000007"
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "datetime": "2021-04-02 16:00:00 UTC",
      "timestamp": 1617379200000,
      "response_by_percentages": [
        {
          "percentage": 0.9,
          "price": "92.13188514508228",
          "response_by_pairs": [
            {
              "pair": "ada-usd",
              "contribution": "10.157886022869157",
              "ref_price": "1.2141673976187375",
              "weight": 0.1,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "1.2128093063448417",
                  "volume": "107143.38469117999"
                },
                {
                  "exchange": "cbse",
                  "price": "1.2142086749468801",
                  "volume": "3525191.7300000032"
                },
                {
                  "exchange": "stmp",
                  "price": "0.0",
                  "volume": "0.0"
                }
              ]
            },
            {
              "pair": "btc-usd",
              "contribution": "40.30999169598328",
              "ref_price": "59432.31125766219",
              "weight": 0.4,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "59427.12972653533",
                  "volume": "193.30433213000433"
                },
                {
                  "exchange": "stmp",
                  "price": "59425.8954255416",
                  "volume": "49.357525309999936"
                },
                {
                  "exchange": "cbse",
                  "price": "59435.46776704534",
                  "volume": "275.4378068199984"
                },
                {
                  "exchange": "gmni",
                  "price": "59453.40333572798",
                  "volume": "21.280975116099974"
                }
              ]
            },
            {
              "pair": "eth-usd",
              "contribution": "21.25300137809248",
              "ref_price": "2066.5540846389476",
              "weight": 0.2,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "2067.3615848735412",
                  "volume": "5101.355564200053"
                },
                {
                  "exchange": "stmp",
                  "price": "2065.2429517064065",
                  "volume": "2345.690675829999"
                },
                {
                  "exchange": "cbse",
                  "price": "2066.4390961104596",
                  "volume": "13570.961299999917"
                },
                {
                  "exchange": "gmni",
                  "price": "2066.992539862674",
                  "volume": "1178.3902252700013"
                }
              ]
            },
            {
              "pair": "ltc-usd",
              "contribution": "20.41100604813737",
              "ref_price": "207.59045125092447",
              "weight": 0.2,
              "response_by_instruments": [
                {
                  "exchange": "bfnx",
                  "price": "208.16900230011748",
                  "volume": "2373.9750840599995"
                },
                {
                  "exchange": "stmp",
                  "price": "207.94761364569408",
                  "volume": "2709.4314194299986"
                },
                {
                  "exchange": "cbse",
                  "price": "207.49248995319408",
                  "volume": "30287.91699937994"
                },
                {
                  "exchange": "gmni",
                  "price": "208.16066650838093",
                  "volume": "1097.6045568000002"
                }
              ]
            }
          ]
        }
      ]
    },
		/*...*/
	],
  "result": "success",
  "continuation_token": "312usdfiuwJx9B8tjXrkviUbsvNHKm9fsJmDabmQYrA4rn8eg3DP3S5P1XaRLt8gk4wy3vLWiV9KDDdt9vgjkkH4FY2KTYZqfgwZBrj2Ss2Qtzm6bxSnj6RFxs6NLDdXxShES2bsTuyLgU2ETkJgKPWLGQjCNNv3iuU22kCHSo7s7uN6XY1hLozkST5BX3gR4wywE2TVqQ6erNubvr9sLnvKSHbnqdxdcbyXVT71J5piyGym8aXpkFpqoPsVaF36p7Wg1bN9yZgFALQbP7m21egNHy1Fdz5wiP5UXCUTG9Q1xTqR9QhHu3ouBYsRZ7n9EnD91NGYZxRpQ3wLqncwUFUDHwAPV4Zo8vK29RthQEscBB8qZgiKGEhSNGtbXE7xxHdMQHDG2FvxQrLBdqKf8JizRgYpVr6Qrz9p82Z8qZtK97Gpm8uhfk5RrxHgE59MhgHTMxfDviY7j8dNByrQPB9uQ3HmXZUxcC2KJ4aNJGQSXk3ciH9NH2MaVMVauHGRXeFMc74LczksqwiB9xvtZwMZ777yvRrfdp2H6NFDnUnVBjdGfC5XURf2k8jDX4Ax2",
  "next_url": "https://us.market-api.kaiko.io/v2/data/trades.v1/valuation?continuation_token=312usdfiuwJx9B8tjXrkviUbsvNHKm9fsJmDabmQYrA4rn8eg3DP3S5P1XaRLt8gk4wy3vLWiV9KDDdt9vgjkkH4FY2KTYZqfgwZBrj2Ss2Qtzm6bxSnj6RFxs6NLDdXxShES2bsTuyLgU2ETkJgKPWLGQjCNNv3iuU22kCHSo7s7uN6XY1hLozkST5BX3gR4wywE2TVqQ6erNubvr9sLnvKSHbnqdxdcbyXVT71J5piyGym8aXpkFpqoPsVaF36p7Wg1bN9yZgFALQbP7m21egNHy1Fdz5wiP5UXCUTG9Q1xTqR9QhHu3ouBYsRZ7n9EnD91NGYZxRpQ3wLqncwUFUDHwAPV4Zo8vK29RthQEscBB8qZgiKGEhSNGtbXE7xxHdMQHDG2FvxQrLBdqKf8JizRgYpVr6Qrz9p82Z8qZtK97Gpm8uhfk5RrxHgE59MhgHTMxfDviY7j8dNByrQPB9uQ3HmXZUxcC2KJ4aNJGQSXk3ciH9NH2MaVMVauHGRXeFMc74LczksqwiB9xvtZwMZ777yvRrfdp2H6NFDnUnVBjdGfC5XURf2k8jDX4Ax2",
  "access": {
    "access_range": {
      "start_timestamp": 1262995200000,
      "end_timestamp": 2186006399000
    },
    "data_range": {
      "start_timestamp": null,
      "end_timestamp": null
    }
  }
}