Oraclize log


Oraclize aims to be the privileged carrier for data between blockchain protocols and the wider Internet.

Our main goal as a company is to provide a way for smart contracts to break free of their constrains and provide them the ability to access all the data they need from the web, without compromising their trustless nature.

In particular, the aim is not to force smart contract developers in having to trust Oraclize with the data they need. Without any backing of authenticity, Oraclize could easily tamper with the data. This is why, in order to complete this complex task, Oraclize returns the data requested along with a proof of the authenticity: i.e that the data comes from the data provider which has been explicity demanded by the smart contract.

More can be read about the authenticity proofs provided by Oraclize, within the dedicated section of this documentation.

What is an oracle

The very definition of oracle defines what such entity does, but not who it is. Different actors are calling themselves oracle and this has lead users over time to a confused idea around the actual meaning of the term. For the sake of an easy but genuine understanding of what follows, we can define it as the party who provides to the blockchain some data that blockchain applications cannot access by themselves.

In general, the reason why the blockchain cannot reach out to external data is that it is inefficient and often impossible to find a decentralized consensus on a centralized data.

What is Oraclize

Oraclize is an elegant solution to the “oracle problem”. We are the “state-of-the-art” oracle service and we enable any datasource (Web APIs, ..) to be used straight away from different blockchain applications.

This means that the datasources don’t need to adapt or understand the blockchain and they can keep providing their data via the channels they already have (tipically their own Web APIs).

Ironically, Oraclize can be seen as a new intermediary in a new world built without intermediaries. While this could be seen as a weakness, it really doesn’t. To understand more on how we ended up designing the system in this way and why this approach is so powerful, please read the next paragraph.


While our initial thoughts were reiterating over the concepts of a decentralized oracle system like Orisi, we soon figured out that the limits of that approach were not really acceptable. In order to stay agnostic to the data itself, it is important to keep the datasource and oracle parts separated. Sticking with that means that the blockchain integration is not something the datasource has to figure out on his side. Thanks to our approach, any datasource can be used out of the box in any context, while removing all the potential risks of putting an extra intermediary into the game. The authenticity proofs we provide can give strong guarantees around the authenticity of data. This means that while the data is sent to the blockchain by us, you can be 100% sure that it is coming, without modifications, from the datasource you have chosen.


Thanks to our model, you can easily leverage our service from different context: at the time being you can use Oraclize from Ethereum, Eris, Roostock, Bitcoin and from any non-blockchain application. Working with both public and private blockchains, Oraclize is a service you can use without limitations on pretty much any context you have in mind.

General Concepts

If this than that

The Oraclize engine replicates internally the “If This Than That” logic. This means that a given set of instructions is given to it and in the case the conditions are met, something you have described will happen. A typical scneario is the recurrent verification of a certain data and it being returned just when a given threshold is reached. This is very generic and can be leveraged in different ways.

Context abstraction

Oraclize wants to stay as generic as possible in regards of the context. This is why each Oraclize query have to specify a datasource and a query text. The datasource is the source of data you want the query to be asked to, the query text is a unique reference to the data you want which is written in a way the datasource can understand.

Data and computations

Thanks to the datasource being generic, it does not need to be a Web API necessarly. It can even be something completely different like an individual, a judge/jury or a piece of code. You can look at the list of the supported datasources in the dedicated section to know more about the datasource we currently support.


Given the above, you can ask things like:

Parsing helpers

In order to facilitate the post-processing of data, some simple to use (and simple to audit) parsing helpers are available. This means you can filter down the results coming from the datasource in a way that only the data you need is sent back to you. Note that the authenticity proof will still reference the full content.

The following parsing helpers are available:

Authenticity proofs

While Oraclize acts as an intermediary, you don’t need to trust it. You can easily verify the authenticity of the data provided thanks to the use of authenticity proofs. You can find more details on that in the “Security Deep-dive” section.

Data privacy

In some context, like smart contract living on the blockchain, you might require some level of privacy to protect your data from public scrutiny. This is possible thanks to the use of encrypted queries. What in means is that you can encrypt with the Oraclize public key your queries, or part of them, so that the level of privacy your application has is fully dependant on your will.

Encrypted Queries

There are some use cases where you are interested in not disclosing your clear text query to the blockchain: for example, if your query includes some API secret credentials.

One option is to encrypt the entire query using Oraclize public key 044992e9473b7d90ca54d2886c7addd14a61109af202f1c95e218b0c99eb060c7134c4ae46345d0383ac996185762f04997d6fd6c393c86e4325c469741e64eca9

This means your request will be stored in the blockchain in an encrypted form and that only Oraclize will be able to decrypt it by using its paired private key.

To encrypt the query, you can use our python script (you can find it here).

The CLI command to encrypt an arbitrary string of text is then:

python -e -p 044992e9473b7d90ca54d2886c7addd14a61109af202f1c95e218b0c99eb060c7134c4ae46345d0383ac996185762f04997d6fd6c393c86e4325c469741e64eca9 "YOUR QUERY"

It will encrypt the query with the default Oraclize public key. You can then use the encrypted string to query Oraclize in an on-chain Ethereum smart contract.

// here we specify the encrypted formula directly

In this case, we have encrypted the following string json(, which uses the JSON helper to parse the API response, but in the query you can specify any datasource and helper that you want. The example uses a public API, but you can use any private API that only require a secret user key authentication method.

The encryption method is also available for POST requests: you can encrypt both the URL and the POST data field as in the following example:

// This is the query that we want to encrypt
  '{"postcodes" : ["OX49 5NU", "M32 0JG", "NE30 1DP"]}')

Encrypt the datasource (URL in this case):
python -e -p 044992e94... "URL"

Result in:

Encrypt the argument(in this case we are using JSON parse helper to retrieve the “status” ):
python -e -p 044992e94... "json("

Result in:

Encrypt the JSON (third argument, the data to POST):
python -e -p 044992e94... '{"postcodes" : ["OX49 5NU", "M32 0JG", "NE30 1DP"]}'

Result in:

// Finally we add all the encrypted text 
// to the oraclize_query (in the right order)
  y2v4+b5+vN8yLIj1trS7p1l341Jf66AjaxnoFPplwLqE=", "BF5u1td9ugoacDabyfVzoTxPBxG

Another use case may be a request from a datasource, as WolframAlpha, Bitcoin blockchain or IPFS. Our encryption system also permits users to encrypt any of the supported datasource option.

Chosen Encryption Scheme

To protect your encrypted queries, we have chosen an Elliptic Curve Integrated Encryption Scheme composed of the following algorithms:


We list here the data-sources you can choose from when using our oracle service.
Please note that datasource selection is not case-sensitive.

Datasource Distributions Proof type
Ethereum Mainnet
Ethereum Morden HTTP API
None TLSNotary
WolframAlpha N/A
decrypt N/A
nested 1 3
computation 1

1 Still experimental

2 Still experimental, will be available on mainnet once it’s stable

3 Depending on the datasources you choose in sub-queries, proofs may be provided for each of them, but not for the aggregation itself


The most generic data-source we provide is the URL one, which can be used to access any public API or page on the Internet. As a first step you need to provide the actual URL whose HTTP GET / POST output you want Oraclize to fetch; and optionally the query-string parameters. Oraclize will forward you the response, while optionally attaching the TLSNotary proof.


The WolframAlpha data-source lets you specify as argument a query to submit to the WolframAlpha knowledge engine. Oraclize will send you back the primary response as a string if any.


The Blockchain data-source provides you with easy access to blockchain-related data. You can see this data-source as a shortcut to common block explorer APIs, but with a built-in easy-to-use syntax. Possible query arguments are:


The IPFS data-source can be used to retrieve the content of a file on the IPFS protocol.

This datasource expects you to specify the IPFS multihash in the query i.e. QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o will return "hello world\n" (note that in this case we have a terminating new line because the original IPFS file had it).

Please note that if we fail to fetch the IPFS content within 20 seconds, such request will fail.


Even though the decrypt datasource can be used as any other, it was specifically designed to be used within the nested datasource to enable partial query encryption.

The result is the decrypted query string. Please note that all the logic, limitations and tools provided by the Encryption feature do apply here with no modification.


The nested datasource is a meta datasource, it does not provide access to additional services. It was designed to provide a simple aggregation logic, enabling a single query to leverage sub-queries based on any available datasource and producing as result a single string.

The query format is built in a way you can specify a sub-datasource and a sub-query as follows: [datasource_name] query_content.

Please mind the square brakets delimiting the datasource name and the whitespace prefixing the actual sub-query. The sub-query content can optionally be delimited by either single or double quotes.

You can optionally specify more than one sub-query, by using as delimitators the ${ special opener and the } special closer.

Example: [WolframAlpha] temperature in ${[IPFS] QmP2ZkdsJG7LTw7jBbizTTgY1ZBeen64PqMgCAWz2koJBL}


The computation datasource enables the auditable execution of a given application into a secure blockchain-unrelated (off-chain) context.

Such application has to print the query result on the last line (on standard output) before its quits. The execution context has to be described by a Dockerfile, where building and running it should start your main application straight away. The Dockerfile initialization + your application execution should terminate as soon as possible: the maximum execution timeout is ~5 minutes on an AWS t2.micro instance.

As the query is the IPFS multihash of a zip archive containing such files (Dockerfile + any external file dependencies, the Dockerfile has to be places in the archive root), you should take care of preparing such archive and pushing it to IPFS beforehand.


  1. Dockerfile content:

  1. zip

  2. ipfs add

    • Output: added QmRxtL9K2de7v7QBYCCrwcjZHjYmuKggZ8xaqZ6UUWvd1s
  3. our query argument is QmRxtL9K2de7v7QBYCCrwcjZHjYmuKggZ8xaqZ6UUWvd1s and the query result will be 72


Public chains

Oraclize is integrated natively with the most widely used public blockchain instances like the Ethereum, Bitcoin, Rootstock mainnets and testnets.

Private chains

By using the Oraclize stargate tool it is possible to connect any private blockchain instance to the Oraclize engine.


Thanks to the features provided by the oraclize-lib, it is possible to fully leverage the Oraclize service potential in any non blockchain context as well.

⚶   Ethereum

The following is meant to be a short but complete introduction to explain how the interfacing of an Ethereum contract with Oraclize actually works. To better profit from the documentation, previous knowledge of Solidity, the most used smart contract language on Ethereum, is required.

All the reference code used is written in Solidity, but since the interface would be the same for any other language.

Sending a query to Oraclize means sending a contract call, also called internal transaction, to the on-chain Oraclize contract.

With that, Oraclize will:

Note that the transaction sent back by Oraclize can trigger any status change in the calling contract, and can include the sending of another query to Oraclize. What can be done in the __callback method is only bounded by the block gas limit.

Getting Everything on Track

First, place usingOraclize contract into your code. You do not need to import the OraclizeI and OraclizeAddrResolverI contract interfaces as this is taken care of.

The purpose of the usingOraclize contract is to make calls to OraclizeI and OraclizeAddrResolverI as painless as possible for you. However, if you know what you are doing, you are free to call our OraclizeI and OraclizeAddrResolverI interfaces directly. The upside is that you would spend a lower amount of gas for contract deployment. The downside is that if anything goes wrong a throw is raised.

In order to simplify the use of our API, we highly recommend that you simply extend the usingOraclize contract and use its inherited methods, about which we discuss below. Indeed, these methods already handle payments and API calls correctly.

All the code you need is found here After making your contract extend usingOraclize, it would look like:

import "";

contract YourContractName is usingOraclize {

    function YourContractName() {


Simple Query

Note: All the code written here assumes that you have already included all the necessary code as described in the paragraphs above, and that your contract already extends our usingOraclize contract (if you are using Solidity).

When sending a query to Oraclize you have to specify at least two arguments:

More information about these can be found in the Overview document.

An example code might look like this:

oraclize_query("WolframAlpha", "random number between 0 and 100");

This code example will ask Oraclize to send you back immediately a transaction with the primary result (as a string) of the given formula (“random number between 0 and 100”) fetched from the data-source “WolframAlpha”.

Similarly, you can use any other data-source, here we list some examples:

oraclize_query("URL", "")
oraclize_query("IPFS", "QmdEJwJG1T9rzHvBD8i69HHuJaRgXRKEQCP7Bh1BVttZbU")
  the only data-source accepting 2 string arguments is
  'URL' when we want it to send an HTTP POST request
  with the 2nd argument being the query-string we want
  to send to the given server.

  note that when the 2nd argument is a valid JSON string
  it will be automatically sent as JSON
oraclize_query("URL", "json(",

Schedule a Query in the Future

If you want Oraclize to execute your query at a scheduled future time, just specify the delay (in seconds) from the current time or the timestamp in the future as first argument.

Please note that in order for the future timestamp to be accepted by Oraclize it must be within 60 days from the current time.

// get the result from the given URL 60 seconds from now
oraclize_query(60, "URL",
// get the result from the given datasource at the specified timestamp in the future
  "WolframAlpha", strConcat("flight ", flight_number, " landed"));

Recursive queries

Thanks to the service offered by Oraclize, you can have a smart contract being effectively autonomous. If your __callback method implements a recursive call (meaning that a new oraclize_query is initiated there), the contract will start interacting with Oraclize in a continuos manner.

This can be useful to implement periodic updates of some on-chain reference data (like price feeds) or to periodically check for some off-chain conditions.

The query ID

Every time you call oraclize_query(...), it returns you a unique ID that represents your query. Whether you store this ID for future reference is up to you.

// get the result from the given URL 60 seconds from now
bytes32 myid = oraclize_query(60, "URL",

Callback Functions

Once your result is ready, Oraclize will send a transaction back to your contract address, and invoke 1 of these 3 methods:

Here are some handling examples:

function __callback(bytes32 myid, string result) {
    if (msg.sender != oraclize_cbAddress()) {
      // just to be sure the calling address is the Oraclize authorized one
    ETHXBT = result; // doing something with the result..
    // new query for Oraclize!
    bytes32 myid = oraclize_query(60, "URL",

In the snippet above we call oraclize_query again within the __callback function. In effect, this makes the contract receive automatically __callback every minute forever. Or at least, until you run out of funds!

Note that myid can be used to implement different behaviours into the __callback function, in particular when there is more than one pending call from Oraclize.

Custom Gas

The transaction originating from Oraclize to your __callback function costs gas, just like any other transaction. However, as you learned earlier, you need to cover Oraclize for this gas cost, and the oraclize_query function helpfully handles that. It defaults at 200,000 gas.

This return gas cost is actually in your control since you write the code in the __callback method, and as such, can estimate it. So, when placing a query with Oraclize, you can also specify how much the gasLimit should be on the __callback transaction. Note however that, since Oraclize sends the transaction, any unspent gas is returned to Oraclize, not you.

If the default, and minimum, value of 200,000 gas, is not enough, you can increase it by specifying a different gasLimit in this way:

// Oraclize will use a 500k gasLimit for the callback transaction, instead of 200k
oraclize_query("WolframAlpha", "random number between 0 and 100", 500000);
// you can set both custom timestamp/delay and custom gasLimit
oraclize_query(60, "WolframAlpha", "random number between 0 and 100", 500000);

Note also that if you offer too low a gasLimit, and your __callback method is long, you may never see a callback.

Authenticity Proof

In order to get, or not, the TLSNotary proof back from Oraclize you need to specify the proofType and proofStorage. You do this by calling:

You may execute this method just once, for instance in the constructor, or at any other time, if, for instance, you need the proof for certain queries only.

proofStorage_IPFS means that Oraclize will:

The proof string is exactly the IPFS multihash that identifies your TLSNotary proof, so you can fetch it for example at

Note: There might not always be a TLSNotary proof for your query, depending on the data source you have chosen

Here is an example:

import "";

contract YourContractName is usingOraclize {

    function YourContractName() {
        oraclize_setProof(proofType_TLSNotary | proofStorage_IPFS);

    function __callback(bytes32 myid, string result, bytes proof) {
        if (msg.sender != oraclize_cbAddress()) throw;


More Examples

You can have a look at more complete and complex examples by heading to our dedicated github repository:

Random Utilities

Since the callback transaction always provides results as strings, the Solidity API helpers also include some convenience functions, which might prove useful to you. Especially since Solidity does not provide any official “standard Library” yet.

You can check them out here.

Best Practices

import "";

contract YourContractName is usingOraclize {

    mapping(bytes32=>bool) myidList;

    function YourContractName(){

    function __callback(bytes32 myid, string result) {
        if(msg.sender != oraclize_cbAddress()) throw;
        if(myidList[myid]==true) {
          // check if this myid was already processed before
        myidList[myid] = true; // mark this myid (default bool value is false)


What follows are some practical tips we recommend you to use when writing Oraclize-based smart contracts:

⚝   Rootstock

The Oraclize integration with Roostock is fully compatible with the one we have with Ethereum, please refer to that one.

☉   Eris

The Oraclize integration with Eris is fully compatible with the one we have with Ethereum, please refer to that one.

⛬   Bitcoin

The Oraclize integration with Bitcoin works in a very different way compared to the Ethereum one - we plan to document it in the coming weeks, stay tuned!

Development Tools

Test query

The TestQuery page can be used to test any Oraclize query. This does not require any code to be written and can be useful to verify the correctness of a given query during the early development stage.

Network Monitor

The Network Monitor, along with the Proof Verification Tool, can be used to verify the integrity and correctness of the authenticity proofs Oraclize has provided.

It is very important to verify independently that those proofs are valid, as this is the only way you can verify if Oraclize has ever provided a wrong answer.


In order to use the encryption-enabling features of Oraclize, you can use tools like the TestQuery page or the Python Encryption Tool. Keep in mind that every time you need to use the same encrypted content in a different Oraclize context (like a different Ethereum contract or a different Oraclize contract), you will need to generate and use a different encrypted string; this is to prevent replay attacks.


If you need to use Oraclize in a private testnet, the Stargate tool enables a full integration of the service in your private context. You can find more information on how to use it in the dedicated section of the documentation.


The Oraclize browser-solidity plugin enables you to test Ethereum Oraclize-based contracts straight from your browser (in “VM mode”), with no need for you to install or setup anything. This is a very handy tool to use fo development.

Ethereum Studio plugin

If you are familiar with the Ethereum-Studio IDE, you can follow the short tutorial Ether-camp provides to enable the Oraclize plugin and test your Oraclize-based contracts straight from there.

Truffle & ethpm

When testing your Oraclize-based contracts with Truffle, you can fully benefit from our ethpm integration and use download the oraclizeAPI Solidity contract by just typing ethpm install oraclize.


Oraclize-lib is an handy nodejs library that you can use to build applications based on the top of the Oraclize service. Note that this is no dependant to the blockchain in any way!

Security deep-dive

As digital technologies have reduced the barrier to entries for information creation and distribution, it has become extremely important to be able to authenticate a piece of information as originating from a known, trusted source.

In the context of web technologies, authentication is provided by the HTTPS protocol, an extension of the HTTP protocol which create an encrypted and authenticated channel between the client and the web-server containing the data.

When dealing with data which could be used to determine different financial transactions, authentication becomes of fundamental importance. Unfortunately, the most used and available blockchain protocols have no direct way of interacting with HTTPS and therefore digesting authenticated data. It would seem then that there is a need for a trusted service which can provide this data or complete actions based on it; but that would in part defeat the point of having a decentralized protocol for exchanging value without trusted parties.

This is the reason why Oraclize has been designing systems for authenticating data and made it part of its core business. These systems are called authenticity proofs, which enable auditability of the oracle’s service record in delivering untampered data. The authenticity proofs leverage different attestation technologies: some are software-based and some rely on trusted hardware technologies.

Authenticity proofs

TLSNotary Proof

The TLSNotary Proof leverages a feature of the TLS 1.0 and 1.1 protocols which enables the splitting of the TLS master key between three parties: the server, an auditee and an auditor. In this scheme, Oraclize is the auditee while a locked-down AWS instance of a specially-designed, open-source Amazon Machine Image acts as the auditor. The TLSNotary protocol is an open-source technology, developed and used by the PageSigner project.

Android Proof

The Android Proof is a result of some of Oraclize’s internal R&D work. It leverages software remote attestation technology developed by Google, called SafetyNet, to validate that a given Android application is running on a safe, non-rooted physical device, connected to Oraclize’s infrastructure. It also remotely validates the application code hash, enabling authentication of the application running on the device. The application code is open-source, thereby enabling auditability and verification of the code hash. The Android Proof goes further, by using the newly introduced Android Hardware Attestion to prove that the physical device is updated to the latest available Android version, further ensuring integrity by having any potential exploits within the system patched. Furthermore, it verifies that the device’s Root-of-Binding-Trust is valid. Both these technologies together effectively turn the physical Android device into a provably-secure environment in which an untampered HTTPS connection to a remote datasource can be initiated. For Oraclize or an external attacker with unauthorized gained access to the infrastructure to compromise the device and generate a false but valid proof, a zero-day exploit unbeknownst to Google must be discovered by said party, which either breaks the Android sandboxing model or is a kernel-level exploit, of the latest version of Android OS and its available security patches. You can access more information about the Android Proof by reading the white paper on it and experiment with it on the Ethereum and Bitcoin testnets. The enabling of the Android Proof on mainnet is pending based on an update by Google, effectively enabling Android Nougat Hardware Attestation.

Storage and Delivery

The authenticity proofs may be relatively large files, of up to a few kilobytes. Delivering such proofs directly within the result of the data payload in an Ethereum transaction can get quite expensive, in terms of EVM execution costs, and may even be impossible for larger data.

Moreover, Oraclize strives to be blockchain agnostic, enabling the proof to be used even on Bitcoin and other blockchains. Therefore the proof is uploaded and saved to IPFS, a decentralized and distributed storage system. In providing a pointer to the content, IPFS uses a custom hashing algorithm called multihash. The resulting address is Base64 encoded and it’s a unique ID specific to the file which can be used to access it globally, and changes along with any edits to the file contained.

IPFS, by itself, doesn’t provide any long-term guarantees of persistency, however as part of Oraclize’s infrastructures it runs the IPFS persistence consortium. Anyone can join Oraclize’s consortium and help in keeping an independent copy of all the proofs by pointing a IPFS persistence consortium node to the following aggregation peer: QmSsSSfJAJwj3jsNfzbSrxtLAjhpYPjbUEsCQT8mWVgBiL


The use of Oraclize APIs requires the payment of a small fee, you can check out the pricing for each integration below:


The fee for Ethereum comes on top of the reimbursement for the full gasLimit we are setting in the transaction when we call back your contract.

Free calls

In order to make the testing of our service a little bit easier (and cheaper) to you, the first Oraclize query call coming from any Ethereum address is completely free of charge. This means we are even covering the callback transaction gas costs for you (up to the default gasLimit of 200k gas).

This might be helpful, for example, to send the first call to Oraclize directly from your contract constructor function without having to create your contract with an attached amount of Wei. This means, again, that you can have one free triggering transaction for any date in the future (up to 60 days).

Call fees

Payment is part and parcel of the oraclize_query function call, and our pricing model is simple. It’s composed of two parts:

Datasource Base price Proof type
None TLSNotary
URL 0.01$ +0.0$ +0.04$
Blockchain 0.01$ +0.0$ +0.04$
WolframAlpha 0.03$ +0.0$ N/A
IPFS 0.01$ +0.0$ N/A