prediction-market-agent-tooling 0.65.5__py3-none-any.whl → 0.69.17.dev1149__py3-none-any.whl

prediction_market_agent_tooling/markets/seer/seer_api.py

@@ -0,0 +1,28 @@
+import httpx
+
+from prediction_market_agent_tooling.gtypes import ChainID, ChecksumAddress
+from prediction_market_agent_tooling.markets.seer.data_models import SeerTransaction
+from prediction_market_agent_tooling.tools.datetime_utc import DatetimeUTC
+from prediction_market_agent_tooling.tools.utils import to_int_timestamp, utcnow
+
+
+def get_seer_transactions(
+    account: ChecksumAddress,
+    chain_id: ChainID,
+    start_time: DatetimeUTC | None = None,
+    end_time: DatetimeUTC | None = None,
+    timeout: int = 60,  # The endpoint is pretty slow to respond atm.
+) -> list[SeerTransaction]:
+    url = "https://app.seer.pm/.netlify/functions/get-transactions"
+    params: dict[str, str | int] = {
+        "account": account,
+        "chainId": chain_id,
+        "startTime": to_int_timestamp(start_time) if start_time else 0,
+        "endTime": to_int_timestamp(end_time if end_time else utcnow()),
+    }
+    response = httpx.get(url, params=params, timeout=timeout)
+    response.raise_for_status()
+    response_json = response.json()
+
+    transactions = [SeerTransaction.model_validate(tx) for tx in response_json]
+    return transactions

prediction_market_agent_tooling/markets/seer/seer_contracts.py

@@ -8,14 +8,20 @@ from prediction_market_agent_tooling.gtypes import (
     ABI,
     ChecksumAddress,
     OutcomeStr,
+    OutcomeWei,
     TxReceipt,
+    Wei,
     xDai,
 )
-from prediction_market_agent_tooling.markets.seer.data_models import RedeemParams
+from prediction_market_agent_tooling.markets.seer.data_models import (
+    ExactInputSingleParams,
+    QuoteExactInputSingleParams,
+)
 from prediction_market_agent_tooling.markets.seer.subgraph_data_models import (
     CreateCategoricalMarketsParams,
 )
 from prediction_market_agent_tooling.tools.contract import (
+    ContractERC20OnGnosisChain,
     ContractOnGnosisChain,
     abi_field_validator,
 )
@@ -83,7 +89,7 @@ class SeerMarketFactory(ContractOnGnosisChain):
 
 
 class GnosisRouter(ContractOnGnosisChain):
-    # https://gnosisscan.io/address/0x83183da839ce8228e31ae41222ead9edbb5cdcf1#code.
+    # https://gnosisscan.io/address/0xeC9048b59b3467415b1a38F63416407eA0c70fB8#code.
     abi: ABI = abi_field_validator(
         os.path.join(
             os.path.dirname(os.path.realpath(__file__)),
@@ -97,12 +103,18 @@ class GnosisRouter(ContractOnGnosisChain):
     def redeem_to_base(
         self,
         api_keys: APIKeys,
-        params: RedeemParams,
+        market: ChecksumAddress,
+        outcome_indexes: list[int],
+        amounts: list[OutcomeWei],
         web3: Web3 | None = None,
     ) -> TxReceipt:
-        params_dict = params.model_dump(by_alias=True)
         # We explicity set amounts since OutcomeWei gets serialized as dict
-        params_dict["amounts"] = [amount.value for amount in params.amounts]
+        params_dict = {
+            "market": market,
+            "outcomeIndexes": outcome_indexes,
+            "amounts": [amount.value for amount in amounts],
+        }
+
         receipt_tx = self.send(
             api_keys=api_keys,
             function_name="redeemToBase",
@@ -110,3 +122,101 @@ class GnosisRouter(ContractOnGnosisChain):
             web3=web3,
         )
         return receipt_tx
+
+    def split_from_base(
+        self,
+        api_keys: APIKeys,
+        market_id: ChecksumAddress,
+        amount_wei: Wei,
+        web3: Web3 | None = None,
+    ) -> TxReceipt:
+        """Splits using xDAI and receives outcome tokens"""
+        return self.send_with_value(
+            api_keys=api_keys,
+            function_name="splitFromBase",
+            amount_wei=amount_wei,
+            function_params=[market_id],
+            web3=web3,
+        )
+
+    def split_position(
+        self,
+        api_keys: APIKeys,
+        collateral_token: ChecksumAddress,
+        market_id: ChecksumAddress,
+        amount: Wei,
+        web3: Web3 | None = None,
+    ) -> TxReceipt:
+        """Splits collateral token into full set of outcome tokens."""
+        receipt_tx = self.send(
+            api_keys=api_keys,
+            function_name="splitPosition",
+            function_params=[collateral_token, market_id, amount],
+            web3=web3,
+        )
+        return receipt_tx
+
+
+class SwaprRouterContract(ContractOnGnosisChain):
+    abi: ABI = abi_field_validator(
+        os.path.join(
+            os.path.dirname(os.path.realpath(__file__)),
+            "../../abis/swapr_router.abi.json",
+        )
+    )
+
+    address: ChecksumAddress = Web3.to_checksum_address(
+        "0xffb643e73f280b97809a8b41f7232ab401a04ee1"
+    )
+
+    def exact_input_single(
+        self,
+        api_keys: APIKeys,
+        params: ExactInputSingleParams,
+        web3: Web3 | None = None,
+    ) -> TxReceipt:
+        erc20_token = ContractERC20OnGnosisChain(address=params.token_in)
+
+        if (
+            erc20_token.allowance(api_keys.bet_from_address, self.address, web3=web3)
+            < params.amount_in
+        ):
+            erc20_token.approve(api_keys, self.address, params.amount_in, web3=web3)
+
+        return self.send(
+            api_keys=api_keys,
+            function_name="exactInputSingle",
+            function_params=[tuple(dict(params).values())],
+            web3=web3,
+            # Use higher gas limit for complex swap operations to avoid slow estimation
+            # Typical Swapr swaps use 150k-300k gas, we set conservative
+            default_gas=400_000,
+        )
+
+
+class SwaprQuoterContract(ContractOnGnosisChain):
+    # File content taken from https://gnosisscan.io/address/0xcBaD9FDf0D2814659Eb26f600EFDeAF005Eda0F7#code.
+    abi: ABI = abi_field_validator(
+        os.path.join(
+            os.path.dirname(os.path.realpath(__file__)),
+            "../../abis/swapr_quoter.abi.json",
+        )
+    )
+
+    address: ChecksumAddress = Web3.to_checksum_address(
+        "0xcBaD9FDf0D2814659Eb26f600EFDeAF005Eda0F7"
+    )
+
+    def quote_exact_input_single(
+        self,
+        params: QuoteExactInputSingleParams,
+        web3: Web3 | None = None,
+    ) -> tuple[Wei, Wei]:
+        # See https://docs.uniswap.org/contracts/v3/guides/swaps/single-swaps.
+        result: tuple[int, int] = self.call(
+            function_name="quoteExactInputSingle",
+            function_params=list(dict(params).values()),
+            web3=web3,
+        )
+        amount_out, fee = result
+        return Wei(amount_out), Wei(fee)

prediction_market_agent_tooling/markets/seer/seer_subgraph_handler.py

@@ -1,27 +1,56 @@
 import sys
 import typing as t
+from collections import defaultdict
+from enum import Enum
 from typing import Any
 
 from subgrounds import FieldPath
 from web3.constants import ADDRESS_ZERO
 
 from prediction_market_agent_tooling.deploy.constants import (
+    DOWN_OUTCOME_LOWERCASE_IDENTIFIER,
     NO_OUTCOME_LOWERCASE_IDENTIFIER,
+    UP_OUTCOME_LOWERCASE_IDENTIFIER,
     YES_OUTCOME_LOWERCASE_IDENTIFIER,
 )
 from prediction_market_agent_tooling.gtypes import ChecksumAddress, Wei
 from prediction_market_agent_tooling.loggers import logger
-from prediction_market_agent_tooling.markets.agent_market import FilterBy, SortBy
+from prediction_market_agent_tooling.markets.agent_market import (
+    ConditionalFilterType,
+    FilterBy,
+    QuestionType,
+    SortBy,
+)
 from prediction_market_agent_tooling.markets.base_subgraph_handler import (
     BaseSubgraphHandler,
 )
-from prediction_market_agent_tooling.markets.seer.data_models import SeerMarket
-from prediction_market_agent_tooling.markets.seer.subgraph_data_models import SeerPool
+from prediction_market_agent_tooling.markets.seer.data_models import (
+    SeerMarket,
+    SeerMarketQuestions,
+    SeerMarketWithQuestions,
+)
+from prediction_market_agent_tooling.markets.seer.subgraph_data_models import (
+    SwaprPool,
+    SwaprSwap,
+)
 from prediction_market_agent_tooling.tools.hexbytes_custom import HexBytes
-from prediction_market_agent_tooling.tools.utils import to_int_timestamp, utcnow
+from prediction_market_agent_tooling.tools.singleton import SingletonMeta
+from prediction_market_agent_tooling.tools.utils import (
+    DatetimeUTC,
+    to_int_timestamp,
+    utcnow,
+)
 from prediction_market_agent_tooling.tools.web3_utils import unwrap_generic_value
 
 
+class TemplateId(int, Enum):
+    """Template IDs used in Reality.eth questions."""
+
+    SCALAR = 1
+    CATEGORICAL = 2
+    MULTICATEGORICAL = 3
+
+
 class SeerSubgraphHandler(BaseSubgraphHandler):
     """
     Class responsible for handling interactions with Seer subgraphs.
@@ -47,7 +76,9 @@ class SeerSubgraphHandler(BaseSubgraphHandler):
             )
         )
 
-    def _get_fields_for_markets(self, markets_field: FieldPath) -> list[FieldPath]:
+    def _get_fields_for_markets(
+        self, markets_field: FieldPath, current_level: int = 0, max_level: int = 1
+    ) -> list[FieldPath]:
         fields = [
             markets_field.id,
             markets_field.factory,
@@ -61,12 +92,26 @@ class SeerSubgraphHandler(BaseSubgraphHandler):
             markets_field.payoutNumerators,
             markets_field.hasAnswers,
             markets_field.blockTimestamp,
-            markets_field.parentMarket.id,
             markets_field.openingTs,
             markets_field.finalizeTs,
             markets_field.wrappedTokens,
             markets_field.collateralToken,
+            markets_field.upperBound,
+            markets_field.lowerBound,
+            markets_field.templateId,
         ]
+        if current_level < max_level:
+            fields.extend(
+                self._get_fields_for_markets(
+                    markets_field.parentMarket, current_level + 1, max_level
+                )
+            )
+            # TODO: Same situation as with `questions` field above.
+            # fields.extend(
+            #     self._get_fields_for_markets(
+            #         markets_field.childMarkets, current_level + 1, max_level
+            #     )
+            # )
         return fields
 
     @staticmethod
@@ -74,12 +119,30 @@ class SeerSubgraphHandler(BaseSubgraphHandler):
         # We do an extra check for the invalid outcome for safety.
         return [m for m in markets if len(m.outcomes) == 3]
 
+    @staticmethod
+    def _create_case_variations_condition(
+        identifier: str,
+        outcome_condition: str = "outcomes_contains",
+        condition: str = "or",
+    ) -> dict[str, list[dict[str, list[str]]]]:
+        return {
+            condition: [
+                {outcome_condition: [variation]}
+                for variation in [
+                    identifier.lower(),
+                    identifier.capitalize(),
+                    identifier.upper(),
+                ]
+            ]
+        }
+
     @staticmethod
     def _build_where_statements(
         filter_by: FilterBy,
         outcome_supply_gt_if_open: Wei,
-        include_conditional_markets: bool = False,
-        include_categorical_markets: bool = True,
+        question_type: QuestionType = QuestionType.ALL,
+        conditional_filter_type: ConditionalFilterType = ConditionalFilterType.ONLY_NOT_CONDITIONAL,
+        parent_market_id: HexBytes | None = None,
     ) -> dict[Any, Any]:
         now = to_int_timestamp(utcnow())
 
@@ -98,31 +161,62 @@ class SeerSubgraphHandler(BaseSubgraphHandler):
             case _:
                 raise ValueError(f"Unknown filter {filter_by}")
 
-        if not include_conditional_markets:
-            and_stms["parentMarket"] = ADDRESS_ZERO.lower()
+        if parent_market_id:
+            and_stms["parentMarket"] = parent_market_id.to_0x_hex().lower()
 
-        # We are only interested in binary markets of type YES/NO/Invalid.
-        yes_stms, no_stms = {}, {}
-        if not include_categorical_markets:
-            # Create single OR conditions with all variations
-            yes_stms["or"] = [
-                {"outcomes_contains": [variation]}
-                for variation in [
-                    YES_OUTCOME_LOWERCASE_IDENTIFIER,
-                    YES_OUTCOME_LOWERCASE_IDENTIFIER.capitalize(),
-                    YES_OUTCOME_LOWERCASE_IDENTIFIER.upper(),
-                ]
-            ]
-            no_stms["or"] = [
-                {"outcomes_contains": [variation]}
-                for variation in [
-                    NO_OUTCOME_LOWERCASE_IDENTIFIER,
-                    NO_OUTCOME_LOWERCASE_IDENTIFIER.capitalize(),
-                    NO_OUTCOME_LOWERCASE_IDENTIFIER.upper(),
-                ]
-            ]
+        outcome_filters: list[dict[str, t.Any]] = []
 
-        where_stms: dict[str, t.Any] = {"and": [and_stms, yes_stms, no_stms]}
+        if question_type == QuestionType.SCALAR:
+            # Template ID "1" + UP/DOWN outcomes for scalar markets
+            and_stms["templateId"] = TemplateId.SCALAR.value
+            up_filter = SeerSubgraphHandler._create_case_variations_condition(
+                UP_OUTCOME_LOWERCASE_IDENTIFIER, "outcomes_contains", "or"
+            )
+            down_filter = SeerSubgraphHandler._create_case_variations_condition(
+                DOWN_OUTCOME_LOWERCASE_IDENTIFIER, "outcomes_contains", "or"
+            )
+            outcome_filters.extend([up_filter, down_filter])
+
+        elif question_type == QuestionType.BINARY:
+            # Template ID "2" + YES/NO outcomes for binary markets
+            and_stms["templateId"] = TemplateId.CATEGORICAL.value
+            yes_filter = SeerSubgraphHandler._create_case_variations_condition(
+                YES_OUTCOME_LOWERCASE_IDENTIFIER, "outcomes_contains", "or"
+            )
+            no_filter = SeerSubgraphHandler._create_case_variations_condition(
+                NO_OUTCOME_LOWERCASE_IDENTIFIER, "outcomes_contains", "or"
+            )
+            outcome_filters.extend([yes_filter, no_filter])
+
+        elif question_type == QuestionType.CATEGORICAL:
+            # Template ID 2 (categorical) OR Template ID 3 (multi-categorical,
+            # we treat them as categorical for now for simplicity)
+            # https://reality.eth.limo/app/docs/html/contracts.html#templates
+            outcome_filters.append(
+                {
+                    "or": [
+                        {"templateId": TemplateId.CATEGORICAL.value},
+                        {"templateId": TemplateId.MULTICATEGORICAL.value},
+                    ]
+                }
+            )
+
+        # Build filters for conditional_filter type
+        conditional_filter = {}
+        match conditional_filter_type:
+            case ConditionalFilterType.ONLY_CONDITIONAL:
+                conditional_filter["parentMarket_not"] = ADDRESS_ZERO.lower()
+            case ConditionalFilterType.ONLY_NOT_CONDITIONAL:
+                conditional_filter["parentMarket"] = ADDRESS_ZERO.lower()
+            case ConditionalFilterType.ALL:
+                pass
+            case _:
+                raise ValueError(
+                    f"Unknown conditional filter {conditional_filter_type}"
+                )
+
+        all_filters = outcome_filters + [and_stms, conditional_filter]
+        where_stms: dict[str, t.Any] = {"and": all_filters}
         return where_stms
 
     def _build_sort_params(
@@ -157,18 +251,18 @@ class SeerSubgraphHandler(BaseSubgraphHandler):
         sort_by: SortBy = SortBy.NONE,
         limit: int | None = None,
         outcome_supply_gt_if_open: Wei = Wei(0),
-        include_conditional_markets: bool = True,
-        include_categorical_markets: bool = True,
-    ) -> list[SeerMarket]:
+        question_type: QuestionType = QuestionType.ALL,
+        conditional_filter_type: ConditionalFilterType = ConditionalFilterType.ONLY_NOT_CONDITIONAL,
+        parent_market_id: HexBytes | None = None,
+    ) -> list[SeerMarketWithQuestions]:
         sort_direction, sort_by_field = self._build_sort_params(sort_by)
 
-        """Returns markets that contain 2 categories plus an invalid outcome."""
-        # Binary markets on Seer contain 3 outcomes: OutcomeA, outcomeB and an Invalid option.
         where_stms = self._build_where_statements(
             filter_by=filter_by,
             outcome_supply_gt_if_open=outcome_supply_gt_if_open,
-            include_conditional_markets=include_conditional_markets,
-            include_categorical_markets=include_categorical_markets,
+            parent_market_id=parent_market_id,
+            question_type=question_type,
+            conditional_filter_type=conditional_filter_type,
         )
 
         # These values can not be set to `None`, but they can be omitted.
@@ -187,62 +281,123 @@ class SeerSubgraphHandler(BaseSubgraphHandler):
         )
         fields = self._get_fields_for_markets(markets_field)
         markets = self.do_query(fields=fields, pydantic_model=SeerMarket)
-        return markets
+        market_ids = [m.id for m in markets]
+        # We fetch questions from all markets and all parents in one go
+        parent_market_ids = [
+            m.parent_market.id for m in markets if m.parent_market is not None
+        ]
+        q = SeerQuestionsCache(seer_subgraph_handler=self)
+        q.fetch_questions(list(set(market_ids + parent_market_ids)))
+
+        # Create SeerMarketWithQuestions for each market
+        return [
+            SeerMarketWithQuestions(
+                **m.model_dump(), questions=q.market_id_to_questions[m.id]
+            )
+            for m in markets
+        ]
+
+    def get_questions_for_markets(
+        self, market_ids: list[HexBytes]
+    ) -> list[SeerMarketQuestions]:
+        where = unwrap_generic_value(
+            {"market_in": [market_id.to_0x_hex().lower() for market_id in market_ids]}
+        )
+        markets_field = self.seer_subgraph.Query.marketQuestions(where=where)
+        fields = self._get_fields_for_questions(markets_field)
+        questions = self.do_query(fields=fields, pydantic_model=SeerMarketQuestions)
+        return questions
 
-    def get_market_by_id(self, market_id: HexBytes) -> SeerMarket:
-        markets_field = self.seer_subgraph.Query.market(id=market_id.hex().lower())
+    def get_market_by_id(self, market_id: HexBytes) -> SeerMarketWithQuestions:
+        markets_field = self.seer_subgraph.Query.market(
+            id=market_id.to_0x_hex().lower()
+        )
         fields = self._get_fields_for_markets(markets_field)
         markets = self.do_query(fields=fields, pydantic_model=SeerMarket)
         if len(markets) != 1:
             raise ValueError(
                 f"Fetched wrong number of markets. Expected 1 but got {len(markets)}"
             )
-        return markets[0]
+        q = SeerQuestionsCache(self)
+        q.fetch_questions([market_id])
+        questions = q.market_id_to_questions[market_id]
+        s = SeerMarketWithQuestions.model_validate(
+            markets[0].model_dump() | {"questions": questions}
+        )
+        return s
 
-    def _get_fields_for_pools(self, pools_field: FieldPath) -> list[FieldPath]:
+    def _get_fields_for_questions(self, questions_field: FieldPath) -> list[FieldPath]:
         fields = [
-            pools_field.id,
-            pools_field.liquidity,
-            pools_field.sqrtPrice,
-            pools_field.token0Price,
-            pools_field.token1Price,
-            pools_field.token0.id,
-            pools_field.token0.name,
-            pools_field.token0.symbol,
-            pools_field.token1.id,
-            pools_field.token1.name,
-            pools_field.token1.symbol,
+            questions_field.question.id,
+            questions_field.question.best_answer,
+            questions_field.question.finalize_ts,
+            questions_field.market.id,
         ]
         return fields
 
+    def get_market_by_wrapped_token(self, tokens: list[ChecksumAddress]) -> SeerMarket:
+        where_stms = {"wrappedTokens_contains": tokens}
+        markets_field = self.seer_subgraph.Query.markets(
+            where=unwrap_generic_value(where_stms)
+        )
+        fields = self._get_fields_for_markets(markets_field)
+        markets = self.do_query(fields=fields, pydantic_model=SeerMarket)
+        if len(markets) != 1:
+            raise ValueError(
+                f"Fetched wrong number of markets. Expected 1 but got {len(markets)}"
+            )
+        return markets[0]
+
+    def _get_fields_for_seer_token(self, fields: FieldPath) -> list[FieldPath]:
+        return [
+            fields.id,
+            fields.name,
+            fields.symbol,
+        ]
+
+    def _get_fields_for_pools(self, pools_field: FieldPath) -> list[FieldPath]:
+        fields = (
+            [
+                pools_field.id,
+                pools_field.liquidity,
+                pools_field.sqrtPrice,
+                pools_field.token0Price,
+                pools_field.token1Price,
+                pools_field.totalValueLockedToken0,
+                pools_field.totalValueLockedToken1,
+            ]
+            + self._get_fields_for_seer_token(pools_field.token0)
+            + self._get_fields_for_seer_token(pools_field.token1)
+        )
+        return fields
+
     def get_pool_by_token(
         self, token_address: ChecksumAddress, collateral_address: ChecksumAddress
-    ) -> SeerPool | None:
+    ) -> SwaprPool | None:
         # We iterate through the wrapped tokens and put them in a where clause so that we hit the subgraph endpoint just once.
-        wheres = []
-        wheres.extend(
-            [
+
+        where_argument = {
+            "or": [
                 {
-                    "token0": token_address.lower(),
-                    "token1": collateral_address.lower(),
+                    "token0_": {"id": token_address.lower()},
+                    "token1_": {"id": collateral_address.lower()},
                 },
                 {
-                    "token0": collateral_address.lower(),
-                    "token1": token_address.lower(),
+                    "token0_": {"id": collateral_address.lower()},
+                    "token1_": {"id": token_address.lower()},
                 },
             ]
-        )
-
+        }
         optional_params = {}
         optional_params["orderBy"] = self.swapr_algebra_subgraph.Pool.liquidity
         optional_params["orderDirection"] = "desc"
 
         pools_field = self.swapr_algebra_subgraph.Query.pools(
-            where=unwrap_generic_value({"or": wheres}), **optional_params
+            where=unwrap_generic_value(where_argument), **optional_params
         )
 
         fields = self._get_fields_for_pools(pools_field)
-        pools = self.do_query(fields=fields, pydantic_model=SeerPool)
+        pools = self.do_query(fields=fields, pydantic_model=SwaprPool)
         # We assume there is only one pool for outcomeToken/sDAI.
         if len(pools) > 1:
             logger.info(
@@ -252,3 +407,79 @@ class SeerSubgraphHandler(BaseSubgraphHandler):
             # We select the first one
             return pools[0]
         return None
+
+    def _get_fields_for_swaps(self, swaps_field: FieldPath) -> list[FieldPath]:
+        fields = (
+            [
+                swaps_field.id,
+                swaps_field.pool.id,
+                swaps_field.sender,
+                swaps_field.recipient,
+                swaps_field.price,
+                swaps_field.amount0,
+                swaps_field.amount1,
+                swaps_field.timestamp,
+            ]
+            + self._get_fields_for_seer_token(swaps_field.token0)
+            + self._get_fields_for_seer_token(swaps_field.token1)
+        )
+        return fields
+
+    def get_swaps(
+        self,
+        recipient: ChecksumAddress,
+        timestamp_gt: DatetimeUTC | None = None,
+        timestamp_lt: DatetimeUTC | None = None,
+    ) -> list[SwaprSwap]:
+        where_argument: dict[str, Any] = {"recipient": recipient.lower()}
+        if timestamp_gt is not None:
+            where_argument["timestamp_gt"] = to_int_timestamp(timestamp_gt)
+        if timestamp_lt is not None:
+            where_argument["timestamp_lt"] = to_int_timestamp(timestamp_lt)
+
+        swaps_field = self.swapr_algebra_subgraph.Query.swaps(where=where_argument)
+        fields = self._get_fields_for_swaps(swaps_field)
+        swaps = self.do_query(fields=fields, pydantic_model=SwaprSwap)
+
+        return swaps
+
+
+class SeerQuestionsCache(metaclass=SingletonMeta):
+    """A singleton cache for storing and retrieving Seer market questions.
+
+    This class provides an in-memory cache for Seer market questions, preventing
+    redundant subgraph queries by maintaining a mapping of market IDs to their
+    associated questions. It implements the singleton pattern to ensure a single
+    cache instance is used throughout the agent run.
+
+    Attributes:
+        market_id_to_questions: A dictionary mapping market IDs to lists of SeerMarketQuestions
+        seer_subgraph_handler: Handler for interacting with the Seer subgraph
+    """
+
+    def __init__(self, seer_subgraph_handler: SeerSubgraphHandler | None = None):
+        self.market_id_to_questions: dict[
+            HexBytes, list[SeerMarketQuestions]
+        ] = defaultdict(list)
+        self.seer_subgraph_handler = seer_subgraph_handler or SeerSubgraphHandler()
+
+    def fetch_questions(self, market_ids: list[HexBytes]) -> None:
+        filtered_list = [
+            market_id
+            for market_id in market_ids
+            if market_id not in self.market_id_to_questions
+        ]
+        if not filtered_list:
+            return
+
+        questions = self.seer_subgraph_handler.get_questions_for_markets(filtered_list)
+        # Group questions by market_id
+        questions_by_market: dict[HexBytes, list[SeerMarketQuestions]] = defaultdict(
+            list
+        )
+        for q in questions:
+            questions_by_market[q.market.id].append(q)
+
+        # Update the cache with the new questions for each market
+        for market_id, market_questions in questions_by_market.items():
+            self.market_id_to_questions[market_id] = market_questions