📂 dApp Developers

Getting Started

Table of Contents

• Starter Project
• Coverage Policies
• dAPI Names
• DapiServer Functions
• Resources

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 data-feed-reader-example (opens new window) starter is an example project for reading from dAPI a 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.

• allow-to-read-with-name.js (opens new window)
• allow-to-read-with-id.js (opens new window)

dAPI Names

A dAPI is a live data point associated with human readable name. 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 dAPI name to the appropriate DapiServer.sol reader function.

• readDataFeedWithDapiName(_dapiName) - returns a value and timestamp
• readDataFeedValueWithDapiName(_dapiName) - returns a value

// Calling the ETH/USD dAPI using the DapiServer contract
(value, timestamp) =
  IDapiServer(_dapiServerContractAddress).readDataFeedWithDapiName("ETH/USD");

Optionally, use Beacon and Beacon set IDs

It is possible to use a Beacon 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.

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.

Resources

• Chains and Contracts: A list of chains, and supporting contracts that dAPIs are available on.
• dAPI Browser: A list of dAPIs that have been deployed.