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 Asset codes 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	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	No	See Pagination Each response will only contain maximum 7 days of data. To get more data, the continuation_token should be used.
end_time	No	Last fixing of the calculation in ISO 8601 (exclusive).
exchanges	No	List of exchanges to source data from. See Exchange codes Default: All exchanges
interval	No	Frequency in time unit after the first fixing. Must be greater than twice the semi_length_window Default: 1d.
start_time	No	First fixing of the calculation in ISO 8601 (inclusive).
sources	No	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

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'

Python

##### 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)

Ruby

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
    }
  }
}