Blockchains store data in ways most apps find difficult to access. Codefi's Fundamental API (formerly called the Alethio 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

The API is currently live on the following networks:

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 the 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"

• HTTP Basic Access Authentication: use your API key as the user name (no password)

$ curl https://api.aleth.io/v1/blocks/latest \
  -u sk_main_0123456789abcdef:
# The colon prevents curl from asking for a password

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"
    }
  }
}

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
    }
  }
}

All the blockchain resources are part a large graph of interconnected concepts. The API is translating these connections into resource relationships. There are two types of relationships:

• A to-one relationship is a link to a single other resource (e.g. there's a single from Account for any Transaction).

• A to-many relationship is a link to a collection of resources sharing the same type (e.g. there is a collection of Transactions for any given Block).

Both the to-one and to-many relationships are represented by a fully-formed URL called the related link. According to the JSON:API specificaton this will be serialized as:

{
  "transactions": {
    "links": {
      "related": "https://api.aleth.io/v1/blocks/genesis/transactions"
    }
  }
}

Additionally, only the to-one relationships will include in the response, along with the link, the identifier data of the related resource:

{
  "hasBeneficiary": {
    "data": {
      "type": "Account",
      "id": "0x0000000000000000000000000000000000000000"
    },
    "links": {
      "related": "https://api.aleth.io/v1/blocks/genesis/hasBeneficiary"
    }
  }
}

Note: In practice, the related links will be normalized to include the canonical identifier of the origin. Instead of /blocks/genesis/... (we used this in the examples above for brevity) the related links will read /blocks/0xd4e56740.../....

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.

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 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"

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

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.

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".

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.

• 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:

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 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.

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').

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.

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.