Forex & Crypto
Forex
Read this section to know everything you need to know about using the various Forex HTTP endpoints.
See Async Support for REST endpoints for asynchronous use cases.
Docs below assume you have already read getting started page and know how to create the client. If you do not know how to create the client, first see General guide for clients & functions and create client as below. As always you can have all 5 different clients together.
import polygon
forex_client = polygon.ForexClient('KEY') # for usual sync client
async_forex_client = polygon.ForexClient('KEY', True) # for an async client
Note that most endpoints require you to specify the currency pairs as separate symbols (a from_symbol
and a to_symbol
).
however a few endpoints require you to supply them as one combined symbol. An example would be the get_aggregates_bars
method.
In those methods, the symbol is expected to have a prefix C:
before the currency symbol names. but the library allows you to specify the symbol with or without the prefix.
See the relevant method’s docs for more information on what the parameters expect.
here is how the client initializer looks like:
- polygon.forex.forex_api.ForexClient(api_key: str, use_async: bool = False, connect_timeout: int = 10, read_timeout: int = 10, pool_timeout: int = 10, max_connections: int | None = None, max_keepalive: int | None = None, write_timeout: int = 10)
Initiates a Client to be used to access all REST Forex endpoints.
- Parameters:
api_key – Your API Key. Visit your dashboard to get yours.
use_async – Set it to
True
to get async client. Defaults to usual non-async client.connect_timeout – The connection timeout in seconds. Defaults to 10. basically the number of seconds to wait for a connection to be established. Raises a
ConnectTimeout
if unable to connect within specified time limit.read_timeout – The read timeout in seconds. Defaults to 10. basically the number of seconds to wait for date to be received. Raises a
ReadTimeout
if unable to connect within the specified time limit.pool_timeout – The pool timeout in seconds. Defaults to 10. Basically the number of seconds to wait while trying to get a connection from connection pool. Do NOT change if you’re unsure of what it implies
max_connections – Max number of connections in the pool. Defaults to NO LIMITS. Do NOT change if you’re unsure of application
max_keepalive – max number of allowable keep alive connections in the pool. Defaults to no limit. Do NOT change if you’re unsure of the applications.
write_timeout – The write timeout in seconds. Defaults to 10. basically the number of seconds to wait for data to be written/posted. Raises a
WriteTimeout
if unable to connect within the specified time limit.
Endpoints
To use any of the below method, simply call it on the client you created above. so if you named your client client
,
you’d call the methods as client.get_historic_forex_ticks
and so on. Async methods will need to be awaited, see Async Support for REST endpoints.
SMA
Simple Moving Average. This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncForexClient.get_sma(symbol: str, timestamp=None, timespan='day', adjusted: bool = True, window_size: int = 50, series_type='close', include_underlying: bool = False, order='desc', limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the Simple Moving Average for a forex ticker
- Parameters:
symbol – The option symbol. You can pass it with or without the prefix
C:
.timestamp – Either a date with the format
YYYY-MM-DD
or a millisecond timestamp.timespan – Size of the aggregate time window. defaults to ‘day’. See
polygon.enums.Timespan
for choicesadjusted – Whether the aggregates used to calculate the simple moving average are adjusted for splits. By default, aggregates are adjusted. Set this to
False
to get results that are NOT adjusted for splits.window_size – The window size used to calculate the simple moving average (SMA). i.e. a window size of 10 with daily aggregates would result in a 10 day moving average.
series_type – The prices in the aggregate which will be used to calculate the SMA. The default
close
will result in using close prices to calculate the SMA. Seepolygon.enums.SeriesType
for choicesinclude_underlying – Whether to include the OCHLV aggregates used to calculate this indicator in the response. Defaults to False which only returns the SMA.
order – The order in which to return the results, ordered by timestamp. See
polygon.enums.SortOrder
for choices. Defaults to Descending (most recent first)limit – Limit the number of results returned, default is 5000 which is also the max
timestamp_lt – Only use results where timestamp is less than supplied value
timestamp_lte – Only use results where timestamp is less than or equal to supplied value
timestamp_gt – Only use results where timestamp is greater than supplied value
timestamp_gte – Only use results where timestamp is greater than or equal to supplied value
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
The response object
EMA
Exponential Moving Average. This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncForexClient.get_ema(symbol: str, timestamp=None, timespan='day', adjusted: bool = True, window_size: int = 50, series_type='close', include_underlying: bool = False, order='desc', limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the Exponential Moving Average for a forex ticker
- Parameters:
symbol – The option symbol. You can pass it with or without the prefix
C:
.timestamp – Either a date with the format
YYYY-MM-DD
or a millisecond timestamp.timespan – Size of the aggregate time window. defaults to ‘day’. See
polygon.enums.Timespan
for choicesadjusted – Whether the aggregates used to calculate the EMA are adjusted for splits. By default, aggregates are adjusted. Set this to
False
to get results that are NOT adjusted for splits.window_size – The window size used to calculate the EMA. i.e. a window size of 10 with daily aggregates would result in a 10 day moving average.
series_type – The prices in the aggregate which will be used to calculate the EMA. The default
close
will result in using close prices to calculate the EMA. Seepolygon.enums.SeriesType
for choicesinclude_underlying – Whether to include the OCHLV aggregates used to calculate this indicator in the response. Defaults to False which only returns the EMA.
order – The order in which to return the results, ordered by timestamp. See
polygon.enums.SortOrder
for choices. Defaults to Descending (most recent first)limit – Limit the number of results returned, default is 5000 which is also the max
timestamp_lt – Only use results where timestamp is less than supplied value
timestamp_lte – Only use results where timestamp is less than or equal to supplied value
timestamp_gt – Only use results where timestamp is greater than supplied value
timestamp_gte – Only use results where timestamp is greater than or equal to supplied value
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
The response object
RSI
Relative Strength Index. This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncForexClient.get_rsi(symbol: str, timestamp=None, timespan='day', adjusted: bool = True, window_size: int = 14, series_type='close', include_underlying: bool = False, order='desc', limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the Relative Strength Index for a forex ticker
- Parameters:
symbol – The option symbol. You can pass it with or without the prefix
C:
.timestamp – Either a date with the format
YYYY-MM-DD
or a millisecond timestamp.timespan – Size of the aggregate time window. defaults to ‘day’. See
polygon.enums.Timespan
for choicesadjusted – Whether the aggregates used to calculate the RSI are adjusted for splits. By default, aggregates are adjusted. Set this to
False
to get results that are NOT adjusted for splits.window_size – The window size used to calculate the RSI. i.e. a window size of 14 with daily aggregates would result in a 14 day RSI.
series_type – The prices in the aggregate which will be used to calculate the RSI. The default
close
will result in using close prices to calculate the RSI. Seepolygon.enums.SeriesType
for choicesinclude_underlying – Whether to include the OCHLV aggregates used to calculate this indicator in the response. Defaults to False which only returns the RSI.
order – The order in which to return the results, ordered by timestamp. See
polygon.enums.SortOrder
for choices. Defaults to Descending (most recent first)limit – Limit the number of results returned, default is 5000 which is also the max
timestamp_lt – Only use results where timestamp is less than supplied value
timestamp_lte – Only use results where timestamp is less than or equal to supplied value
timestamp_gt – Only use results where timestamp is greater than supplied value
timestamp_gte – Only use results where timestamp is greater than or equal to supplied value
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
The response object
MACD
Moving Average Convergence/Divergence. This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncForexClient.get_macd(symbol: str, timestamp=None, timespan='day', adjusted: bool = True, long_window_size: int = 50, series_type='close', include_underlying: bool = False, order='desc', limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, short_window_size: int = 50, signal_window_size: int = 50, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the Moving Average Convergence/Divergence for a forex ticker
- Parameters:
symbol – The option symbol. You can pass it with or without the prefix
C:
.timestamp – Either a date with the format
YYYY-MM-DD
or a millisecond timestamp.timespan – Size of the aggregate time window. defaults to ‘day’. See
polygon.enums.Timespan
for choicesadjusted – Whether the aggregates used to calculate the MACD are adjusted for splits. By default, aggregates are adjusted. Set this to
False
to get results that are NOT adjusted for splits.long_window_size – The long window size used to calculate the MACD data
series_type – The prices in the aggregate which will be used to calculate the MACD. The default
close
will result in using close prices to calculate the MACD. Seepolygon.enums.SeriesType
for choicesinclude_underlying – Whether to include the OCHLV aggregates used to calculate this indicator in the response. Defaults to False which only returns the MACD.
order – The order in which to return the results, ordered by timestamp. See
polygon.enums.SortOrder
for choices. Defaults to Descending (most recent first)limit – Limit the number of results returned, default is 5000 which is also the max
timestamp_lt – Only use results where timestamp is less than supplied value
timestamp_lte – Only use results where timestamp is less than or equal to supplied value
timestamp_gt – Only use results where timestamp is greater than supplied value
timestamp_gte – Only use results where timestamp is greater than or equal to supplied value
short_window_size – The short window size used to calculate the MACD data
signal_window_size – The window size used to calculate the MACD signal line.
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
The response object
Real Time currency conversion
- SyncForexClient.real_time_currency_conversion(from_symbol: str, to_symbol: str, amount: float, precision: int = 2, raw_response: bool = False)
Get currency conversions using the latest market conversion rates. Note than you can convert in both directions. For example USD to CAD or CAD to USD. Official Docs
- Parameters:
from_symbol – The “from” symbol of the pair.
to_symbol – The “to” symbol of the pair.
amount – The amount to convert,
precision – The decimal precision of the conversion. Defaults to 2 which is 2 decimal places accuracy.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Historic forex ticks
- SyncForexClient.get_historic_forex_ticks(from_symbol: str, to_symbol: str, date, offset: str | int | None = None, limit: int = 500, raw_response: bool = False)
Get historic trade ticks for a forex currency pair. Official Docs
- Parameters:
from_symbol – The “from” symbol of the forex currency pair.
to_symbol – The “to” symbol of the forex currency pair.
date – The date/day of the historic ticks to retrieve. Could be
datetime
,date
or stringYYYY-MM-DD
offset – The timestamp offset, used for pagination. This is the offset at which to start the results. Using the timestamp of the last result as the offset will give you the next page of results. I’m thinking about a good way to implement this type of pagination in the lib which doesn’t have a
next_url
in the response attributes.limit – Limit the size of the response, max 10000. Default 500
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Quotes (NBBO)
This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncForexClient.get_quotes(symbol: str, timestamp: int | None = None, order=None, sort=None, limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get NBBO Quotes for a forex ticker symbol in a given time range. Official Docs
- Parameters:
symbol – The ticker symbol you want quotes for. e.g.:
C:EUR-USD
. you can pass with or without prefix C:timestamp – Query by trade timestamp. Could be
datetime
ordate
or stringYYYY-MM-DD
or a nanosecond timestamporder – sort order. see
polygon.enums.SortOrder
for available choices. defaults to Nonesort – field key to sort against. Defaults to None. see
polygon.enums.ForexQuotesSort
for choiceslimit – Limit the size of the response, max 50000 and default 5000.
timestamp_lt – return results where timestamp is less than the given value. Can be date or date string or nanosecond timestamp
timestamp_lte – return results where timestamp is less than/equal to the given value. Can be date or date string or nanosecond timestamp
timestamp_gt – return results where timestamp is greater than the given value. Can be date or date string or nanosecond timestamp
timestamp_gte – return results where timestamp is greater than/equal to the given value. Can be date or date string or nanosecond timestamp
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary. This is ignored if pagination is set to True.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object. If pagination is set to True, will return a merged response of all pages for convenience.
Get Last Quote
- SyncForexClient.get_last_quote(from_symbol: str, to_symbol: str, raw_response: bool = False)
Get the last trade tick for a forex currency pair. Official Docs
- Parameters:
from_symbol – The “from” symbol of the forex currency pair.
to_symbol – The “to” symbol of the forex currency pair.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Aggregate Bars (Candles)
The library added a better aggregate function if you’re looking to get data for large time frames at minute/hour granularity.
(for example 15 years historical data , 1 minute candles)
See Bulk Aggregate Bars (Full Range) for complete details on how to use it well and control how it behaves.
- SyncForexClient.get_aggregate_bars(symbol: str, from_date, to_date, multiplier: int = 1, timespan='day', adjusted: bool = True, sort='asc', limit: int = 5000, full_range: bool = False, run_parallel: bool = True, max_concurrent_workers: int = 10, info: bool = True, warnings: bool = True, high_volatility: bool = False, raw_response: bool = False)
Get aggregate bars for a forex pair over a given date range in custom time window sizes. For example, if
timespan = ‘minute’
andmultiplier = ‘5’
then5-minute
bars will be returned. Official Docs- Parameters:
symbol – The ticker symbol of the forex pair. e.g.:
C:EURUSD
. You can supply with or without prefixC:
from_date – The start of the aggregate time window. Could be
datetime
,date
or stringYYYY-MM-DD
to_date – The end of the aggregate time window. Could be
datetime
,date
or stringYYYY-MM-DD
multiplier – The size of the timespan multiplier
timespan – The size of the time window. Defaults to day candles. see
polygon.enums.Timespan
for choicesadjusted – whether the results are adjusted for splits. By default, results are adjusted. Set this to False to get results that are NOT adjusted for splits.
sort – Sort the results by timestamp. see
polygon.enums.SortOrder
for available choices. Defaults toasc
which is oldest at the top.limit – Limits the number of base aggregates queried to create the aggregate results. Max 50000 and Default 5000.
full_range – Default False. If set to True, it will get the ENTIRE range you specify and merge all the responses and return ONE single list with all data in it. You can control its behavior with the next few arguments.
run_parallel – Only considered if
full_range=True
. If set to true (default True), it will run an internal ThreadPool to get the responses. This is fine to do if you are not running your own ThreadPool. If you have many tickers to get aggs for, it’s better to either use the async version of it OR set this to False and spawn threads for each ticker yourself.max_concurrent_workers – Only considered if
run_parallel=True
. Defaults toyour cpu cores * 5
. controls how many worker threads to use in internal ThreadPoolinfo – Set to False to disable printing mild warnings / informational messages if any when fetching the aggs. E.g. if there was no data in a response but the response had an OK status
warnings – Set to False to disable printing warnings if any when fetching the aggs. Defaults to True.
high_volatility – Specifies whether the symbol/security in question is highly volatile which just means having a very high number of trades or being traded for a high duration (e.g. SPY, Bitcoin) If set to True, the lib will use a smaller chunk of time to ensure we don’t miss any data due to 50k candle limit. Defaults to False.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary. Will be ignored iffull_range=True
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object. Iffull_range=True
, will return a single list with all the candles in it.
Get Grouped Daily Bars (Candles)
- SyncForexClient.get_grouped_daily_bars(date, adjusted: bool = True, raw_response: bool = False)
Get the daily open, high, low, and close (OHLC) for the entire forex markets. Official Docs
- Parameters:
date – The date for the aggregate window. Could be
datetime
,date
or stringYYYY-MM-DD
adjusted – whether the results are adjusted for splits. By default, results are adjusted. Set this to False to get results that are NOT adjusted for splits.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Previous Close
- SyncForexClient.get_previous_close(symbol: str, adjusted: bool = True, raw_response: bool = False)
Get the previous day’s open, high, low, and close (OHLC) for the specified forex pair. Official Docs
- Parameters:
symbol – The ticker symbol of the forex pair.
adjusted – whether the results are adjusted for splits. By default, results are adjusted. Set this to False to get results that are NOT adjusted for splits.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Gainers & Losers
- SyncForexClient.get_gainers_and_losers(direction='gainers', raw_response: bool = False)
Get the current top 20 gainers or losers of the day in forex markets. Official docs
- Parameters:
direction – The direction of the snapshot results to return. See
polygon.enums.SnapshotDirection
for available choices. Defaults to Gainers.raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Crypto
Read this section to know everything you need to know about using the various Crypto HTTP endpoints.
See Async Support for REST endpoints for asynchronous use cases.
Docs below assume you have already read getting started page and know how to create the client. If you do not know how to create the client, first see General guide for clients & functions and create client as below. As always you can have all 5 different clients together.
import polygon
crypto_client = polygon.CryptoClient('KEY') # for usual sync client
async_crypto_client = polygon.CryptoClient('KEY', True) # for an async client
Note that most endpoints require you to specify the currency pairs as separate symbols (a from_symbol
and a to_symbol
).
however a few endpoints require you to supply them as one combined symbol. An example would be the get_aggregates_bars
method.
In those methods, the symbol is expected to have a prefix X:
before the currency symbol names. but the library allows you to specify the symbol with or without the prefix.
See the relevant method’s docs for more information on what the parameters expect.
here is how the client initializer looks like:
- polygon.crypto.crypto_api.CryptoClient(api_key: str, use_async: bool = False, connect_timeout: int = 10, read_timeout: int = 10, pool_timeout: int = 10, max_connections: int | None = None, max_keepalive: int | None = None, write_timeout: int = 10)
Initiates a Client to be used to access all REST crypto endpoints.
- Parameters:
api_key – Your API Key. Visit your dashboard to get yours.
use_async – Set it to
True
to get async client. Defaults to usual non-async client.connect_timeout – The connection timeout in seconds. Defaults to 10. basically the number of seconds to wait for a connection to be established. Raises a
ConnectTimeout
if unable to connect within specified time limit.read_timeout – The read timeout in seconds. Defaults to 10. basically the number of seconds to wait for date to be received. Raises a
ReadTimeout
if unable to connect within the specified time limit.pool_timeout – The pool timeout in seconds. Defaults to 10. Basically the number of seconds to wait while trying to get a connection from connection pool. Do NOT change if you’re unsure of what it implies
max_connections – Max number of connections in the pool. Defaults to NO LIMITS. Do NOT change if you’re unsure of application
max_keepalive – max number of allowable keep alive connections in the pool. Defaults to no limit. Do NOT change if you’re unsure of the applications.
write_timeout – The write timeout in seconds. Defaults to 10. basically the number of seconds to wait for data to be written/posted. Raises a
WriteTimeout
if unable to connect within the specified time limit.
Endpoints
To use any of the below method, simply call it on the client you created above. so if you named your client client
,
you’d call the methods as client.get_historic_trades
and so on. Async methods will need to be awaited, see Async Support for REST endpoints.
SMA
Simple Moving Average. This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncCryptoClient.get_sma(symbol: str, timestamp=None, timespan='day', adjusted: bool = True, window_size: int = 50, series_type='close', include_underlying: bool = False, order='desc', limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the Simple Moving Average for a crypto pair
- Parameters:
symbol – The option symbol. You can pass it with or without the prefix
X:
.timestamp – Either a date with the format
YYYY-MM-DD
or a millisecond timestamp.timespan – Size of the aggregate time window. defaults to ‘day’. See
polygon.enums.Timespan
for choicesadjusted – Whether the aggregates used to calculate the simple moving average are adjusted for splits. By default, aggregates are adjusted. Set this to
False
to get results that are NOT adjusted for splits.window_size – The window size used to calculate the simple moving average (SMA). i.e. a window size of 10 with daily aggregates would result in a 10 day moving average.
series_type – The prices in the aggregate which will be used to calculate the SMA. The default
close
will result in using close prices to calculate the SMA. Seepolygon.enums.SeriesType
for choicesinclude_underlying – Whether to include the OCHLV aggregates used to calculate this indicator in the response. Defaults to False which only returns the SMA.
order – The order in which to return the results, ordered by timestamp. See
polygon.enums.SortOrder
for choices. Defaults to Descending (most recent first)limit – Limit the number of results returned, default is 5000 which is also the max
timestamp_lt – Only use results where timestamp is less than supplied value
timestamp_lte – Only use results where timestamp is less than or equal to supplied value
timestamp_gt – Only use results where timestamp is greater than supplied value
timestamp_gte – Only use results where timestamp is greater than or equal to supplied value
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
The response object
EMA
Exponential Moving Average. This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncCryptoClient.get_ema(symbol: str, timestamp=None, timespan='day', adjusted: bool = True, window_size: int = 50, series_type='close', include_underlying: bool = False, order='desc', limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the Exponential Moving Average for a crypto pair
- Parameters:
symbol – The option symbol. You can pass it with or without the prefix
X:
.timestamp – Either a date with the format
YYYY-MM-DD
or a millisecond timestamp.timespan – Size of the aggregate time window. defaults to ‘day’. See
polygon.enums.Timespan
for choicesadjusted – Whether the aggregates used to calculate the EMA are adjusted for splits. By default, aggregates are adjusted. Set this to
False
to get results that are NOT adjusted for splits.window_size – The window size used to calculate the EMA. i.e. a window size of 10 with daily aggregates would result in a 10 day moving average.
series_type – The prices in the aggregate which will be used to calculate the EMA. The default
close
will result in using close prices to calculate the EMA. Seepolygon.enums.SeriesType
for choicesinclude_underlying – Whether to include the OCHLV aggregates used to calculate this indicator in the response. Defaults to False which only returns the EMA.
order – The order in which to return the results, ordered by timestamp. See
polygon.enums.SortOrder
for choices. Defaults to Descending (most recent first)limit – Limit the number of results returned, default is 5000 which is also the max
timestamp_lt – Only use results where timestamp is less than supplied value
timestamp_lte – Only use results where timestamp is less than or equal to supplied value
timestamp_gt – Only use results where timestamp is greater than supplied value
timestamp_gte – Only use results where timestamp is greater than or equal to supplied value
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
The response object
RSI
Relative Strength Index. This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncCryptoClient.get_rsi(symbol: str, timestamp=None, timespan='day', adjusted: bool = True, window_size: int = 14, series_type='close', include_underlying: bool = False, order='desc', limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the Relative Strength Index for a crypto pair
- Parameters:
symbol – The option symbol. You can pass it with or without the prefix
X:
.timestamp – Either a date with the format
YYYY-MM-DD
or a millisecond timestamp.timespan – Size of the aggregate time window. defaults to ‘day’. See
polygon.enums.Timespan
for choicesadjusted – Whether the aggregates used to calculate the RSI are adjusted for splits. By default, aggregates are adjusted. Set this to
False
to get results that are NOT adjusted for splits.window_size – The window size used to calculate the RSI. i.e. a window size of 14 with daily aggregates would result in a 14 day RSI.
series_type – The prices in the aggregate which will be used to calculate the RSI. The default
close
will result in using close prices to calculate the RSI. Seepolygon.enums.SeriesType
for choicesinclude_underlying – Whether to include the OCHLV aggregates used to calculate this indicator in the response. Defaults to False which only returns the RSI.
order – The order in which to return the results, ordered by timestamp. See
polygon.enums.SortOrder
for choices. Defaults to Descending (most recent first)limit – Limit the number of results returned, default is 5000 which is also the max
timestamp_lt – Only use results where timestamp is less than supplied value
timestamp_lte – Only use results where timestamp is less than or equal to supplied value
timestamp_gt – Only use results where timestamp is greater than supplied value
timestamp_gte – Only use results where timestamp is greater than or equal to supplied value
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
The response object
MACD
Moving Average Convergence/Divergence. This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncCryptoClient.get_macd(symbol: str, timestamp=None, timespan='day', adjusted: bool = True, long_window_size: int = 50, series_type='close', include_underlying: bool = False, order='desc', limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, short_window_size: int = 50, signal_window_size: int = 50, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get the Moving Average Convergence/Divergence for a crypto pair
- Parameters:
symbol – The option symbol. You can pass it with or without the prefix
X:
.timestamp – Either a date with the format
YYYY-MM-DD
or a millisecond timestamp.timespan – Size of the aggregate time window. defaults to ‘day’. See
polygon.enums.Timespan
for choicesadjusted – Whether the aggregates used to calculate the MACD are adjusted for splits. By default, aggregates are adjusted. Set this to
False
to get results that are NOT adjusted for splits.long_window_size – The long window size used to calculate the MACD data
series_type – The prices in the aggregate which will be used to calculate the MACD. The default
close
will result in using close prices to calculate the MACD. Seepolygon.enums.SeriesType
for choicesinclude_underlying – Whether to include the OCHLV aggregates used to calculate this indicator in the response. Defaults to False which only returns the MACD.
order – The order in which to return the results, ordered by timestamp. See
polygon.enums.SortOrder
for choices. Defaults to Descending (most recent first)limit – Limit the number of results returned, default is 5000 which is also the max
timestamp_lt – Only use results where timestamp is less than supplied value
timestamp_lte – Only use results where timestamp is less than or equal to supplied value
timestamp_gt – Only use results where timestamp is greater than supplied value
timestamp_gte – Only use results where timestamp is greater than or equal to supplied value
short_window_size – The short window size used to calculate the MACD data
signal_window_size – The window size used to calculate the MACD signal line.
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
The response object
Get Historic Trades
- SyncCryptoClient.get_historic_trades(from_symbol: str, to_symbol: str, date, offset: str | int | None = None, limit: int = 500, raw_response: bool = False)
Get historic trade ticks for a cryptocurrency pair. Official Docs
- Parameters:
from_symbol – The “from” symbol of the crypto pair.
to_symbol – The “to” symbol of the crypto pair.
date – The date/day of the historic ticks to retrieve. Could be
datetime
,date
or stringYYYY-MM-DD
offset – The timestamp offset, used for pagination. This is the offset at which to start the results. Using the timestamp of the last result as the offset will give you the next page of results. I’m trying to think of a good way to implement pagination in the library for these endpoints which do not return a
next_url
attribute.limit – Limit the size of the response, max 10000. Default 500
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Trades
This endpoint supports pagination. Passing all_pages=True
enables it. See Pagination Support for better info
- SyncCryptoClient.get_trades(symbol: str, timestamp: int | None = None, order=None, sort=None, limit: int = 5000, timestamp_lt=None, timestamp_lte=None, timestamp_gt=None, timestamp_gte=None, all_pages: bool = False, max_pages: int | None = None, merge_all_pages: bool = True, verbose: bool = False, raw_page_responses: bool = False, raw_response: bool = False)
Get trades for a crypto ticker symbol in a given time range. Official Docs
- Parameters:
symbol – The ticker symbol you want trades for. e.g.
X:BTC-USD
. you can pass with or without the prefixC:
timestamp – Query by trade timestamp. Could be
datetime
ordate
or stringYYYY-MM-DD
or a nanosecond timestamporder – sort order. see
polygon.enums.SortOrder
for available choices. defaults to Nonesort – field key to sort against. Defaults to None. see
polygon.enums.CryptoTradesSort
for choiceslimit – Limit the size of the response, max 50000 and default 5000.
timestamp_lt – return results where timestamp is less than the given value. Can be date or date string or nanosecond timestamp
timestamp_lte – return results where timestamp is less than/equal to the given value. Can be date or date string or nanosecond timestamp
timestamp_gt – return results where timestamp is greater than the given value. Can be date or date string or nanosecond timestamp
timestamp_gte – return results where timestamp is greater than/equal to the given value. Can be date or date string or nanosecond timestamp
all_pages – Whether to paginate through next/previous pages internally. Defaults to False. If set to True, it will try to paginate through all pages and merge all pages internally for you.
max_pages – how many pages to fetch. Defaults to None which fetches all available pages. Change to an integer to fetch at most that many pages. This param is only considered if
all_pages
is set to Truemerge_all_pages – If this is True, returns a single merged response having all the data. If False, returns a list of all pages received. The list can be either a list of response objects or decoded data itself, controlled by parameter
raw_page_responses
. This argument is Only considered ifall_pages
is set to True. Default: Trueverbose – Set to True to print status messages during the pagination process. Defaults to False.
raw_page_responses – If this is true, the list of pages will be a list of corresponding Response objects. Else, it will be a list of actual data for pages. This parameter is only considered if
merge_all_pages
is set to False. Default: Falseraw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary. This is ignored if pagination is set to True.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object. If pagination is set to True, will return a merged response of all pages for convenience.
Get Last Trade
- SyncCryptoClient.get_last_trade(from_symbol: str, to_symbol: str, raw_response: bool = False)
Get the last trade tick for a cryptocurrency pair. Official Docs
- Parameters:
from_symbol – The “from” symbol of the pair.
to_symbol – The “to” symbol of the pair.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Daily Open Close
- SyncCryptoClient.get_daily_open_close(from_symbol: str, to_symbol: str, date, adjusted: bool = True, raw_response: bool = False)
Get the open, close prices of a cryptocurrency symbol on a certain day. Official Docs:
- Parameters:
from_symbol – The “from” symbol of the pair.
to_symbol – The “to” symbol of the pair.
date – The date of the requested open/close. Could be
datetime
,date
or stringYYYY-MM-DD
.adjusted – whether the results are adjusted for splits. By default, results are adjusted. Set this to False to get results that are NOT adjusted for splits.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Aggregate Bars (Candles)
The library added a better aggregate function if you’re looking to get data for large time frames at minute/hour granularity.
(for example 15 years historical data , 1 minute candles)
See Bulk Aggregate Bars (Full Range) for complete details on how to use it well and control how it behaves.
- SyncCryptoClient.get_aggregate_bars(symbol: str, from_date, to_date, multiplier: int = 1, timespan='day', adjusted: bool = True, sort='asc', limit: int = 5000, full_range: bool = False, run_parallel: bool = True, max_concurrent_workers: int = 10, info: bool = True, warnings: bool = True, high_volatility: bool = False, raw_response: bool = False)
Get aggregate bars for a cryptocurrency pair over a given date range in custom time window sizes. For example, if
timespan=‘minute’
andmultiplier=‘5’
then 5-minute bars will be returned. Official Docs- Parameters:
symbol – The ticker symbol of the currency pair. e.g.:
X:BTCUSD
. You can specify with or without prefixX:
from_date – The start of the aggregate time window. Could be
datetime
,date
or stringYYYY-MM-DD
to_date – The end of the aggregate time window. Could be
datetime
,date
or stringYYYY-MM-DD
multiplier – The size of the timespan multiplier
timespan – The size of the time window. Defaults to day candles. see
polygon.enums.Timespan
for choicesadjusted – whether the results are adjusted for splits. By default, results are adjusted. Set this to False to get results that are NOT adjusted for splits.
sort – Order of sorting the results. See
polygon.enums.SortOrder
for available choices. Defaults toasc
(oldest at the top)limit – Limits the number of base aggregates queried to create the aggregate results. Max 50000 and Default 5000.
full_range – Default False. If set to True, it will get the ENTIRE range you specify and merge all the responses and return ONE single list with all data in it. You can control its behavior with the next few arguments.
run_parallel – Only considered if
full_range=True
. If set to true (default True), it will run an internal ThreadPool to get the responses. This is fine to do if you are not running your own ThreadPool. If you have many tickers to get aggs for, it’s better to either use the async version of it OR set this to False and spawn threads for each ticker yourself.max_concurrent_workers – Only considered if
run_parallel=True
. Defaults toyour cpu cores * 5
. controls how many worker threads to use in internal ThreadPoolinfo – Set to False to disable printing mild warnings / informational messages if any when fetching the aggs. E.g. if there was no data in a response but the response had an OK status
warnings – Set to False to disable printing warnings if any when fetching the aggs. Defaults to True.
high_volatility – Specifies whether the symbol/security in question is highly volatile which just means having a very high number of trades or being traded for a high duration (e.g. SPY, Bitcoin) If set to True, the lib will use a smaller chunk of time to ensure we don’t miss any data due to 50k candle limit. Defaults to False.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary. Will be ignored iffull_range=True
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object. Iffull_range=True
, will return a single list with all the candles in it.
Get Grouped Daily Bars (Candles)
- SyncCryptoClient.get_grouped_daily_bars(date, adjusted: bool = True, raw_response: bool = False)
Get the daily open, high, low, and close (OHLC) for the entire cryptocurrency market. Official Docs
- Parameters:
date – The date for the aggregate window. Could be
datetime
,date
or stringYYYY-MM-DD
adjusted – whether the results are adjusted for splits. By default, results are adjusted. Set this to False to get results that are NOT adjusted for splits.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Previous Close
- SyncCryptoClient.get_previous_close(symbol: str, adjusted: bool = True, raw_response: bool = False)
Get the previous day’s open, high, low, and close (OHLC) for the specified cryptocurrency pair. Official Docs
- Parameters:
symbol – The ticker symbol of the currency pair. e.g.:
X:BTCUSD
. You can specify with or without the prefixX:
adjusted – whether the results are adjusted for splits. By default, results are adjusted. Set this to False to get results that are NOT adjusted for splits.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Snapshot All
- SyncCryptoClient.get_snapshot_all(symbols: list, raw_response: bool = False)
Get the current minute, day, and previous day’s aggregate, as well as the last trade and quote for all traded cryptocurrency symbols Official Docs
- Parameters:
symbols – A list of tickers to get snapshots for.
raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Snapshot
- SyncCryptoClient.get_snapshot(symbol: str, raw_response: bool = False)
Get the current minute, day, and previous day’s aggregate, as well as the last trade and quote for a single traded cryptocurrency symbol. Official Docs
- Parameters:
symbol – Symbol of the currency pair. e.g.:
X:BTCUSD
. you can specify with or without prefixX:
raw_response – whether to return the Response Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Gainers and Losers
- SyncCryptoClient.get_gainers_and_losers(direction='gainers', raw_response: bool = False)
Get the current top 20 gainers or losers of the day in cryptocurrency markets. Official docs
- Parameters:
direction – The direction of the snapshot results to return. See
polygon.enums.SnapshotDirection
for available choices. Defaults to Gainers.raw_response – whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object
Get Level 2 Book
- SyncCryptoClient.get_level2_book(symbol: str, raw_response: bool = False)
Get the current level 2 book of a single ticker. This is the combined book from all of the exchanges. Official Docs
- Parameters:
symbol – The cryptocurrency ticker. e.g.:
X:BTCUSD
. You can specify with or without the prefix`X:
raw_response – Whether to return the
Response
Object. Useful for when you need to say check the status code or inspect the headers. Defaults to False which returns the json decoded dictionary.
- Returns:
A JSON decoded Dictionary by default. Make
raw_response=True
to get underlying response object