API Reference

Solana Agent

Simplified client interface for interacting with the Solana Agent system.

This module provides a clean API for end users to interact with the agent system without dealing with internal implementation details.

class solana_agent.client.solana_agent.SolanaAgent(config_path=None, config=None, *, instructions=None, privy_user_id=None, name=None, specialization=None, model=None, stateless_model=None, base_url=None, api_key=None, tools=None, x402_preferred_asset=None, max_output_tokens=None, context_window_tokens=None, tokenizer_model=None)[source]

Bases: SolanaAgent

Simplified client interface for interacting with the agent system.

Parameters:

config_path (str | None)
config (Dict[str, Any] | None)
instructions (str | None)
privy_user_id (str | None)
name (str | None)
specialization (str | None)
model (str | None)
stateless_model (str | None)
base_url (str | None)
api_key (str | None)
tools (List[str] | None)
x402_preferred_asset (str | None)
max_output_tokens (int | None)
context_window_tokens (int | None)
tokenizer_model (str | None)

async process(message, search_enabled=None, prompt=None, capture_schema=None, capture_name=None, output_format='text', audio_voice='nova', audio_output_format='aac', audio_input_format='mp4', images=None, output_model=None, **runtime_context)[source]

Process a user message (text or audio) and optional images, yielding low-level chunks.

Parameters:

message (str | bytes) – Text message or audio bytes
**runtime_context (Any) – Per-request hosted runtime metadata
search_enabled (bool | None) – Enable the hosted search add-on for this request
prompt (str | None) – Optional prompt for the agent
output_format (Literal['text', 'audio']) – Response format (“text” or “audio”)
capture_schema (Dict[str, Any] | None) – Optional Pydantic schema for structured output
capture_name (str | None) – Optional name for structured output capture
audio_voice (Literal['alloy', 'ash', 'ballad', 'coral', 'echo', 'fable', 'onyx', 'nova', 'sage', 'shimmer']) – Voice to use for audio output
audio_output_format (Literal['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm']) – Audio output format
audio_input_format (Literal['flac', 'mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'ogg', 'wav', 'webm']) – Audio input format
images (List[str | bytes] | None) – Optional list of image URLs (str) or image bytes.
output_model (Type[BaseModel] | None) – Optional Pydantic model for structured output

Returns:

Async generator yielding response chunks. Hosted chat completions are executed as non-streaming requests; use process_message to collect the final response automatically.

Return type:

AsyncGenerator[str | bytes | BaseModel, None]

async process_message(message, search_enabled=None, prompt=None, capture_schema=None, capture_name=None, output_format='text', audio_voice='nova', audio_output_format='aac', audio_input_format='mp4', images=None, output_model=None, **runtime_context)[source]

Process one request and collect the final response payload.

This is the default hosted-SDK entrypoint because the hosted platform delivers chat completions as non-streaming JSON responses.

Parameters:

message (str | bytes)
search_enabled (bool | None)
prompt (str | None)
capture_schema (Dict[str, Any] | None)
capture_name (str | None)
output_format (Literal['text', 'audio'])
audio_voice (Literal['alloy', 'ash', 'ballad', 'coral', 'echo', 'fable', 'onyx', 'nova', 'sage', 'shimmer'])
audio_output_format (Literal['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm'])
audio_input_format (Literal['flac', 'mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'ogg', 'wav', 'webm'])
images (List[str | bytes] | None)
output_model (Type[BaseModel] | None)
runtime_context (Any)

Return type:

str | bytes | BaseModel | None

async message(message, search_enabled=None, prompt=None, capture_schema=None, capture_name=None, output_format='text', audio_voice='nova', audio_output_format='aac', audio_input_format='mp4', images=None, output_model=None, **runtime_context)[source]

Process one request using the README-friendly method name.

Parameters:

message (str | bytes)
search_enabled (bool | None)
prompt (str | None)
capture_schema (Dict[str, Any] | None)
capture_name (str | None)
output_format (Literal['text', 'audio'])
audio_voice (Literal['alloy', 'ash', 'ballad', 'coral', 'echo', 'fable', 'onyx', 'nova', 'sage', 'shimmer'])
audio_output_format (Literal['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm'])
audio_input_format (Literal['flac', 'mp3', 'mp4', 'mpeg', 'mpga', 'm4a', 'ogg', 'wav', 'webm'])
images (List[str | bytes] | None)
output_model (Type[BaseModel] | None)
runtime_context (Any)

Return type:

str | bytes | BaseModel | None

async context(*, conversation_id=None, model=None, memory_ttl_tier=None, service_tier=None, search_enabled=None, chain_type='solana', **runtime_context)[source]

Build flat hosted runtime context for a message call.

Parameters:

conversation_id (str | None)
model (str | None)
memory_ttl_tier (Literal['work', 'project'] | None)
service_tier (Literal['standard', 'priority'] | None)
search_enabled (bool | None)
chain_type (Literal['solana', 'ethereum'])
runtime_context (Any)

Return type:

Dict[str, Any]

register_tool(agent_name, tool)[source]

Register a tool with the agent system.

Parameters:

agent_name (str) – Name of the agent to register the tool with
tool (Tool) – Tool instance to register

Returns:

True if successful, False

Return type:

bool

async create_privy_user()[source]

Create a hosted Privy user and return its DID.

Return type:: Dict[str, Any]

async create_wallet(privy_user_id=None, chain_type='solana')[source]

Create or return the active Privy-backed wallet for a user.

Parameters:

privy_user_id (str | None)
chain_type (Literal['solana', 'ethereum'])

Return type:

Dict[str, Any]

async rotate_wallet(privy_user_id=None, chain_type='solana')[source]

Rotate the active Privy-backed wallet for a user.

Parameters:

privy_user_id (str | None)
chain_type (Literal['solana', 'ethereum'])

Return type:

Dict[str, Any]

async export_wallet_private_key(wallet_id=None, privy_user_id=None, chain_type='solana')[source]

Export the hosted wallet private key for self-custody.

Parameters:

wallet_id (str | None)
privy_user_id (str | None)
chain_type (Literal['solana', 'ethereum'])

Return type:

str

async get_wallet_address(wallet_id=None)[source]

Return the hosted wallet public address.

When wallet_id is omitted, the active wallet for config.ai.privy_user_id is created or fetched first.

Parameters:: wallet_id (str | None)
Return type:: str

async prepare_x402_runtime_context(*, chain_type='solana', **runtime_context)[source]

Return runtime context populated with the Privy-backed wallet.

Parameters:

chain_type (Literal['solana', 'ethereum'])
runtime_context (Any)

Return type:

Dict[str, Any]

async get_account_summary(**runtime_context)[source]

Get hosted billing and usage summary for the authenticated wallet account.

Parameters:: runtime_context (Any)
Return type:: Dict[str, Any]

async get_usage_report(granularity, from_date=None, to_date=None, group_by=None, **runtime_context)[source]

Get hosted usage buckets for the authenticated wallet account.

Parameters:

granularity (str)
from_date (str | None)
to_date (str | None)
group_by (str | None)
runtime_context (Any)

Return type:

Dict[str, Any]

async get_usage_forecast(window_days=30, **runtime_context)[source]

Get hosted usage forecast for the authenticated wallet account.

Parameters:

window_days (int)
runtime_context (Any)

Return type:

Dict[str, Any]

async get_pricing_info(**runtime_context)[source]

Get hosted pricing information for the authenticated wallet account.

Parameters:: runtime_context (Any)
Return type:: Dict[str, Any]

Tools

Plugin manager for the Solana Agent system.

This module implements the concrete PluginManager that discovers, loads, and manages plugins.

class solana_agent.plugins.manager.PluginManager(config=None, tool_registry=None)[source]

Bases: PluginManager

Manager for discovering and loading plugins.

Parameters:

config (Dict[str, Any] | None)
tool_registry (ToolRegistry | None)

register_plugin(plugin)[source]

Register a plugin in the manager.

Parameters:: plugin (Plugin) – The plugin to register
Returns:: True if registration succeeded, False otherwise
Return type:: bool

load_plugins()[source]

Load all plugins using entry points and apply configuration.

Returns:: List of loaded plugin names
Return type:: List[str]

get_plugin(name)[source]

Get a plugin by name.

Parameters:: name (str) – Name of the plugin to retrieve
Returns:: Plugin instance or None if not found
Return type:: Plugin | None

list_plugins()[source]

List all registered plugins with their details.

Returns:: List of plugin details dictionaries
Return type:: List[Dict[str, Any]]

async execute_tool(tool_name, **kwargs)[source]

Execute a tool with the given parameters.

Parameters:

tool_name (str) – Name of the tool to execute
**kwargs – Parameters to pass to the tool

Returns:

Dictionary with execution results

Return type:

Dict[str, Any]

configure(config)[source]

Configure the plugin manager and all plugins.

Parameters:: config (Dict[str, Any]) – Configuration dictionary
Return type:: None

Tool registry for the Solana Agent system.

This module implements the concrete ToolRegistry that manages tools and their access permissions.

class solana_agent.plugins.registry.ToolRegistry(config=None)[source]

Bases: ToolRegistry

Instance-based registry that manages tools and their access permissions.

Parameters:: config (Dict[str, Any])

register_tool(tool)[source]

Register a tool with this registry.

Parameters:: tool (Tool)
Return type:: bool

get_tool(tool_name)[source]

Get a tool by name.

Parameters:: tool_name (str)
Return type:: Tool | None

assign_tool_to_agent(agent_name, tool_name)[source]

Give an agent access to a specific tool.

Parameters:

agent_name (str)
tool_name (str)

Return type:

bool

get_agent_tools(agent_name)[source]

Get all tools available to an agent.

Parameters:: agent_name (str)
Return type:: List[Dict[str, Any]]

list_all_tools()[source]

List all registered tools.

Return type:: List[str]

configure_all_tools(config)[source]

Configure all registered tools with new configuration.

Parameters:: config (Dict[str, Any]) – Configuration dictionary to apply
Return type:: None

AutoTool implementation for the Solana Agent system.

This module provides the base AutoTool class that implements the Tool interface and can be extended to create custom tools.

class solana_agent.plugins.tools.auto_tool.AutoTool(name, description, registry=None)[source]

Bases: Tool

Base class for tools that automatically register with the system.

Parameters:

name (str)
description (str)

property name: str: Get the name of the tool.

property description: str: Get the description of the tool.

configure(config)[source]

Configure the tool with settings from config.

Parameters:: config (Dict[str, Any])
Return type:: None

get_schema()[source]

Return the JSON schema for this tool’s parameters.

Return type:: Dict[str, Any]

async execute(**params)[source]

Execute the tool with the provided parameters.

Return type:: Dict[str, Any]

Plugin system interfaces.

These interfaces define the contracts for the plugin system, enabling extensibility through tools and plugins.

class solana_agent.interfaces.plugins.plugins.Tool[source]

Bases: ABC

Interface for tools that can be used by agents.

abstract property name: str: Get the name of the tool.

abstract property description: str: Get the description of the tool.

abstractmethod configure(config)[source]

Configure the tool with global configuration.

Parameters:: config (Dict[str, Any])
Return type:: None

abstractmethod get_schema()[source]

Get the schema for the tool parameters.

Return type:: Dict[str, Any]

abstractmethod async execute(**params)[source]

Execute the tool with the given parameters.

Return type:: Dict[str, Any]

class solana_agent.interfaces.plugins.plugins.ToolRegistry[source]

Bases: ABC

Interface for the tool registry.

abstractmethod register_tool(tool)[source]

Register a tool in the registry.

Parameters:: tool (Tool)
Return type:: bool

abstractmethod get_tool(tool_name)[source]

Get a tool by name.

Parameters:: tool_name (str)
Return type:: Tool | None

abstractmethod assign_tool_to_agent(agent_name, tool_name)[source]

Give an agent access to a specific tool.

Parameters:

agent_name (str)
tool_name (str)

Return type:

bool

abstractmethod get_agent_tools(agent_name)[source]

Get all tools available to an agent.

Parameters:: agent_name (str)
Return type:: List[Dict[str, Any]]

abstractmethod list_all_tools()[source]

List all registered tools.

Return type:: List[str]

abstractmethod configure_all_tools(config)[source]

Configure all registered tools with the same config.

Parameters:: config (Dict[str, Any])
Return type:: None

class solana_agent.interfaces.plugins.plugins.Plugin[source]

Bases: ABC

Interface for plugins that can be loaded by the system.

abstract property name: str: Get the name of the plugin.

abstract property description: str: Get the description of the plugin.

abstractmethod initialize(tool_registry)[source]

Initialize the plugin and register its tools.

Parameters:: tool_registry (ToolRegistry)
Return type:: bool

class solana_agent.interfaces.plugins.plugins.PluginManager[source]

Bases: ABC

Interface for the plugin manager.

abstractmethod register_plugin(plugin)[source]

Register a plugin in the manager.

Parameters:: plugin (Plugin)
Return type:: bool

abstractmethod load_plugins()[source]

Load all registered plugins.

Return type:: List[str]

abstractmethod get_plugin(name)[source]

Get a plugin by name.

Parameters:: name (str)
Return type:: Plugin | None

abstractmethod list_plugins()[source]

List all registered plugins with their details.

Return type:: List[Dict[str, Any]]

abstractmethod async execute_tool(tool_name, **kwargs)[source]

Execute a tool with the given parameters.

Parameters:: tool_name (str)
Return type:: Dict[str, Any]

abstractmethod configure(config)[source]

Configure the plugin manager and all plugins.

Parameters:: config (Dict[str, Any])
Return type:: None