1. Select the desired HTTP method to get data from an API or website. To execute custom JavaScript without fetching any data, select “No HTTP request”.


2. Enter the URL for the API or website. The entire URL, with all applicable endpoints, must be used.


3. If necessary, add headers to the HTTP request. These headers must be entered in JSON format, with curly brackets, as in the example shown below.
   • { Authorization: "Bearer YOUR_TOKEN_HERE" }
   
   
   • Any JavaScript code entered into the headers box will be evaluated client-side before the headers are used in a request. For example, to convert data to base 64, use the function btoa(“YOUR_TOKEN_HERE”) which will be evaluated before the request is sent as shown in the example below.
   
   
   • { Authorization: "Bearer " + btoa("YOUR_TOKEN_HERE") }


4. Select if headers should be included directly in an on-chain request, or if they should be stored on the external adapter and be used when an on-chain request is made. If headers are included directly in an on-chain request, they will be publicly visible.
   • In order to upload headers, the address of the contract which is authorized to make requests utilizing the uploaded headers must be known. In addition, a unique reference ID string must be provided which is used to get the correct headers for a particular request. Only requests made from a matching contract address can use the uploaded headers. This reference ID is included in the on-chain request so that the correct headers are used. Multiple different sets of headers can be used by a single contract, provided all the reference ID strings are unique.
   
   
   • If the contract address is not yet known, a reference ID can be provided and the “Address” box can be left blank in order to generate the Solidity code to make the request on-chain. Then, after the contract is deployed and the address is known, it can be entered in the “Address” box and the headers can be successfully uploaded. An example of this is shown in the Twitter example in the overview video.
   
   
   • All headers are transmitted to the external adapter via SSL encryption. This keeps headers private when sending test requests or uploading headers to the external adapter.


5. Data can also be included with HTTP requests such as POST or PUT. Data should be structured as a JSON object similar to the headers as shown below.
   • { name: "YOUR_NAME", id: 12345 }


6. Select the correct return type. The return type must match the return type of the executed JavaScript code. If bytes32 is selected, the return type of the JavaScript code must be a string with less than 32 ASCII characters.


7. Select the source of the JavaScript code. Code can either be provided directly in a request, or it can be uploaded to IPFS and the content ID can be sent in the request.
   • To access the results of the HTTP request, use the response variable. For example, response.data contains the string or object returned by the HTTP request.
   
   
   • Provided JavaScript code is automatically wrapped in a function before it is executed by the external adapter and the returned value will be posted on-chain.
   
   
   • The maximum response time for the external adapter is limited to 30 seconds. This means the total time for the HTTP request to resolve and the JavaScript code to execute must be under 30 seconds before the request is terminated. In addition, the maximum memory utilization is limited to 256 megabytes per Adapter.js instance.
   
   
   • For security, no Node.js modules can be used. Only vanilla Node.js code can be executed without any imports. All code is executed in a secure sandbox.
   
   
   • Code can be uploaded to IPFS from the simulator using Web3.Storage. To upload a JavaScript file, a Web3.Storage token must be provided. Currently, getting a Web3.Storage token is free. Get one at Web3.Storage.
   
   
   • If the content ID is provided, the external adapter will download a single JavaScript file from IPFS and execute the code within the file. The code must be in the same format as previously described and must end by returning a single value.
   
   
   • An example of a file which can be uploaded to IPFS and used in a request can be found on GitHub. This particular example is intended to be used with the result of an HTTP get request made to https://cointelegraph.com/tags/altcoin.


8. Send a test request by clicking the “SEND REQUEST” button. The request will return the returned value or an error. Errors can reference either an HTTP request failure, or an error with the JavaScript code that was provided.


9. Solidity code to make a request on-chain can be generated by selecting the desired blockchain network and clicking the “GENERATE CODE” button.
   • Generated code can be pasted into a smart contract by following the instruction comments provided when the code is generated.
   
   
   • All the provided code is generic, except for the addresses, job IDs, and the parameters string which is added to the Chainlink request. For a description for how the parameters string is structured, see the next section.

The parameters string "p" in the Chainlink request contains all the necessary information to make a call to the external adapter. It is structured as a JSON object string.

In order to make calls to Adapter.js more gas efficient, all variables contained in the parameters string use only a single character, which shortens the parameters string.

The following documentation describes what each variable in the request means and how it is structured. This information can be used to modify a request to Adapter.js on-chain by modifying the parameters string before it is added to the Chainlink request.

Below is an example of the parameters JSON object string being added to a Chainlink request.

Variables in the Parameters JSON Object String

t: Return Type

• Specifies the Solidity type that will be returned on-chain. The options are int256, uint256, bool or bytes32.
• This value must be included.

m: HTTP Request Method

• Specifies the HTTP method to use in the HTTP request which can be either get, post, put, delete, patch, head, options, or trace.
• Do not include this value to make a request without performing an HTTP request.

u: URL

• Specifies the URL for the HTTP request.
• This value must be included if the HTTP request method, m, is specified.

h: HTTP Request Headers

• Directly specifies the headers JSON object to be used in the HTTP request.
• Since this value is included directly in a request, this value is publicly visible on the blockchain.
• To use headers in the HTTP request, either this value or headers reference ID, r, should be included, but not both.

r: HTTP Headers Reference ID

• Specifies the reference ID for headers object that has been uploaded to the external adapter.
• The reference ID must match the reference ID that was entered when the headers were uploaded.
• If a contract has multiple different sets of uploaded headers, the reference ID for each set of headers must be unique.
• Only requests made by a contract address that was entered when the headers were uploaded can use the referenced headers in the HTTP request.
• To use headers in the HTTP request, either this value or the directly provided headers value, h, should be included, but not both.

d: HTTP Request Data

• Specifies the JSON object to be used in the body of the HTTP request.
• This value can be included for the HTTP methods, post, put, delete and patch, which have request bodies.
• This value is optional if no data should be used in the body of the HTTP request.

j: JavaScript

• A string which contains the JavaScript to be executed, where the returned value is returned by the Chainlink request.
• The provided code is wrapped in a function before it is executed by the external adapter.
• Code can only contain vanilla Node.js code, without any imports.
• The maximum execution time for both the HTTP request and the provided JavaScript must be under 30 seconds.
• The maximum memory usage for an entire Adapter.js instance is 256 megabytes.
• The result of the HTTP request can be accessed by using the variable response in the provided JavaScript code. To access the data returned by the HTTP request, use response.data.
• Either this value should be included should be included or the IPFS content ID, but not both.

i: IPFS Content ID

• Specifies the IPFS content ID of the file which contains the JavaScript which should be executed in the request.
• The code in the uploaded file is executed the same way and has the same constraints as if the code were sent as a string, as described above.
• The file uploaded to IPFS must be a single JavaScript file.
• JavaScript files can easily be uploaded to IPFS using Web3.Storage via the Adapter.js simulator.
• Either the IPFS content ID or JavaScript value, j, should be included, but not both.

If you are having difficulty making an on-chain request with Adapter.js, please follow the troubleshooting steps below.

• Confirm that the contract is funded with LINK.


• Verify that the request is valid by using the simulator. The simulator sends requests directly to the external adapter so if it works in the simulator it should work on-chain, provided the request is structured the same way.


• Use the code generator to check how the request parameters string should be structured.


• Verify the correct oracle address and LINK token contract address are used for the particular blockchain to which the contract is deployed.


• Check that the job ID is correct for the oracle to which the request is being sent.


• Ensure any required headers have been successfully uploaded to the external adapter and that the correct reference ID is being used.

If you have read the documentation and followed the troubleshooting steps but are still encountering difficulties, please reach out via Discord.