Alethio API (1.5.5)

Download OpenAPI specification:Download

Introduction

Blockchains store data in ways most apps find difficult to access. Alethio's API gives you a robust and reliable way to query synthesized, indexed Ethereum data in real-time via a JSON:API compliant REST interface.

We designed the endpoints around the frequent needs and pain points of building an Ethereum-powered project. We give you access to the data you need, exactly how you need it - through a comprehensive, general-purpose data model based on EthOn with meaningful aggregation and filtering capabilities exposed via query parameters.

Here are only a few examples that illustrate the power of the API - these use cases are typically not supported by the standard Ethereum json-rpc interface:

  • Retrieve the transaction history of any Ethereum account

  • Retrieve a complete list of incoming and outgoing Ether transfers for any account - including transfers sent by smart contracts

  • Retrieve the token transfer history for any account

  • Retrieve a full map of contract messages (internal transactions) for any account and smart contract

  • Efficiently filter through the entire history of event logs emmitted by any smart contract

Networks

The API is currently live on the following networks:

Network Base URL
Ethereum Mainnet https://api.aleth.io/v1

Authentication

The API can be tested without authentication on low volumes. Unauthenticated access is throttled at ~60 req/min per IP address with a HTTP 429 response code.

For higher throughput and volumes, please register an account with Alethio's Developer Portal and use the provided API Key in one of the following supported authentication mechanisms:

  • Bearer Token via an Authorization: Bearer API_KEY header
$ curl https://api.aleth.io/v1/blocks/latest \
  -H "Authorization: Bearer sk_main_0123456789abcdef"
$ curl https://api.aleth.io/v1/blocks/latest \
  -u sk_main_0123456789abcdef:
# The colon prevents curl from asking for a password

Response format

All API responses are serialized as JSON objects and follow the conventions of the JSON:API specificaton:

  • If the response object has a data property, the request was successful and the value of the data property can be either a single object (representing a Resource) or an array of objects (representing a Collection).

  • Otherwise, the response object will have a single errors property, whose value is an array of Error objects.

The meta object

All succesful responses include a meta property along with the data property in the response object. The meta object includes helper information that can vary depending on the type of request and will be described along with the relevant functionality (e.g. the sections on Pagination and Reorg Handling).

For all API responses, however, the meta object includes a few details about the latest block of the canonical chain, as it is seen by the API at the time of the request. This can serve as an anchor for queries that ask for the most recent items of a collection (e.g. latest transactions for an account), as it defines what 'most recent' means to the API at the time of the request:

{
  "meta": {
    "latestBlock": {
      "number": 4242424,
      "blockCreationTime": 1504648858,
      "blockHash": "0x30b65c7412e887eb888abadb230171e7dc09da7bbe0f2a475c0feeed6950dc3b"
    }
  }
}

Resources

The API is organized around the concepts of Resources and Collections.

A Resource typically represents a single blockchain-related concept (e.g. Block, Transaction, Account, etc.) whereas a Collection is a group (array) of resources sharing the same type.

Each resource is uniquely dentified by its type and id. We will refer to this as the resource identifier data.

Let's take Ethereum's genesis block as an example:

curl "https://api.aleth.io/v1/blocks/genesis"

You will find the identifier data as part of the resource payload:

{
  "type": "Block",
  "id": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3"
  // ...
}

Along with the identifier data, all resources have two other types of properties:

  • attributes are static values specific to the resource

  • relationships are pointers to other (related) resources or collections

For example, the genesis block has:

{
  "attributes": {
    "number": 0,
    "blockCreationTime": 1438226773
    // ... other attibutes
  },
  "relationships": {
    "hasBeneficiary": {
      // pointer to the miner's Account
    },
    "transactions": {
      // pointer to the collection of Transactions
    }
  }
}

Multi-Resource Queries

Sometimes it's helpful to fetch a bundle of related resources with a single API request. The API enables you to do this via the include URL parameter. You can choose to include any subset of to-one relationships by providing a comma-separated list of the relationship names in the request.

Let's explore the first Ethereum transaction, along with the details of its from and to Accounts:

curl "https://api.aleth.io/v1/transactions/0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060?include=from,to"

Note the trailing include=from,to argument in the URL. This asks the API to append the related resources to the response, grouped under the included key:

{
  "data": {
    "type": "Transaction",
    "id": "0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060",
    "relationships": {
      "from": {
        "data": {"type": "Account", "id": "0xa1e4380a3b1f749673e270229993ee55f35663b4"}
        // "links" not relevant for this example
      },
      "to": {
        "data": {"type": "Account", "id": "0x5df9b87991262f6ba471f09758cde1c0fc1de734"}
        // "links" not relevant for this example
      }
    }
    // ... other Transaction details
  },
  "included": [
    {
      "type": "Account",
      "id": "0xa1e4380a3b1f749673e270229993ee55f35663b4",
      // ... other Account details
    },
    {
      "type": "Account",
      "id": "0x5df9b87991262f6ba471f09758cde1c0fc1de734",
      // ... other Account details
    }
  ]
}

An included resource will be appended to the included array one time, even if it's referenced by more than one relationship (e.g. if the from and the to Accounts would have been identical in the example above, that Account wouldn't be included twice in the array).

Note: Only the to-one relationships can be multiplexed in a single request. All to-many relationships need to be queried explicitly in separate requests. We chose this approach so we could simplify the API query logic for collection pagination and filtering.

Collection ordering

The default sorting order for all resources that directly relate to activity on a timeline (e.g. Blocks, Transactions, ContractMessages, LogEntries) is reverse chronological (most recent entries are first on the list). We chose this approach as most often than not, users are interested primarily in events or transactions that happened recently, rather than the ones that happened a long time ago.

The globalRank attribute, where present, serves as an aid to this ordering criteria, as it aggregates a hierarchy of indexes into a single composite value:

  • The block number

  • The index of a message (transaction or contract message) in the context of a block

  • The index of an event in the context of a transaction

This value allows you to sort heterogeneous collections of items chronologically, according to the relative order in which they were executed.

Filters

Filters can assist you in refining your queries and distilling the data sets down to resources that have certain properties (attributes or relationships). As a general rule, the filters are applied through the filter[NAME] URL argument. Multiple filters can be chained within a single request, as long as they're targeting different properties.

Example: Let's query the list of transactions between two specific accounts:

curl "https://api.aleth.io/v1/transactions?filter[from]=0x5A0b54D5dc17e0AadC383d2db43B0a0D3E029c4c&filter[to]=0x962f7a7146ca5527fb9bf92491da675f3d2de0d8"

Note: All collections of the same resource type have support for the same filtering parameters.

You will find a full list of supported filters for each collection type in the endpoint reference below. Please note that all filters are only listed once for each collection type, although they can be applied on related collections as well.

Examples:

  1. filter[token] is documented for the root collection /token-transfers, but can be applied to an Account's token transfers as well, for retrieving the list of TokenTransfers related to that Account, in a given Token:

    curl "https://api.aleth.io/v1/accounts/0xd6f480e6e7d75346e254db5d99efa2561d3f3288/tokenTransfers?filter[token]=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
  2. Here's how you can apply the LogEntry topic filter filter[hasLogTopics.0] to retrieve all ERC20 Approve events triggered a given block:

    curl "https://api.aleth.io/v1/blocks/8048150/logEntries?filter[hasLogTopics.0]=0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925"

Pagination

All resource collections that are exported by the API share a uniform pagination strategy.

  • The maximum number of items on a page is controlled by the page[limit] URL argument. The default value is 10 and the maximum allowed value is 100.

  • The beginning or end of the requested page is controlled by a cursor value assigned to either the page[next] or page[prev] URL arguments. Each resource has an immutable cursor attribute that can be used for this purpose.

Note: All the resources that are subject to pagination have a reverse chronological default ordering. This can make the pagination language counter-intuitive, unless you think of the items as being part of an 'activity feed' (with the most recent activity shown on the top of the list). Thus, the first (default) page will always start with the most recent items and progress towards older items. The next page will display older items than the current page, whereas the prev page will display more recent items.

  • The page[next]=cursor argument requests the next page starting immediately after cursor

  • The page[prev]=cursor argument requests the previous page ending immediately before cursor

Pages relative to a cursor

The API automatically creates links for the next and prev pages relative to the set of items included in the active (current) page, and appends these links to the response under the links property.

Let's look into the transactions of Block number 4242424:

curl "https://api.aleth.io/v1/blocks/4242424/transactions?page[limit]=2"
{
  "data": [
    // List of 2 Transaction resources:
    // - first with cursor 0x0040bbf800a60000100030b65c7412e8
    // - second with cursor 0x0040bbf800a50000100030b65c7412e8
  ],
  "links": {
    "prev": "(...) transactions?page[limit]=2&page[prev]=0x0040bbf800a60000100030b65c7412e8",
    "next": "(...) transactions?page[limit]=2&page[next]=0x0040bbf800a50000100030b65c7412e8"
  }
}

Notice how links.prev and links.next were generated to include the cursors of the first and the last items in the current page.

Note: The values set for page[limit] (along with any other filter[] applied to the current page) will be preserved in the pagination links for the next and prev pages.

For all paginated collections, the meta object assigned to the response will include a page object that provides information about the items of the next and prev pages:

  • meta.page.hasNext is a boolean value that indicates whether the next page (starting immediately after the cursor of the last item in the current page) has at least one item.

  • meta.page.hasPrev is a boolean value that indicates whether the previous page (ending immediately before the cursor of the first item in the current page) has at least one item.

Reorg Handling

Data Latency

Our data pipeline keeps track of the blockchain growth in real-time, so you get access to the most recent activity as soon as it takes place. We don't require you to wait for an arbitrary number of confirmations until you get access to the data, so you can build applications that react as quickly as possible to the on-chain events, with minimal delays for your users.

This is a powerful feature that introduces a subtle layer of complexity due to how distributed consensus works: the miners are competing for producing new blocks and sometimes the latest section of the chain becomes a stale branch because a better branch was produced by other nodes. This is also known as a "chain reorg".

Chain reorg

In the image above, the block segment P1-P2 (that was part of the canonical chain) becomes a stale branch because a better chain was created via M1-M2-M3. After the reorg took place, any transaction that was included in P1 or P2 is no longer part of the main chain (hence no longer confirmed), unless it is mined again in one of the blocks that are now part of the main chain.

Rollbacks

We designed the API to handle these situations with minimal overhead for you. The pagination cursors are reorg-safe, so you can surf through resource collections or poll for updates without worrying about data inconsistencies related to reorgs. If we detect that a subset of the items that we've given you have become stale (because the chain reorganized in between requests), we'll simply append a list of rollback items to the next response, to notify you that the status of those items is no longer valid.

In other words, if the pagination cursor that you've just sent is pointing to an item that's no longer part of the main chain, the API will do the heavy lifting by shifting the cursor back into the main chain and returning a list of rollback items whose status you might want to update.

Under the Hood

Here is a step-by-step explanation of how our data pipeline handles a pagination cursor that's pointing to a reorged block (Pc). This is purely informative and you don't need to understand it to successfully use the API, as most of this logic takes place in our backend.

Rollbacks based on a cursor

  • The API will determine A, the most recent common ancestor of Pc and the current tip of the main chain

  • Create a meta.rollback collection that includes all the relevant items on the stale branch (according to the active filters)

  • For page[next]: create a data collection that returns all the relevant items on the main chain (according to the active filters), whose block number is less than or equal to A

  • For page[prev]: same as above, but the block number needs to be strictly greater than A

Let's take a more granular example:

Paginating reorged items

Assume the active query asks for all transactions of a given account X.

The transactions matching the active query are highlighted in the image as lines inside blocks. Note that some blocks might not have any transactions related to the account X, so they are shown empty (no lines) in the image.

The cursor C points to a transaction that’s outside the main chain (block Pc).

The API will send a meta.rollback collection that includes all the transactions of X in the orange blocks.

Important: The rollback dataset won't include all transactions from all the orange blocks, but only the ones that match the active filters (in this example, only the transactions associated with the account X).

Note: The rollback dataset is not paginated, it will include all the relevant items in a single list of resource identifier objects (only the type and id is provided for each rollback item).

  • For page[next]=C, the API will send a data collection that includes the next page[limit] transactions matching the active filters, starting with (and including) block A (note that some blocks might not have any transactions for account X, in this example A and M3 don’t have matching transactions).

  • The same applies for page[prev], but with blocks higher than (and not including) A.

Here is an abstracted example for the query /accounts/X/transactions?page[limit]=3&page[next]=C in the context of the diagram above:

{
  "data": [
    {
      "type": "Transaction",
      "id": "M5-tx1",
      // ... more Transaction details
    },
    {
      "type": "Transaction",
      "id": "M4-tx1",
      // ... more Transaction details
    },
    {
      "type": "Transaction",
      "id": "M2-tx1",
      // ... more Transaction details
    }
  ],
  "meta": {
    "rollback": [
      // only the resource identifiers, no other details
      { "type": "Transaction", "id": "P6-tx1" },
      { "type": "Transaction", "id": "P6-tx2" },
      { "type": "Transaction", "id": "P4-tx1" },
      { "type": "Transaction", "id": "R1-tx1" },
      { "type": "Transaction", "id": "Pc-tx1" },
      { "type": "Transaction", "id": "Pc-tx2" },
      { "type": "Transaction", "id": "Pc-tx3" },
      { "type": "Transaction", "id": "P1-tx1" },
      { "type": "Transaction", "id": "P1-tx2" }
      // always includes the full list, no pagination
    ]
  }
}

Webhooks

Webhooks allow users to monitor any given query for updates and receive real-time notifications when new resources that satisfy the query criteria become part of the blockchain.

Motivation

Let's take the example of monitoring inbound and outbound DAI transfers for the 0x0 account.

We can use the account and token filters on the token transfers endpoint to retrieve a list of transfers, then periodically poll the links.prev link to retrieve fresh updates (the prev link asks for the previous page, which consists of more recent items than the first item in the current list).

$ curl "https://api.aleth.io/v1/token-transfers?filter[account]=0x0000000000000000000000000000000000000000&filter[token]=0x6b175474e89094c44da98b954eedeac495271d0f"
{
  "data": [
    {
      "type": "EtherTransfer",
      "id": "0x008b40460130000041007687f464fcf6",
      "attributes": {
        "transferType": "TransactionTransfer",
        "value": "0",
        "fee": "261479290958400",
        "total": "261479290958400",
        "blockCreationTime": 1576678602,
        ...
      }
    },
    ...
  ],
  "links": {
    "next": "https://api.aleth.io/v1/ether-transfers/0x0000000000000000000000000000000000000000/etherTransfers?filter%5Baccount%5D=0x0000000000000000000000000000000000000000\u0026page%5Blimit%5D=1\u0026page%5Bnext%5D=0x008b40460130000041007687f464fcf6",
    "prev": "https://api.aleth.io/v1/accounts/0x0000000000000000000000000000000000000000/etherTransfers?filter%5Baccount%5D=0x0000000000000000000000000000000000000000\u0026page%5Blimit%5D=1\u0026page%5Bprev%5D=0x008b40460130000041007687f464fcf6"
  }
}

This approach is inconvenient, as it adds a certain delay (the polling interval) and creates many requests that will result in empty responses.

With the new Webhooks system, users can register a Webhook instance that monitors a given query and sends a HTTP POST request to a configurable target URL as soon as new resources that match the query have been included in the chain.

Webhook Behavior

Each Webhook instance is associated with an underlying data query - expressed via the webhook's endpoint, filters and confirmations attributes. For the example above, the underlying query is

https://api.aleth.io/v1/token-transfers?filter[account]=0x0000000000000000000000000000000000000000&filter[token]=0x6b175474e89094c44da98b954eedeac495271d0f

and the corresponding webhook configuration is

{
  "endpoint": "/token-transfers",
  "filters": {
    "account": "0x0000000000000000000000000000000000000000",
    "token": "0x6b175474e89094c44da98b954eedeac495271d0f"
  }
}

The webhook will monitor the result set of this query and synchronize the results with the target (remote server) by keeping track of an internal cursor and pushing paginated results in two distinct stages:

  • The backfill stage: starting with the earliest (oldest) entry in the dataset, pages of maximum 100 items will be POSTed to the target URL.

  • The live stage: as soon as the entire history is synchronized, the webhook will hibernate until one (or potentially more) new items are included in the dataset as a result of a new block being appended to the chain. The webhook will then issue a POST request to the remote URL and send the new items in the body of the request.

The payload of each HTTP POST issued to the target URL will include a list of resources (under the data property) and meta information about the Webhook:

{
  "data": [
    {
      "type": "EtherTransfer",
      "id": "0x008b40460130000041007687f464fcf6",
      "attributes": {...},
      "relationships": {...}
    },
    ...
  ],
  "meta": {
    "webhook": {
      "type": "Webhook",
      "id": "006cfb85008d000010008ca21f438ee5",
      "links": {
        "self": "https://api.aleth.io/v1/webhooks/006cfb85008d000010008ca21f438ee5"
      }
    }
  }
}

Webhook Management

API users can manage their own decicated Webhooks programatically using a separate set of endpoints detailed in the Webhooks section below.

Data Model

The follwing section provides a comprehensive list of all the API endpoints and their associated responses.

The Resource data model borrows a lot from EthOn - the community-sourced Ethereum Ontology. You can use it as a secondary reference for the response schema.

Note: You can access a detailed view of each response (including descriptions of all the fields) by expanding the green pills underneath each endpoint (e.g. the expandable green area reading '200 Block').

Blocks

A Block is the basic element of a 'blockchain'. It functions as an entry in a distributed ledger, recording a series of transactions together with a reference to the previous block. A block is chained to its preceeding block by a cryptographic hash of its contents as a means of reference. Blocks contain an identifier for the final state after all transactions contained in it are validated. There is a consensus mechanism that provides incentives for nodes adding new blocks to the chain ("miners" in the Proof of Work protocol used by the main Ethereum network) that comply with the rules of Ethereum by issuing newly generated tokens ('Ether') to an account specified by the block's author.

All blocks

Returns the list of all Block resources that are currently part of the main (canonical) chain, in reverse chronological order (most recently mined first).

Responses

200

Block List

get/blocks
https://api.aleth.io/v1/blocks

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Block by hash

Returns the Block resource identified by a given block hash. The block can either be part of the current main (canonical) chain or part of a stale (reorged) branch, if the branch was visible to Alethio's network nodes at the time of the reorg.

path Parameters
blockHash
required
string <hex256>
Example: 0x40dd9a773b81b00aacdc81598d19a5beef3ab66d391cc1cea6fb083294e7a184

The block hash in hex format.

Responses

200

Block

get/blocks/{blockHash}
https://api.aleth.io/v1/blocks/{blockHash}

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Block by number

Returns the Block resource for a given block number.

path Parameters
number
required
integer
Example: 4041179

The block number.

Responses

200

Block

get/blocks/{number}
https://api.aleth.io/v1/blocks/{number}

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Block by label

Returns the Block resource for a given label (genesis or latest).

path Parameters
label
required
string
Enum: "genesis" "latest"
Example: latest

The block label.

Responses

200

Block

get/blocks/{label}
https://api.aleth.io/v1/blocks/{label}

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Block parent

Returns the Block resource representing the parent of a given block.

path Parameters
blockHash
required
string <hex256>
Example: 0x40dd9a773b81b00aacdc81598d19a5beef3ab66d391cc1cea6fb083294e7a184

The block hash in hex format.

Responses

200

Block

get/blocks/{blockHash}/parentBlock
https://api.aleth.io/v1/blocks/{blockHash}/parentBlock

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Block beneficiary

Returns the Account resource representing the beneficiary of a given block. The beneficiary of a Block is the account to which fees or mining rewards from the successful mining are transferred.

path Parameters
blockHash
required
string <hex256>
Example: 0x40dd9a773b81b00aacdc81598d19a5beef3ab66d391cc1cea6fb083294e7a184

The block hash in hex format.

Responses

200

Account

get/blocks/{blockHash}/hasBeneficiary
https://api.aleth.io/v1/blocks/{blockHash}/hasBeneficiary

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Block transactions

Returns the list of Transaction resources included in a block, sorted in reverse chronological order (descending by their globalRank attribute).

path Parameters
blockHash
required
string <hex256>
Example: 0x40dd9a773b81b00aacdc81598d19a5beef3ab66d391cc1cea6fb083294e7a184

The block hash in hex format.

Responses

200

Transaction List

get/blocks/{blockHash}/transactions
https://api.aleth.io/v1/blocks/{blockHash}/transactions

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Block contract messages

Returns the list of ContractMessage resources included in a block, sorted in reverse chronological order (descending by their globalRank attribute).

path Parameters
blockHash
required
string <hex256>
Example: 0x40dd9a773b81b00aacdc81598d19a5beef3ab66d391cc1cea6fb083294e7a184

The block hash in hex format.

Responses

200

ContractMessage List

get/blocks/{blockHash}/contractMessages
https://api.aleth.io/v1/blocks/{blockHash}/contractMessages

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Block log entries

Returns the list of LogEntry resources included in a block, sorted in reverse chronological order (descending by their globalRank attribute).

path Parameters
blockHash
required
string <hex256>
Example: 0x40dd9a773b81b00aacdc81598d19a5beef3ab66d391cc1cea6fb083294e7a184

The block hash in hex format.

Responses

200

LogEntry List

get/blocks/{blockHash}/logEntries
https://api.aleth.io/v1/blocks/{blockHash}/logEntries

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Block Ether transfers

Returns the list of EtherTransfer resources included in a block, sorted in reverse chronological order (descending by their globalRank attribute).

path Parameters
blockHash
required
string <hex256>
Example: 0x40dd9a773b81b00aacdc81598d19a5beef3ab66d391cc1cea6fb083294e7a184

The block hash in hex format.

Responses

200

EtherTransfer List

get/blocks/{blockHash}/etherTransfers
https://api.aleth.io/v1/blocks/{blockHash}/etherTransfers

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Block token transfers

Returns the list of TokenTransfer resources included in a block, sorted in reverse chronological order (descending by their globalRank attribute).

path Parameters
blockHash
required
string <hex256>
Example: 0x40dd9a773b81b00aacdc81598d19a5beef3ab66d391cc1cea6fb083294e7a184

The block hash in hex format.

Responses

200

TokenTransfer List

get/blocks/{blockHash}/tokenTransfers
https://api.aleth.io/v1/blocks/{blockHash}/tokenTransfers

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Filter by canonical status

Returns the list of Block resources filtered by their status of being included in the current canonical (main) chain produced by the consensus network. If this filter is not set explicitly set, its implicit value is true.

query Parameters
value
boolean

The boolean flag representing the canonical status to filter by.

Responses

200

Block List

get/blocks?filter[canonical]={value}
https://api.aleth.io/v1/blocks?filter[canonical]={value}

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Accounts

An Account is the superclass of all account types in Ethereum. All accounts are identified by an address (which, however, is derived differently for external and contract accounts) and an account state that contains the contract's balance and total message count, which is called its nonce. Contract accounts also have an associated storage state and EVM code. The address of an external account is derived from the public key of a public and private keypair, while a contract account address is a concatenation of the creator account's address and its nonce.

Account details

Returns the details of a given Account address.

path Parameters
address
required
string <hex160>
Example: 0x50126e8fcb9be29f83c6bbd913cc85b40eaf86fc

Account hex address.

Responses

200

Account

get/accounts/{address}
https://api.aleth.io/v1/accounts/{address}

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Account contract

Returns the Contract resource associated with a given Account.

path Parameters
address
required
string <hex160>
Example: 0x50126e8fcb9be29f83c6bbd913cc85b40eaf86fc

Account hex address.

Responses

200

Contract

get/accounts/{address}/contract
https://api.aleth.io/v1/accounts/{address}/contract

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Account transactions

Returns the list of Transaction resources associated with a given Account, sorted in reverse chronological order (most recent first). Both the transactions originating from and sent to the account are included.

This collection supports the same filters as the Transactions collection.

path Parameters
address
required
string <hex160>
Example: 0x50126e8fcb9be29f83c6bbd913cc85b40eaf86fc

Account hex address.

Responses

200

Transaction List

get/accounts/{address}/transactions
https://api.aleth.io/v1/accounts/{address}/transactions

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Account contract messages

Returns the list of ContractMessage resources associated with a given Account, sorted in reverse chronological order (most recent first). Both the contract messages originating from and sent to the account are included.

This collection supports the same filters as the ContractMessages collection.

path Parameters
address
required
string <hex160>
Example: 0x50126e8fcb9be29f83c6bbd913cc85b40eaf86fc

Account hex address.

Responses

200

ContractMessage List

get/accounts/{address}/contractMessages
https://api.aleth.io/v1/accounts/{address}/contractMessages

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Account Ether transfers

Returns the list of EtherTransfer resources associated with a given Account, sorted in reverse chronological order (most recent first). Both the transfers that were sent to or received by the account are included.

This collection supports the same filters as the EtherTransfers collection.

path Parameters
address
required
string <hex160>
Example: 0x50126e8fcb9be29f83c6bbd913cc85b40eaf86fc

Account hex address.

Responses

200

EtherTransfer List

get/accounts/{address}/etherTransfers
https://api.aleth.io/v1/accounts/{address}/etherTransfers

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Account token transfers

Returns the list of TokenTransfer resources associated with a given Account, sorted in reverse chronological order (most recent first). Both the transfers that were sent to or received by the account are included.

This collection supports the same filters as the TokenTransfers collection.

path Parameters
address
required
string <hex160>
Example: 0x50126e8fcb9be29f83c6bbd913cc85b40eaf86fc

Account hex address.

Responses

200

TokenTransfer List

get/accounts/{address}/tokenTransfers
https://api.aleth.io/v1/accounts/{address}/tokenTransfers

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Account token balances

Returns the list of TokenBalance resources associated with a given Account, sorted in alphabetical order by Token address.

This collection supports the same filters as the TokenBalances collection.

path Parameters
address
required
string <hex160>
Example: 0x50126e8fcb9be29f83c6bbd913cc85b40eaf86fc

Account hex address.

Responses

200

TokenBalance List

get/accounts/{address}/tokenBalances
https://api.aleth.io/v1/accounts/{address}/tokenBalances

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Account activity

Consolidates the activity of a given Account in a unified list of entries.

Returns an aggregated list of Transaction, ContractMessage, EtherTransfer and TokenTransfer resources, sorted in reverse chronological order.

path Parameters
address
required
string <hex160>
Example: 0x50126e8fcb9be29f83c6bbd913cc85b40eaf86fc

Account hex address.

Responses

200

Account Activity List

get/accounts/{address}/activity
https://api.aleth.io/v1/accounts/{address}/activity

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Contracts

A Contract account is an account whose behaviour is controlled by a smart contract. Contract accounts are identified by their address which is derived from the creator account's address and nonce. A contract account has a non-empty associated EVM code. It's state data consists of the bytecode, the contract's balance and the storage state of the contract's code (for example the value of variables). A contract account can only act when it is triggered by a message. It may not create and sign transactions, but it can receive transactions from external accounts as well as send and receive contract messages, which may involve a transfer of Ether. Contract accounts can also contain events which create log entries when triggered.

Contract details

Returns the Contract resource linked to a given address.

path Parameters
address
required
string <hex160>
Example: 0x2af47a65da8CD66729b4209C22017d6A5C2d2400

Contract hex address.

Responses

200

Contract

get/contracts/{address}
https://api.aleth.io/v1/contracts/{address}

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Contract account

Returns the Account resource associated with a given Contract.

path Parameters
address
required
string <hex160>
Example: 0x2af47a65da8CD66729b4209C22017d6A5C2d2400

Contract hex address.

Responses

200

Account

get/contracts/{address}/account
https://api.aleth.io/v1/contracts/{address}/account

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Contract token

Returns the Token resource that encapsulates the details of a token (supply, symbol, etc.) managed by the given Contract, if the contract code is compatible with a supported token standard.

path Parameters
address
required
string <hex160>
Example: 0x89d24a6b4ccb1b6faa2625fe562bdd9a23260359

Contract hex address.

Responses

200

Token

get/contracts/{address}/token
https://api.aleth.io/v1/contracts/{address}/token

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Contract creation block

Returns the Block resource associated with the block where the Contract was created.

path Parameters
address
required
string <hex160>
Example: 0x2af47a65da8CD66729b4209C22017d6A5C2d2400

Contract hex address.

Responses

200

Block

get/contracts/{address}/createdAtBlock
https://api.aleth.io/v1/contracts/{address}/createdAtBlock

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Contract creation transaction

Returns the Transaction resource associated with the Contract creation.

path Parameters
address
required
string <hex160>
Example: 0x2af47a65da8CD66729b4209C22017d6A5C2d2400

Contract hex address.

Responses

200

Transaction

get/contracts/{address}/createdAtTransaction
https://api.aleth.io/v1/contracts/{address}/createdAtTransaction

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Contract creation message

Returns the ContractMessage resource that triggered the Contract creation.

path Parameters
address
required
string <hex160>
Example: 0x2f6392a729b76a6a3056b44e262c70442d26d3c7

Contract hex address.

Responses

200

ContractMessage

get/contracts/{address}/createdAtContractMessage
https://api.aleth.io/v1/contracts/{address}/createdAtContractMessage

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Contract transactions

Returns the list of Transaction resources that were sent to a given Contract, sorted in reverse chronological order (most recent first).

path Parameters
address
required
string <hex160>
Example: 0x2af47a65da8CD66729b4209C22017d6A5C2d2400

Contract hex address.

Responses

200

Transaction List

get/contracts/{address}/transactions
https://api.aleth.io/v1/contracts/{address}/transactions

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Contract messages

Returns the list of ContractMessage resources associated with a given Contract, sorted in reverse chronological order (descending by their globalRank attribute). Both the contract messages originating from and sent to the contract are included.

path Parameters
address
required
string <hex160>
Example: 0x2af47a65da8CD66729b4209C22017d6A5C2d2400

Contract hex address.

Responses

200

ContractMessage List

get/contracts/{address}/contractMessages
https://api.aleth.io/v1/contracts/{address}/contractMessages

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Contract log entries

Returns the list of LogEntry resources that were logged by a given Contract, sorted in reverse chronological order (descending by their globalRank attribute).

path Parameters
address
required
string <hex160>
Example: 0x2af47a65da8CD66729b4209C22017d6A5C2d2400

Contract hex address.

Responses

200

LogEntry List

get/contracts/{address}/logEntries
https://api.aleth.io/v1/contracts/{address}/logEntries

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Transactions

A Transaction is a message between two accounts that may transfer Ether and may contain a payload. Transactions always originate from an external account that is controlled by an external actor by means of a private key. The execution of a transaction creates a 'transaction receipt'.

Transaction details

Returns the Transaction resource identified by the given hash.

path Parameters
txHash
required
string <hex256>
Example: 0x9ed4aff20ae7c029affc78c3467cc4950922bd3d0e925ea6e097cb2f7e8ccf85

Transaction hash.

Responses

200

Transaction

get/transactions/{txHash}
https://api.aleth.io/v1/transactions/{txHash}

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Transaction sender

Returns the Account resource representing the sender (from field) of a given Transaction.

path Parameters
txHash
required
string <hex256>
Example: 0x9ed4aff20ae7c029affc78c3467cc4950922bd3d0e925ea6e097cb2f7e8ccf85

Transaction hash.

Responses

200

Account

get/transactions/{txHash}/from
https://api.aleth.io/v1/transactions/{txHash}/from

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Transaction destination

Returns the Account resource representing the destinaton (to field) of given Transaction.

path Parameters
txHash
required
string <hex256>
Example: 0x9ed4aff20ae7c029affc78c3467cc4950922bd3d0e925ea6e097cb2f7e8ccf85

Transaction hash.

Responses

200

Account

get/transactions/{txHash}/to
https://api.aleth.io/v1/transactions/{txHash}/to

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Transaction block

Returns the Block resource representing the canonical block where the Transaction was included.

path Parameters
txHash
required
string <hex256>
Example: 0x9ed4aff20ae7c029affc78c3467cc4950922bd3d0e925ea6e097cb2f7e8ccf85

Transaction hash.

Responses

200

Block

get/transactions/{txHash}/includedInBlock
https://api.aleth.io/v1/transactions/{txHash}/includedInBlock

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Transaction created contracts

Returns the list of Contract resources that were created as a result of executing the Transaction (and all its descendant ContractMessage resources).

path Parameters
txHash
required
string <hex256>
Example: 0x9ed4aff20ae7c029affc78c3467cc4950922bd3d0e925ea6e097cb2f7e8ccf85

Transaction hash.

Responses

200

Contract List

get/transactions/{txHash}/createsContracts
https://api.aleth.io/v1/transactions/{txHash}/createsContracts

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Transaction contract messages

Returns the list of all ContractMessage resources that were triggered as a result of executing the given Transaction.

path Parameters
txHash
required
string <hex256>
Example: 0x9ed4aff20ae7c029affc78c3467cc4950922bd3d0e925ea6e097cb2f7e8ccf85

Transaction hash.

Responses

200

ContractMessage List

get/transactions/{txHash}/contractMessages
https://api.aleth.io/v1/transactions/{txHash}/contractMessages

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Transaction log entries

Returns the list of all LogEntry resources that were created as a result of executing the given transaction.

path Parameters
txHash
required
string <hex256>
Example: 0x9ed4aff20ae7c029affc78c3467cc4950922bd3d0e925ea6e097cb2f7e8ccf85

Transaction hash.

Responses

200

LogEntry List

get/transactions/{txHash}/logEntries
https://api.aleth.io/v1/transactions/{txHash}/logEntries

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Transaction token transfers

Returns the list of all TokenTransfer resources that were created as a result of executing the given Transaction.

path Parameters
txHash
required
string <hex256>
Example: 0x9ed4aff20ae7c029affc78c3467cc4950922bd3d0e925ea6e097cb2f7e8ccf85

Transaction hash.

Responses

200

TokenTransfer List

get/transactions/{txHash}/tokenTransfers
https://api.aleth.io/v1/transactions/{txHash}/tokenTransfers

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Filter by sender

Returns the list of Transaction resources that were sent by a given Account address, sorted in reverse chronological order (most recent first).

query Parameters
address
required
string <hex160>
Example: address=0x50126e8fcb9be29f83c6bbd913cc85b40eaf86fc

The hex address of the originator Account.

Responses

200

Transaction List

get/transactions?filter[from]={address}
https://api.aleth.io/v1/transactions?filter[from]={address}

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Filter by destination

Returns the list of Transaction resources received by a given Account address, sorted in reverse chronological order (most recent first).

query Parameters
address
required
string <hex160>
Example: address=0x50126e8fcb9be29f83c6bbd913cc85b40eaf86fc

The hex address of the destination Account.

Responses

200

Transaction List

get/transactions?filter[to]={address}
https://api.aleth.io/v1/transactions?filter[to]={address}

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Filter by account

Returns the list of Transaction resources that were either sent to or received by a given Account address, sorted in reverse chronological order (most recent first).

query Parameters
address
required
string <hex160>
Example: address=0x50126e8fcb9be29f83c6bbd913cc85b40eaf86fc

The hex address of the Account.

Responses

200

Transaction List

get/transactions?filter[account]={address}
https://api.aleth.io/v1/transactions?filter[account]={address}

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Filter by type

Returns the list of Transaction resources filtered by their message type, sorted in reverse chronological order (most recent first).

query Parameters
type
required
string
Enum: "ValueTx" "CallTx" "CreateTx"
Example: type=ValueTx

The type of the Transaction.

Responses

200

Transaction List

get/transactions?filter[msgType]={type}
https://api.aleth.io/v1/transactions?filter[msgType]={type}

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

Contract-Messages

A Contract Message is passed between a contract account and any other account (external or contract). It is the result of an execution chain originally triggered by an external eccount.

ContractMessage details

Returns the ContractMessage resource identified by the given id.

path Parameters
id
required
string
Example: msg:0xb53fdc2d618b5c35da706b399f9201721a74082fdb46ee90e487c82e422a4c8c:4

The ContractMessage ID.

Responses

200

ContractMessage

get/contract-messages/{id}
https://api.aleth.io/v1/contract-messages/{id}

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{}

ContractMessage sender

Returns the Account resource representing the sender of a given ContractMessage.

path Parameters
id
required
string
Example: msg:0xb53fdc2d618b5c35da706b399f9201721a74082fdb46ee90e487c82e422a4c8c:4

The ContractMessage ID.

Responses

200

Account

get/contract-messages/{id}/from
https://api.aleth.io/v1/contract-messages/{id}/from

Response samples

Content type
application/vnd.api+json
Copy
Expand all Collapse all
{