Skip to main content

Chainlink Direct Requests (Any API)

An in-depth guide to Chainlink's Direct Request model, including key terminology, and how to get started requesting data from us.

Chainlink Direct Requests (Any API)

On this page:

Overview​

Chainlink Direct Requests (also called Basic Requests, or Any API) are a type of oracle request that allows your blockchain smart contract to request data directly from a given Chainlink oracle team.

As compared to Chainlink Functions, Direct Requests are convenient for the end-user in the following 3 ways:

  1. They support the greatest range of data types, data sizes, and blockchain networks.
  2. They are often the cheapest option for the end-user (allowing for negotiation with the specific node operator based on volume and request size).
  3. They require the least amount of technical effort to implement. The oracle team simply provides you with a request() and fulfill() function to place into your smart contract, leaving you free to focus on the development of the rest of your smart contract application.

As Direct Requests place much of the burden of implementation on the oracle team that you've chosen, it's important to choose an oracle team that you trust.

info

LinkWell Nodes is a full-service Chainlink oracle solution that provides secure, reliable, direct-to-consumer data feeds in exchange for a per-request fee. We offer free development services for any efforts required to get your data feed integration up and running.


You can find our direct request job IDs and oracle addresses within our Chainlink data feed documentation, as well as our Service-Level Agreement (SLA).

Direct Requests architecture​

Before diving deeper into the direct request architecture, it's important to understand the direct request (basic request) model for Chainlink oracle requests.

High-level request workflow:

  1. Your consumer contract (ie, ChainlinkClient) makes a request to our oracle contract, via the request() function.
  2. Our Chainlink nodes receive the request, make an HTTP request to the appropriate API endpoint, and write the result back to your consumer contract, via execution of your fulfill() function.
  3. Your Web3 application reads the data from your consumer contract.

Chainlink Basic Request Model

Chainlink Direct Request workflow

Key terms​

  • Consumer contract: A smart contract deployed by you (the data requester / consumer) that orchestrates the sending / receiving of off-chain data to a Chainlink oracle. It contains logic to describe the data request, send the request, and receive the resulting data. Full examples of consumer contracts can be found in our Direct Request Job Documentation.
  • Request function: The function (method) within your consumer contract that initiates the request to the Chainlink oracle. The required data request parameters (ie, URL, headers, etc.) are usually defined here. Once this function is executed, the Chainlink oracle picks up the emitted event, and begins its work retrieving the requested data.
  • Fulfill function: The function (method) within your consumer contract that receives the data requested from the Chainlink oracle. This function is triggered by the oracle itself, via the oracle contract - usually within 3-5 blocks of the request() function being triggered, depending on the blockchain.
  • Oracle contract (also known as an operator contract): A smart contract deployed by the Chainlink node operator that orchestrates the sending / receiving of off-chain data between the consumer contract and the oracle node. All communication between the consumer contract and the oracle node passes through this contract.
  • Oracle (also known as a Chainlink node): An off-chain server that receives on-chain requests from the consumer contract (via the oracle contract), retrieves the requested data, and then delivers the result on-chain to the consumer contract, by execution of a blockchain transaction within the oracle contract.

Process diagram​

The following diagram demonstrates the direct request workflow.

Key points:

  1. The diagram begins with a call to your consumer contract's request function, via an EVM-compatible IDE such as Remix, combined with a Web3 wallet provider such as MetaMask.
  2. The left-hand workflow (testnets) is virtually the same as the right-hand workflow (mainnets) with the exception of needing to fund your consumer contract with LINK tokens before making a request.

Chainlink Direct Request workflow (in-depth diagram)

Chainlink Direct Request workflow (in-depth diagram)

Requesting data from LinkWell Nodes​

The following section illustrates how to trigger an oracle request from within your smart contract, using the LinkWell Nodes oracle infrastructure.

Prepare your request:

  1. (mainnet customers only) Fill out our Oracle request survey form, so that we can fulfill our compliance obligations and better understand your data needs.
  2. Design your consumer contract, using our Data Feeds Documentation as a guide (code examples included).
  3. Deploy your contract using an EVM-compatible IDE such as Remix.
info

For mainnet chains, please wait several hours after filling out our Getting Started form to receive our mainnet contract info and custom job ID. Please also ensure that your consumer contract is properly funded with enough LINK tokens to make the request.

Execute your request:

  1. From your IDE (ie, Remix) trigger your contract's request() function (also called the transferAndCall() or _sendOperatorRequest() function).
  2. Once triggered, your contract will emit an OracleRequest event, which will get picked up by one of our off-chain oracle nodes. On mainnets, the appropriate amount of LINK token will simultaneously be sent to the oracle contract as a form of payment.
  3. After detecting the OracleRequest event, one of our oracle nodes will use the emitted data to perform the designated job. This typically involves an HTTP request to an API endpoint for data retrieval.
  4. Once the data has been retrieved, parsed, and converted into a blockchain compatible format, our oracle node executes a blockchain transaction against the oracle contract, which in turn writes the data back to your consumer contract via its fulfill() function.

Retrieve your result:

  1. As soon as the fulfill() function is called within your consumer contract, a RequestFulfilled event will be emitted. If desired, you can monitor for this event using an RPC connection and Web3 library (ie, web3.js), in order to trigger a response within your Web3 application.
  2. Your data should now be available within your consumer contract for consumption by your Web3 application!
info

The end-to-end workflow from triggering your request() function to receiving your oracle response within the fulfill() function should take ~3-5 blocks. This typically occurs in less than a minute of waiting time, but depends highly on your chosen network's block time and congestion, as well as your chosen oracle team's security configuration.


At LinkWell Nodes, we are able to offer a faster oracle response time (2 blocks minimum) on mainnets for a small increase in fee. Please reach out to us via our Getting Started form, and include the specific details of your requirements.

Need more help?​

Join our Discord server for immediate assistance!