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.

GET/v1/insights/market/status

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

GET

/v1/insights/market/status

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"
    }
  }
}

GET/v1/insights/market/holidays

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

GET

/v1/insights/market/holidays

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" }
      ]
    }
  }
}

GET/v1/insights/market/performance

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

GET

/v1/insights/market/performance

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
      }
    }
  }
}

GET/v1/insights/sector/performance

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 provide ALL
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
Description
You can choose between various US funds as your benchmark to compare sector performance against. Supported values are ↓
SPY QQQ DIA

Request

GET

/v1/insights/sector/performance

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/v1/users/:id

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

DELETE

/v1/users/WAz8eIbvDR60rouK

curl -X DELETE https://api.protocol.chat/v1/users/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"