Zerion API

This is a socket-based interactive api based on the Socket.io library.

Installation

Please, make sure to use Socket.io v2 client API.

// Javascript
npm i socket.io-client@2.4.0
// Python
pip install python-socketio==4.6.1

Example client code

JavaScript

import io from 'socket.io-client';

const FALLBACK_URL = 'wss://api-v4.zerion.io/';
const BASE_URL = process.env.API_URL || FALLBACK_URL;

function verify(request, response) {
  // each value in request payload must be found in response meta
  return Object.keys(request.payload).every(key => {
    const requestValue = request.payload[key];
    const responseMetaValue = response.meta[key];
    if (typeof requestValue === 'object') {
      return JSON.stringify(requestValue) === JSON.stringify(responseMetaValue);
    }
    return responseMetaValue === requestValue;
  });
}

const assetsSocket = {
  namespace: 'assets',
  socket: io(`${BASE_URL}assets`, {
    transports: ['websocket'],
    timeout: 60000,
    query: {
      api_token:
        process.env.ZERION_API_KEY_V4 ||
        'Demo.ukEVQp6L5vfgxcz4sBke7XvS873GMYHy',
    },
  }),
};

function get(socketNamespace, requestBody) {
  return new Promise(resolve => {
    const { socket, namespace } = socketNamespace;
    function handleReceive(data) {
      if (verify(requestBody, data)) {
        unsubscribe();
        resolve(data);
      }
    }
    const model = requestBody.scope[0];
    function unsubscribe() {
      socket.off(`received ${namespace} ${model}`, handleReceive);
      socket.emit('unsubscribe', requestBody);
    }
    socket.emit('get', requestBody);
    socket.on(`received ${namespace} ${model}`, handleReceive);
  });
}

get(assetsSocket, {
  scope: ['info'],
  payload: {
    explore_section: 1,
    currency: 'usd',
    offset: 0,
    limit: 20,
  },
}).then(response => {
  console.log(response.payload.info);
});

Python

import asyncio
import socketio
URI = "wss://api-v4.zerion.io"
API_TOKEN = "Demo.ukEVQp6L5vfgxcz4sBke7XvS873GMYHy"
ORIGIN = "http://localhost:3000"
sio = socketio.AsyncClient()
@sio.event
def connect():
  print("I'm connected!")
@sio.event
def connect_error():
  print("The connection failed!")
async def sio_connect():
  await sio.connect(f"{URI}/?api_token={API_TOKEN}", headers={"Origin": ORIGIN})
if name == '__main__':
  loop = asyncio.get_event_loop()
  loop.create_task(sio_connect())

Overview

In order to connect, a valid api_token query parameter must be specified.All tokens are restricted by Origin and therefore a valid HTTP_ORIGIN header is expected.

let io_options = {transports: ['websocket'], query: {api_token: 'YOUR API TOKEN'}};
socket = io('wss://api.zerion.io', io_options);

Actions

There are three supported types of messages:

• get - requests data, returns a single response and does not emit continuous messages

• subscribe - returns a single response (the same as get) + creates a subscription

• unsubscribe - deletes the subscription

Request

Each request has the following structure:

[
    "{action}",
    {
      "scope": ["scope1", "scope2"],
      "payload": {
          "parameter1": "value1",
          "parameter2": "value2"
      }
    }
]

Response

[ 
    "received {namespace} {model}",
    {
       "meta": {
           "status": "ok",
           "request parameter1": "value1",
           "request parameter2": "value2"
       },
       "payload": {
           "{scope}": "__result__"
       }
    }
]

Change

[ 
    "changed|appended|removed {namespace} {model}",
    {
       "meta": {
           "subscription parameter1": "value1",
           "subscription parameter2": "value2"
       },
       "payload": {
           // changed model
       }
    }
]

Handlers

AddressHandler (/address)

• Payload

Field	Type	Default
address	str	-
addresses	list	[]
currency	PriceCurrency	usd
charts_type	str	d
charts_max_assets	int	0
charts_min_percentage	int	100
transactions_limit	int	50
transactions_offset	int	0
transactions_search_query	str	-
portfolio_fields	PortfolioFields	assets
asset_codes	list	[]

• Messages

Scope	Result
info	AddressInfo
assets	Dict[str, AddressAsset]
portfolio	Portfolio
transactions	List[Transaction]
charts	Dict[str, List[Tuple[int, float]]]
deposits	List[Deposit]
loans	List[Loan]
locked-assets	List[LockedAsset]
staked-assets	List[StakedAsset]
bsc-assets	Dict[str, AddressBSCAsset]
polygon-assets	Dict[str, AddressPolygonAsset]

AssetsHandler (/assets)

• Payload

Field	Type	Default
address	str	-
addresses	list	[]
asset_code	str	-
asset_codes	list	[]
currency	PriceCurrency	usd
limit	int	10000
offset	int	0
explore_section	str	-
order_by	dict	{}
charts_type	str	d
explore_sections	list	[]
category_id	str	-
explore_sections_aliases	list	[]
search_query	str	-
tags_group	str	all

• Messages

Scope	Result
prices	Dict[str, Asset]
info	List[AssetInfo]
full-info	Optional[zerion_api.entities.socketio.AssetFullInfo]
explore-sections	List[ExploreSection]
charts	Dict[str, List[Tuple[int, float]]]
tags	List[AssetTag]
actions	List[AssetAction]
stats	AssetStats
list	List[AssetInfo]
tokenlists	List[Tokenlist]
categories	List[Category]

BlockLagHandler (/block_lag)

• Payload

Field	Type	Default

• Messages

Scope	Result
block-lag	BlockLag

CompoundHandler (/compound)

• Payload

Field	Type	Default
address	str	-
currency	PriceCurrency	usd

• Messages

Scope	Result
info	CompoundInfo
assets	List[CompoundAsset]
actions	List[CompoundAction]
deposits	List[CompoundDeposit]
loans	List[CompoundLoan]

DyDxHandler (/dydx)

• Payload

Field	Type	Default
address	str	-
currency	PriceCurrency	usd

• Messages

Scope	Result
deposits	List[DyDxAccountBalance]
loans	List[DyDxAccountBalance]

GasPriceHandler (/gas)

• Payload

Field	Type	Default

• Messages

Scope	Result
price	GasPriceInfo

MakerHandler (/maker)

• Payload

Field	Type	Default
cdp_id	str	-
vault_id	str	-
currency	PriceCurrency	usd

• Messages

Scope	Result
cdp	MakerCDP
vault	MakerVault
cdp-actions	List[MakerCDPAction]
vault-actions	List[MakerVaultAction]

Models

AddressAsset

Name	Type	Optional
asset	Asset
quantity	str

AddressBSCAsset

Name	Type	Optional
asset	CovalentAsset
quantity	str

AddressInfo

Name	Type	Optional
address	str
type	str
proxies	str	yes
cdps	int	yes
vaults	int	yes
aggregated_at	int	yes

AddressPolygonAsset

Name	Type	Optional
asset	CovalentAsset
quantity	str

Asset

Name	Type	Optional
asset_code	str
name	str
symbol	str
decimals	int
type	AssetType
icon_url	str	yes
price	Price	yes
is_displayable	bool
is_verified	bool

AssetAction

Name	Type	Optional
id	str
transaction_hash	str
type	AssetActionType
value	float	yes
quantity	str
price	float	yes
datetime	int
asset	Asset
status	TransactionStatus
direction	Direction
fee	AssetActionFee	yes

AssetActionAmount

Name	Type	Optional
base	float
currency	float	yes

AssetActionFee

Name	Type	Optional
quantity	str
value	float

AssetComponent

Name	Type	Optional
asset	Asset
quantity	float
share	float
allocation	float

AssetDescription

Name	Type	Optional
asset_code	str
full	str	yes

AssetFullInfo

Name	Type	Optional
asset	Asset
title	str
stats	AssetFullInfoStats
components	str	yes
gradient_color	str	yes
explore_sections	int	yes
subtitle	str	yes
tagline	str	yes
market_cap	float	yes
fully_diluted_valuation	float	yes
total_supply	float	yes
circulating_supply	float	yes
relative_changes	str	yes
description	str	yes
relevant_resources	AssetRelevantResource	yes
tags	str	yes
is_tradable	bool

AssetFullInfoStats

Name	Type	Optional
asset_code	str
year_min	float	yes
year_max	float	yes
volume_24h	float	yes

AssetInfo

Name	Type	Optional
asset	Asset
title	str
gradient_color	str	yes
explore_sections	int	yes
subtitle	str	yes
tagline	str	yes
market_cap	float	yes
total_supply	float	yes
circulating_supply	float	yes
relative_changes	str	yes
tags	str	yes

AssetRelevantResource

Name	Type	Optional
name	str
url	str
displayable_name	str	yes

AssetStats

Name	Type	Optional
total_returned	float	yes
total_returned_net	float	yes
total_returned_change	float	yes
total_fee_spent	float	yes
avg_buy_price	float	yes
avg_buy_price_net	float	yes
avg_sell_price	float	yes
avg_sell_price_net	float	yes

AssetTag

Name	Type	Optional
id	str

BlockLag

Name	Type	Optional
block_lag	int	yes

Category

Name	Type	Optional
id	str
title	str
tagline	str
order_by	str	yes
display_type	CategoryDisplayType

CompoundAction

Name	Type	Optional
id	str
type	TransactionAction
transaction_hash	str
status	TransactionStatus
ctoken	str	yes
ctoken_value	float	yes
underlying_value	float	yes
datetime	datetime

CompoundAsset

Name	Type	Optional
underlying	Asset
underlying_eth_price	float
asset	Asset
borrow_rate	float	yes
supply_rate	float	yes
exchange_rate	float	yes

CompoundDeposit

Name	Type	Optional
asset	CompoundAsset
deposited	float
earned_interest	float
ctokens	int

CompoundInfo

Name	Type	Optional
loans	CompoundLoan	yes
deposits	CompoundDeposit	yes
total_debt	float
total_collateral	float

CompoundLoan

Name	Type	Optional
asset	CompoundAsset
borrowed	float
accrued_interest	float

CovalentAsset

Name	Type	Optional
asset_code	str
name	str
symbol	str
decimals	int
icon_url	str	yes
value	float	yes

Deposit

Name	Type	Optional
id	str
asset	Asset
deposited	float
value	float
supply_rate	float	yes
section	str
protocol	str
displayed_on_chart	bool

DyDxAccountBalance

Name	Type	Optional
owner	str
account_number	str
normalized_balance	float
balance	float
asset	Asset

ExploreSection

Name	Type	Optional
id	int
title	str
tagline	str
order	int
alias	str	yes

GasPriceInfo

Name	Type	Optional
rapid	int	yes
fast	int	yes
standard	int	yes
slow	int	yes
source	GasPriceSource
datetime	datetime

Loan

Name	Type	Optional
id	str
asset	Asset
borrowed	float
value	float
borrow_rate	float	yes
section	str
protocol	str
displayed_on_chart	bool

LockedAsset

Name	Type	Optional
id	str
asset	Asset
locked	float
value	float
section	str
protocol	str
displayed_on_chart	bool

MakerCDP

Name	Type	Optional
id	int
owner	str
debt	float
collateral	float

MakerCDPAction

Name	Type	Optional
type	str
transaction	str
timestamp	int
dai_value	float	yes
eth_value	float	yes
peth_value	float	yes
owner	str	yes
new_owner	str	yes

MakerVault

Name	Type	Optional
id	int
owner	str
normalized_debt	float
outstanding_debt	float
total_borrowed	float
total_repaid	float
accrued_interest	float
collateral	float
collateral_type	str

MakerVaultAction

Name	Type	Optional
id	str
vault	int
type	MakerDSSActionType
transaction_hash	str
normalized_debt_change	float	yes
debt_change	float	yes
collateral_change	float	yes
owner	str	yes
new_owner	str	yes
datetime	datetime

Portfolio

Name	Type	Optional
assets_value	float
deposited_value	float
borrowed_value	float
locked_value	float
staked_value	float
bsc_assets_value	float
polygon_assets_value	float
total_value	float
absolute_change_24h	float
relative_change_24h	float	yes

Price

Name	Type	Optional
value	float
relative_change_24h	float	yes
changed_at	int

PriceStat

Name	Type	Optional
min	float
max	float
relative_change	float

StakedAsset

Name	Type	Optional
id	str
asset	Asset
staked	float
value	float
section	str
protocol	str
displayed_on_chart	bool

Tokenlist

Name	Type	Optional
id	str
name	str
icon_url	str
total_tokens	int
has_asset_code	bool

Transaction

Name	Type	Optional
id	str
type	RDBTransactionType
protocol	str
mined_at	int
block_number	int
status	TransactionStatus
hash	str
direction	Direction	yes
address_from	str	yes
address_to	str	yes
contract	str	yes
nonce	int	yes
changes	TransactionChange	yes
fee	TransactionFee	yes
meta	str	yes

TransactionChange

Name	Type	Optional
asset	Asset
value	int
direction	Direction
address_from	str
address_to	str
price	float	yes

TransactionFee

Name	Type	Optional
value	int
price	float

Structures

AssetType

• aave

• aave-uniswap

• aave-v2

• alpha-homora

• badger-sett

• balancer

• bancor

• bitcoin

• cream

• curve

• compound

• dmm

• dodo

• dodo-v2

• enzyme

• ethereum

• fulcrum

• harvest-vault

• idle

• iearn-curve

• iearn-v2

• iearn-v3

• indexed

• keeperdao

• maker

• melon

• mooniswap

• mstable

• mushroom-vault

• nft

• one-inch

• pickle-jar

• piedao-pool

• pool-together

• realt

• snowswap

• stablecoin

• synthetix

• sushi

• swerve

• tokenset

• tokenset-v2

• trash

• uniswap

• uniswap-v2

• xsushi

• yearn-vault

• yearn-vault-v2

• None

  TransactionStatus

• confirmed

• failed

• pending

  MakerDSSActionType

• open

• deposit

• withdraw

• borrow

• repay

• transfer

• liquidate

  TransactionAction

• Authorize

• Trade

• Deposit

• Withdraw

• Borrow

• Repay

• Liquidate

• Enable Borrowing

• Open CDP

• Close CDP

• Transfer CDP

• Migrate CDP

• Open Vault

• Close Vault

• Transfer Vault

• Migrate

• Create Exchange

• Add Liquidity

• Remove Liquidity

• Stake

• Unstake

• Claim Rewards

• Register ENS Domain

• Renew ENS Domain

  PriceCurrency

• eth

• btc

• usd

• eur

• krw

• rub

• gbp

• aud

• cad

• inr

• jpy

• nzd

• try

• zar

• cny

• chf

  RDBTransactionType

• send

• receive

• trade

• authorize

• execution

• deployment

• cancel

• deposit

• withdraw

• borrow

• repay

• stake

• unstake

• claim

  CategoryDisplayType

• short

• detailed

  Direction

• in

• out

• self

  PortfolioFields

• all

• assets

  AssetActionType

• buy

• sell

• send

• receive

• borrow

• deposit

• authorize

• withdraw

• repay

• stake

• unstake

• claim

  GasPriceSource

• gas-now

• eth-gas-station