Tellor Docs

Solidity Integration

Connecting to the Oracle

To use Tellor data, you can use the UsingTellor helper contract. After connecting it to the oracle, you can read a value using your queryId. This guide uses the BTC/USD SpotPrice as an example query.


To install usingtellor, run the following command:
npm install usingtellor


To import the UsingTellor contract into your Solidity file, pass the desired Tellor address (see the references page for the address) as a parameter:
pragma solidity >=0.8.0;
import "usingtellor/contracts/UsingTellor.sol";
contract MyContract is UsingTellor {
constructor(address payable _tellorAddress) UsingTellor(_tellorAddress) {
// ...
Note: In the constructor on line 7, you need to specify the Tellor contract address. For testing, you can use a Tellor Playground address. In production, use the Oracle address on your chosen network.

Reading data

You can either use our QueryId builder to create a queryId and hardcode it, or use solidity to generate it. Once you have created a queryId, you can add the Tellor data feed to your contract code.
The best practice for reading Tellor data is to use thegetDataBefore function with a buffer time that allows time for bad values to be disputed:
getDataBefore(_queryId, block.timestamp - 20 minutes);
It's also best practice to require/check that the data is not too old. For example:
require(block.timestamp - _timestampRetrieved < 24 hours);
In the example below, we add a function getBtcSpotPrice that reads the BTC/USD price feed from the Oracle:
// SPDX-License-Identifier: MIT
pragma solidity 0.8.3;
import "usingtellor/contracts/UsingTellor.sol";
contract ExampleContract is UsingTellor {
function getBtcSpotPrice() external view returns(uint256) {
bytes memory _queryData = abi.encode("SpotPrice", abi.encode("btc", "usd"));
bytes32 _queryId = keccak256(_queryData);
(bytes memory _value, uint256 _timestampRetrieved) =
getDataBefore(_queryId, block.timestamp - 20 minutes);
if (_timestampRetrieved == 0) return 0;
require(block.timestamp - _timestampRetrieved < 24 hours);
return abi.decode(_value, (uint256);