Skip to content

[Deprecated] API Documentation

Jump to bottom
Taylor Dawson edited this page Aug 9, 2019 · 1 revision

Contents

Getting Started
  Installation
  Usage
Web3data-js API
  Web3data
  Blockchains
    .blockchains()
    .blockchains(blockchainId/slug)
  Addresses
    .Address(hash)
    .addresses()
    .addresses(hash)
      .info()
      .stats()
      .transactions()
      .transactions(txhash)
      .logs()
      .logs(logHash)
      .messages()
      .messages(messageHash)
      .tokens()
      .tokens(tokenHash)
  Modifiers
    Filters
      .filter(filterOptions)
    Pagination
      .limit(n)
      .offset(index)
      .orderBy(fieldName)
      .direction(dir)
  Websockets
    .websockets()
    .websockets(options)

Getting started

Installation

Node

npm install web3data

Yarn

yarn add web3data

As Browser Module

CDN
<script src=".../web3data.min.js"></script>
Bower
bower install web3data

Web3data-js API

web3data

Web3data(configObject) The web3data object provides all methods.

Parameters
  • configObject | Type: Object - An object that contains configurations options
    • apiKey | Type: String - Authorized api key, user based
    • blockchainId | Type: Object - The blockchain id referencing the blockchain with which the user wishes to interact
Returns
  • Web3data instance
Example
import Web3data from 'web3data-js'
let config = {
	'apiKey': 't_42e84016b2f18a5a40592292843cb4de',
	'blockchainId': '1c9c969065fcd1cf ' // or 'slug': 'ethereum-mainnet'
}
const web3data = new Web3data(config)

Blockchains

.blockchains()

web3data.blockchains()

Parameters
  • None
Returns
Example
let blockchains = web3data.blockchains()
console.log(blockchains)

/* --- Returns --- */
[
	{
		"blockchainId": "k9j7d...",
		"config": {...},
		.
		.
		.
	},
	{...},
	{...}
]

.blockchains(blockchainId/slug)

web3data.blockchains(blockchainId /* or slug */)

Parameters
  • blockchainId | Type: String - The perdetermined ID corresponding to a blockchain and network or
  • slug | Type: String - The human readable name corresponding to a blockchain and network
Returns
  • Type: Object - An object containing data pertaining to the specified blockchain:
    • blockchainId | Type: String - The predetermined ID corresponding to a blockchain and network
    • config
      • icon | Type: String - The URL of the blockchain's logo
      • color | Type: String - The hex value referring to the blockchain's primary brand color
      • website | Type: String - The URL of the blockchain's main website
      • decimals | Type: Int - The number of significant digits, per smart contract definition
      • unit | Type: String - The name of the smallest denomination of a token
      • utility | Type: String - The name of the unit of computation, based proof of work systems
      • token | Type: String - The name of the payment medium of a network
      • ethAddress | Type: String - The address of the smart contract on Ethereum that is used for inter-chain communication
    • consensus | Type: String - The type of consensus mechanism employed by the network // TODO: List possible values
    • name | Type: String - The name of the blockchain
    • network | Type: String - The name of the network within the given blockchain
    • type | Type: String - The type of network. Ex. production: mainnet vs development: testnet
    • slug | Type: String - The human readable name corresponding to a blockchain and network
    • admin | Type: String - Returns true if the x-amberdata-api-key is the owner of the blockchain
Example
let blockchains = web3data.blockchains("1c9c969065fcd1cf" /*Ethereum Mainnet id*/)
console.log(blockchains)

/* --- Returns --- */
{
    "blockchainId": "1c9c969065fcd1cf",
    "config": {
      "icon": "https://s3.us-east-2.amazonaws.com/amberdata-public/images/ethereum_logo_mainnet.svg",
      "color": "#222222",
      "website": "https://ethereum.org/",
      "decimals": 18,
      "unit": "wei",
      "utility": "gas",
      "token": "Ether",
      "ethAddress": ""
    },
    "consensus": "PoW",
    "name": "Ethereum",
    "network": "Mainnet",
    "type": "mainnet",
    "slug": "ethereum-mainnet",
    "admin": false
  }

Addresses

Methods to retrieve address statistics and general information.

.Address(hash)

web3data.Address(hash) Constructs an address object. Provided to allow reuse when working with a frequently used address. For instance, a contract address used by a dApp.

Modifiers
  • None
Parameters
  • hash | Type: String - The address hash
Returns
  • Type: Object - An address object
Example
let address = new web3data.Address("0x407d73d...")

// All method calls a 'address' will pertain to the previously specfied address
let transactions = address.transactions()
let info = address.info()
// etc...

.addresses()

web3data.addresses() Retrieves paginated list of addresses in a blockchain.

Modifiers
  • None
Parameters
  • None
Returns
  • Type: Array - An array of address objects
Example
let addresses = web3data.addresses()
console.log(addresses)

.addresses(hash)

web3data.addresses(hash) Retrieves data pertaining to the specified address (invokes .info() under the hood). Can be chained with other methods as shown below.

Parameters
  • hash | Type: String - The address hash
Returns
  • Type: Object - An object containing data pertaining to the specified address.
Example
let addresses = web3data.addresses("0x407d73d...")
console.log(addresses)
/* --- Returns --- */
// Result of addresses("0x407d73d...").info()

.info()

web3data.addresses(hash).info() Provides information pertaining to the specified address.

Modifiers
  • None
Parameters
  • None
Returns
  • Type: Array - An array containing information about the specified address organised by blockchain and network, ordered by likelihood of accuracy (most probable first and least probable last).
    • type | Type: String - The type of account: address or contract.
    • contractTypes | Type: Array - An array of Strings corresponding to the type of contract interface/standard.
    • firstSeen | Type: String - The ISO Formatted date of when the address made its first public appearance.
    • network | Type: Object - An object containing network specific data
      • name | Type: String - The name of the network
      • slug | Type: String - The human readable name corresponding to a blockchain and network
      • blockchainId | Type: String - The predetermined ID corresponding to a blockchain and network
      • link | Type: String - Link to address details page
Example
let addressInfo = web3data.addresses("0x407d73d...").info()
console.log(addressInfo)
// or
let address = new web3data.Address("0x407d73d...")
console.log(address.info())

/* --- Returns --- */
[
  {
    // Address/Account spec
    type: 'address',
    contractTypes: ['ERC20', 'ERC721'],
    firstSeen: "2018-01-09T07:02:49.000Z",
    network: {
        name: 'testnet',
        slug: 'fake-testnet',
        blockchainId: '40592292843cb4de',
        link: 'https://fake-testnet.amberdata.io/addresses/:hash',
     }
  },
  {
    type: 'address',
    contractTypes: ['Token'],
    firstSeen: "2018-01-09T07:02:49.000Z",
    network: {
        name: 'testnet2',
        slug: 'fake-testnet2',
        blockchainId: '123abc456def789',
        link: 'https://fake-testnet2.amberdata.io/addresses/:hash',
    }
  }
]

.stats()

web3data.address(hash).stats() Provides key insights into history, operations & metrics of an address

Modifiers
  • None
Parameters
  • None
Returns
  • Type: Object - An object containing key insights into history, operations & metrics of the specified address
    • balance | Type: String - The current balance of the address
    • balanceIn | Type: String - The balance that has been transferred into the address
    • balanceOut | Type: String - The balance that has been transferred out of the address
    • decimals | Type: Int - The number of significant digits, per smart contract definition
    • name* | Type: String - Name of the contract
    • numHolders* | Type: Int - The total amount of unique addresses
    • numTransfers | Type: Int - The total amount of unique transfers where any type of transaction has occurred
    • symbol* | Type: String - The token symbol
    • totalSupply* | Type: String - Total number of tokens in circulation
    • totalValueUSD* | Type: String - Total value of all tokens
    • unitValueUSD* | Type: String - The value of the token in USD

*specific to contract addresses

Example
let addressStats = web3data.addresses("0x407d73d...").stats()
console.log(addressStats)
// or
let address = new web3data.Address("0x407d73d...")
console.log(address.stats())

/* --- Returns --- */
{
  balance: '1392408324.943209090',
  balanceIn: '1392408324.943209090',
  balanceOut: '0',
  decimals: 18,
  name: "0x Protocol Token"
  numHolders: 654,
  numTransfers: 489241,
  symbol: 'ZRX',
  totalSupply: '1000000000.0000000000000000',
  totalValueUSD: '881363131.50000000000000000000000000',
  unitValueUSD: '0.8813631315',
}

.transactions()

web3data.addresses(hash).transactions() Retrieves a list of all transactions pertaining to the specified address.

Modifiers:
  • filter
  • pagination
Parameters
  • None
Returns
  • Type: Array - An array of transaction objects
Example
let allTransactions = web3data.addresses("0x407d73d...").transactions()
console.log(allTransactions)
// or 
let address = new web3data.Address("0x407d73d...")
console.log(address.transactions())

/* --- Returns --- */
{
	`totalRecords': 2132,
	'records': [
	{
		'blockNumber': '6124274',
		.
		.
		'amount': {...}
	},
	{...},
	{...},
	.
	.
	{...}
	]
}

.transactions(txhash)

web3data.addresses(hash).transactions(txhash) Retrieves data pertaining to the specified transaction hash.

Parameters
  • txhash | Type: String - The transaction hash
Returns
  • Type: Object - An object containing data pertaining to the specified transaction
    • blockNumber | Type String - The blocknumber of the block which contains the specified transaction.
    • index | Type Int - The index of the transaction within the block
    • hash | Type String - The transaction hash
    • timestamp | Type String - The time of when the transaction was confirmed
    • value| Type String - The blockchain value
    • from | Type String - The address hash of the sender
    • to | Type String - The address hash of the recipient
    • gasLimit | Type Int - An object containing details about the gas price of the transaction
      • type | Type String -
      • unit | Type String -
      • value | Type String -
    • gasPrice | Type Object - An object containing details about the gas price of the transaction
      • type | Type String -
      • unit | Type String -
      • value | Type String -
    • gasUsed | Type Object - An object containing details about the gas used in the transaction
      • type | Type String -
      • unit | Type String -
      • value | Type String -
    • confirmations | Type String - The number of confirmations on the block in which this transaction resides
    • fee | Type Object - An object containing details about the transaction fee
      • type | Type String -
      • unit | Type String -
      • value | Type String - The transaction fee amount
    • miner | Type String - The address hash of the miner who mined the block in which this transaction resides
      • inputSize | Type Int - The size in bytes of the input data
      • nonce | Type Int - The number of transactions sent from an address (this is typically used to prevent double spending for example)
Example
let singleTransaction = web3data.addresses("0x407d73d...").transactions("0xe9b36f1...")
console.log(singleTransaction)
// or 
let address = new web3data.Address("0x407d73d...")
console.log(address.transactions("0xe9b36f1..."))

/* --- Returns --- */
{
  "blockNumber": "6124274",
  "index": 28,
  "hash": "0xe7be36f174503d8bc40839ca55502b2a27f9aa7ac2bd02da57d3aa408cd51b4b",
  "timestamp": "2018-08-10T20:19:25.000Z",
  "value": "0",
  "from": "0x40120b5a5994f7e3afe3c0a3dc56d1ccb0b75262",
  "to": "0xe41d2489571d322189246dafa5ebde1f4699f498",
  "gasLimit": {
    "type": "metric",
    "unit": "k",
    "value": "74.34"
  },
  "gasPrice": {
    "type": "wei",
    "unit": "Gwei",
    "value": "20"
  },
  "gasUsed": {
    "type": "metric",
    "unit": "k",
    "value": "22.17"
  },
  "confirmations": "8",
  "fee": {
    "type": "wei",
    "unit": "ether",
    "value": "0.0004434"
  },
  "miner": "0xea674fdde714fd979de3edf0f56aa9716b898ec8",
}

.logs()

web3data.addresses(hash).logs()

Modifiers:
  • filter
  • pagination
Parameters
  • None
Returns
  • Type: Object - An object contain log information about the specified address.
    • totalRecords | Type Int - The total number of log records
    • records | Type Array - An array containing a list of log objects. (See below)
Example
let addressLogs = web3data.addresses("0x407d73d...").logs()
console.log(addressLogs)
// or
let address = new web3data.Address("0x407d73d...")
console.log(address.logs())

/* --- Returns --- */
{
	"totalRecords": 5,
	"records": [
		{...},
		{...},
		.
		.
		{...}
	]
}

.logs(logHash)

web3data.addresses(hash).logs(logHash)

Parameters
  • logHash | Type: String - The hash of the log
Returns
  • Type: Object - An object contain log information about the specified address.
    • LogIndex | Type Int - The index of the log
    • address | Type String - The address that the log is associated with
    • data | Type Array - The arguments of the function call
    • topics | Type Array - The indexed argument names
    • name | Type String - The name of the event
Example
let addressLog = web3data.addresses("0x407d73d...").logs("0x6f8f73...")
console.log(addressLog)
// or
let address = new web3data.Address("0x407d73d...")
console.log(address.logs("0x6f8f73..."))

/* --- Returns --- */
{
	"logIndex": 8,
	"address": "0xdd9fd6b6f8f7ea932997992bbe67eabb3e316f3c",
	"data": ["67c026...", "79646d...", ..."2dab3f..."],
	"topics": ["0x8f36...", "0x0000..."],
	"name": null
},

.messages()

web3data.addresses(hash).messages()

Modifiers:
  • filter
  • pagination
Parameters
  • None
Returns
  • Type: Object - An object containing messages corresponding to the specified address
    • totalRecords | Type Int - The total number of messages
    • records | Type Array - An array containing a list of message objects (see below).
Example
let messages = web3data.addresses("0x407d73d...").messages()
console.log(messages)
// or
let address = new web3data.Address("0x407d73d...")
console.log(address.messages())
/* --- Returns --- */
{
	"totalRecords": 5,
	"records": [
		{...},
		{...},
		.
		.
		{...}
	]
}

.messages(messageHash)

web3data.addresses(hash).messages(messageHash)

Parameters
  • messageHash | Type: String The has of the message
Returns
  • Type: Object - An object containing details about a message
    • initialGas | Type: String - The gas before the message (transaction) is sent
    • leftOverGas | Type: String - The gas after the message (transaction) is sent
    • from | Type: String - The address hash of the message sender
    • to | Type: String - The address hash of the message recipient
    • value | Type: String - The data associated with the message
    • depth | Type: Int - The call stack depth of messages
    • opcode | Type: String - The name of opcode
    • error | Type: String - The error message if applicable. Empty if no error message.
    • messageIndex | Type: Int -
Example
let message = web3data.addresses("0x407d73d...").messages("0xe9b36f1...")
console.log(message)
// or 
let address = new web3data.Address("0x407d73d...")
console.log(address.messages("0xe9b36f1..."))
/* --- Returns --- */
{
	"initialGas": "98065",
	"leftOverGas": "39992",
	"from": "0xc35a5fe...",
	"to": "0x06012c...",
	"value": "8000000000000000",
	"depth": 0,
	"opcode": "CALL",
	"error": "",
	"messageIndex": 0
}

.tokens()

web3data.addresses(hash).tokens()

Modifiers:
  • filter
  • pagination
Parameters
  • None
Returns
  • Type: Object - An object contain messages corresponding to the specified address
    • totalBalance | Type String - The summation of the token unit values
    • records | Type Array - An array containing a list of token objects which details tokens owned by the specified address (see below).
Example
/* --- Returns --- */
{
  "totalBalance": 334.80467768332375,
  "records": [
		{...},
		{...},
		.
		.
		{...}
  ]
}

.tokens(tokenHash)

web3data.addresses(hash).tokens(tokenHash)

Parameters
  • tokenHash | Type: String - (Conf) The address hash of the token
Returns
  • Type: Object - An object containing details about a token owned by the specified address
    • address | Type: String - (Conf) The address hash of the token
    • name | Type: String - The token name
    • symbol | Type: String - The token symbol
    • totalSupply | Type: String - Total number of tokens in circulation
    • unitValue | Type: String -
    • totalValue | Type: String -
Example
/* --- Returns --- */

{
    "address": "0x08f5a9...",
    "name": "Tierion Network Token",
    "symbol": "TNT",
    "totalSupply": "14864.2730000000000000",
    "unitValue": "0.0225241206",
    "totalValue": "334.80467768332380000000000000"
}

Modifiers

Filters

.filter(filterOptions)

web3data.address(hash).transactions().filter(filterOptions)

Parameters
  • filterOptions | Type: Object - An object containing desired filter options
    • status | Type: String - (what does this apply to? transactions doesn't have status field)
    • dateStart | Type: String - ISO Formatted date
    • dateEnd | Type: String - ISO Formatted date
    • from | Type: String - The address hash of the sender
    • to | Type: String - The address hash of the recipient
    • blockNumber | Type: Int - The blocknumber
Returns
  • Type: Object -
Example
let filter = {
	'status':'',
	'dateStart':'',
	'dateEnd':'',
	'from':'',
	'to':'',
	'blockNumber':'',
}
let transactions = web3data.addresses("0x407d73d...").transactions().filter(filter)
console.log(transactions)
/* --- Returns --- */
/* TODO: Fill in

Pagination

.limit(n) or .size(n)

web3data.address(hash).transactions().limit(n)

Parameters
  • n | Type: Int - Number of results per page
Returns
  • Type: Array - An array containing n results. (Is there a page number?)
Example
/* --- Returns --- */
/* TODO: Fill in */

.offset(index) or .page(index)

web3data.address(hash).transactions().offset(index) Used to retrieve a single page from the list of pages returned by .limit(n).

Parameters
  • index | Type: Int - Index of the page to display. . Required: index < n (totla pages)
Returns
  • Type: Array - An array containing the results of the query
Example
/* --- Returns --- */
/* TODO: Fill in */

.orderBy(fieldName)

web3data.address(hash).transactions().orderBy(fieldName) Order the returned results by the specified field. Note: Currently, only the default value is supported.

Parameters
  • fieldName | Type: String the name of the field by which to order (default value: timestamp)*
Returns
  • Type: Array - An array containing the results of the query
Example
/* --- Returns --- */
/* TODO: Fill in */

.direction(dir)

web3data.address(hash).transactions().direction(dir) The direction of which to order the results of query.

Parameters
  • dir | Type: String - The direction with which to order the results. Accepted values: asc, desc.
Returns
  • Type: Array - An array containing the results of the query
Example
/* --- Returns --- */
/* TODO: Fill in */

Websockets

.websockets()

.websockets(options)

let socket = new web3data.websocket(configObj)
socket.connect(callback/asyc await) // returns erros / connection status
socket.on(eventName, function(payload))
socket.off
socket.close
Parameters
  • None
Returns
  • Type: Object -
Example
/* --- Returns --- */
/* TODO: Fill in
Clone this wiki locally