Market & Economic Insights
As the name suggests, users are a core part of Protocol — the very reason Protocol exists is so you can have secure conversations with your users. On this page, we'll dive into the different user endpoints you can use to manage users programmatically. We'll look at how to query, create, update, and delete users.
Introduction
The user model contains all the information about your users, such as their username, avatar, and phone number. It also contains a reference to the conversation between you and the user and information about when they were last active on Protocol.
Market Status
This endpoint returns a comprehensive list of the major global financial markets, offering real-time information on their current trading status - indicating whether they're open, closed, or trading after hours.
Response Attributes
- Name
regions
- Type
- object
- Description
An object representing different regions and their market information.
- Name
US / UK / EU / JP / CN
- Type
- object
- Description
An object containing market information specific to the geographic area represented by the key.
- Name
isMarketOpen
- Type
- boolean
- Description
Indicates whether the market is currently open (true) or closed (false).
- Name
marketStatus
- Type
- string
- Description
Specifies the current status of the market. Possible values include "open" | "closed" | "pre-market" | "after-hours" | "lunch" | "holiday"
- Name
referencedExchanges
- Type
- array
- Description
Lists the exchanges referenced within the region as an array.
- Name
localTime
- Type
- array
- Description
Provides the local date and time information for the region. The first element represents the date and time in ISO 8601 format, and the second element represents the timezone abbreviation.
- Name
nextOpen
- Type
- string
- Description
Specifies the date and time of the next market open for the region in ISO 8601 format.
Request
curl -G https://api.ungage.io/v1/insights/market/status \
-H "Authorization: Bearer {token}" \
Response
{
"regions": {
"US": {
"isMarketOpen": true,
"marketStatus": "open",
"referencedExchanges": ["NASDAQ", "NYSE"],
"localTime": ["YYYY-MM-DDT09:30:00-05:00", "EST/EDT"],
"nextOpen": "YYYY-MM-DDT09:30:00-05:00"
},
"UK": {
"isMarketOpen": true,
"marketStatus": "open",
"referencedExchanges": ["LSE"],
"localTime": ["YYYY-MM-DDT08:30:00Z", "GMT/BST"],
"nextOpen": "YYYY-MM-DDT08:30:00Z"
},
"EU": {
"isMarketOpen": true,
"marketStatus": "open",
"referencedExchanges": ["EURONEXT"],
"localTime": ["YYYY-MM-DDT09:00:00+01:00", "CET/CEST"],
"nextOpen": "YYYY-MM-DDT09:00:00+01:00"
},
"JP": {
"isMarketOpen": true,
"marketStatus": "open",
"referencedExchanges": ["TSE"],
"localTime": ["YYYY-MM-DDT09:00:00+09:00", "JST"],
"nextOpen": "YYYY-MM-DDT09:00:00+09:00"
},
"CN": {
"isMarketOpen": true,
"marketStatus": "open",
"referencedExchanges": ["SSE"],
"localTime": ["YYYY-MM-DDT09:30:00+08:00", "CST"],
"nextOpen": "YYYY-MM-DDT09:30:00+08:00"
}
}
}
Upcoming Market Holidays
This endpoint returns the upcoming trading holidays for all global major stock exchanges
Response Attributes
- Name
regions
- Type
- object
- Description
An object representing the various regions this endpoint provides data for.
- Name
US / UK / EU / JP / CN
- Type
- object
- Description
An object containing exchange holiday information specific to the geographic area represented by the key.
- Name
referencedExchanges
- Type
- array
- Description
An array of exchanges referenced for the region.
- Name
holidays
- Type
- array
- Description
An array of holiday objects specific to the region.
- Name
date
- Type
- string
- Description
The date of the holiday in the format "YYYY-MM-DD".
- Name
name
- Type
- string
- Description
The name of the holiday.
Request
curl -G https://api.ungage.io/v1/insights/market/holidays \
-H "Authorization: Bearer {token}" \
Response
{
"regions": {
"US": {
"referencedExchanges": ["NASDAQ", "NYSE"],
"holidays": [
{ "date": "YYYY-MM-DD", "name": "Independence Day" },
{ "date": "YYYY-MM-DD", "name": "Christmas" }
]
},
"UK": {
"referencedExchanges": ["LSE"],
"holidays": [
{ "date": "YYYY-MM-DD", "name": "Bank Holiday" },
{ "date": "YYYY-MM-DD", "name": "Good Friday" }
]
},
"EU": {
"referencedExchanges": ["EURONEXT"],
"holidays": [
{ "date": "YYYY-MM-DD", "name": "Christmas" },
{ "date": "YYYY-MM-DD", "name": "Boxing Day" }
]
},
"JP": {
"referencedExchanges": ["TSE"],
"holidays": [
{ "date": "YYYY-MM-DD", "name": "Old Age Day" },
{ "date": "YYYY-MM-DD", "name": "Culture Day" }
]
},
"CN": {
"referencedExchanges": ["SSE"],
"holidays": [
{ "date": "YYYY-MM-DD", "name": "Chinese New Year" },
{ "date": "YYYY-MM-DD", "name": "Dragon Boat Festival" }
]
}
}
}
Market Performance
This endpoint allows you to retrieve the market performance of a specific region. The performance data provided is based on the flagship benchmark fund for each region. For the United States, the performance is based on the S&P 500, which is widely recognized as a prominent benchmark for the US market.
Query Parameters
- Name
region
- Type
- string
- Description
Provide the region to calculate the current market performance for. The current supported regions are: "US" (United States) | "UK" (United Kingdom) | "EU" (Europe) | "AS" (Asia) | "ALL" (All Markets). If no region is provided, it defaults to the US.
- Name
startDate
- Type
- date / string
- Description
Provide a start date in format: YYYY-MM-DD, an ISO 8601 string to filter for, OR "WTD" | "MTD" | "YTD" which will override the start/end dates. If not provided, it defaults to the start of the current month (MTD).
- Name
endDate
- Type
- date
- Description
Provide an end date in format: YYYY-MM-DD, or an ISO 8601 string to filter for. If not provided, it defaults to the current date.
- Name
benchmark
- Type
- string (US Only)
- Description
For the US, you can choose between various funds as your benchmark for market performance. Supported values are: "S&P500" | "NASDAQ" | "DOWJ".
Response Attributes
- Name
marketPerformance
- Type
- object
- Description
Represents the market performance based on a specific benchmark and region.
- Name
region
- Type
- string
- Description
Indicates the region for which the market performance is provided.
- Name
benchmark
- Type
- string
- Description
Specifies the benchmark against which the market performance is measured.
- Name
startDate
- Type
- date
- Description
Represents the start date of the market performance data. The date follows the format "YYYY-MM-DD".
- Name
endDate
- Type
- date
- Description
Represents the end date of the market performance data. The date follows the format "YYYY-MM-DD".
- Name
return
- Type
- string
- Description
Indicates the market return percentage for the specified benchmark and region. This value represents the overall performance of the market within the specified time period.
Request
curl -G https://api.ungage.io/v1/insights/market/performance \
-H "Authorization: Bearer {token}" \
-d "region=ALL" \
-d "startDate=WTD" \
-d "benchmark=S&P500" \
Response
{
"regions": {
"US": {
"benchmark": "SPDR S&P 500 | SPY",
"marketPerformance": {
"timeRange": ["2023-01-01", "2023-07-12"],
"priceRange": [390.12, 450.12],
"return": 11.23
}
},
"UK": {
"benchmark": "iShares MSCI United Kingdom | EWU",
"marketPerformance": {
"timeRange": ["2023-01-01", "2023-07-12"],
"priceRange": [390.12, 450.12],
"return": 11.23
}
},
"EU": {
"benchmark": "iShares Core MSCI Europe | IEUR",
"marketPerformance": {
"timeRange": ["2023-01-01", "2023-07-12"],
"priceRange": [390.12, 450.12],
"return": 11.23
}
},
"AS": {
"benchmark": "iShares MSCI Emerging Markets Asia ETF | EEMA",
"marketPerformance": {
"timeRange": ["2023-01-01", "2023-07-12"],
"priceRange": [390.12, 450.12],
"return": 11.23
}
}
}
}
Sector Performance
This endpoint returns the performance of a specific sector and compares it to the benchmark, enabling you to monitor whether various industries are outperforming or underperforming the overall market. Sector data is based on the US market.
Query Parameters
- Name
sector
- Type
- string
- Description
Provide the sector to retreive performance information about. The supported regions are the 11 sectors based on the Global Industry Classification Standard (GICS) ↓
energy
materials
industrials
utilities
healthcare
financials
consumer-discretionary
consumer-staples
information-technology
communication-services
real-estate
If you would like to retireve data for all sectors, either exclude this query parameter, or provideALL
- Name
startDate
- Type
- date / string
- Description
Provide a start date in format:
YYYY-MM-DD
, an ISO 8601 string to filter for, ORWTD
MTD
YTD
which will override the start/end dates. If not provided, it defaults to the start of the current monthMTD
- Name
endDate
- Type
- date
- Description
Provide an end date in format:
YYYY-MM-DD
, or an ISO 8601 string to filter for. If not provided, it defaults to the current date.
- Name
benchmark
- Type
- string
- Description
You can choose between various US funds as your benchmark to compare sector performance against. Supported values are ↓
SPY
QQQ
DIA
Request
curl -X PUT https://api.protocol.chat/v1/users/WAz8eIbvDR60rouK \
-H "Authorization: Bearer {token}" \
-d role_id="hSIhXBhNe8X1d8Et" \
-d branch_access=["hSIhXBhNe8X1d8Et"]
Response
{
"benchmarkPerformance": {
"benchmarkFund": "SPDR S&P 500 | SPY",
"startDate": "YYYY-MM-DD",
"endDate": "YYYY-MM-DD",
"return": 1.23
},
"sectors": {
"energy": {
"sectorFund": "iShares U.S. Energy ETF | IYE",
"sectorPerformance":
{ "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD", "return": 1.23, "vsBenchmark": -1.23 }
},
"materials": {
"sectorFund": "iShares U.S. Basic Materials ETF | IYM",
"sectorPerformance":
{ "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD", "return": 1.23, "vsBenchmark": -1.23 }
},
"industrials": {
"sectorFund": "iShares U.S. Industrials ETF | IYJ",
"sectorPerformance":
{ "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD", "return": 1.23, "vsBenchmark": -1.23 }
},
"utilities": {
"sectorFund": "iShares U.S. Utilities ETF | IDU",
"sectorPerformance":
{ "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD", "return": 1.23, "vsBenchmark": -1.23 }
},
"healthcare": {
"sectorFund": "iShares U.S. Healthcare ETF | IYH",
"sectorPerformance":
{ "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD", "return": 1.23, "vsBenchmark": -1.23 }
},
"financials": {
"sectorFund": "iShares U.S. Financials ETF | IYF",
"sectorPerformance":
{ "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD", "return": 1.23, "vsBenchmark": -1.23 }
},
"consumer-discretionary": {
"sectorFund": "iShares U.S. Consumer Discretionary ETF | IYC",
"sectorPerformance":
{ "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD", "return": 1.23, "vsBenchmark": -1.23 }
},
"consumer-staples": {
"sectorFund": "iShares U.S. Consumer Staples ETF | IYK",
"sectorPerformance":
{ "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD", "return": 1.23, "vsBenchmark": -1.23 }
},
"information-technology": {
"sectorFund": "iShares U.S. Technology ETF | IYW",
"sectorPerformance":
{ "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD", "return": 1.23, "vsBenchmark": -1.23 }
},
"communication-services": {
"sectorFund": "iShares U.S. Communication Services ETF | IYZ",
"sectorPerformance":
{ "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD", "return": 1.23, "vsBenchmark": -1.23 }
},
"real-estate": {
"sectorFund": "iShares U.S. Real Estate ETF | IYR",
"sectorPerformance":
{ "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD", "return": 1.23, "vsBenchmark": -1.23 }
}
}
}
Delete a user
This endpoint allows you to delete users from your user list in Protocol. Note: This will also delete your conversation with the given user.
Request
curl -X DELETE https://api.protocol.chat/v1/users/WAz8eIbvDR60rouK \
-H "Authorization: Bearer {token}"