Oraclize log


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

The Oraclize service allows smart contracts to break free from their constraints by providing a trustless way to access data from the web.

Smart contract developers should not have to blindly trust Oraclize to securely and accurately transmit the data they need. Oraclize provides a proof of authenticity along with the data requested to prove that the data was transmitted untampered from the provider defined by the smart contract.

A more detailed overview of Oraclize authenticity proofs is provided in the Authenticity Proofs section of this documentation.

What is an oracle?

In a nutshell, an oracle is something (or someone) that provides data to blockchain applications that these applications cannot (efficiently) access by themselves.

Oracles are necessary because it is inefficient and often impossible to reach a decentralized consensus on centralized data.

What is Oraclize?

Oraclize is an elegant solution to the “oracle problem” and is the “state-of-the-art” oracle service. We allow blockchain applications to easily and efficiently access data from any datasource (ex. Web APIs).

This means that existing datasources can be used without needing to adapt them for the blockchain and can continue providing data via existing channels (typically a Web API).

Oraclize can be seen as an intermediary in a world designed to exist without intermediaries. While this can be seen as a “weakness”, it actually provides significant benefits. The following Rationale section details why we designed the system in this way and why this approach is so powerful


When desiging Oraclize, we initally considered reiterating the concepts of decentralized oracle systems like Orisi. We soon realized that the limitations of the decentralized approach make it basically unacceptable. Our core design philosophy required that existing datasources not have to adapt to or even understand the blockchain. We felt it was important to ensure that the datasource and oracle components of the service were separated. Our approach allows blockchain applications to interact with any datasource via standard channels, out of the box. Oraclize authenticity proofs provide strong guarantees regarding the authenticity of the data. Applications can be 100% certain that requested data is being transmitted, without modifications, from the datasource it was requested from.


Thanks to our model, you can easily leverage our service from multiple contexts. Currently, Oraclize can be used from Ethereum, Eris, Rootstock, Bitcoin, and from any non-blockchain application. As the state-of-the-art oracle service for both public and private blockchains, Oraclize can be used without limitations in pretty much any context.

General Concepts

If this then that

The Oraclize engine internally replicates the “If This Then That” logic. This means that it will execute a given set of instructions if some other given conditions are met. For example, you might want to repeatedly verify and return some data every x seconds. This is very generic and can be leveraged in many different ways.

Context abstraction

To allow Oraclize to stay as context-generic as possible, Oraclize queries must specify both a datasource and a query text. The “datasource” field tells Oraclize where to look for your data. Available datasources include “URL”, “WolframAlpha”, “IFPS”, and many others. The “query” field tells Oraclize what to fetch. An example URL query could be “” while an example WolframAlpha query could be “Who is the president of the US?”

Data and computations

Thanks to our context-generic implementation, your queries don’t necessarily need to be to Web APIs. You can query other blockchains, IPFS, WolframAlpha, and much more. You’ll find a list of supported datasources in the dedicated “Datasources” section.


Given the above, you can ask things like:

Parsing helpers

In ordet to facilitate data post-processing, we supply simple simple to use (and audit) parsing helpers. This makes it easier to return only the necessary data and decrease on-chain processing cost and complexity. Note that authenticity proofs will still reference the full, original content.

The following parsing helpers are available:

For example, when querying the Kraken API:

Authenticity Proofs

Oraclize is designed to act as an intermediary that you shouldn’t have to trust. You can easily verify the authenticity of query data returned via authenticity proofs. You’ll find more details on authenticity proofs in the “Security Deep-dive” section.

Data Privacy

Certain contexts, such as smart contracts on public blockchains, might require a level of privacy to protect data from public scrutiny. Developers can make encrypted Oraclize queries by encrypting a part (or all) of a query with the Oraclize public key.

Encrypted Queries

Developers might be interested in keeping part (or all) of their queries private. For example, you might want to keep an API key secret from the rest of a public blockchain.

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

This means your request will be encrypted before being stored in the blockchain, and that only Oraclize will be able to decrypt your request 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"

This will encrypt the query with the default Oraclize public key. You could 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"


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


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


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

You can also do this with a request to another datasource like WolframAlpha, the Bitcoin blockchain, or IPFS. Our encryption system also permits users to encrypt any of the supported datasource options.

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 Android Ledger
Random N/A N/A N/A N/A N/A N/A
WolframAlpha N/A N/A N/A
Blockchain N/A N/A
decrypt N/A N/A N/A
nested 1 3
computation 1 N/A N/A

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 rationale behind this method of securely feeding off-chain randomness into the blockchain is explained in the “A Scalable Architecture for On-Demand, Untrusted Delivery of Entropy” whitepaper.

The design described there prevents Oraclize from tampering with the random results coming from the Trusted Execution Envirnment (TEE) and protects the user from a number of attack vectors.

The authenticity proof, attached with the result, can be easily verified not just off-chain but even by any Solidity contract receiving them. The example presented here, showing how to integrate the verification process, discards any random result whose authenticity proofs don’t pass the verification process.

The randon datasource is leveraging the Ledger proof to prove that the origin of the generated randomness is really a secure Ledger device.


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, up to ~2500 chars) 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 is required.

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