Tangany’s Ethereum Read API

The release of Tangany Custody Suite 1.5 included a powerful engine to read historical information of wallets and smart contracts on Ethereum. This article will take a deep-dive to explore the capability of that feature from a technical perspective.

Our Read API provides four new API endpoints. The endpoints enable user-friendly browsing and reading of all transactions and events on the Ethereum blockchain.

1. Transactions

Using the route GET /eth/transactions, every transaction on the Ethereum blockchain can be searched. Different search parameters and sorting options can be provided via the URL. The result includes the number of hits found, a list of transaction hashes found, and pagination links to get further results of the same search.

Search Parameters

Individual parameters are combined and sorted in a similar way to an AND operator. A transaction search can be defined using the following parameters:

  • from: Ethereum address of a sender
  • to: a recipient’s Ethereum address
  • blocknr: filter for a specific block number
  • nonce: filter for a specific nonce
  • iserror: filter for incorrect or successful transactions (all transactions are taken into account by default)
  • sort: sorting options (by default, the latest transactions are displayed first)
  • limit: number of search results (minimum 1, maximum 100, by default 10 results are returned)
  • index: cursor of the result list (minimum 0, maximum 10000, by default the result list starts at 0)

Sorting Options

Search results can be sorted based on transaction properties. A selection of sorting options is available for this:

  • blocknr / blocknrdesc
  • from / fromdesc
  • nonce / noncedesc
  • timestamp / timestampdesc
  • to / todesc
  • value / valuedesc

Search Results

A search result always contains three values: number of hits, list of hits and pagination links. The return of a transaction search that finds no hits looks like this:

{
  hits: { total: 0 },
  list: [ ],
  links: {
   next:null,
   previous: null
 }
}

The number of search results is conveyed via the hits.total value. This can be between 0 and a maximum of 10,000.

The list value contains an array of search results. A search result is formed based on the hash of the found transaction and at least one possible link for retrieving the resource.

{
 hash: "0x1d143d9696851b5ced...",
 links: [ {
  href: "/eth/transaction/0x1d143d9696851b5ced...",
  type: "GET",
  rel: "transaction"
 }]
}

In case there is a pagination, the results include two links for the next page and the previous one.

Example

/eth/transactions?to=0xda[shortened]ec7&iserror=true&sort=valuedesc&index=100&limit=50

Here, all faulty transactions are searched for in which the transferred address is entered as the recipient. The return contains a maximum of 50 transactions, with the first 100 search results being skipped. Furthermore, the search results are sorted in descending order according to their transmitted value in ether.

2. Wallet Transactions

Using the route GET /eth/wallet/:wallet/transactions, all transactions of a wallet can be searched. This route forms a shortcut to the transaction search as all search parameters and sorting options can be used.

Without specifying parameters, the search returns the transaction history of the wallet, i.e. all incoming and outgoing transactions.

Search Parameter Direction

In addition to the transaction search, the wallet-based search offers another search parameter: direction 'in' | 'out'.

This parameter enables the filtering of search results according to incoming or outgoing transactions of the wallet without specifying specific addresses. The direction parameter cannot be used with from or to search parameters at the same time.

/eth/wallet/:wallet/transactions?direction=in, for example, returns all transactions on the wallet starting with the latest.

3. Contract Events Search

With the API endpoint GET /eth/contract/:contract/events, events of a smart contract can be searched. As with the transaction search, search parameters and sorting options can be passed to define the search.

Search Parameters

  • blocknr: filter for a specific block number
  • event: filter for a specific event (case sensitive)
  • hash: filter for a specific transaction hash
  • sort: sort options (by default, the latest events are displayed first)
  • limit: number of search results (minimum 1, maximum 100, by default 10 results are returned)
  • index: cursor of the result list (minimum 0, maximum 10000, by default the result list starts at 0)

Sorting options

  • blocknr / blocknrdesc
  • event / eventdesc
  • logindex / logindexdesc
  • timestamp / timestampdesc

Search Results

The search results contain the number of hits and pagination links found, if available. The result list is structured similarly to the transaction search. It contains an array of hits, each containing the name of the event and at least one possible link to get the resource. This URL has the respective transaction hash and log index. Since several events can be assigned to a single transaction, the log index of an event is used for unambiguous identification.

{
 "hits": {…},
 "list": [{
   "event": "transfer",
   "links": [ {
     "href": "/eth/transaction/0x2882c9[shortened]f7b852332/event/69",
     "type": "GET",
     "rel": "event"
 }]
 }],
 "links": { … }
}

4. Contract Event

If a search was carried out for smart contract events, URLs for the respective hits can be found in the search results in the following format: GET /eth/transaction/:hash/event/:index.

Individual events and their properties can be called up via this API endpoint. :index is the LogIndex of an event that is required for unambiguous identification. The return for the following request /eth/transaction/0x2925c9[shortened]b877052332/event/69 looks like this:

{
 "event": "transfer",
 "contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
 "timestamp": 1594033889,
 "transactionIndex": 80,
 "logIndex": 69,
 "blockNr": 10405547,
 "inputs": [{
    "value": "0xB364B4db2e46474B86F411E272e64B59c488e1Cc",
    "name": "from",
    "type": "address"
   }, {
    "value": "0x45E0b446f02F29B33e2E7532D84b0F99c66c6BD4",
    "name": "to",
    "type": "address"
   }, {
    "value": "400000000",
    "name": "value",
    "type": "uint256"
   }]
}

Conclusion

Reading the information on transactions and events on Ethereum can be tricky as there are various parameters that have to be included. There are also public services like Etherscan to execute the task of reading, yet it’s more useful to have only one 3rd party API to fulfill all tasks such as wallet creation, custodian service, and reading API.

For that, we at Tangany have released our own reading solution. That can be used with our existing unified API. Easy, reliable, and scalable.

Martin
Martin
Martin is one of the Co-founders of Tangany. As a Blockchain enthusiast, he loves to support various companies with their Blockchain implementation. At Tangany he is responsible for marketing, legal & regulatory and finance. Besides Blockchain Martin has a huge fable for good metal music.
Share on email
Email
Share on twitter
Twitter
Share on linkedin
LinkedIn
Share on xing
XING
Share on facebook
Facebook

What you may also like

Release Notes 1.6

With this new release, we are expanding WaaS’s capabilities to interact with Ethereum smart contracts and also introduce several quality-of-life

Read More »

Release Notes 1.5

Highlights Until now, Tangany Custody Suite was mainly focused on write access to blockchains. That included the creation of new

Read More »
Receive the latest news

Tangany Newsletter