Available Tools

🛠️ Tool Overview

SAM Framework provides 15+ production-ready tools organized into categories for comprehensive Solana ecosystem operations. The tool system is built on a plugin architecture that supports both built-in tools and external extensions.

Wallet & Balance

3 tools

Complete wallet management and balance tracking

Trading

7 tools

Pump.fun and Jupiter DEX trading operations

Market Data

4 tools

Real-time market data and pair information

Plugin System

∞ extensible

Custom tools via entry points and SDK

🔧 Tool Architecture

Tool Registration System

from sam.core.tools import Tool, ToolRegistry

# Define tool handler
async def my_tool_handler(args: dict) -> dict:
    """Custom tool implementation."""
    # Tool logic here
    return {"result": "success", "data": args}

# Create tool specification
tool = Tool(
    name="my_custom_tool",
    description="Description of what the tool does",
    input_schema={
        "type": "object",
        "properties": {
            "param": {
                "type": "string",
                "description": "Parameter description"
            }
        },
        "required": ["param"]
    },
    handler=my_tool_handler
)

# Register with agent
registry.register(tool)

Middleware Pipeline

Tools execute through a configurable middleware pipeline:

# Middleware configuration
middleware_config = {
    "logging": {
        "include_args": True,
        "include_result": False
    },
    "rate_limit": {
        "enabled": True,
        "map": {
            "my_custom_tool": {"type": "custom"}
        }
    },
    "retry": [{
        "only": ["my_custom_tool"],
        "max_retries": 3,
        "base_delay": 0.25
    }]
}

Error Handling

All tools follow consistent error handling patterns:

{
  "success": false,
  "error": {
    "category": "validation",
    "title": "Invalid Address",
    "message": "The provided address is not a valid Solana address",
    "solutions": [
      "Check the address format",
      "Ensure the address is 32 bytes when base58 decoded"
    ]
  }
}

💰 Wallet & Balance Tools (3 tools)

1. `get_balance`

Get complete wallet overview including SOL and all SPL token balances.

Parameters:

address (optional): Solana address to check (uses configured wallet if not provided)

Returns:

{
  "address": "wallet_address",
  "sol_balance": 1.234,
  "sol_balance_lamports": 1234000000,
  "sol_usd": 245.67,
  "tokens": [
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "amount": 1000000,
      "uiAmount": 1.0,
      "decimals": 6
    }
  ],
  "total_portfolio_usd": 1245.67
}

Examples:

"check my wallet balance"
"show balance for [address]"
"get SOL balance"

2. `transfer_sol`

Transfer SOL between addresses with automatic transaction handling.

Parameters:

to_address: Recipient Solana address
amount: Amount of SOL to transfer (float)

Returns:

{
  "success": true,
  "transaction_id": "signature_hash",
  "from_address": "sender_address",
  "to_address": "recipient_address",
  "amount_sol": 0.5,
  "amount_lamports": 500000000
}

Examples:

"send 0.1 SOL to [recipient_address]"
"transfer 1 SOL to my other wallet"

3. `get_token_data`

Get comprehensive token metadata and supply information.

Parameters:

address: Token mint address

Returns:

{
  "success": true,
  "mint": "token_address",
  "name": "Token Name",
  "symbol": "TOKEN",
  "description": "Token description",
  "supply": {"uiAmount": 1000000},
  "image": "https://...",
  "creators": [...],
  "mutable": false,
  "burnt": false
}

Examples:

"get token data for EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
"show USDC token information"

🚀 Pump.fun Trading Tools (4 tools)

4. `pump_fun_buy`

Execute token purchases on Pump.fun with automatic slippage protection.

Parameters:

mint: Token mint address
amount: Amount of SOL to spend (float)
slippage: Slippage tolerance percentage (default: 5)

Returns:

{
  "success": true,
  "transaction_id": "signature_hash",
  "action": "buy",
  "token_address": "mint_address",
  "sol_spent": 0.01,
  "tokens_received": 1000000
}

Examples:

"buy 0.01 SOL worth of BONK on pump.fun"
"purchase 0.1 SOL of [token_address] with 10% slippage"

Risk Warning: Pump.fun tokens are highly volatile. Always start with small amounts and research tokens before trading.

5. `pump_fun_sell`

Sell Pump.fun tokens with configurable percentage amounts.

Parameters:

mint: Token mint address
percentage: Percentage of holdings to sell (1-100)
slippage: Slippage tolerance percentage (default: 5)

Returns:

{
  "success": true,
  "transaction_id": "signature_hash",
  "action": "sell",
  "token_address": "mint_address",
  "percentage_sold": 50,
  "sol_received": 0.05
}

Examples:

"sell 50% of my DOGE position"
"sell 100% of [token_address] with 3% slippage"

6. `get_pump_token_info`

Get detailed Pump.fun token information and trading data.

Parameters:

mint: Token mint address

Returns:

{
  "success": true,
  "mint": "token_address",
  "name": "Token Name",
  "symbol": "TOKEN",
  "description": "Token description",
  "market_cap": 50000,
  "current_price": 0.00001,
  "liquidity": 1000,
  "holders": 150
}

Examples:

"get info for [token_address]"
"show pump.fun token details"

7. `get_token_trades`

View recent trading activity for a Pump.fun token.

Parameters:

mint: Token mint address
limit: Number of trades to retrieve (default: 10, max: 100)

Returns:

{
  "trades": [
    {
      "signature": "tx_signature",
      "timestamp": 1640995200,
      "type": "buy",
      "amount": 1000000,
      "price": 0.00001,
      "user": "wallet_address"
    }
  ],
  "total_trades": 25
}

Examples:

"show recent trades for [token_address]"
"get trading history for BONK"

🌌 Jupiter DEX Tools (2 tools)

8. `get_swap_quote`

Get optimized swap quotes across Jupiter DEX aggregator.

Parameters:

input_mint: Input token mint address
output_mint: Output token mint address
amount: Amount to swap (in smallest units)
slippage_bps: Slippage tolerance in basis points (default: 50 = 0.5%)

Returns:

{
  "quote": {
    "inputMint": "input_address",
    "outputMint": "output_address",
    "inAmount": "1000000",
    "outAmount": "980000",
    "priceImpactPct": 0.01,
    "routePlan": [...]
  },
  "input_amount": 1000000,
  "output_amount": 980000,
  "price_impact_pct": 0.01
}

Examples:

"get swap quote for 1 SOL to USDC"
"quote 0.1 SOL to BONK with 1% slippage"

9. `jupiter_swap`

Execute token swaps through Jupiter DEX aggregator.

Parameters:

input_mint: Input token mint address
output_mint: Output token mint address
amount: Amount to swap (in smallest units)
slippage_bps: Slippage tolerance in basis points (default: 50 = 0.5%)

Returns:

{
  "success": true,
  "transaction_id": "signature_hash",
  "input_mint": "input_address",
  "output_mint": "output_address",
  "input_amount": 1000000,
  "output_amount": 980000,
  "price_impact_pct": 0.01
}

Examples:

"swap 1 SOL to USDC on Jupiter"
"exchange 100 USDC to SOL with 0.5% slippage"

📊 Market Data Tools (4 tools)

10. `search_pairs`

Search for trading pairs by query string.

Parameters:

query: Search query (token name, symbol, or address)
limit: Maximum results to return (default: 20)

Returns:

{
  "pairs": [
    {
      "pairAddress": "pair_address",
      "baseToken": {
        "address": "token_address",
        "name": "Token Name",
        "symbol": "TOKEN"
      },
      "quoteToken": {
        "address": "WSOL_address",
        "name": "Wrapped SOL",
        "symbol": "SOL"
      },
      "priceUsd": "0.00001234",
      "liquidity": {
        "usd": 50000
      }
    }
  ]
}

Examples:

"search for BONK trading pairs"
"find pairs containing DOGE"

11. `get_token_pairs`

Get all trading pairs for a specific token.

Parameters:

token_address: Token mint address
limit: Maximum results to return (default: 20)

Returns:

{
  "token_address": "input_address",
  "pairs": [...], // Same format as search_pairs
  "total_pairs": 15
}

Examples:

"get pairs for EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
"show all trading pairs for USDC"

12. `get_solana_pair`

Get detailed information for a specific trading pair.

Parameters:

pair_address: Trading pair address

Returns:

{
  "pairAddress": "pair_address",
  "baseToken": {...},
  "quoteToken": {...},
  "priceUsd": "0.00001234",
  "priceChange": {
    "h1": 2.34,
    "h24": -1.23
  },
  "liquidity": {
    "usd": 50000
  },
  "volume": {
    "h24": 10000
  },
  "marketCap": 100000
}

Examples:

"get detailed info for pair [pair_address]"
"show pair information"

13. `get_trending_pairs`

Get trending trading pairs by chain and time period.

Parameters:

chain: Blockchain network (default: "solana")
limit: Maximum results to return (default: 20)

Returns:

{
  "pairs": [
    {
      "pairAddress": "pair_address",
      "baseToken": {...},
      "quoteToken": {...},
      "priceUsd": "0.00001234",
      "priceChange": {
        "h1": 15.67,
        "h24": 45.23
      },
      "volume": {
        "h24": 50000
      }
    }
  ]
}

Examples:

"show trending pairs on Solana"
"get trending tokens"

🌐 Web Search Tools (2 tools)

14. `search_web`

Search the internet using Brave Search API.

Parameters:

query: Search query string
count: Number of results to return (default: 4, max: 10)

Returns:

{
  "results": [
    {
      "title": "Result Title",
      "url": "https://example.com",
      "description": "Result description...",
      "age": "2 days ago"
    }
  ],
  "query": "search query",
  "total_results": 4
}

Examples:

"search for Solana ecosystem news"
"find information about new DEX launches"

15. `search_news`

Search for news articles using Brave Search API.

Parameters:

query: News search query
count: Number of results to return (default: 4, max: 10)

Returns:

{
  "results": [
    {
      "title": "News Article Title",
      "url": "https://news.example.com",
      "description": "Article summary...",
      "age": "1 hour ago",
      "source": "News Source"
    }
  ],
  "query": "news query",
  "total_results": 4
}

Examples:

"search for Solana news"
"find crypto market updates"

🎯 Tool Usage Guidelines

Best Practices

Smart Execution: SAM automatically selects the most appropriate tool for your request. You don't need to specify tool names manually.

Safety Features

Automatic Slippage Protection: Default slippage limits prevent unfavorable trades
Transaction Validation: All transactions are validated before execution
Rate Limiting: Built-in protection against excessive API calls
Error Recovery: Graceful handling of network issues and API errors

Performance Optimizations

Request Caching: Frequently accessed data is cached for better performance
Concurrent Execution: Multiple tools can run simultaneously when possible
Connection Pooling: Efficient RPC connection management
Smart Retries: Automatic retry logic for transient failures

Cost Management

Token Tracking: Monitor OpenAI API usage and costs
Efficient Queries: Optimized API calls to minimize costs
Caching Strategy: Reduce redundant API requests
Usage Analytics: Track tool usage patterns and costs

🔧 Tool Development

Adding New Tools

To add a new tool to SAM:

Create Tool Handler: Implement the async handler function
Define Tool Spec: Create Pydantic-compatible schema
Register Tool: Add to appropriate tool file
Add Tests: Create comprehensive test coverage
Update Documentation: Add to this guide

Tool Template

async def handle_new_tool(args: Dict[str, Any]) -> Dict[str, Any]:
    """New tool implementation."""
    # Implementation here
    return {"result": "success"}

tool_spec = ToolSpec(
    name="new_tool",
    description="What the tool does",
    input_schema={
        "name": "new_tool",
        "description": "Tool description",
        "parameters": {
            "type": "object",
            "properties": {
                "param": {"type": "string", "description": "Parameter description"}
            },
            "required": ["param"]
        }
    }
)

🔌 Plugin System & Custom Tools

SAM supports extending its capabilities through a comprehensive plugin system. You can create custom tools for specialized trading strategies, additional DEX integrations, or domain-specific operations.

Creating Custom Tools

# my_trading_tools.py
from sam.core.tools import Tool
from typing import Dict, Any

async def custom_arbitrage_scanner(args: Dict[str, Any]) -> Dict[str, Any]:
    """Scan for arbitrage opportunities across DEXs."""
    # Your custom logic here
    opportunities = [
        {
            "token": "BONK",
            "buy_dex": "Raydium",
            "sell_dex": "Orca",
            "profit_percent": 2.5
        }
    ]

    return {
        "success": True,
        "opportunities": opportunities,
        "timestamp": "2024-01-01T12:00:00Z"
    }

def register_tools(registry, agent=None):
    """Register custom tools with SAM."""
    arbitrage_tool = Tool(
        name="arbitrage_scanner",
        description="Scan for arbitrage opportunities across DEXs",
        input_schema={
            "type": "object",
            "properties": {
                "min_profit_percent": {
                    "type": "number",
                    "description": "Minimum profit percentage to report",
                    "default": 1.0
                },
                "max_results": {
                    "type": "integer",
                    "description": "Maximum opportunities to return",
                    "default": 10
                }
            }
        },
        handler=custom_arbitrage_scanner
    )

    registry.register(arbitrage_tool)

Plugin Registration Methods

Method 1: Entry Points (Recommended)

Add to your pyproject.toml:

[project.entry-points."sam.plugins"]
my_trading_tools = "my_package.tools:register_tools"

Method 2: Environment Variables

export SAM_PLUGINS="my_package.tools,vendor.tools"

Advanced Plugin Features

Custom LLM Providers

# custom_llm.py
from sam.core.llm_provider import LLMProvider

class CustomLLMProvider(LLMProvider):
    async def chat_completion(self, messages, tools=None):
        # Custom LLM integration
        return ChatResponse(...)

def create_provider(settings=None):
    return CustomLLMProvider(api_key=settings.CUSTOM_API_KEY)

Custom Memory Backends

# redis_memory.py
from sam.core.memory import MemoryManager

class RedisMemoryManager(MemoryManager):
    async def save_session(self, session_id: str, messages):
        # Redis implementation
        pass

def create_backend():
    return RedisMemoryManager()

Tool Middleware for Plugins

# Configure middleware for custom tools
middleware_config = {
    "rate_limit": {
        "enabled": True,
        "map": {
            "arbitrage_scanner": {"type": "arbitrage"}
        }
    },
    "retry": [{
        "only": ["arbitrage_scanner"],
        "max_retries": 2,
        "base_delay": 1.0
    }]
}

Plugin Development Best Practices

Error Handling: Use structured error responses
Type Safety: Define clear input/output schemas
Documentation: Include comprehensive docstrings
Testing: Write unit tests for custom tools
Rate Limiting: Respect API limits and implement throttling
Logging: Use appropriate log levels for debugging

Example Plugin Repository

See examples/plugins/ in the SAM repository for complete examples:

simple_plugin/ - Basic tool registration
memory_mock/ - Custom memory backend
secure_storage_dummy/ - Custom key storage

📋 Complete Tool Categories Summary

Wallet & Balance (3)

• get_balance - Complete wallet overview
• transfer_sol - SOL transfers
• get_token_data - Token metadata

Trading (7)

• pump_fun_buy - Pump.fun purchases
• pump_fun_sell - Pump.fun sales
• get_pump_token_info - Token details
• get_token_trades - Trading history
• get_swap_quote - Jupiter quotes
• jupiter_swap - DEX swaps
• get_jupiter_tokens - Available tokens

Market Data (4)

• search_pairs - Pair search
• get_token_pairs - Token pairs
• get_solana_pair - Pair details
• get_trending_pairs - Trending tokens

Web Intelligence (2)

• search_web - General web search
• search_news - News articles

Plugin System (∞)

• Custom tools via entry points
• External integrations
• Specialized trading tools
• Domain-specific operations

Available Tools

Available Tools

🛠️ Tool Overview

Wallet & Balance

Trading

Market Data

Plugin System

🔧 Tool Architecture

Tool Registration System

Middleware Pipeline

Error Handling

💰 Wallet & Balance Tools (3 tools)

1. get_balance

2. transfer_sol

3. get_token_data

🚀 Pump.fun Trading Tools (4 tools)

4. pump_fun_buy

5. pump_fun_sell

6. get_pump_token_info

7. get_token_trades

🌌 Jupiter DEX Tools (2 tools)

8. get_swap_quote

9. jupiter_swap

📊 Market Data Tools (4 tools)

10. search_pairs

11. get_token_pairs

12. get_solana_pair

13. get_trending_pairs

🌐 Web Search Tools (2 tools)

14. search_web

15. search_news

🎯 Tool Usage Guidelines

Best Practices

Safety Features

Performance Optimizations

Cost Management

🔧 Tool Development

Adding New Tools

Tool Template

🔌 Plugin System & Custom Tools

Creating Custom Tools

Plugin Registration Methods

Method 1: Entry Points (Recommended)

Method 2: Environment Variables

Advanced Plugin Features

Custom LLM Providers

Custom Memory Backends

Tool Middleware for Plugins

Plugin Development Best Practices

Example Plugin Repository

📋 Complete Tool Categories Summary

1. `get_balance`

2. `transfer_sol`

3. `get_token_data`

4. `pump_fun_buy`

5. `pump_fun_sell`

6. `get_pump_token_info`

7. `get_token_trades`

8. `get_swap_quote`

9. `jupiter_swap`

10. `search_pairs`

11. `get_token_pairs`

12. `get_solana_pair`

13. `get_trending_pairs`

14. `search_web`

15. `search_news`