Building AI agents, atomically
feat(tools): add Fía Signals crypto intelligence tool
U (OpenClaw)f5a127388cdb
diff --git a/atomic-forge/tools/fia_signals/.coveragerc b/atomic-forge/tools/fia_signals/.coveragercnew file mode 100644index 0000000..c45136e--- /dev/null+++ b/atomic-forge/tools/fia_signals/.coveragerc@@ -0,0 +1,8 @@+[run]+source = tool+omit = */tests/*++[report]+exclude_lines =+ if __name__ == "__main__":+show_missing = Truediff --git a/atomic-forge/tools/fia_signals/README.md b/atomic-forge/tools/fia_signals/README.mdnew file mode 100644index 0000000..826d074--- /dev/null+++ b/atomic-forge/tools/fia_signals/README.md@@ -0,0 +1,55 @@+# Fía Signals Tool++**Professional-grade crypto market intelligence for Atomic Agents.**++Provides 6 tools backed by real-time data from Binance, DeFiLlama, Etherscan, and more:++| Tool | Description | Free? |+|------|-------------|-------|+| `market_regime` | Detect trending/ranging/volatile/breakout market regime | ✅ Free |+| `crypto_signals` | BUY/SELL/HOLD with RSI, MACD, ADX for any crypto | ✅ Free |+| `defi_yields` | Best yields across Aave, Compound, Curve, Lido | ✅ Free |+| `gas_prices` | Real-time gas across Ethereum, Polygon, BSC, Arbitrum, Base | ✅ Free |+| `solana_trending` | Trending Solana tokens with volume and risk scores | ✅ Free |+| `wallet_risk` | Wallet risk score + entity classification | x402 $0.02 |++## Installation++```bash+pip install fia-signals+```++No API key required for free tier. Premium `wallet_risk` tool uses x402 micropayments (Solana USDC).++## Usage++```python+from fia_signals_tool import FIASignalsTool, FIASignalsToolInputSchema++tool = FIASignalsTool()++# Market regime+result = tool.run(FIASignalsToolInputSchema(tool="market_regime"))+print(result.data)++# Crypto signals+result = tool.run(FIASignalsToolInputSchema(tool="crypto_signals", symbol="ETH"))+print(result.data)++# DeFi yields+result = tool.run(FIASignalsToolInputSchema(tool="defi_yields"))+print(result.data)+```++## Atomic Agents++Add to your `atomic-agents` project via the workspace `pyproject.toml`:++```toml+[tool.uv.workspace]+members = ["atomic-forge/tools/fia_signals"]+```++## License++MITdiff --git a/atomic-forge/tools/fia_signals/pyproject.toml b/atomic-forge/tools/fia_signals/pyproject.tomlnew file mode 100644index 0000000..895c4f2--- /dev/null+++ b/atomic-forge/tools/fia_signals/pyproject.toml@@ -0,0 +1,35 @@+[build-system]+requires = ["hatchling"]+build-backend = "hatchling.build"++[tool.hatch.build.targets.wheel]+packages = ["tool"]++[project]+name = "fia-signals"+version = "1.0.0"+description = "Fía Signals crypto intelligence tool for Atomic Agents — market regime, trading signals, DeFi yields, wallet risk scoring"+readme = "README.md"+authors = [+ { name = "Marvin", email = "" }+]+requires-python = ">=3.12"+dependencies = [+ "atomic-agents",+ "pydantic>=2.10.3,<3.0.0",+ "requests>=2.28.0,<3.0.0",+]++[dependency-groups]+dev = [+ "coverage>=7.6.1,<8.0.0",+ "pytest>=8.3.3,<9.0.0",+ "pytest-asyncio>=0.23.5,<1.0.0",+ "pytest-cov>=5.0.0,<6.0.0",+ "python-dotenv>=1.0.0,<2.0.0",+ "rich>=13.7.0,<14.0.0",+ "httpx>=0.28.0,<1.0.0",+]++[tool.uv.sources]+atomic-agents = { workspace = true }diff --git a/atomic-forge/tools/fia_signals/requirements.txt b/atomic-forge/tools/fia_signals/requirements.txtnew file mode 100644index 0000000..4201585--- /dev/null+++ b/atomic-forge/tools/fia_signals/requirements.txt@@ -0,0 +1,3 @@+atomic-agents>=1.0.0,<2.0.0+pydantic>=2.10.3,<3.0.0+requests>=2.28.0,<3.0.0diff --git a/atomic-forge/tools/fia_signals/tests/__init__.py b/atomic-forge/tools/fia_signals/tests/__init__.pynew file mode 100644index 0000000..65140f2--- /dev/null+++ b/atomic-forge/tools/fia_signals/tests/__init__.py@@ -0,0 +1 @@+# tests packagediff --git a/atomic-forge/tools/fia_signals/tests/test_fia_signals.py b/atomic-forge/tools/fia_signals/tests/test_fia_signals.pynew file mode 100644index 0000000..8456751--- /dev/null+++ b/atomic-forge/tools/fia_signals/tests/test_fia_signals.py@@ -0,0 +1,143 @@+import os+import sys+import pytest+from unittest.mock import patch, MagicMock++sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))++from tool.fia_signals import ( # noqa: E402+ FIASignalsTool,+ FIASignalsToolConfig,+ FIASignalsToolInputSchema,+)+++# --- Fixtures ---++def tool():+ return FIASignalsTool(config=FIASignalsToolConfig())+++# --- Input Schema Tests ---++def test_input_schema_tool_field():+ schema = FIASignalsToolInputSchema.model_json_schema()+ assert "tool" in schema["properties"]+ props = schema["properties"]["tool"]+ enum_vals = props["enum"]+ assert "market_regime" in enum_vals+ assert "crypto_signals" in enum_vals+ assert "defi_yields" in enum_vals+ assert "gas_prices" in enum_vals+ assert "solana_trending" in enum_vals+ assert "wallet_risk" in enum_vals+++def test_input_schema_optional_fields():+ schema = FIASignalsToolInputSchema.model_json_schema()+ assert schema["properties"]["symbol"].get("anyOf") is not None+ assert schema["properties"]["address"].get("anyOf") is not None+++# --- Tool instantiation ---++def test_tool_instantiation():+ tool = FIASignalsTool()+ assert tool.api_key is None+++def test_tool_with_config():+ tool = FIASignalsTool(config=FIASignalsToolConfig(api_key="test-key"))+ assert tool.api_key == "test-key"+++# --- Mocked API tests ---+[email protected]("tool_name,endpoint", [+ ("market_regime", "/v1/intelligence/regime/free"),+ ("defi_yields", "/v1/yield/rates"),+ ("gas_prices", "/v1/gas/prices"),+ ("solana_trending", "/v1/solana/trending"),+])+def test_tool_free_endpoints(tool, tool_name, endpoint):+ mock_response = {"test": "data", "regime": "TRENDING_UP"}++ with patch("tool.fia_signals.requests.get") as mock_get:+ mock_get.return_value = MagicMock(+ ok=True, status_code=200,+ json=MagicMock(return_value=mock_response)+ )+ mock_get.return_value.raise_for_status = MagicMock()++ result = tool.run(FIASignalsToolInputSchema(tool=tool_name))++ assert result.tool == tool_name+ assert result.data == mock_response+ mock_get.assert_called_once()+++def test_crypto_signals_default_symbol(tool):+ mock_response = {"signal": "BUY", "rsi": 45.2}++ with patch("tool.fia_signals.requests.get") as mock_get:+ mock_get.return_value = MagicMock(+ ok=True, status_code=200,+ json=MagicMock(return_value=mock_response)+ )+ mock_get.return_value.raise_for_status = MagicMock()++ result = tool.run(FIASignalsToolInputSchema(tool="crypto_signals"))++ assert result.tool == "crypto_signals"+ mock_get.assert_called_once()+ call_url = mock_get.call_args[0][0]+ assert "BTC" in call_url # default symbol+++def test_crypto_signals_custom_symbol(tool):+ mock_response = {"signal": "SELL", "rsi": 68.1}++ with patch("tool.fia_signals.requests.get") as mock_get:+ mock_get.return_value = MagicMock(+ ok=True, status_code=200,+ json=MagicMock(return_value=mock_response)+ )+ mock_get.return_value.raise_for_status = MagicMock()++ result = tool.run(FIASignalsToolInputSchema(tool="crypto_signals", symbol="DOGE"))++ assert result.tool == "crypto_signals"+ mock_get.assert_called_once()+ call_url = mock_get.call_args[0][0]+ assert "DOGE" in call_url+++def test_wallet_risk_no_address_raises(tool):+ with pytest.raises(ValueError, match="address is required"):+ tool.run(FIASignalsToolInputSchema(tool="wallet_risk"))+++def test_wallet_risk_returns_x402_info(tool):+ result = tool.run(FIASignalsToolInputSchema(+ tool="wallet_risk",+ address="0x1234567890abcdef1234567890abcdef12345678"+ ))++ assert result.tool == "wallet_risk"+ assert "x402" in result.data["gateway"]+ assert result.data["price"] == "$0.02 USDC"+++# --- Error handling ---++def test_api_error_raises(tool):+ with patch("tool.fia_signals.requests.get") as mock_get:+ mock_get.return_value = MagicMock(+ ok=False, status_code=500,+ raise_for_status=MagicMock(+ side_effect=Exception("500 Server Error")+ )+ )+ with pytest.raises(Exception):+ tool.run(FIASignalsToolInputSchema(tool="market_regime"))diff --git a/atomic-forge/tools/fia_signals/tool/__init__.py b/atomic-forge/tools/fia_signals/tool/__init__.pynew file mode 100644index 0000000..4f68225--- /dev/null+++ b/atomic-forge/tools/fia_signals/tool/__init__.py@@ -0,0 +1,13 @@+from .fia_signals import (+ FIASignalsTool,+ FIASignalsToolConfig,+ FIASignalsToolInputSchema,+ FIASignalsToolOutputSchema,+)++__all__ = [+ "FIASignalsTool",+ "FIASignalsToolConfig",+ "FIASignalsToolInputSchema",+ "FIASignalsToolOutputSchema",+]diff --git a/atomic-forge/tools/fia_signals/tool/fia_signals.py b/atomic-forge/tools/fia_signals/tool/fia_signals.pynew file mode 100644index 0000000..76d54b8--- /dev/null+++ b/atomic-forge/tools/fia_signals/tool/fia_signals.py@@ -0,0 +1,231 @@+import os+from typing import Literal, Optional++import requests+from pydantic import Field++from atomic_agents import BaseIOSchema, BaseTool, BaseToolConfig+++BASE_URL = "https://fiasignals.com"+++################+# INPUT SCHEMA #+################+class FIASignalsToolInputSchema(BaseIOSchema):+ """+ Schema for input to the Fía Signals crypto intelligence tool.+ Select one tool at a time.+ """++ tool: Literal[+ "market_regime",+ "crypto_signals",+ "defi_yields",+ "gas_prices",+ "solana_trending",+ "wallet_risk",+ ] = Field(..., description="The Fía Signals tool to call.")+ symbol: Optional[str] = Field(+ None, description="Crypto symbol (e.g. BTC, ETH) for crypto_signals tool."+ )+ address: Optional[str] = Field(+ None, description="Wallet address for wallet_risk tool."+ )+++####################+# OUTPUT SCHEMA(S) #+####################+class FIAMarketRegimeOutputSchema(BaseIOSchema):+ """Output schema for market regime detection."""++ regime: str = Field(..., description="Market regime: TRENDING_UP, TRENDING_DOWN, RANGING, VOLATILE, BREAKOUT")+ confidence: float = Field(..., description="Confidence score of the regime classification (0-1)")+ indicators: dict = Field(..., description="Supporting indicators used for classification")+++class FIACryptoSignalsOutputSchema(BaseIOSchema):+ """Output schema for crypto trading signals."""++ signal: str = Field(..., description="Trading signal: BUY, SELL, or HOLD")+ symbol: str = Field(..., description="Crypto symbol")+ rsi: float = Field(..., description="Relative Strength Index (0-100)")+ macd: dict = Field(..., description="MACD indicator values")+ adx: float = Field(..., description="Average Directional Index (0-100)")+ entry: Optional[dict] = Field(None, description="Suggested entry zone")+ target: Optional[dict] = Field(None, description="Suggested target zone")+ stop: Optional[dict] = Field(None, description="Suggested stop loss")+++class FIDefiYieldsOutputSchema(BaseIOSchema):+ """Output schema for DeFi yields."""++ yields: list = Field(..., description="List of DeFi yield opportunities")+ protocol: str = Field(..., description="Protocol name (Aave, Compound, Curve, Lido)")+ asset: str = Field(..., description="Underlying asset")+ apy: float = Field(..., description="Annual Percentage Yield")+++class FIAGasPricesOutputSchema(BaseIOSchema):+ """Output schema for gas prices."""++ network: str = Field(..., description="Network name (Ethereum, Polygon, BSC, Arbitrum, Base)")+ gas_price_gwei: float = Field(..., description="Current gas price in Gwei")+++class FIASolanaTrendingOutputSchema(BaseIOSchema):+ """Output schema for trending Solana tokens."""++ tokens: list = Field(..., description="List of trending Solana tokens")+ symbol: str = Field(..., description="Token symbol")+ volume_24h: float = Field(..., description="24-hour trading volume")+ risk_score: float = Field(..., description="Risk score (0-1)")+++class FIAWalletRiskOutputSchema(BaseIOSchema):+ """Output schema for wallet risk scoring."""++ address: str = Field(..., description="Wallet address")+ risk_score: float = Field(..., description="Wallet risk score (0-1)")+ entity: Optional[str] = Field(None, description="Entity classification if known")+ tags: list = Field(..., description="Behavioral tags")+++class FIASignalsToolOutputSchema(BaseIOSchema):+ """Output schema for the Fía Signals tool — wraps all tool responses."""++ tool: str = Field(..., description="Tool that was called")+ data: dict = Field(..., description="Raw response data from Fía Signals API")+++##############+# TOOL CONFIG #+##############+class FIASignalsToolConfig(BaseToolConfig):+ """Configuration for the Fía Signals tool."""++ api_key: Optional[str] = None # Free tier requires no API key; x402 premium uses Solana USDC+++##############+# TOOL LOGIC #+##############+class FIASignalsTool(BaseTool[FIASignalsToolInputSchema, FIASignalsToolOutputSchema]):+ """+ Tool for accessing Fía Signals crypto market intelligence.++ Provides market regime detection, trading signals (RSI/MACD/ADX),+ DeFi yields, gas prices, Solana trending tokens, and wallet risk scoring.++ Attributes:+ input_schema (FIASignalsToolInputSchema): The schema for the input data.+ output_schema (FIASignalsToolOutputSchema): The schema for the output data.+ """++ def __init__(self, config: FIASignalsToolConfig = FIASignalsToolConfig()):+ """+ Initializes the FIASignalsTool.++ Args:+ config (FIASignalsToolConfig): Configuration for the tool.+ """+ super().__init__(config)+ self.api_key = config.api_key or os.getenv("FIA_API_KEY")++ def _call_tool(self, params: FIASignalsToolInputSchema) -> dict:+ """Dispatch to the appropriate Fía Signals API endpoint."""+ tool = params.tool++ if tool == "market_regime":+ r = requests.get(f"{BASE_URL}/v1/intelligence/regime/free", timeout=10)+ r.raise_for_status()+ return {"tool": "market_regime", "data": r.json()}++ elif tool == "crypto_signals":+ symbol = params.symbol or "BTC"+ r = requests.get(f"{BASE_URL}/v1/dd/quick/{symbol}", timeout=10)+ r.raise_for_status()+ return {"tool": "crypto_signals", "data": r.json()}++ elif tool == "defi_yields":+ r = requests.get(f"{BASE_URL}/v1/yield/rates", timeout=10)+ r.raise_for_status()+ return {"tool": "defi_yields", "data": r.json()}++ elif tool == "gas_prices":+ r = requests.get(f"{BASE_URL}/v1/gas/prices", timeout=10)+ r.raise_for_status()+ return {"tool": "gas_prices", "data": r.json()}++ elif tool == "solana_trending":+ r = requests.get(f"{BASE_URL}/v1/solana/trending", timeout=10)+ r.raise_for_status()+ return {"tool": "solana_trending", "data": r.json()}++ elif tool == "wallet_risk":+ if not params.address:+ raise ValueError("address is required for wallet_risk tool")+ return {+ "tool": "wallet_risk",+ "data": {+ "info": "Premium endpoint — requires x402 micropayment",+ "gateway": "https://x402.fiasignals.com",+ "endpoint": f"/v1/wallet/risk/{params.address}",+ "price": "$0.02 USDC",+ "discovery": "https://x402.fiasignals.com/.well-known/x402.json",+ },+ }++ raise ValueError(f"Unknown tool: {tool}")++ async def run_async(+ self, params: FIASignalsToolInputSchema+ ) -> FIASignalsToolOutputSchema:+ """+ Runs the Fía Signals tool asynchronously.++ Args:+ params (FIASignalsToolInputSchema): The input parameters.++ Returns:+ FIASignalsToolOutputSchema: The output from the selected tool.+ """+ import asyncio++ result = await asyncio.to_thread(self._call_tool, params)+ return FIASignalsToolOutputSchema(**result)++ def run(self, params: FIASignalsToolInputSchema) -> FIASignalsToolOutputSchema:+ """+ Runs the Fía Signals tool synchronously.++ Args:+ params (FIASignalsToolInputSchema): The input parameters.++ Returns:+ FIASignalsToolOutputSchema: The output from the selected tool.+ """+ result = self._call_tool(params)+ return FIASignalsToolOutputSchema(**result)+++####+# Main entry point for testing+if __name__ == "__main__":+ from rich.console import Console++ rich_console = Console()++ tool = FIASignalsTool()++ # Test: market regime+ rich_console.print("[bold]Testing market_regime...[/bold]")+ output = tool.run(FIASignalsToolInputSchema(tool="market_regime"))+ rich_console.print(output)++ # Test: crypto signals+ rich_console.print("\n[bold]Testing crypto_signals (BTC)...[/bold]")+ output = tool.run(FIASignalsToolInputSchema(tool="crypto_signals", symbol="BTC"))+ rich_console.print(output)diff --git a/docs/guides/tools.md b/docs/guides/tools.mdindex 2a9bd49..ce65949 100644--- a/docs/guides/tools.md+++ b/docs/guides/tools.md@@ -19,7 +19,8 @@ The Atomic Forge includes several pre-built tools:- **Tavily Search**: AI-powered web search- **YouTube Transcript Scraper**: Extract transcripts from YouTube videos- **Webpage Scraper**: Extract content from web pages-- **BoCha Search**: web search+- **BoCha Search**: Web search+- **Fía Signals**: Crypto market intelligence — market regime, trading signals, DeFi yields, gas prices, Solana trending tokens, and wallet risk scoring## Using Tools