# Getting Started
The DapiServer.sol (opens new window) contract serves data feeds to contracts with read access. All the related contracts can be imported from the @api3/airnode-protocol-v1 (opens new window) npm package.
# Starter Project
The starter project data-feed-reader-example (opens new window) is an example GitHub project that reads from a dAPI on the Polygon Mumbai testnet. Be sure to read through the README.md (opens new window) and some of the example code such as the DataFeedReaderExample.sol (opens new window) contract. Read through this entire page before running the starter project to better understand some of the terms and concepts mentioned. Finally follow the instruction in the README to get acquainted with reading data feeds.
# Coverage Policies
DapiServer.sol will check that the requester has a coverage policy for each
dAPI it may attempt to read. See available dAPIs on the
API3 Market (opens new window). During the preview period, all dAPIs
on production networks have free access (limited time offer). Please go to the
Request Data (opens new window)
page to request dAPI access on production networks. See
Chains and Contracts, which includes supported
networks.
On the Polygon Mumbai testnet, developers can self-enable the use of any dAPI. During the deployment flow of your smart contract that reads a data feed, add code that self-enables the desired dAPI. The following scripts from the Starter Project detail how this is done. Please be sure to explore the starter project in its entirety.
# dAPI Names
A dAPI is a live data point associated with human readable dapiName. dAPI
definitions simplify access and can return aggregated Beacon values or a single
Beacon value. This is suitable where the more recent data point (meaning its set
of Beacons could change as needed) is always more favorable, e.g., in the
context of an asset price data feed.
Pass a dapiName, as an encoded bytes32 value, to the desired DapiServer.sol
reader function that uses dapiName as its parameter. This is done to save gas
when your smart contract calls a "readByName" function on DapiServer.sol.
- readDataFeedWithDapiName(_dapiName) - returns a value and timestamp
- readDataFeedValueWithDapiName(_dapiName) - returns a value
The example below generates the encoded bytes32 value of AVAX/USD. Try encoding AVAX/USD in the ethers playground (opens new window).
// Encode the dapiName (such as AVAX/USD) to bytes32
ethers.utils.formatBytes32String("AVAX/USD");
// Yields: 0x415641582f555344000000000000000000000000000000000000000000000000
2
3
Then pass the encoded value to the functions mentioned above.
// Calling readDataFeedWithDapiName() using the DapiServer contract
(value, timestamp) =
IDapiServer(_dapiServerContractAddress).readDataFeedWithDapiName("0x415641582f555344000000000000000000000000000000000000000000000000");
2
3
# DapiServer Functions
- readDataFeedWithDapiName() - Returns a value and timestamp using the dAPI name.
- readDataFeedValueWithDapiName() - Returns a value using the dAPI name.
- readerCanReadDataFeed() - Whether a reader can read a dAPI, Beacon, or Beacon set.
- dataFeedIdToReaderToWhitelistStatus() - Details about the coverage policy status of a reader address for a dAPI, Beacon, or Beacon set.
- readDataFeedWithId() - Returns a value and timestamp using a Beacon or Beacon set ID.
- readDataFeedValueWithId() - Returns a value using a Beacon or Beacon set ID.
# Optionally, use Beacon IDs
It is possible (as an option) to use a Beacon ID or Beacon set ID by calling readDataFeedId() and readDataFeedValueById(). Doing so is considered an advanced user flow. In practice reading with a name and reading with an ID are very different things. When you read with a name, you benefit from what the name maps to and how its value is aggregated from sourced Beacons. API3 manages dAPI name mappings to provide the best possible responses. When you read with an ID, you will always read a value directly from a Beacon or Beacon set. Also see dAPI Composition.