add: improvements swap agent deploy

src/agents/metadata.py

@@ -1,18 +1,52 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from src.agents.swap.storage import SwapStateRepository
+
+
 class Metadata:
     def __init__(self):
-        self.crypto_data_agent = {}
-        self.swap_agent = {}
+        self.crypto_data_agent: Dict[str, Any] = {}
+        self._swap_repo = SwapStateRepository.instance()
 
     def get_crypto_data_agent(self):
         return self.crypto_data_agent
-    
+
     def set_crypto_data_agent(self, crypto_data_agent):
         self.crypto_data_agent = crypto_data_agent
 
-    def get_swap_agent(self):
-        return self.swap_agent
-    
-    def set_swap_agent(self, swap_agent):
-        self.swap_agent = swap_agent
+    def get_swap_agent(self, user_id: str | None = None, conversation_id: str | None = None):
+        try:
+            return self._swap_repo.get_metadata(user_id, conversation_id)
+        except ValueError:
+            return {}
+
+    def set_swap_agent(
+        self,
+        swap_agent: Dict[str, Any] | None,
+        user_id: str | None = None,
+        conversation_id: str | None = None,
+    ):
+        try:
+            if swap_agent:
+                self._swap_repo.set_metadata(user_id, conversation_id, swap_agent)
+            else:
+                self._swap_repo.clear_metadata(user_id, conversation_id)
+        except ValueError:
+            # Ignore clears when identity is missing; no actionable state to update.
+            return
+
+    def get_swap_history(
+        self,
+        user_id: str | None = None,
+        conversation_id: str | None = None,
+        limit: int | None = None,
+    ):
+        try:
+            return self._swap_repo.get_history(user_id, conversation_id, limit)
+        except ValueError:
+            return []
+
 
-metadata = Metadata()
+metadata = Metadata()

src/agents/supervisor/agent.py

@@ -1,7 +1,8 @@
 from langchain_google_genai import ChatGoogleGenerativeAI, GoogleGenerativeAIEmbeddings
 from langgraph_supervisor import create_supervisor
+from langchain_core.messages import HumanMessage, SystemMessage, AIMessage
 from src.agents.config import Config
-from typing import TypedDict, Literal, List, Any, Tuple
+from typing import TypedDict, Literal, List, Any, Tuple, Optional
 import re
 import json
 from src.agents.metadata import metadata
@@ -12,6 +13,8 @@ from src.agents.crypto_data.agent import CryptoDataAgent
 from src.agents.database.agent import DatabaseAgent
 from src.agents.default.agent import DefaultAgent
 from src.agents.swap.agent import SwapAgent
+from src.agents.swap.tools import swap_session
+from src.agents.swap.prompt import SWAP_AGENT_SYSTEM_PROMPT
 from src.agents.search.agent import SearchAgent
 from src.agents.database.client import is_database_available
 
@@ -55,7 +58,8 @@ class Supervisor:
             databaseAgent = None
 
         swapAgent = SwapAgent(llm)
-        agents.append(swapAgent.agent)
+        self.swap_agent = swapAgent.agent
+        agents.append(self.swap_agent)
         available_agents_text += (
             "- swap_agent: Handles swap operations on the Avalanche network and any other swap question related.\n"
         )
@@ -120,6 +124,9 @@ class Supervisor:
             CryptoConfig.API_ERROR_MESSAGE.lower(),
         }
 
+        self._active_user_id: str | None = None
+        self._active_conversation_id: str | None = None
+
         # Prepare database guidance text to avoid backslashes in f-string expressions
         if databaseAgent:
             database_instruction = "When a user asks for data analysis, database queries, or information from the database, delegate to the database_agent."
@@ -297,6 +304,25 @@ Examples of general queries to handle directly:
                 return art
         return {}
 
+    def _invoke_swap_agent(self, langchain_messages):
+        scoped_messages = [SystemMessage(content=SWAP_AGENT_SYSTEM_PROMPT)]
+        scoped_messages.extend(langchain_messages)
+        try:
+            with swap_session(
+                user_id=self._active_user_id,
+                conversation_id=self._active_conversation_id,
+            ):
+                response = self.swap_agent.invoke({"messages": scoped_messages})
+        except Exception as exc:
+            print(f"Error invoking swap agent directly: {exc}")
+            return None
+
+        if not response:
+            return None
+
+        agent, text, messages_out = self._extract_response_from_graph(response)
+        return agent, text, messages_out
+
     def _extract_response_from_graph(self, response: Any) -> Tuple[str, str, list]:
         messages_out = response.get("messages", []) if isinstance(response, dict) else []
         final_response = None
@@ -389,8 +415,21 @@ Examples of general queries to handle directly:
 
     def _build_metadata(self, agent_name: str, messages_out) -> dict:
         if agent_name == "swap_agent":
-            swap_meta = metadata.get_swap_agent()
-            return swap_meta.copy() if swap_meta else {}
+            swap_meta = metadata.get_swap_agent(
+                user_id=self._active_user_id,
+                conversation_id=self._active_conversation_id,
+            )
+            if swap_meta:
+                history = metadata.get_swap_history(
+                    user_id=self._active_user_id,
+                    conversation_id=self._active_conversation_id,
+                )
+                if history:
+                    swap_meta = swap_meta.copy()
+                    swap_meta.setdefault("history", history)
+                else:
+                    swap_meta = swap_meta.copy()
+            return swap_meta if swap_meta else {}
         if agent_name == "crypto_agent":
             tool_meta = self._collect_tool_metadata(messages_out)
             if tool_meta:
@@ -398,8 +437,15 @@ Examples of general queries to handle directly:
             return metadata.get_crypto_data_agent() or {}
         return {}
 
-    def invoke(self, messages: List[ChatMessage]) -> dict:
-        from langchain_core.messages import HumanMessage, SystemMessage, AIMessage
+    def invoke(
+        self,
+        messages: List[ChatMessage],
+        conversation_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> dict:
+        self._active_user_id = user_id
+        self._active_conversation_id = conversation_id
+        swap_state = metadata.get_swap_agent(user_id=user_id, conversation_id=conversation_id)
 
         langchain_messages = []
         for msg in messages:
@@ -410,9 +456,37 @@ Examples of general queries to handle directly:
             elif msg.get("role") == "assistant":
                 langchain_messages.append(AIMessage(content=msg.get("content", "")))
 
+        if swap_state and swap_state.get("status") == "collecting":
+            swap_result = self._invoke_swap_agent(langchain_messages)
+            if swap_result:
+                final_agent, cleaned_response, messages_out = swap_result
+                meta = self._build_metadata(final_agent, messages_out)
+                self._active_user_id = None
+                self._active_conversation_id = None
+                return {
+                    "messages": messages_out,
+                    "agent": final_agent,
+                    "response": cleaned_response or "Sorry, no meaningful response was returned.",
+                    "metadata": meta,
+                }
+            # If direct swap invocation failed, fall through to supervisor graph with hints
+            next_field = swap_state.get("next_field")
+            pending_question = swap_state.get("pending_question")
+            guidance_parts = [
+                "There is an in-progress token swap intent for this conversation.",
+                "Keep routing messages to the swap_agent until the intent is complete unless the user explicitly cancels or changes topic.",
+            ]
+            if next_field:
+                guidance_parts.append(f"The next field to collect is: {next_field}.")
+            if pending_question:
+                guidance_parts.append(f"Continue the swap flow by asking: {pending_question}")
+            guidance_text = " ".join(guidance_parts)
+            langchain_messages.insert(0, SystemMessage(content=guidance_text))
+
         try:
-            response = self.app.invoke({"messages": langchain_messages})
-            print("DEBUG: response", response)
+            with swap_session(user_id=user_id, conversation_id=conversation_id):
+                response = self.app.invoke({"messages": langchain_messages})
+                print("DEBUG: response", response)
         except Exception as e:
             print(f"Error in Supervisor: {e}")
             return {
@@ -457,6 +531,9 @@ Examples of general queries to handle directly:
         print("cleaned_response: ", cleaned_response)
         print("final_agent: ", final_agent)
 
+        self._active_user_id = None
+        self._active_conversation_id = None
+
         return {
             "messages": messages_out,
             "agent": final_agent,

src/agents/swap/config.py

@@ -1,153 +1,139 @@
-"""Network-aware swap configuration helpers."""
+"""Network-aware swap configuration helpers loaded from a registry file."""
 
 from __future__ import annotations
 
-from typing import Dict, Iterable, Optional, Set, Tuple
+import json
+from pathlib import Path
+from typing import Any, Dict, Iterable, Optional, Set, Tuple
 
 
 class SwapConfig:
     """Expose swap metadata so tools can validate user input safely."""
 
-    # Canonical networks we support. Values are the tokens available on that chain.
-    _NETWORK_TOKENS: Dict[str, Set[str]] = {
-        "avalanche": {
-            "AVAX",
-            "WAVAX",
-            "UNI",
-            "USDC",
-            "USDT",
-            "AAVE",
-            "BTC.B",
-            "JOE",
-            "MIM",
-        },
-        "ethereum": {
-            "ETH",
-            "WETH",
-            "USDC",
-            "USDT",
-            "WBTC",
-            "AAVE",
-            "UNI",
-            "LINK",
-            "LDO",
-            "USDE",
-            "DAI",
-        },
-        "binance-smart-chain": {
-            "USDT",
-            "USDC",
-            "CAKE",
-            "ADA",
-            "DOGE",
-            "XRP",
-            "DOT",
-            "TUSD",
-        },
-        "polygon": {
-            "USDT",
-            "USDC",
-            "WETH",
-            "DAI",
-            "QUICK",
-            "AAVE",
-            "SAND",
-        },
-        "arbitrum": {
-            "ARB",
-            "USDT",
-            "USDC",
-            "ETH",
-            "GMX",
-        },
-        "base": {
-            "USDC",
-            "ETH",
-            "CBBTC",
-            "AERO",
-        },
-        "optimism": {
-            "USDC",
-            "USDT",
-            "OP",
-        },
-    }
-
-    # Friendly aliases -> canonical keys
-    _NETWORK_ALIASES: Dict[str, str] = {
-        "avax": "avalanche",
-        "avalanche": "avalanche",
-        "ethereum": "ethereum",
-        "eth": "ethereum",
-        "ethereum mainnet": "ethereum",
-        "binance smart chain": "binance-smart-chain",
-        "binance-smart-chain": "binance-smart-chain",
-        "bsc": "binance-smart-chain",
-        "bnb": "binance-smart-chain",
-        "polygon": "polygon",
-        "matic": "polygon",
-        "arbitrum": "arbitrum",
-        "arbitrum one": "arbitrum",
-        "base": "base",
-        "optimism": "optimism",
-    }
-
-    _TOKEN_ALIASES: Dict[str, str] = {
-        "avax": "AVAX",
-        "wavax": "WAVAX",
-        "usdc": "USDC",
-        "usdt": "USDT",
-        "dai": "DAI",
-        "btc.b": "BTC.B",
-        "btcb": "BTC.B",
-        "wbtc": "WBTC",
-        "eth": "ETH",
-        "weth": "WETH",
-        "uni": "UNI",
-        "aave": "AAVE",
-        "joe": "JOE",
-        "mim": "MIM",
-        "link": "LINK",
-        "chainlink": "LINK",
-        "ldo": "LDO",
-        "usde": "USDE",
-        "cake": "CAKE",
-        "ada": "ADA",
-        "doge": "DOGE",
-        "xrp": "XRP",
-        "dot": "DOT",
-        "tusd": "TUSD",
-        "quick": "QUICK",
-        "sand": "SAND",
-        "arb": "ARB",
-        "gmx": "GMX",
-        "cbbtc": "CBBTC",
-        "cb-btc": "CBBTC",
-        "aero": "AERO",
-        "op": "OP",
-    }
-
-    # Optional allow list of directional routes (canonical network names).
+    _REGISTRY_PATH: Path = Path(__file__).with_name("registry.json")
+    _NETWORK_TOKENS: Dict[str, Set[str]] = {}
+    _NETWORK_ALIASES: Dict[str, str] = {}
+    _TOKEN_ALIASES: Dict[str, str] = {}
+    _TOKEN_DETAILS: Dict[str, Dict[str, Dict[str, Any]]] = {}
     _SUPPORTED_ROUTES: Set[Tuple[str, str]] = set()
-    for _src in _NETWORK_TOKENS.keys():
-        for _dst in _NETWORK_TOKENS.keys():
-            _SUPPORTED_ROUTES.add((_src, _dst))
+    _GLOBAL_TOKENS: Set[str] = set()
+    _LOADED: bool = False
+
+    # ---------- Registry management ----------
+    @classmethod
+    def reload(cls) -> None:
+        data = cls._load_registry()
+        cls._rebuild(data)
+
+    @classmethod
+    def _ensure_loaded(cls) -> None:
+        if not cls._LOADED:
+            cls.reload()
+
+    @classmethod
+    def _load_registry(cls) -> Dict[str, Any]:
+        try:
+            raw = cls._REGISTRY_PATH.read_text()
+        except FileNotFoundError as exc:
+            raise RuntimeError(f"Swap registry not found: {cls._REGISTRY_PATH}") from exc
+        try:
+            data = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise RuntimeError(f"Invalid JSON registry for swap config: {exc}") from exc
+        if not isinstance(data, dict):
+            raise RuntimeError("Swap registry must be a JSON object with 'networks'.")
+        return data
+
+    @classmethod
+    def _rebuild(cls, data: Dict[str, Any]) -> None:
+        network_tokens: Dict[str, Set[str]] = {}
+        network_aliases: Dict[str, str] = {}
+        token_aliases: Dict[str, str] = {}
+        token_details: Dict[str, Dict[str, Dict[str, Any]]] = {}
+        global_tokens: Set[str] = set()
+
+        for network in data.get("networks", []):
+            if not isinstance(network, dict):
+                continue
+            name = (network.get("name") or "").strip().lower()
+            if not name:
+                continue
+            aliases = [name, *(network.get("aliases") or [])]
+            for alias in aliases:
+                alias_key = (alias or "").strip().lower()
+                if alias_key:
+                    network_aliases[alias_key] = name
+
+            tokens_for_network: Set[str] = set()
+            details_for_network: Dict[str, Dict[str, Any]] = {}
+            for token in network.get("tokens", []):
+                if not isinstance(token, dict):
+                    continue
+                symbol = (token.get("symbol") or "").strip().upper()
+                if not symbol:
+                    continue
+                tokens_for_network.add(symbol)
+                clean = dict(token)
+                clean["symbol"] = symbol
+                details_for_network[symbol] = clean
+                global_tokens.add(symbol)
+                token_aliases[symbol.lower()] = symbol
+                for alias in token.get("aliases", []):
+                    alias_key = (alias or "").strip().lower()
+                    if alias_key:
+                        token_aliases[alias_key] = symbol
+
+            network_tokens[name] = tokens_for_network
+            token_details[name] = details_for_network
+
+        routes = data.get("routes", "all")
+        supported_routes: Set[Tuple[str, str]]
+        if routes == "all":
+            supported_routes = {
+                (src, dst) for src in network_tokens for dst in network_tokens
+            }
+        else:
+            supported_routes = set()
+            for route in routes or []:
+                if isinstance(route, dict):
+                    src = (route.get("from") or "").strip().lower()
+                    dst = (route.get("to") or "").strip().lower()
+                elif isinstance(route, (list, tuple)) and len(route) == 2:
+                    src = (route[0] or "").strip().lower()
+                    dst = (route[1] or "").strip().lower()
+                else:
+                    continue
+                src_key = network_aliases.get(src)
+                dst_key = network_aliases.get(dst)
+                if src_key and dst_key:
+                    supported_routes.add((src_key, dst_key))
+
+        cls._NETWORK_TOKENS = network_tokens
+        cls._NETWORK_ALIASES = network_aliases
+        cls._TOKEN_ALIASES = token_aliases
+        cls._TOKEN_DETAILS = token_details
+        cls._GLOBAL_TOKENS = global_tokens
+        cls._SUPPORTED_ROUTES = supported_routes
+        cls._LOADED = True
 
     # ---------- Public helpers ----------
     @classmethod
     def list_networks(cls) -> Iterable[str]:
         """Return supported networks in a stable order."""
+        cls._ensure_loaded()
         return sorted(cls._NETWORK_TOKENS.keys())
 
     @classmethod
     def list_tokens(cls, network: str) -> Iterable[str]:
         """Return supported tokens for a given network."""
+        cls._ensure_loaded()
         normalized = cls._normalize_network(network)
-        if normalized not in cls._NETWORK_TOKENS:
+        tokens = cls._NETWORK_TOKENS.get(normalized)
+        if tokens is None:
             raise ValueError(
                 f"Unsupported network '{network}'. Available: {sorted(cls._NETWORK_TOKENS)}"
             )
-        return sorted(cls._NETWORK_TOKENS[normalized])
+        return sorted(tokens)
 
     @classmethod
     def validate_network(cls, network: str) -> str:
@@ -157,6 +143,7 @@ class SwapConfig:
     @classmethod
     def validate_or_raise(cls, token: str, network: Optional[str] = None) -> str:
         """Validate a token, optionally scoping by network, and return canonical symbol."""
+        cls._ensure_loaded()
         canonical = cls._normalize_token(token)
         if network is not None:
             normalized_network = cls._normalize_network(network)
@@ -165,27 +152,39 @@ class SwapConfig:
                 raise ValueError(
                     f"Unsupported token '{token}' on {normalized_network}. Available: {sorted(tokens)}"
                 )
-        elif canonical not in cls._all_tokens():
+        elif canonical not in cls._GLOBAL_TOKENS:
             raise ValueError(
-                f"Unsupported token '{token}'. Supported tokens: {sorted(cls._all_tokens())}"
+                f"Unsupported token '{token}'. Supported tokens: {sorted(cls._GLOBAL_TOKENS)}"
             )
         return canonical
 
     @classmethod
     def routes_supported(cls, from_network: str, to_network: str) -> bool:
         """Return whether a swap route is supported."""
+        cls._ensure_loaded()
         source = cls._normalize_network(from_network)
         dest = cls._normalize_network(to_network)
         return (source, dest) in cls._SUPPORTED_ROUTES
 
     @classmethod
     def list_supported(cls) -> Iterable[str]:
-        """Backwards compatible helper returning all tokens across networks."""
-        return sorted(cls._all_tokens())
+        """Return all supported tokens across networks."""
+        cls._ensure_loaded()
+        return sorted(cls._GLOBAL_TOKENS)
+
+    @classmethod
+    def get_token_policy(cls, network: str, token: str) -> Dict[str, Any]:
+        """Return token metadata (decimals, min/max amounts) for a network/token pair."""
+        cls._ensure_loaded()
+        normalized_network = cls._normalize_network(network)
+        canonical = cls._normalize_token(token)
+        policy = cls._TOKEN_DETAILS.get(normalized_network, {}).get(canonical, {})
+        return dict(policy)
 
     # ---------- Internal helpers ----------
     @classmethod
     def _normalize_network(cls, network: str) -> str:
+        cls._ensure_loaded()
         key = (network or "").strip().lower()
         if not key:
             raise ValueError("Network is required.")
@@ -198,14 +197,12 @@ class SwapConfig:
 
     @classmethod
     def _normalize_token(cls, token: str) -> str:
+        cls._ensure_loaded()
         key = (token or "").strip().lower()
         if not key:
             raise ValueError("Token is required.")
         return cls._TOKEN_ALIASES.get(key, key.upper())
 
-    @classmethod
-    def _all_tokens(cls) -> Set[str]:
-        tokens: Set[str] = set()
-        for chain_tokens in cls._NETWORK_TOKENS.values():
-            tokens.update(chain_tokens)
-        return tokens
+
+# Ensure the registry is warm on import so validation errors surface early.
+SwapConfig._ensure_loaded()

src/agents/swap/prompt.py

@@ -0,0 +1,37 @@
+"""System prompt for the specialized swap agent."""
+from __future__ import annotations
+
+SWAP_AGENT_SYSTEM_PROMPT = """
+You are Zico's token swap orchestrator.
+
+Primary responsibilities:
+1. Collect all swap intent fields (`from_network`, `from_token`, `to_network`, `to_token`, `amount`) by invoking the `update_swap_intent` tool.
+2. Use progressive loading: start with the minimum detail you need, then request the remaining fields one at a time.
+3. Validate user inputs via tools. Ask the user to pick from the returned choices whenever a value is invalid or missing.
+4. Never fabricate swap rates, quotes, or execution results. Only confirm that the intent is ready once the tool reports `event == "swap_intent_ready"`.
+5. Preserve context: if the tool response says the intent is still collecting, summarize what you know, ask the next question, and remind the user how to continue.
+6. Reinforce guardrails: warn if the user requests unsupported networks/tokens or amounts outside the allowed range, and guide them back to valid options.
+
+Interaction pattern:
+- ALWAYS call `update_swap_intent` when the user provides new swap information.
+- Use `list_networks` or `list_tokens` before suggesting options, so your choices mirror the backend configuration.
+- After each tool call, read the returned `event`, `ask`, and `next_action` fields to decide whether to ask follow-up questions or conclude the intent.
+
+Example 1 – progressive collection:
+User: I want to swap some AVAX to USDC.
+Assistant: (call `update_swap_intent` with `from_token="AVAX"`, `to_token="USDC"`)
+Tool: `ask` -> "From which network?"
+Assistant: "Sure — which network will you be swapping from?"
+User: Avalanche, amount is 12.
+Assistant: (call `update_swap_intent` with `from_network="avalanche"`, `amount=12`)
+Tool: `ask` -> "To which network?"
+Assistant: "Got it. Which destination network do you prefer?"
+
+Example 2 – validation and completion:
+User: Swap 50 USDC from Ethereum to WBTC on Arbitrum.
+Assistant: (call `update_swap_intent` with all fields)
+Tool: `event` -> `swap_intent_ready`
+Assistant: "All set. Ready to swap 50 USDC on Ethereum for WBTC on Arbitrum. Let me know if you want to execute or adjust values."
+
+Keep responses concise, reference the remaining required field explicitly, and never skip the tool call even if you believe all details are already known.
+"""

src/agents/swap/registry.json

@@ -0,0 +1,94 @@
+{
+  "routes": "all",
+  "networks": [
+    {
+      "name": "avalanche",
+      "aliases": ["avalanche", "avax"],
+      "tokens": [
+        {"symbol": "AVAX", "aliases": ["avax"], "decimals": 18, "min_amount": "0.0001", "max_amount": "100000"},
+        {"symbol": "WAVAX", "aliases": ["wavax"], "decimals": 18, "min_amount": "0.0001", "max_amount": "100000"},
+        {"symbol": "UNI", "aliases": ["uni"], "decimals": 18, "min_amount": "0.01", "max_amount": "100000"},
+        {"symbol": "USDC", "aliases": ["usdc"], "decimals": 6, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "USDT", "aliases": ["usdt"], "decimals": 6, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "AAVE", "aliases": ["aave"], "decimals": 18, "min_amount": "0.01", "max_amount": "250000"},
+        {"symbol": "BTC.B", "aliases": ["btc.b", "btcb"], "decimals": 8, "min_amount": "0.0001", "max_amount": "100"},
+        {"symbol": "JOE", "aliases": ["joe"], "decimals": 18, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "MIM", "aliases": ["mim"], "decimals": 18, "min_amount": "1", "max_amount": "1000000"}
+      ]
+    },
+    {
+      "name": "ethereum",
+      "aliases": ["ethereum", "eth", "ethereum mainnet"],
+      "tokens": [
+        {"symbol": "ETH", "aliases": ["eth"], "decimals": 18, "min_amount": "0.0001", "max_amount": "10000"},
+        {"symbol": "WETH", "aliases": ["weth"], "decimals": 18, "min_amount": "0.0001", "max_amount": "10000"},
+        {"symbol": "USDC", "aliases": ["usdc"], "decimals": 6, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "USDT", "aliases": ["usdt"], "decimals": 6, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "WBTC", "aliases": ["wbtc"], "decimals": 8, "min_amount": "0.0001", "max_amount": "100"},
+        {"symbol": "AAVE", "aliases": ["aave"], "decimals": 18, "min_amount": "0.01", "max_amount": "250000"},
+        {"symbol": "UNI", "aliases": ["uni"], "decimals": 18, "min_amount": "0.01", "max_amount": "250000"},
+        {"symbol": "LINK", "aliases": ["link", "chainlink"], "decimals": 18, "min_amount": "0.01", "max_amount": "500000"},
+        {"symbol": "LDO", "aliases": ["ldo"], "decimals": 18, "min_amount": "0.01", "max_amount": "500000"},
+        {"symbol": "USDE", "aliases": ["usde"], "decimals": 18, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "DAI", "aliases": ["dai"], "decimals": 18, "min_amount": "1", "max_amount": "1000000"}
+      ]
+    },
+    {
+      "name": "binance-smart-chain",
+      "aliases": ["binance smart chain", "binance-smart-chain", "bsc", "bnb"],
+      "tokens": [
+        {"symbol": "USDT", "aliases": ["usdt"], "decimals": 18, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "USDC", "aliases": ["usdc"], "decimals": 18, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "CAKE", "aliases": ["cake"], "decimals": 18, "min_amount": "0.1", "max_amount": "1000000"},
+        {"symbol": "ADA", "aliases": ["ada"], "decimals": 18, "min_amount": "1", "max_amount": "5000000"},
+        {"symbol": "DOGE", "aliases": ["doge"], "decimals": 8, "min_amount": "10", "max_amount": "10000000"},
+        {"symbol": "XRP", "aliases": ["xrp"], "decimals": 6, "min_amount": "10", "max_amount": "10000000"},
+        {"symbol": "DOT", "aliases": ["dot"], "decimals": 10, "min_amount": "0.1", "max_amount": "100000"},
+        {"symbol": "TUSD", "aliases": ["tusd"], "decimals": 18, "min_amount": "1", "max_amount": "1000000"}
+      ]
+    },
+    {
+      "name": "polygon",
+      "aliases": ["polygon", "matic"],
+      "tokens": [
+        {"symbol": "USDT", "aliases": ["usdt"], "decimals": 6, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "USDC", "aliases": ["usdc"], "decimals": 6, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "WETH", "aliases": ["weth"], "decimals": 18, "min_amount": "0.0001", "max_amount": "10000"},
+        {"symbol": "DAI", "aliases": ["dai"], "decimals": 18, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "QUICK", "aliases": ["quick"], "decimals": 18, "min_amount": "0.1", "max_amount": "1000000"},
+        {"symbol": "AAVE", "aliases": ["aave"], "decimals": 18, "min_amount": "0.01", "max_amount": "250000"},
+        {"symbol": "SAND", "aliases": ["sand"], "decimals": 18, "min_amount": "1", "max_amount": "1000000"}
+      ]
+    },
+    {
+      "name": "arbitrum",
+      "aliases": ["arbitrum", "arbitrum one"],
+      "tokens": [
+        {"symbol": "ARB", "aliases": ["arb"], "decimals": 18, "min_amount": "0.1", "max_amount": "1000000"},
+        {"symbol": "USDT", "aliases": ["usdt"], "decimals": 6, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "USDC", "aliases": ["usdc"], "decimals": 6, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "ETH", "aliases": ["eth"], "decimals": 18, "min_amount": "0.0001", "max_amount": "10000"},
+        {"symbol": "GMX", "aliases": ["gmx"], "decimals": 18, "min_amount": "0.1", "max_amount": "1000000"}
+      ]
+    },
+    {
+      "name": "base",
+      "aliases": ["base"],
+      "tokens": [
+        {"symbol": "USDC", "aliases": ["usdc"], "decimals": 6, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "ETH", "aliases": ["eth"], "decimals": 18, "min_amount": "0.0001", "max_amount": "10000"},
+        {"symbol": "CBBTC", "aliases": ["cbbtc", "cb-btc"], "decimals": 8, "min_amount": "0.0001", "max_amount": "100"},
+        {"symbol": "AERO", "aliases": ["aero"], "decimals": 18, "min_amount": "0.1", "max_amount": "100000"}
+      ]
+    },
+    {
+      "name": "optimism",
+      "aliases": ["optimism", "op"],
+      "tokens": [
+        {"symbol": "USDC", "aliases": ["usdc"], "decimals": 6, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "USDT", "aliases": ["usdt"], "decimals": 6, "min_amount": "1", "max_amount": "1000000"},
+        {"symbol": "OP", "aliases": ["op"], "decimals": 18, "min_amount": "0.1", "max_amount": "1000000"}
+      ]
+    }
+  ]
+}

src/agents/swap/storage.py

@@ -0,0 +1,228 @@
+"""Persistent storage for swap intents and metadata."""
+from __future__ import annotations
+
+import copy
+import json
+import os
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from threading import Lock
+from typing import Any, Dict, List, Optional
+
+_STATE_TEMPLATE: Dict[str, Dict[str, Any]] = {
+    "intents": {},
+    "metadata": {},
+    "history": {},
+}
+
+
+class SwapStateRepository:
+    """File-backed storage for swap agent state with TTL and history support."""
+
+    _instance: "SwapStateRepository" | None = None
+    _instance_lock: Lock = Lock()
+
+    def __init__(
+        self,
+        path: Optional[Path] = None,
+        ttl_seconds: int = 3600,
+        history_limit: int = 10,
+    ) -> None:
+        env_path = os.getenv("SWAP_STATE_PATH")
+        default_path = Path(__file__).with_name("swap_state.json")
+        self._path = Path(path or env_path or default_path)
+        self._ttl_seconds = ttl_seconds
+        self._history_limit = history_limit
+        self._lock = Lock()
+        self._state: Dict[str, Dict[str, Any]] = copy.deepcopy(_STATE_TEMPLATE)
+        self._ensure_parent()
+        with self._lock:
+            self._load_locked()
+
+    @classmethod
+    def instance(cls) -> "SwapStateRepository":
+        if cls._instance is None:
+            with cls._instance_lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    @classmethod
+    def reset(cls) -> None:
+        with cls._instance_lock:
+            cls._instance = None
+
+    def _ensure_parent(self) -> None:
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+        except OSError:
+            pass
+
+    def _load_locked(self) -> None:
+        if not self._path.exists():
+            self._state = copy.deepcopy(_STATE_TEMPLATE)
+            return
+        try:
+            data = json.loads(self._path.read_text())
+        except Exception:
+            self._state = copy.deepcopy(_STATE_TEMPLATE)
+            return
+        if not isinstance(data, dict):
+            self._state = copy.deepcopy(_STATE_TEMPLATE)
+            return
+        state = copy.deepcopy(_STATE_TEMPLATE)
+        for key in state:
+            if isinstance(data.get(key), dict):
+                state[key] = data[key]
+        self._state = state
+
+    def _persist_locked(self) -> None:
+        self._ensure_parent()
+        tmp_path = self._path.with_suffix(".tmp")
+        payload = json.dumps(self._state, ensure_ascii=False, indent=2)
+        try:
+            tmp_path.write_text(payload)
+            tmp_path.replace(self._path)
+        except Exception:
+            pass
+
+    @staticmethod
+    def _normalize_identifier(value: Optional[str], label: str) -> str:
+        candidate = (value or "").strip()
+        if not candidate:
+            raise ValueError(f"{label} is required for swap state operations.")
+        return candidate
+
+    def _key(self, user_id: Optional[str], conversation_id: Optional[str]) -> str:
+        user = self._normalize_identifier(user_id, "user_id")
+        conversation = self._normalize_identifier(conversation_id, "conversation_id")
+        return f"{user}::{conversation}"
+
+    def _purge_locked(self) -> None:
+        if self._ttl_seconds <= 0:
+            return
+        cutoff = time.time() - self._ttl_seconds
+        intents = self._state["intents"]
+        metadata = self._state["metadata"]
+        stale_keys = [
+            key for key, record in intents.items() if record.get("updated_at", 0) < cutoff
+        ]
+        for key in stale_keys:
+            intents.pop(key, None)
+            metadata.pop(key, None)
+
+    @staticmethod
+    def _format_timestamp(value: float) -> str:
+        return datetime.fromtimestamp(value, tz=timezone.utc).isoformat()
+
+    def _history_unlocked(self, key: str, limit: Optional[int] = None) -> List[Dict[str, Any]]:
+        history = self._state["history"].get(key, [])
+        sorted_history = sorted(history, key=lambda item: item.get("timestamp", 0), reverse=True)
+        effective_limit = limit or self._history_limit
+        if effective_limit:
+            sorted_history = sorted_history[:effective_limit]
+        results: List[Dict[str, Any]] = []
+        for item in sorted_history:
+            entry = copy.deepcopy(item)
+            ts = entry.get("timestamp")
+            if ts is not None:
+                entry["timestamp"] = self._format_timestamp(float(ts))
+            results.append(entry)
+        return results
+
+    def load_intent(self, user_id: str, conversation_id: str) -> Optional[Dict[str, Any]]:
+        key = self._key(user_id, conversation_id)
+        with self._lock:
+            self._purge_locked()
+            record = self._state["intents"].get(key)
+            if not record:
+                return None
+            return copy.deepcopy(record.get("intent"))
+
+    def persist_intent(
+        self,
+        user_id: str,
+        conversation_id: str,
+        intent: Dict[str, Any],
+        metadata: Dict[str, Any],
+        done: bool,
+        summary: Optional[Dict[str, Any]] = None,
+    ) -> List[Dict[str, Any]]:
+        key = self._key(user_id, conversation_id)
+        with self._lock:
+            self._purge_locked()
+            now = time.time()
+            if done:
+                self._state["intents"].pop(key, None)
+            else:
+                self._state["intents"][key] = {
+                    "intent": copy.deepcopy(intent),
+                    "updated_at": now,
+                }
+            if metadata:
+                meta_copy = copy.deepcopy(metadata)
+                meta_copy["updated_at"] = now
+                self._state["metadata"][key] = meta_copy
+            if done and summary:
+                history = self._state["history"].get(key, [])
+                summary_copy = copy.deepcopy(summary)
+                summary_copy.setdefault("timestamp", now)
+                history.append(summary_copy)
+                self._state["history"][key] = history[-self._history_limit:]
+            try:
+                self._persist_locked()
+            except Exception:
+                pass
+            return self._history_unlocked(key)
+
+    def set_metadata(self, user_id: str, conversation_id: str, metadata: Dict[str, Any]) -> None:
+        key = self._key(user_id, conversation_id)
+        with self._lock:
+            self._purge_locked()
+            if metadata:
+                meta_copy = copy.deepcopy(metadata)
+                meta_copy["updated_at"] = time.time()
+                self._state["metadata"][key] = meta_copy
+            else:
+                self._state["metadata"].pop(key, None)
+            try:
+                self._persist_locked()
+            except Exception:
+                pass
+
+    def clear_metadata(self, user_id: str, conversation_id: str) -> None:
+        self.set_metadata(user_id, conversation_id, {})
+
+    def clear_intent(self, user_id: str, conversation_id: str) -> None:
+        key = self._key(user_id, conversation_id)
+        with self._lock:
+            self._state["intents"].pop(key, None)
+            try:
+                self._persist_locked()
+            except Exception:
+                pass
+
+    def get_metadata(self, user_id: str, conversation_id: str) -> Dict[str, Any]:
+        key = self._key(user_id, conversation_id)
+        with self._lock:
+            self._purge_locked()
+            meta = self._state["metadata"].get(key)
+            if not meta:
+                return {}
+            entry = copy.deepcopy(meta)
+            ts = entry.pop("updated_at", None)
+            if ts is not None:
+                entry["updated_at"] = self._format_timestamp(float(ts))
+            return entry
+
+    def get_history(
+        self,
+        user_id: str,
+        conversation_id: str,
+        limit: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        key = self._key(user_id, conversation_id)
+        with self._lock:
+            return self._history_unlocked(key, limit)
+

src/agents/swap/swap_state.json

@@ -0,0 +1,63 @@
+{
+  "intents": {
+    "<user_id>::<conversation_id>": {
+      "intent": {
+        "user_id": "<user_id>",
+        "conversation_id": "<conversation_id>",
+        "from_network": null,
+        "from_token": null,
+        "to_network": null,
+        "to_token": null,
+        "amount": null,
+        "updated_at": 1760231993.3835566
+      },
+      "updated_at": 1760231993.3835785
+    }
+  },
+  "metadata": {
+    "<user_id>::<conversation_id>": {
+      "event": "swap_intent_pending",
+      "status": "collecting",
+      "from_network": null,
+      "from_token": null,
+      "to_network": null,
+      "to_token": null,
+      "amount": null,
+      "user_id": "<user_id>",
+      "conversation_id": "<conversation_id>",
+      "missing_fields": [
+        "from_network",
+        "from_token",
+        "to_network",
+        "to_token",
+        "amount"
+      ],
+      "next_field": "from_network",
+      "pending_question": "From which network?",
+      "choices": [
+        "arbitrum",
+        "avalanche",
+        "base",
+        "binance-smart-chain",
+        "ethereum",
+        "optimism",
+        "polygon"
+      ],
+      "error": null,
+      "updated_at": 1760231993.3868954
+    }
+  },
+  "history": {
+    "user123::crypto-conv-1": [
+      {
+        "status": "ready",
+        "from_network": "ethereum",
+        "from_token": "LINK",
+        "to_network": "avalanche",
+        "to_token": "AVAX",
+        "amount": "1",
+        "timestamp": 1760232078.673952
+      }
+    ]
+  }
+}

src/agents/swap/tools.py

@@ -2,29 +2,58 @@
 
 from __future__ import annotations
 
-from dataclasses import asdict, dataclass
-from typing import Dict, List, Optional
+import time
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from decimal import Decimal, InvalidOperation
+from typing import Any, Dict, List, Optional
 
 from langchain_core.tools import tool
 from pydantic import BaseModel, Field, field_validator
 
 from src.agents.metadata import metadata
 from src.agents.swap.config import SwapConfig
+from src.agents.swap.storage import SwapStateRepository
 
-# ---------- In-memory intent store (swap session) ----------
-# Replace with persistent storage if the agent runs in multiple instances.
-_INTENTS: Dict[str, "SwapIntent"] = {}
-_DEFAULT_USER_ID = "__default_swap_user__"
+
+# ---------- Helpers ----------
+_STORE = SwapStateRepository.instance()
+
+
+def _format_decimal(value: Decimal) -> str:
+    normalized = value.normalize()
+    exponent = normalized.as_tuple().exponent
+    if exponent > 0:
+        normalized = normalized.quantize(Decimal(1))
+    text = format(normalized, "f")
+    if "." in text:
+        text = text.rstrip("0").rstrip(".")
+    return text
+
+
+def _to_decimal(value: Any) -> Optional[Decimal]:
+    if value is None:
+        return None
+    try:
+        return Decimal(str(value))
+    except (InvalidOperation, TypeError, ValueError):
+        return None
 
 
 @dataclass
 class SwapIntent:
-    user_id: str = _DEFAULT_USER_ID
+    user_id: str
+    conversation_id: str
     from_network: Optional[str] = None
     from_token: Optional[str] = None
     to_network: Optional[str] = None
     to_token: Optional[str] = None
-    amount: Optional[float] = None
+    amount: Optional[Decimal] = None
+    updated_at: float = field(default_factory=lambda: time.time())
+
+    def touch(self) -> None:
+        self.updated_at = time.time()
 
     def is_complete(self) -> bool:
         return all(
@@ -33,7 +62,7 @@ class SwapIntent:
                 self.from_token,
                 self.to_network,
                 self.to_token,
-                self.amount,
+                self.amount is not None,
             ]
         )
 
@@ -51,18 +80,129 @@ class SwapIntent:
             fields.append("amount")
         return fields
 
+    def amount_as_str(self) -> Optional[str]:
+        if self.amount is None:
+            return None
+        return _format_decimal(self.amount)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "user_id": self.user_id,
+            "conversation_id": self.conversation_id,
+            "from_network": self.from_network,
+            "from_token": self.from_token,
+            "to_network": self.to_network,
+            "to_token": self.to_token,
+            "amount": self.amount_as_str(),
+            "updated_at": self.updated_at,
+        }
+
+    def to_public(self) -> Dict[str, Optional[str]]:
+        public = self.to_dict()
+        public["amount"] = self.amount_as_str()
+        return public
+
+    def to_summary(self, status: str, error: Optional[str] = None) -> Dict[str, Any]:
+        summary: Dict[str, Any] = {
+            "status": status,
+            "from_network": self.from_network,
+            "from_token": self.from_token,
+            "to_network": self.to_network,
+            "to_token": self.to_token,
+            "amount": self.amount_as_str(),
+        }
+        if error:
+            summary["error"] = error
+        return summary
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SwapIntent":
+        amount = _to_decimal(data.get("amount"))
+        intent = cls(
+            user_id=(data.get("user_id") or "").strip(),
+            conversation_id=(data.get("conversation_id") or "").strip(),
+            from_network=data.get("from_network"),
+            from_token=data.get("from_token"),
+            to_network=data.get("to_network"),
+            to_token=data.get("to_token"),
+            amount=amount,
+        )
+        intent.updated_at = float(data.get("updated_at", time.time()))
+        return intent
+
+
+# ---------- Swap session context ----------
+_CURRENT_SESSION: ContextVar[tuple[str, str]] = ContextVar(
+    "_current_swap_session",
+    default=("", ""),
+)
+
+
+def set_current_swap_session(user_id: Optional[str], conversation_id: Optional[str]) -> None:
+    """Store the active swap session for tool calls executed by the agent."""
+
+    resolved_user = (user_id or "").strip()
+    resolved_conversation = (conversation_id or "").strip()
+    if not resolved_user:
+        raise ValueError("swap_agent requires 'user_id' to identify the swap session.")
+    if not resolved_conversation:
+        raise ValueError("swap_agent requires 'conversation_id' to identify the swap session.")
+    _CURRENT_SESSION.set((resolved_user, resolved_conversation))
+
+
+@contextmanager
+def swap_session(user_id: Optional[str], conversation_id: Optional[str]):
+    """Context manager that guarantees session scoping for swap tool calls."""
+
+    set_current_swap_session(user_id, conversation_id)
+    try:
+        yield
+    finally:
+        clear_current_swap_session()
+
+
+def clear_current_swap_session() -> None:
+    """Reset the active swap session after the agent finishes handling a message."""
+
+    _CURRENT_SESSION.set(("", ""))
+
+
+def _resolve_session(user_id: Optional[str], conversation_id: Optional[str]) -> tuple[str, str]:
+    active_user, active_conversation = _CURRENT_SESSION.get()
+    resolved_user = (user_id or active_user or "").strip()
+    resolved_conversation = (conversation_id or active_conversation or "").strip()
+    if not resolved_user:
+        raise ValueError("user_id is required for swap operations.")
+    if not resolved_conversation:
+        raise ValueError("conversation_id is required for swap operations.")
+    return resolved_user, resolved_conversation
+
+
+def _load_intent(user_id: str, conversation_id: str) -> SwapIntent:
+    stored = _STORE.load_intent(user_id, conversation_id)
+    if stored:
+        intent = SwapIntent.from_dict(stored)
+        intent.user_id = user_id
+        intent.conversation_id = conversation_id
+        return intent
+    return SwapIntent(user_id=user_id, conversation_id=conversation_id)
+
 
 # ---------- Pydantic input schema ----------
 class UpdateSwapIntentInput(BaseModel):
     user_id: Optional[str] = Field(
         default=None,
-        description="Stable ID for the end user / chat session. Optional, but required for multi-user disambiguation.",
+        description="Stable ID for the end user / chat session. Optional if context manager is set.",
+    )
+    conversation_id: Optional[str] = Field(
+        default=None,
+        description="Conversation identifier to scope swap intents within a user.",
     )
     from_network: Optional[str] = None
     from_token: Optional[str] = None
     to_network: Optional[str] = None
     to_token: Optional[str] = None
-    amount: Optional[float] = Field(None, gt=0)
+    amount: Optional[Decimal] = Field(None, gt=Decimal("0"))
 
     @field_validator("from_network", "to_network", mode="before")
     @classmethod
@@ -74,34 +214,15 @@ class UpdateSwapIntentInput(BaseModel):
     def _norm_token(cls, value: Optional[str]) -> Optional[str]:
         return value.upper() if isinstance(value, str) else value
 
-
-# ---------- Output helpers ----------
-def _response(
-    intent: SwapIntent,
-    ask: Optional[str],
-    choices: Optional[List[str]] = None,
-    done: bool = False,
-    error: Optional[str] = None,
-) -> Dict[str, object]:
-    """Consistent payload for the UI layer."""
-
-    payload: Dict[str, object] = {
-        "event": "swap_intent_ready" if done else "ask_user",
-        "intent": asdict(intent),
-        "ask": ask,
-        "choices": choices or [],
-        "error": error,
-    }
-    if done:
-        payload["metadata"] = {
-            "event": "swap_intent_ready",
-            "from_network": intent.from_network,
-            "from_token": intent.from_token,
-            "to_network": intent.to_network,
-            "to_token": intent.to_token,
-            "amount": intent.amount,
-        }
-    return payload
+    @field_validator("amount", mode="before")
+    @classmethod
+    def _norm_amount(cls, value):
+        if value is None or isinstance(value, Decimal):
+            return value
+        decimal_value = _to_decimal(value)
+        if decimal_value is None:
+            raise ValueError("Amount must be a number.")
+        return decimal_value
 
 
 # ---------- Validation utilities ----------
@@ -132,15 +253,146 @@ def _validate_route(from_network: str, to_network: str) -> None:
             )
 
 
+def _validate_amount(amount: Optional[Decimal], intent: SwapIntent) -> Optional[Decimal]:
+    if amount is None:
+        return None
+    if not intent.from_network or not intent.from_token:
+        raise ValueError("Provide the source network and token before specifying an amount.")
+
+    policy = SwapConfig.get_token_policy(intent.from_network, intent.from_token)
+    decimals_value = policy.get("decimals", 18)
+    try:
+        decimals = int(decimals_value)
+    except (TypeError, ValueError):
+        decimals = 18
+
+    if decimals >= 0 and amount.as_tuple().exponent < -decimals:
+        raise ValueError(
+            f"Amount precision exceeds {decimals} decimal places allowed for {intent.from_token}."
+        )
+
+    minimum = _to_decimal(policy.get("min_amount"))
+    maximum = _to_decimal(policy.get("max_amount"))
+
+    if minimum is not None and amount < minimum:
+        raise ValueError(
+            f"The minimum amount for {intent.from_token} on {intent.from_network} is {minimum}."
+        )
+    if maximum is not None and amount > maximum:
+        raise ValueError(
+            f"The maximum amount for {intent.from_token} on {intent.from_network} is {maximum}."
+        )
+
+    return amount
+
+
+# ---------- Output helpers ----------
+def _store_swap_metadata(
+    intent: SwapIntent,
+    ask: Optional[str],
+    done: bool,
+    error: Optional[str],
+    choices: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    intent.touch()
+    missing = intent.missing_fields()
+    next_field = missing[0] if missing else None
+    meta: Dict[str, Any] = {
+        "event": "swap_intent_ready" if done else "swap_intent_pending",
+        "status": "ready" if done else "collecting",
+        "from_network": intent.from_network,
+        "from_token": intent.from_token,
+        "to_network": intent.to_network,
+        "to_token": intent.to_token,
+        "amount": intent.amount_as_str(),
+        "user_id": intent.user_id,
+        "conversation_id": intent.conversation_id,
+        "missing_fields": missing,
+        "next_field": next_field,
+        "pending_question": ask,
+        "choices": list(choices or []),
+        "error": error,
+    }
+    summary = intent.to_summary("ready" if done else "collecting", error=error) if done else None
+    history = _STORE.persist_intent(
+        intent.user_id,
+        intent.conversation_id,
+        intent.to_dict(),
+        meta,
+        done=done,
+        summary=summary,
+    )
+    if history:
+        meta["history"] = history
+    metadata.set_swap_agent(meta, intent.user_id, intent.conversation_id)
+    return meta
+
+
+def _build_next_action(meta: Dict[str, Any]) -> Dict[str, Any]:
+    if meta.get("status") == "ready":
+        return {
+            "type": "complete",
+            "prompt": None,
+            "field": None,
+            "choices": [],
+        }
+    return {
+        "type": "collect_field",
+        "prompt": meta.get("pending_question"),
+        "field": meta.get("next_field"),
+        "choices": meta.get("choices", []),
+    }
+
+
+def _response(
+    intent: SwapIntent,
+    ask: Optional[str],
+    choices: Optional[List[str]] = None,
+    done: bool = False,
+    error: Optional[str] = None,
+) -> Dict[str, Any]:
+    meta = _store_swap_metadata(intent, ask, done, error, choices)
+
+    payload: Dict[str, Any] = {
+        "event": meta.get("event"),
+        "intent": intent.to_public(),
+        "ask": ask,
+        "choices": choices or [],
+        "error": error,
+        "next_action": _build_next_action(meta),
+        "history": meta.get("history", []),
+    }
+
+    if done:
+        payload["metadata"] = {
+            key: meta.get(key)
+            for key in (
+                "event",
+                "status",
+                "from_network",
+                "from_token",
+                "to_network",
+                "to_token",
+                "amount",
+                "user_id",
+                "conversation_id",
+                "history",
+            )
+            if meta.get(key) is not None
+        }
+    return payload
+
+
 # ---------- Core tool ----------
 @tool("update_swap_intent", args_schema=UpdateSwapIntentInput)
 def update_swap_intent_tool(
     user_id: Optional[str] = None,
+    conversation_id: Optional[str] = None,
     from_network: Optional[str] = None,
     from_token: Optional[str] = None,
     to_network: Optional[str] = None,
     to_token: Optional[str] = None,
-    amount: Optional[float] = None,
+    amount: Optional[Decimal] = None,
 ):
     """Update the swap intent and surface the next question or final metadata.
 
@@ -149,15 +401,21 @@ def update_swap_intent_tool(
     and keep calling it until the response event becomes 'swap_intent_ready'.
     """
 
-    intent_key = user_id or _DEFAULT_USER_ID
-    intent = _INTENTS.get(intent_key) or SwapIntent(user_id=intent_key)
-    if user_id:
-        intent.user_id = user_id
-    _INTENTS[intent_key] = intent
+    resolved_user, resolved_conversation = _resolve_session(user_id, conversation_id)
+    intent = _load_intent(resolved_user, resolved_conversation)
+    intent.user_id = resolved_user
+    intent.conversation_id = resolved_conversation
 
     try:
         if from_network is not None:
-            intent.from_network = _validate_network(from_network)
+            canonical_from = _validate_network(from_network)
+            if canonical_from != intent.from_network:
+                intent.from_network = canonical_from
+                if intent.from_token:
+                    try:
+                        SwapConfig.validate_or_raise(intent.from_token, canonical_from)
+                    except ValueError:
+                        intent.from_token = None
 
         if intent.from_network is None and from_token is not None:
             return _response(
@@ -170,7 +428,14 @@ def update_swap_intent_tool(
             intent.from_token = _validate_token(from_token, intent.from_network)
 
         if to_network is not None:
-            intent.to_network = _validate_network(to_network)
+            canonical_to = _validate_network(to_network)
+            if canonical_to != intent.to_network:
+                intent.to_network = canonical_to
+                if intent.to_token:
+                    try:
+                        SwapConfig.validate_or_raise(intent.to_token, canonical_to)
+                    except ValueError:
+                        intent.to_token = None
 
         if intent.to_network is None and to_token is not None:
             return _response(
@@ -183,7 +448,7 @@ def update_swap_intent_tool(
             intent.to_token = _validate_token(to_token, intent.to_network)
 
         if amount is not None:
-            intent.amount = amount
+            intent.amount = _validate_amount(amount, intent)
 
         if intent.from_network and intent.to_network:
             _validate_route(intent.from_network, intent.to_network)
@@ -205,6 +470,12 @@ def update_swap_intent_tool(
                 list(SwapConfig.list_tokens(intent.from_network)),
                 error=message,
             )
+        if "amount" in lowered and intent.from_token:
+            return _response(
+                intent,
+                f"Provide a valid amount in {intent.from_token}.",
+                error=message,
+            )
         return _response(intent, "Please correct the input.", error=message)
 
     if intent.from_network is None:
@@ -235,16 +506,8 @@ def update_swap_intent_tool(
         denom = intent.from_token
         return _response(intent, f"What is the amount in {denom}?")
 
-    meta = {
-        "event": "swap_intent_ready",
-        "from_network": intent.from_network,
-        "from_token": intent.from_token,
-        "to_network": intent.to_network,
-        "to_token": intent.to_token,
-        "amount": intent.amount,
-    }
-    metadata.set_swap_agent(meta)
-    return _response(intent, ask=None, done=True)
+    response = _response(intent, ask=None, done=True)
+    return response
 
 
 class ListTokensInput(BaseModel):
@@ -262,9 +525,15 @@ def list_tokens_tool(network: str):
 
     try:
         canonical = _validate_network(network)
+        tokens = list(SwapConfig.list_tokens(canonical))
+        policies = {
+            token: SwapConfig.get_token_policy(canonical, token)
+            for token in tokens
+        }
         return {
             "network": canonical,
-            "tokens": list(SwapConfig.list_tokens(canonical)),
+            "tokens": tokens,
+            "policies": policies,
         }
     except ValueError as exc:
         return {

src/app.py

@@ -114,6 +114,24 @@ def _map_agent_type(agent_name: str) -> str:
     }
     return mapping.get(agent_name, "supervisor")
 
+
+def _resolve_identity(request: ChatRequest) -> tuple[str, str]:
+    """Ensure each request has a stable user and conversation identifier."""
+
+    user_id = (request.user_id or "").strip()
+    if not user_id or user_id.lower() == "anonymous":
+        wallet = (request.wallet_address or "").strip()
+        if wallet and wallet.lower() != "default":
+            user_id = f"wallet::{wallet.lower()}"
+        else:
+            raise HTTPException(
+                status_code=400,
+                detail="A stable 'user_id' or wallet_address is required for swap operations.",
+            )
+
+    conversation_id = (request.conversation_id or "").strip() or "default"
+    return user_id, conversation_id
+
 @app.get("/health")
 def health_check():
     return {"status": "ok"}
@@ -135,21 +153,27 @@ def get_conversations(request: Request):
 def chat(request: ChatRequest):
     print("request: ", request)
     try:
+        user_id, conversation_id = _resolve_identity(request)
+
         # Add the user message to the conversation
         chat_manager_instance.add_message(
             message=request.message.dict(),
-            conversation_id=request.conversation_id,
-            user_id=request.user_id
+            conversation_id=conversation_id,
+            user_id=user_id
         )
         
         # Get all messages from the conversation to pass to the agent
         conversation_messages = chat_manager_instance.get_messages(
-            conversation_id=request.conversation_id,
-            user_id=request.user_id
+            conversation_id=conversation_id,
+            user_id=user_id
         )
         
         # Invoke the supervisor agent with the conversation
-        result = supervisor.invoke(conversation_messages)
+        result = supervisor.invoke(
+            conversation_messages,
+            conversation_id=conversation_id,
+            user_id=user_id,
+        )
         
         # Add the agent's response to the conversation
         if result and isinstance(result, dict):
@@ -165,7 +189,10 @@ def chat(request: ChatRequest):
             if isinstance(result, dict) and result.get("metadata"):
                 response_metadata.update(result.get("metadata") or {})
             elif agent_name == "token swap":
-                swap_meta = metadata.get_swap_agent()
+                swap_meta = metadata.get_swap_agent(
+                    user_id=user_id,
+                    conversation_id=conversation_id,
+                )
                 if swap_meta:
                     response_metadata.update(swap_meta)
                     swap_meta_snapshot = swap_meta
@@ -178,8 +205,8 @@ def chat(request: ChatRequest):
                 agent_name=agent_name,
                 agent_type=_map_agent_type(agent_name),
                 metadata=result.get("metadata", {}),
-                conversation_id=request.conversation_id,
-                user_id=request.user_id,
+                conversation_id=conversation_id,
+                user_id=user_id,
                 requires_action=True if agent_name == "token swap" else False,
                 action_type="swap" if agent_name == "token swap" else None
             )
@@ -187,8 +214,8 @@ def chat(request: ChatRequest):
             # Add the response message to the conversation
             chat_manager_instance.add_message(
                 message=response_message.dict(),
-                conversation_id=request.conversation_id,
-                user_id=request.user_id
+                conversation_id=conversation_id,
+                user_id=user_id
             )
 
             # Return only the clean response
@@ -201,14 +228,26 @@ def chat(request: ChatRequest):
                 if swap_meta_snapshot:
                     response_meta = swap_meta_snapshot
                 else:
-                    swap_meta = metadata.get_swap_agent()
+                    swap_meta = metadata.get_swap_agent(
+                        user_id=user_id,
+                        conversation_id=conversation_id,
+                    )
                     if swap_meta:
                         response_meta = swap_meta
-                    metadata.set_swap_agent({})
             if response_meta:
                 response_payload["metadata"] = response_meta
             if agent_name == "token swap":
-                metadata.set_swap_agent({})
+                should_clear = False
+                if response_meta:
+                    status = response_meta.get("status") if isinstance(response_meta, dict) else None
+                    event = response_meta.get("event") if isinstance(response_meta, dict) else None
+                    should_clear = status == "ready" or event == "swap_intent_ready"
+                if should_clear:
+                    metadata.set_swap_agent(
+                        {},
+                        user_id=user_id,
+                        conversation_id=conversation_id,
+                    )
             return response_payload
         
         return {"response": "No response available", "agent": "supervisor"}

src/service/chat_manager.py

@@ -101,6 +101,8 @@ class ChatManager:
         conversation_id = self._get_conversation_id(conversation_id)
         conversation = self._get_or_create_conversation(conversation_id, user_id)
         chat_message = ChatMessage(**message)
+        chat_message.conversation_id = conversation_id
+        chat_message.user_id = user_id
         if "timestamp" not in message:
             chat_message.timestamp = datetime.utcnow()
         conversation.messages.append(chat_message)