NAV
Oraclize log
Oraclize
Solidity Serpent

Overview

Oraclize is a provably-honest oracle service enabling smart contracts to access the Internet.

We are platform-agnostic and provide an abstraction interface to all the major smart-contracts-capable platforms out there (Bitcoin and Ethereum at the time of writing). We think that it’s just by throwing tons of meaningful data into the blockchain jar that the smart contracts industry can flourish and many useful applications can finally come to life.

While any platform is providing access to on-chain data only, Oraclize provides them with an interface to any data-feed on the Internet.

This documentation covers our API integration with the Ethereum platform.

The documentation covering our HTTP API and the Bitcoin integration are coming soon.

Problem

Even though the oracle concept, in the blockchain sense, has been around for a while, we haven’t seen any advanced implementations. All implementations were nothing more than proof of concepts or of very limited use in themselves.

One of the reasons for this failure to provide a proper oracle service is that trying to build a distributed oracle network where nodes attempt to find consensus to a specific query is very hard and needs a proper inter-oracle communication protocol (which Orisi was a first attempt to build) rather than merely a convincing incentive for the oracles not to lie.

How does an oracle work

An oracle, in the blockchain sense, is a third party which sends to your on-chain smart contract some specific data your smart contract code cannot fetch by itself. As the oracle is a centralized party, you shouldn’t take its response for granted.

For example, if you ask an oracle to give you the last trading price of ETH/USD the oracle needs to fetch this data from some exchanges on the Internet and than send this data back to you. While doing this the oracle might compromise the exchange data and send back to you a compromised value. This is the reason why, by itself, the oracle cannot be trusted. It is important to trust the data-feed provider (in our example this is the exchange trading the ETH/USD pair) but this can easily be mitigated by using different data-sources and using them to determine consensus.

However, how can we trust the oracle not to alter this data in the first place? This is achievable using the same mitigation technique we just explained above for data-sources or by using a cryptographic proof such as the TLSNotary one.

Our solution

Oraclize wants to fill in this industry gap by providing an oracle service which is as generic as possible. We are not trying to build the Internet here but to provide a good compromise instead.

Although we are a centralized service we share the vision behind decentralized networks and we understand how reputation is key which is why we are providing a provably-honest service too.

Datasources

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
URL
WolframAlpha N/A
Blockchain
IPFS 1 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

URL

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.

WolframAlpha

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.

Blockchain

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:

IPFS

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.

decrypt

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.

nested

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}

computation

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.

Example:

  1. Dockerfile content:

  1. zip -rarchive.zip.

  2. ipfs add archive.zip

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

Additional Features

Parsing helpers

In order to make things simpler to handle on the smart-contract side, you can provide the URL inside one of the following parsing helpers:

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 encrypted_queries_tools.py python script (you can find it here).

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

python encrypted_queries_tools.py -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
oraclize_query("URL","AzK149Vj4z65WphbBPiuWQ2PStTINeVp5sS9PSwqZi8NsjQy6jJLH765qQu3U/bZPNeEB/bYZJYBivwmmREXTGjmKJk/62ikcO6mIMQfB5jBVVUOqzzZ/A8ecWR2nOLv0CKkkkFzBYp2sW1H31GI+SQzWV9q64WdqZsAa4gXqHb6jmLkVFjOGI0JvrA/Zh6T5lyeLPSmaslI");
# here we specify the encrypted formula directly
oraclize_query("URL","AzK149Vj4z65WphbBPiuWQ2PStTINeVp5sS9PSwqZi8NsjQy6jJLH765qQu3U/bZPNeEB/bYZJYBivwmmREXTGjmKJk/62ikcO6mIMQfB5jBVVUOqzzZ/A8ecWR2nOLv0CKkkkFzBYp2sW1H31GI+SQzWV9q64WdqZsAa4gXqHb6jmLkVFjOGI0JvrA/Zh6T5lyeLPSmaslI");

In this case, we have encrypted the following string json(https://poloniex.com/public?command=returnTicker).BTC_ETH.last, 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
oraclize_query("URL","json(https://api.postcodes.io/postcodes).status",'{"postcodes" : ["OX49 5NU", "M32 0JG", "NE30 1DP"]}')
# This is the query that we want to encrypt
oraclize_query("URL","json(https://api.postcodes.io/postcodes).status",'{"postcodes" : ["OX49 5NU", "M32 0JG", "NE30 1DP"]}')

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

Result in:
BEIGVzv6fJcFiYQNZF8ArHnvNMAsAWBz8Zwl0YCsy4K/RJTN8ERHfBWtSfYHt+uegdD1wtXTkP30sTW+3xR3w/un1i3caSO0Rfa+wmIMmNHt4aOS

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

Result in:
BNKdFtmfmazLLR/bfey4mP8v/R5zCIUK7obcUrF2d6CWUMvKKUorQqYZNu1YfRZsGlp/F96CAQhSGomJC7oJa3PktwoW5J1Oti/y2v4+b5+vN8yLIj1trS7p1l341Jf66AjaxnoFPplwLqE=

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

Result in:
BF5u1td9ugoacDabyfVzoTxPBxGNtmXuGV7AFcO1GLmXkXIKlBcAcelvaTKIbmaA6lXwZCJCSeWDHJOirHiEl1LtR8lCt+1ISttWuvpJ6sPx3Y/QxTajYzxZfQb6nCGkv+8cczX0PrqKKwOn/Elf9kpQQCXeMglunT09H2B4HfRs7uuI

// Finally we add all the encrypted text 
// to the oraclize_query (in the right order)
oraclize_query("BEIGVzv6fJcFiYQNZF8ArHnvNMAsAWBz8Zwl0YCsy4K/RJTN8ERHfBWtSfYHt+uegdD1wtXTkP30sTW+3xR3w/un1i3caSO0Rfa+wmIMmNHt4aOS","BNKdFtmfmazLLR/bfey4mP8v/R5zCIUK7obcUrF2d6CWUMvKKUorQqYZNu1YfRZsGlp/F96CAQhSGomJC7oJa3PktwoW5J1Oti/y2v4+b5+vN8yLIj1trS7p1l341Jf66AjaxnoFPplwLqE=","BF5u1td9ugoacDabyfVzoTxPBxGNtmXuGV7AFcO1GLmXkXIKlBcAcelvaTKIbmaA6lXwZCJCSeWDHJOirHiEl1LtR8lCt+1ISttWuvpJ6sPx3Y/QxTajYzxZfQb6nCGkv+8cczX0PrqKKwOn/Elf9kpQQCXeMglunT09H2B4HfRs7uuI")
# Finally we add all the encrypted text
# to the oraclize_query (in the right order)
oraclize_query("BEIGVzv6fJcFiYQNZF8ArHnvNMAsAWBz8Zwl0YCsy4K/RJTN8ERHfBWtSfYHt+uegdD1wtXTkP30sTW+3xR3w/un1i3caSO0Rfa+wmIMmNHt4aOS","BNKdFtmfmazLLR/bfey4mP8v/R5zCIUK7obcUrF2d6CWUMvKKUorQqYZNu1YfRZsGlp/F96CAQhSGomJC7oJa3PktwoW5J1Oti/y2v4+b5+vN8yLIj1trS7p1l341Jf66AjaxnoFPplwLqE=","BF5u1td9ugoacDabyfVzoTxPBxGNtmXuGV7AFcO1GLmXkXIKlBcAcelvaTKIbmaA6lXwZCJCSeWDHJOirHiEl1LtR8lCt+1ISttWuvpJ6sPx3Y/QxTajYzxZfQb6nCGkv+8cczX0PrqKKwOn/Elf9kpQQCXeMglunT09H2B4HfRs7uuI")

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:

Security

Since Oraclize acts as a data carrier, the service could potentially tamper the result and provide some wrong data (different from the one provided by the chosen datasource). In order to avoid this dishonest behaviour, we optionally provide cryptographic proofs showing that this didn’t happen.

These honesty proofs, as we call them, are generated via different methodologies (based on different forms of SW/HW attestation) which provide you strong authenticity guarantees.

Some of those proofs are based on external projects we leverage, while others were designed by us in-house in order to make our service more and more secure.

We are listing here the honesty proofs that Oraclize provides. Other than the original TLSNotary-based one, we have others in the workings which will be released in the coming weeks.

Proofs Storage & delivery

IPFS

In some circumstances you might want to avoid including the raw proof data into your response. One reason could be the fact that the delivery method you choose is expensive (i.e.: Ethereum transactions). IPFS can be used as storage & delivery method, by making the proof data both permanent and persistent.

IPFS enables the permanence of the proof data by design. This means that your query result can include the multihash of the proof data only, while the actual content can be pinned to IPFS nodes and float around the network whenever you try reaching such a multihash-addressed content.

IPFS doesn’t provide by itself any persistency guarantee, however we run as part of our infrastructure a IPFS persistence consortium.

You can help in keeping an independent copy of our proofs data by pointing your IPFS persistence consortium node to the following aggregation peer: QmSsSSfJAJwj3jsNfzbSrxtLAjhpYPjbUEsCQT8mWVgBiL

TLSNotary proof

TLSNotary is a project implementing a modification of TLS. By using it you can prove that a certain server has really sent some data to you at a given point in time.

Pagesigner is a TLSNotary-based system which is designed to generate a distributable proof that anybody can use to indipendently verify the authenticity of a TLS response.

Oraclize provides the above proof, along with the result, so that you can be 100% sure that we are behaving honestly and that our response is really coming from a certain server at a specific time.

Android proof

In this whitepaper, we present a new experimental proof-of-honesty which uses a physical Android device as a secure environment for creating successful HTTPS connections. Guarantees of security, as well as the capability to prove this security to a third party, come from the use of SafetyNet Software Attestation and Android Hardware Attestation. SafetyNet provides guarantees that root certificate authorities have not been tampered with, and Android Hardware Attestation provides proof that the private key used to sign the data is hardware-backed, that the device is updated, and that the device’s Root-Of-Binding-Trust is valid.

Ethereum integration

The following is meant to be a short but complete manual to explain how the interfacing of an Ethereum contract with Oraclize actually works.

All the reference code we will be using next is written in Solidity, but since the interface would be the same for any other language, feel free to use one you like.

Sending a query to Oraclize means sending a transaction to the last Oraclize contract. In order to do that we have to:

With that, Oraclize will:

Note that the transaction sent back by Oraclize can trigger any status change in your contract, and can include the sending of another query to Oraclize. What can be done in the __callback method is limited by your immagination and, well, the gasLimit.

Getting everything on track

If you are using Solidity: First, you need to import our 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 http://dev.oraclize.it/api.sol. After making your contract extend usingOraclize, it would look like:

/*
import "dev.oraclize.it/api.sol" just works while using 
dev.oraclize.it web IDE, needs to be imported manually otherwise 
*/
import "dev.oraclize.it/api.sol";

contract YourContractName is usingOraclize {

    function YourContractName(){
        ..
    } 

}

If you are using Serpent: You just need to import the oraclize API via inset() command, you can find all the code you need to import here http://dev.oraclize.it/api.se

# In serpent you just need to import (inset)
# the oraclize API inside your contract

inset("oraclizeAPI.se")

def init():
    ..

Network selection

Oraclize is available both on the public Ethereum mainnet and on the Morden testnet.

There is no need anymore to manually specify the network your contract will be deployed to: the helper functions will figure it out automagically.

If you are looking for an Oraclize integration with your private blockchain please get in touch with us to know more about the options we provide.

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");
oraclize_query(text("WolframAlpha"), text("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", "api.kraken.com/0/public/Ticker?pair=ETHXBT");
oraclize_query(text("URL"), text("api.kraken.com/0/public/Ticker?pair=ETHXBT"))
oraclize_query("URL", "json(https://www.therocktrading.com/api/ticker/BTCEUR).result.0.last");
oraclize_query(text("URL"), text("json(https://www.therocktrading.com/api/ticker/BTCEUR).result.0.last"))
oraclize_query("IPFS", "QmdEJwJG1T9rzHvBD8i69HHuJaRgXRKEQCP7Bh1BVttZbU");
oraclize_query(text("IPFS"), text("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(https://shapeshift.io/sendamount).success.deposit", '{"pair": "eth_btc", "amount": "1", "withdrawal": "1AAcCo21EUc1jbocjssSQDzLna9Vem2UN5"}');
# 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 escaped JSON string it will be automatically sent as JSON
#      in serpent you must escape the JSON object

oraclize_query(text("URL"), text("json(https://shapeshift.io/sendamount).success.deposit"), text("{\"pair\": \"eth_btc\", \"amount\": \"1\", \"withdrawal\": \"1AAcCo21EUc1jbocjssSQDzLna9Vem2UN5\"}"))

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", "json(https://api.kraken.com/0/public/Ticker?pair=ETHXBT).result.XETHXXBT.c.0");
# get the result from the given URL 60 seconds from now
oraclize_query(60, text("URL"), text("json(https://api.kraken.com/0/public/Ticker?pair=ETHXBT).result.XETHXXBT.c.0"))
// get the result from the given datasource at the specified timestamp in the future
oraclize_query(scheduled_arrivaltime+3*3600, "WolframAlpha", strConcat("flight ", flight_number, " landed"));
# get the result from the given datasource at the specified timestamp in the future
oraclize_query(scheduled_arrivaltime+3*3600, text("WolframAlpha"), strConcat(text("flight "), text(flight_number), text(" landed")))

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", "json(https://api.kraken.com/0/public/Ticker?pair=ETHXBT).result.XETHXXBT.c.0");
# get the result from the given URL 60 seconds from now
data myid

self.myid = oraclize_query(60, text("URL"), text("json(https://api.kraken.com/0/public/Ticker?pair=ETHXBT).result.XETHXXBT.c.0"));

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()) throw; // just to be sure the calling address is the Oraclize authorized one
    ETHXBT = result; // doing something with the result..
    bytes32 myid = oraclize_query(60, "URL", "json(https://api.kraken.com/0/public/Ticker?pair=ETHXBT).result.XETHXXBT.c.0"); // new query for Oraclize!
}
data myid

def __callback(myid:bytes32, result:string):
    if (msg.sender != oraclize_cbAddress()):
        return # just to be sure the calling address is the Oraclize authorized one
    self.ETHXBT = result # doing something with the result..
    self.myid = oraclize_query(60, text("URL"), text("json(https://api.kraken.com/0/public/Ticker?pair=ETHXBT).result.XETHXXBT.c.0")) # new query for Oraclize!

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_query("WolframAlpha", "random number between 0 and 100", 500000); // Oraclize will use a 500k gasLimit for the callback transaction, instead of 200k
oraclize_query(text("WolframAlpha"), text("random number between 0 and 100"), 500000) # Oraclize will use a 500k gasLimit for the callback transaction, instead of 200k
oraclize_query(60, "WolframAlpha", "random number between 0 and 100", 500000); // you can set both custom timestamp/delay and custom gasLimit
oraclize_query(60, text("WolframAlpha"), text("random number between 0 and 100"), 500000) # you can set both custom timestamp/delay and custom gasLimit

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

TLSNotary 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 http://ipfs.io/ipfs/proof

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 "dev.oraclize.it/api.sol" just works while using 
dev.oraclize.it web IDE, needs to be imported manually otherwise 
*/
import "dev.oraclize.it/api.sol";

contract YourContractName is usingOraclize {

    function YourContractName(){
        oraclize_setProof(proofType_TLSNotary | proofStorage_IPFS);
        oraclize_query("URL", "xml(https://www.fueleconomy.gov/ws/rest/fuelprices).fuelPrices.diesel");
    }

    function __callback(bytes32 myid, string result, bytes proof){
        if (msg.sender != oraclize_cbAddress()) throw;
        ..
    }
}
# In serpent you just need to import (inset)
# the oraclize API inside your contract

inset("oraclizeAPI.se")

def init():
    oraclize_setProof(proofType_TLSNotary | proofStorage_IPFS)
    oraclize_query(text("URL"), text("xml(https://www.fueleconomy.gov/ws/rest/fuelprices).fuelPrices.diesel"))

def __callback(myid:bytes32, result:string, proof:bytes):
    if (msg.sender != oraclize_cbAddress()):
        return
    ..

More examples

You can have a look at more complete and complex examples by heading to our dedicated github repository: https://github.com/oraclize/ethereum-examples

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 "dev.oraclize.it/api.sol" just works while using 
dev.oraclize.it web IDE, needs to be imported manually otherwise 
*/
import "dev.oraclize.it/api.sol";

contract YourContractName is usingOraclize {

    mapping(bytes32=>bool) myidList;

    function YourContractName(){
         oraclize_query("URL","json(http://exampleUrl.url).result");
    }

    function __callback(bytes32 myid, string result) {
        if(msg.sender != oraclize_cbAddress()) throw;
        if(myidList[myid]==true) throw; // 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:

Pricing

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

Ethereum

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