API Reference
Start typing to search…

Portfolio Timeseries

Access historical timeseries data using the Pulsar SDK.

Usage Costs:

Wallet timeseries request cost 1 credit per wallet.

Overview

This page provides detailed instructions on using the Pulsar SDK to access historical wallet values over time. The Timeseries feature allows developers to retrieve and analyze wallet performance across various time periods, such as 1 day, 1 week, and 1 month.

Wallet Timeseries

To retrieve historical timeseries data for a wallet, use the get_wallet_timeseries method provided by the Pulsar SDK. This method returns a Timeseries object containing both the wallet's value over time and various wallet events within the specified period.

import PulsarSDK, { ChainKeys, TierKeys } from "pulsar_sdk_js";

const chain = ChainKeys.ETHEREUM;
const responses_list = [];
const wallet_addr = "YOUR WALLET ADDR";
const API_KEY = "YOUR API KEY";
const tier = TierKeys.ONE_MONTH;
const sdk = new PulsarSDK(API_KEY);

async function getWalletTimeseries() {
  const timeseries = sdk.balances.getWalletTimeseries(wallet_addr, chain, tier);
  for await (const data of timeseries) {
    responses_list.push(data);
  }
}

getWalletTimeseries().then(() => {
  console.log(responses_list);
});

import asyncio
from pulsar_sdk_py import PulsarSDK
from pulsar_sdk_py.enums import ChainKeys, TierKeys

sdk = PulsarSDK(API_KEY)
responses_list = []

async def main():
    async for timeseries in sdk.balances.get_wallet_timeseries(
        wallet_addr="YOUR WALLET_ADDR", chain=ChainKeys.AVALANCHE, tier=TierKeys.ONE_MONTH
    ):
        responses_list.append(timeseries)

if __name__ == "__main__":
    asyncio.run(main())

Using the Pulsar SDK for Wallet Timeseries

When querying for the historical value of an address, your response will have this type:

export enum TimeseriesEventKey {
  NEW_TOKEN = 'NEW_TOKEN',
  NEW_INTEGRATION = 'NEW_INTEGRATION',
  PRICE_NOT_FOUND = 'PRICE_NOT_FOUND',
  WALLET_CREATED = 'WALLET_CREATED_EVENT',
  NEW_TOKEN_BALANCE_CHANGE = 'NEW_TOKEN_BALANCE_CHANGE',
  NEW_INTEGRATION_BALANCE_CHANGE = 'NEW_INTEGRATION_BALANCE_CHANGE',
}

export class Timeseries {
  wallet: BaseWallet;
  tier: TierKeys;
  events: Record<number, TimeseriesEvent[]>;
  timeseries?: Record<number, number>;
}

export class TimeseriesEvent {
  event_key: TimeseriesEventKey;
  event_data: Record<any, any>;
}

class TimeseriesEventKey(Enum):
    NEW_TOKEN = "NEW_TOKEN"
    NEW_INTEGRATION = "NEW_INTEGRATION"
    PRICE_NOT_FOUND = "PRICE_NOT_FOUND"
    WALLET_CREATED = "WALLET_CREATED_EVENT"
    NEW_TOKEN_BALANCE_CHANGE = "NEW_TOKEN_BALANCE_CHANGE"
    NEW_INTEGRATION_BALANCE_CHANGE = "NEW_INTEGRATION_BALANCE_CHANGE"

@dataclass
class Timeseries:
    wallet: BaseWallet
    tier: TierKeys
    timeseries: dict[str, float | None]
    events: dict[str, list[TimeseriesEvent]]
    last_balances: list[dict]

@dataclass
class TimeseriesEvent:
    event_key: TimeseriesEventKey
    event_data: dict

Input Typing

TierKeys Enumeration

enum TierKeys {
    ONE_DAY = '1d',
    ONE_WEEK = '7d',
    ONE_MONTH = '30d',
    ONE_YEAR = '365d',
}

Request Structure

The get_wallet_timeseries method expects a JSON object with the following structure:

{
  "method": "COMMAND",
  "command": {
    "key": "GET_WALLET_TIMESERIES",
    "data": {
      "address": "string",             // Wallet address (e.g., "0x2b78d022af87d411ba84474ffbc7eef8b4addb45")
      "chain": "string",               // Chain identifier (e.g., "ETHEREUM")
      "tier": "string",                // TierKeys enumeration (e.g., "1d")
      "hide_tokens": ["string"],       // List of token IDs to exclude
      "hide_integrations": ["string"], // List of integration IDs to exclude
      "hide_nfts": ["string"]          // List of NFT IDs to exclude
    }
  },
  "request_id": "string"                // Unique request identifier
}

Example Request

{
  "method": "COMMAND",
  "command": {
    "key": "GET_WALLET_TIMESERIES",
    "data": {
      "address": "0x2b78d022af87d411ba84474ffbc7eef8b4addb45",
      "chain": "ETHEREUM",
      "tier": "1d",
      "hide_tokens": [],
      "hide_integrations": [],
      "hide_nfts": []
    }
  },
  "request_id": "a9d4b2a1-1f10-4a88-9112-338a35029013"
}

Response Example

The get_wallet_timeseries method returns a JSON object containing the wallet's historical values and related events. Below is an example of a typical response:

{
  "data": [
    {
      "wallet": { // Wallet address and associated chain
        "address": "0x2b78d022af87d411ba84474ffbc7eef8b4addb45",
        "chain": "ARBITRUM"
      },
      "tier": "1d",
      "timeseries": { // Wallet USD value over time
        "1705363200": 227.97114996695302,
        // ...
        "1736812800": 254.72555816288587
      },
      "events": { // Wallet events categorized by timestamp
        "1736353200": [
          {
            "event_key": "NEW_INTEGRATION",
            "event_data": {
              "integration_id": "ARB_ABRACADABRA_GLP_STAKING__0x85667409a723684fe1e57dd1abde8d88c2f54214"
            }
          },
          {
            "event_key": "NEW_TOKEN",
            "event_data": {
              "token_in_chain_id": "ARBITRUM_address_0x371c7ec6d8039ff7933a2aa28eb827ffe1f52f07"
            }
          },
          {
            "event_key": "NEW_TOKEN_BALANCE_CHANGE",
            "event_data": {
              "balance_change": -0.004117883777972483,
              "token_in_chain_id": "ARBITRUM_native_token_eth",
              "timestamp": 1707696000
            }
          }
        ]
      },
      "last_balances": [ // The most recent balances saved for this wallet
        {
          "balance": 0.005491983636412722,
          "token_in_chain_id": "ARBITRUM_native_token_eth",
          "usd_value": 16.736512981934997
        },
        {
          "balance": 0.000025119114670483,
          "token_in_chain_id": "ARBITRUM_address_0x7a5d193fe4ed9098f7eadc99797087c96b002907",
          "usd_value": 0.00001698372061195489
        },
        {
          "balance": 1.559273,
          "token_in_chain_id": "ARBITRUM_address_0xeb466342c4d449bc9f53a865d5cb90586f405215",
          "usd_value": 1.5250525369693035
        }
      ]
    }
  ]
}

Using the Pulsar SDK for Wallet Timeseries

When querying for the historical value of an address, your response will have this type:

export class Timeseries {
    wallet: BaseWallet;
    tier: TierKeys;
    events: Record<number, TimeseriesEvent[]>;
    timeseries?: Record<number, number>;
}

export class TimeseriesEvent {
    event_key: TimeseriesEventKey;
    event_data: Record<any, any>;
}

export enum TimeseriesEventKey {
    NEW_TOKEN = 'NEW_TOKEN',
    NEW_INTEGRATION = 'NEW_INTEGRATION',
    PRICE_NOT_FOUND = 'PRICE_NOT_FOUND',
    WALLET_CREATED = 'WALLET_CREATED_EVENT',
    NEW_TOKEN_BALANCE_CHANGE = 'NEW_TOKEN_BALANCE_CHANGE',
    NEW_INTEGRATION_BALANCE_CHANGE = 'NEW_INTEGRATION_BALANCE_CHANGE',
}

@dataclass
class Timeseries:
    wallet: BaseWallet
    tier: TierKeys
    timeseries: dict[str, float | None]
    events: dict[str, list[TimeseriesEvent]]
    last_balances: list[dict]

@dataclass
class TimeseriesEvent:
    event_key: TimeseriesEventKey
    event_data: dict

class TimeseriesEventKey(StrEnum):
    NEW_TOKEN = "NEW_TOKEN"
    NEW_INTEGRATION = "NEW_INTEGRATION"
    PRICE_NOT_FOUND = "PRICE_NOT_FOUND"
    WALLET_CREATED = "WALLET_CREATED_EVENT"
    NEW_TOKEN_BALANCE_CHANGE = "NEW_TOKEN_BALANCE_CHANGE"
    NEW_INTEGRATION_BALANCE_CHANGE = "NEW_INTEGRATION_BALANCE_CHANGE"

To use this feature, call the get_wallet_timeseries method, which returns a Timeseries object with two important fields: timeseries and events.

  • timeseries: Presents your wallet's value over time in USD.
  • events: Captures various wallet events within the chosen time range, such as changes in balances and received tokens.
import PulsarSDK, { ChainKeys, TierKeys } from "pulsar_sdk_js";

const chain = ChainKeys.ETHEREUM;
const responses_list: any[] = [];
const wallet_addr = "YOUR WALLET ADDR";
const API_KEY = "YOUR API KEY";
const tier = TierKeys.ONE_MONTH;
const sdk = new PulsarSDK(API_KEY);

async function getWalletTimeseries() {
  const balances = sdk.balances.getWalletTimeseries(wallet_addr, chain, tier);
  for await (const balance of balances) {
    responses_list.push(balance);
  }
}

getWalletTimeseries().then(() => {
  console.log(responses_list);
});

import asyncio
from pulsar_sdk_py import PulsarSDK
from pulsar_sdk_py.enums import ChainKeys, TierKeys

sdk = PulsarSDK(API_KEY)
responses_list = []

async def main():
    global responses_list
    async for timeseries in sdk.balances.get_wallet_timeseries(
        wallet_addr="YOUR WALLET_ADDR", chain=ChainKeys.AVALANCHE, tier=TierKeys.ONE_MONTH
    ):
        responses_list.append(timeseries)

if __name__ == "__main__":
    asyncio.run(main())

Input Typing

enum TierKeys {
    ONE_DAY = '1d',
    ONE_WEEK = '7d',
    ONE_MONTH = '30d',
    ONE_YEAR = '365d',
}

{
  "method": string,
  "command": {
    "key": string,
    "data": {
      "address": string,
      "chain": string,
      "tier": string,
      "hide_tokens": Array<string>,
      "hide_integrations": Array<string>,
      "hide_nfts": Array<string>
    }
  },
}

{
   "method":"COMMAND",
   "command":{
      "key":"GET_WALLET_TIMESERIES",
      "data":{
         "address":"0x2b78d022af87d411ba84474ffbc7eef8b4addb45",
         "chain":"ETHEREUM",
         "tier":"1d",
         "hide_tokens":[],
         "hide_integrations":[],
         "hide_nfts":[]
      }
   },
   "request_id":"a9d4b2a1-1f10-4a88-9112-338a35029013"
}

Response Example

{
  "data":[
    {
      "wallet":{
        "address":"0x2b78d022af87d411ba84474ffbc7eef8b4addb45",
        "chain":"ARBITRUM"
      },
      "tier":"1d",
      "timeseries":{
        "1705363200":227.97114996695302,
        // ...
        "1736812800":254.72555816288587
      },
      "events":{
        "1736353200":[
          {
            "event_key":"NEW_INTEGRATION",
            "event_data":{
              "integration_id":"ARB_ABRACADABRA_GLP_STAKING__0x85667409a723684fe1e57dd1abde8d88c2f54214"
            }
          },
          {
            "event_key":"NEW_TOKEN",
            "event_data":{
              "token_in_chain_id":"ARBITRUM_address_0x371c7ec6d8039ff7933a2aa28eb827ffe1f52f07"
            }
          },
          {
            "event_key":"NEW_TOKEN_BALANCE_CHANGE",
            "event_data":{
              "balance_change":-0.004117883777972483,
              "token_in_chain_id":"ARBITRUM_native_token_eth",
              "timestamp":1707696000
            }
          }
        ]
      },
      "last_balances":[
        {
          "balance":0.005491983636412722,
          "token_in_chain_id":"ARBITRUM_native_token_eth",
          "usd_value":16.736512981934997
        },
        {
          "balance":0.000025119114670483,
          "token_in_chain_id":"ARBITRUM_address_0x7a5d193fe4ed9098f7eadc99797087c96b002907",
          "usd_value":0.00001698372061195489
        },
        {
          "balance":1.559273,
          "token_in_chain_id":"ARBITRUM_address_0xeb466342c4d449bc9f53a865d5cb90586f405215",
          "usd_value":1.5250525369693035
        },
        // ...
      ]
    }
  ]
}

Updated about 10 hours ago

Did this page help you?

Updated about 10 hours ago

Did this page help you?