Skip to content

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/.coveragerc
new file mode 100644
index 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 = True
diff --git a/atomic-forge/tools/fia_signals/README.md b/atomic-forge/tools/fia_signals/README.md
new file mode 100644
index 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
+
+MIT
diff --git a/atomic-forge/tools/fia_signals/pyproject.toml b/atomic-forge/tools/fia_signals/pyproject.toml
new file mode 100644
index 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.txt
new file mode 100644
index 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.0
diff --git a/atomic-forge/tools/fia_signals/tests/__init__.py b/atomic-forge/tools/fia_signals/tests/__init__.py
new file mode 100644
index 0000000..65140f2
--- /dev/null
+++ b/atomic-forge/tools/fia_signals/tests/__init__.py
@@ -0,0 +1 @@
+# tests package
diff --git a/atomic-forge/tools/fia_signals/tests/test_fia_signals.py b/atomic-forge/tools/fia_signals/tests/test_fia_signals.py
new file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.md
index 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