Options Specific

Learn to fetch information about option contracts.

We'll cover the following

In an options contract, buyers have the right to buy or sell underlying securities within a specific time at a specific price. There are two types of options contracts:

  1. Option calls:  This contract gives buyers the right to buy assets.

  2. Option puts: This contract gives buyers the right to sell assets.

Options contracts

Polygon API gives us free access to the information about active and expired options contracts within the previous two years through the options contracts endpoint.

Press + to interact
The options contracts endpoint
The options contracts endpoint

The base URL for this endpoint is as follows:

https://api.polygon.io/v3/reference/options/contracts

Request Parameters

By default, the options contracts endpoint provides a list of 10 options contracts. However, we can filter our search by providing some additional request parameters.

The following table gives details about the request parameters for the options contracts endpoint:

Name

Type

Category

Description

ticker

String

Optional

The ticker associated with the options contract we are looking for.

underlying_ticker

String

Optional

The ticker associated with the underlying stock.

contract_type

String

Optional

The type of options contract we are looking for.

Accepted input: call or put.

expiration_date

String

Optional

This is used to define the expiration date. The accepted format is YYYY-MM-DD.

as_of

String

Optional

This is used to find contracts within the specified date in the format YYYY-MM-DD.

strike_price

Integer

Optional

This is used to filter contracts by strike price, which is the price at which the contract is traded.

expired

Boolean

Optional

If this is set to true, the result includes expired contracts.

sort

String

Optional

The field used to sort the results.

Accepted input: ticker, underlying_ticker, expiration_date, or strike_price.

order

String

Optional

The order in which the results will be sorted, depending on the input given in sort.

Accepted input: asc or desc for ascending and descending, respectively.

limit

Integer

Optional

This is the number of contracts required in the result. By default, it is set to 10 and the maximum input is 1000.

We can provide additional filter parameters, such as .lt (less than), .gt (greater than), .lte (less than equal to), and .gte (greater than equal to), for the underlying_ticker, expiration_date, and strike_price parameters. For example, if we want option contracts where the strike price is less than 200, we can give the following request parameter:

const queryParameters = new URLSearchParams({
  "strike_price.lt" : 200
});

Let’s call the options contracts endpoint with its default parameters in the following code:

Press + to interact
// Importing libraries here
import fetch from "node-fetch";
// Define API key here
const apiKey = '{{API_KEY}}';
// Define endpoint URL here
const endpointUrl = new URL(`https://api.polygon.io/v3/reference/options/contracts`);
// Define Header Parameters here
const headerParameters = {
  authorization: `Bearer ${apiKey}`
};
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function OptionsContracts() {
  try {
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
// Calling function to make API call
OptionsContracts();

Here’s an explanation for the above code:

  • Line 8: We define the endpoint URL.

  • Lines 11–13: We define the API key in the header parameter.

  • Lines 16–19: We define the options parameters and set the request type as GET.

  • Lines 22–32: We define the OptionsContract function, which calls the endpoint.

  • Line 35: We call the OptionsContract function.

Now, let’s call this endpoint to fetch option contracts whose contract type is put, and sort them in ascending order based on ticker.

Press + to interact
// Importing libraries here
import fetch from "node-fetch";
// Define API key here
const apiKey = '{{API_KEY}}';
// Define endpoint URL here
const endpointUrl = new URL(`https://api.polygon.io/v3/reference/options/contracts`);
// Define Header Parameters here
const headerParameters = {
  authorization: `Bearer ${apiKey}`,
  contentType: 'application/json',
};
// Define Query Parameters here
const queryParameters = new URLSearchParams({
  contract_type: 'put',
  sort: 'ticker',
  order: 'asc',
});
// Setting API call options
const options = {
  method: 'GET',
  headers: headerParameters,
};
// Function to make API call
async function OptionContract() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    // Custom function for printing the error message
    printError(error);
  }
}
// Calling function to make API call
OptionContract();

In lines 17–21, we have provided contract_type, sort, and order in the query parameters. We can change these to fetch different options contracts.

Response fields

The following table gives details about the attributes found in the response object:

Name

Type

Description

results

Array

This has the details about the option contracts sent as an input parameter.

results.cfi

String

The CFI code of the contract.

results.contract_type

String

This is type of contract. It can be put or call. In some rare cases, the output can be other.

results.exercise_style

Enum

This defines the class of the option.

Possible output: american, european, or bermudan.

results.expiration_date

String

This is the expiration date of the contract given in the YYYY-MM-DD format.

results.primary_exchange

String

The code of the primary exchange of the options contract.

results.shares_per_contract

Integer

The total number of shares in the contract.

results.strike_price

Integer

The price at which the contract is traded.

results.ticker

String

The ticker associated with the option contract.

results.underlying_ticker

String

The ticker of the underlying asset to which the options contract is related.

results.additional_underlyings

Array

This contains information about the additional underlying asset of the options contract.

status

String

The response to our query.

request_id

String

The ID associated with our query.

next_url

String

The URL to the next page, if it exists.