sakit 19.0.5
Solana Agent Kit
License: MIT
Requires Python: <3.14,>=3.13
Keywords: ai, openai, ai agents, agi

# Solana Agent Kit

[![PyPI - Version](https://img.shields.io/pypi/v/sakit)](https://pypi.org/project/sakit)
[![Python 3.13](https://img.shields.io/badge/python-3.13-blue.svg)](https://www.python.org/downloads/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/sakit)](https://pypi.org/project/sakit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![codecov](https://img.shields.io/codecov/c/github/truemagic-coder/solana-agent-kit/main.svg)](https://codecov.io/gh/truemagic-coder/solana-agent-kit)
[![Build Status](https://img.shields.io/github/actions/workflow/status/truemagic-coder/solana-agent-kit/ci.yml?branch=main)](https://github.com/truemagic-coder/solana-agent-kit/actions/workflows/ci.yml)
[![Ruff Style](https://img.shields.io/badge/style-ruff-41B5BE)](https://github.com/astral-sh/ruff)

A collection of powerful plugins to extend the capabilities of Solana Agent.

## 🚀 Features
Solana Agent Kit provides a growing library of plugins that enhance your Solana Agent with new capabilities:

* Solana Transfer - Transfer Solana tokens between the agent's wallet and the destination wallet
* Solana Ultra - Swap Solana tokens using Jupiter Ultra API with automatic slippage, priority fees, and transaction landing
* Solana Ultra Quote - Preview swap details and price impact before executing swaps
* Solana DFlow Swap - Fast token swaps using DFlow API
* Jupiter Trigger - Create, cancel, and manage limit orders using Jupiter Trigger API
* Jupiter Recurring - Create, cancel, and manage DCA orders using Jupiter Recurring API
* Jupiter Earn - Deposit/withdraw assets and mint/redeem shares using Jupiter Earn API
* Jupiter Holdings - Get token holdings with USD values for any wallet
* Jupiter Shield - Get security warnings and risk information for tokens
* Jupiter Token Search - Search for tokens by symbol, name, or address
* DFlow Prediction - Trade prediction markets with safety scoring and quality filters
* Privy DFlow Prediction - Trade prediction markets with Privy delegated wallets
* Privy Transfer - Transfer tokens using Privy delegated wallets with sponsored transactions
* Privy Privacy Cash - Private deposits, withdrawals, transfers, and balance checks via PrivacyCash
* Privy Ultra - Swap tokens using Jupiter Ultra with Privy delegated wallets
* Privy Ultra Quote - Preview swap details and price impact before executing swaps with Privy wallets
* Privy Trigger - Create and manage limit orders with Privy delegated wallets
* Privy Recurring - Create and manage DCA orders with Privy delegated wallets
* Privy Earn - Earn deposits/withdrawals and share mint/redeem using Privy delegated wallets
* Privy DFlow Swap - Fast token swaps using DFlow API with Privy delegated wallets
* Privy Wallet Address - Get the wallet address of a Privy delegated wallet
* Privy Create User - Create a new Privy user with a linked Telegram account (for bot-first flows)
* Privy Create Wallet - Create a Solana wallet for a Privy user
* Privy Get User by Telegram - Look up an existing Privy user by their Telegram ID
* Rugcheck - Check if a token is a rug
* Vybe - Look up and label known Solana wallets (CEX, market makers, AMM pools, treasuries)
* Birdeye - Comprehensive token analytics including prices, OHLCV, trades, wallet data, trending tokens, top traders, and more
* Internet Search - Search the internet in real-time using Perplexity, Grok, or OpenAI
* MCP - Interface with MCP web servers
* Image Generation - Generate images with OpenAI, Grok, or Gemini with uploading to S3 compatible storage
* Technical Analysis - Comprehensive technical indicators (EMA, SMA, MACD, RSI, Bollinger Bands, etc.) for any token using Birdeye OHLCV data
* Token Math - Reliable token amount calculations for swaps, limit orders, and transfers (LLMs are bad at math!)

## 📦 Installation

```bash
pip install sakit
```

## 🔌 Plugins

### Solana Transfer

This plugin enables Solana Agent to transfer SOL and SPL tokens from the agent's wallet to the destination wallet.

Don't use tickers - but mint addresses in your user queries.

```python
config = {
    "tools": {
        "solana_transfer": {
            "rpc_url": "my-rpc-url", # Required - your RPC URL - Helius is recommended
            "private_key": "my-private-key", # Required - base58 string - please use env vars to store the key as it is very confidential
        },
    },
}
```

### Solana Ultra

This plugin enables Solana Agent to swap tokens using Jupiter Ultra API. Jupiter Ultra automatically handles slippage, priority fees, and transaction landing for reliable swaps.

Don't use tickers - but mint addresses in your user queries.

```python
config = {
    "tools": {
        "solana_ultra": {
            "private_key": "my-private-key", # Required - base58 string - please use env vars to store the key as it is very confidential
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag (60 req/min on free tier)
            "rpc_url": "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY", # Required - Helius RPC for reliable tx sending
            "referral_account": "my-referral-account", # Optional - your Jupiter referral account public key for collecting fees
            "referral_fee": 50, # Optional - fee in basis points (50-255 bps, e.g., 50 = 0.5%). Jupiter takes 20% of this fee.
            "payer_private_key": "payer-private-key", # Optional - base58 private key for gasless transactions (integrator pays gas)
        },
    },
}
```

**Features:**
- **Jupiter Ultra API**: Access to competitive pricing with automatic slippage protection
- **Helius RPC**: Transactions sent directly via RPC instead of Jupiter's execute endpoint for reliability
- **Priority Fees**: Automatically calculated to ensure transaction landing
- **Referral Fees**: Optionally collect integrator fees (50-255 bps) via your Jupiter referral account
- **Integrator Gas Payer**: Optionally pay for gas on behalf of users for truly gasless swaps

**API Key (Required):**
Get a free Jupiter API key at [portal.jup.ag](https://portal.jup.ag). The free tier provides 60 requests per minute. The lite API (no key) was deprecated on December 31, 2025.

**RPC URL (Required):**
Transactions are sent directly via your RPC instead of Jupiter's `/execute` endpoint, which can have reliability issues. Helius RPC is recommended (`https://mainnet.helius-rpc.com/?api-key=YOUR_KEY`). Get a free API key at [helius.dev](https://helius.dev).

**Setting up Referral Account:**
To collect fees, you need a Jupiter referral account. Create one at [referral.jup.ag](https://referral.jup.ag/). Jupiter takes 20% of the referral fee you set. You also need to create token accounts for the tokens you want to collect fees in.

**Gasless Transactions:**
By default, Jupiter Ultra provides gasless swaps when the user has < 0.01 SOL and trade is > $10. However, this **doesn't work with referral fees**. To enable gasless + referral fees, configure `payer_private_key` - this wallet will pay all gas fees and you recoup costs via referral fees.

### Solana Ultra Quote

This plugin enables Solana Agent to preview swap details (amounts, slippage, price impact) before executing using Jupiter Ultra API. Perfect for showing users the exact impact before they confirm a swap.

```python
config = {
    "tools": {
        "solana_ultra_quote": {
            "private_key": "my-private-key", # Required - base58 string
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag
            "referral_account": "my-referral-account", # Optional
            "referral_fee": 50, # Optional
            "payer_private_key": "payer-private-key", # Optional
        },
    },
}
```

**Features:**
- **Preview Before Execute**: Get exact swap amounts and costs without executing
- **Show Slippage**: Display slippage tolerance in basis points
- **Show Price Impact**: Display price impact percentage
- **No Gas Fees**: Quote calls don't consume gas, safe to preview
- **Same Config as Solana Ultra**: Reuses the same configuration

**Workflow:**
1. Call `solana_ultra_quote` to preview the swap
2. Show user the in_amount, out_amount, slippage_bps, and price_impact_pct
3. If user approves, call `solana_ultra` to execute the actual swap

### Solana DFlow Swap


This plugin enables Solana Agent to swap tokens using DFlow's Swap API with a Solana keypair. DFlow offers faster swaps compared to Jupiter Ultra with competitive rates.

**Note:** Platform fees are not supported with DFlow. Use Jupiter Ultra (solana_ultra) if you need to collect fees on swaps.

```python
config = {
    "tools": {
        "solana_dflow_swap": {
            "private_key": "my-private-key", # Required - base58 string
            "payer_private_key": "payer-private-key", # Optional - for gasless/sponsored transactions
            "rpc_url": "https://api.mainnet-beta.solana.com", # Optional - RPC URL (defaults to mainnet)
        },
    },
}
```

**Features:**
- **Fast Swaps**: DFlow typically executes faster than Jupiter Ultra
- **Gasless Transactions**: Optionally sponsor gas fees for users via `payer_private_key`

### Jupiter Trigger

This plugin enables Solana Agent to create, cancel, and manage limit orders using Jupiter's Trigger API. It's a smart tool that handles the full lifecycle of limit orders with a single action parameter.

Transactions are sent directly via your RPC (Helius recommended) instead of Jupiter's `/execute` endpoint for improved reliability.

```python
config = {
    "tools": {
        "jupiter_trigger": {
            "private_key": "my-private-key", # Required - base58 string
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag
            "rpc_url": "https://mainnet.helius-rpc.com/?api-key=xxx", # Required - Helius RPC URL for transaction sending
            "referral_account": "my-referral-account", # Optional - for collecting fees
            "referral_fee": 50, # Optional - fee in basis points (50-255 bps)
            "payer_private_key": "payer-private-key", # Optional - for gasless transactions
        },
    },
}
```

**Actions:**
- `create` - Create a new limit order (requires input_mint, output_mint, making_amount, taking_amount)
- `cancel` - Cancel a specific order (requires order_pubkey)
- `cancel_all` - Cancel all open orders for the wallet
- `list` - List all orders for the wallet

**Features:**
- **Smart Action Routing**: Single tool handles create, cancel, and list operations
- **Limit Orders**: Set exact prices for token swaps
- **Order Expiry**: Optionally set expiration time for orders
- **Referral Fees**: Collect integrator fees on filled orders
- **Gasless Transactions**: Optionally pay gas on behalf of users

### Jupiter Recurring

This plugin enables Solana Agent to create, cancel, and manage DCA (Dollar Cost Averaging) orders using Jupiter's Recurring API.

```python
config = {
    "tools": {
        "jupiter_recurring": {
            "private_key": "my-private-key", # Required - base58 string
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag
            "payer_private_key": "payer-private-key", # Optional - for gasless transactions
        },
    },
}
```

**Actions:**
- `create` - Create a new DCA order (requires input_mint, output_mint, in_amount, order_count, frequency)
- `cancel` - Cancel a specific DCA order (requires order_pubkey)
- `list` - List all DCA orders for the wallet

**Parameters for Create:**
- `input_mint` - Token to sell
- `output_mint` - Token to buy
- `in_amount` - Total amount to DCA (in base units)
- `order_count` - How many orders to split into
- `frequency` - Time between orders in seconds (e.g., '3600' for hourly, '86400' for daily)
- `min_out_amount` / `max_out_amount` - Optional output amount bounds per order
- `start_at` - Optional start time (unix timestamp)

**Features:**
- **Time-Based DCA**: Automatically split large orders over time
- **Amount Bounds**: Set min/max output amount limits per order
- **Flexible Frequency**: Specify interval in seconds
- **Gasless Transactions**: Optionally pay gas on behalf of users

### Jupiter Earn

This plugin enables Solana Agent to deposit/withdraw assets and mint/redeem shares using Jupiter's Earn (Lend) API.

```python
config = {
    "tools": {
        "jupiter_earn": {
            "private_key": "my-private-key", # Required - base58 string
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag
            "rpc_url": "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY", # Required - Helius RPC for reliable tx sending
        },
    },
}
```

**Actions:**
- `deposit` - Deposit SOL/USDC into Earn (requires asset, amount)
- `withdraw` - Withdraw SOL/USDC from Earn (requires asset, amount)
- `mint` - Mint shares for SOL/USDC (requires asset, shares)
- `redeem` - Redeem shares for SOL/USDC (requires asset, shares)
- `tokens` - List earn tokens (filtered to SOL/USDC)
- `positions` - List user positions (filtered to SOL/USDC)
- `earnings` - Get user earnings (filtered to SOL/USDC)

**Notes:**
- Only SOL and USDC are supported for earn transactions.
- Transactions are sent directly via your RPC (Helius recommended).

### Jupiter Holdings

This plugin enables Solana Agent to get token holdings with USD values for any wallet address using Jupiter Ultra API.

```python
config = {
    "tools": {
        "jupiter_holdings": {
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag
        },
    },
    "agents": [
        {
            "name": "portfolio_analyst",
            "instructions": "You are an expert in analyzing Solana portfolios. Use the jupiter_holdings tool to get wallet token balances.",
            "specialization": "Portfolio analysis",
            "tools": ["jupiter_holdings"],
        }
    ]
}
```

**Returns:**
- Token mint addresses, symbols, and names
- Token balances and USD values
- Total portfolio value in USD

### Jupiter Shield

This plugin enables Solana Agent to get security warnings and risk information for Solana tokens using Jupiter's Shield API.

```python
config = {
    "tools": {
        "jupiter_shield": {
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag
        },
    },
    "agents": [
        {
            "name": "security_analyst",
            "instructions": "You are a security expert for Solana tokens. Use the jupiter_shield tool to check token security before trading.",
            "specialization": "Token security analysis",
            "tools": ["jupiter_shield"],
        }
    ]
}
```

**Returns:**
- Security warnings for each token
- Risk flags and descriptions
- Recommended caution levels

### Jupiter Token Search

This plugin enables Solana Agent to search for Solana tokens by symbol, name, or address using Jupiter's search API.

```python
config = {
    "tools": {
        "jupiter_token_search": {
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag
        },
    },
    "agents": [
        {
            "name": "token_researcher",
            "instructions": "You are an expert in finding Solana tokens. Use the jupiter_token_search tool to search for tokens.",
            "specialization": "Token research",
            "tools": ["jupiter_token_search"],
        }
    ]
}
```

**Returns:**
- Token mint addresses
- Token symbols and names
- Token metadata (logo, decimals, etc.)


### Privy Transfer

This plugin enables Solana Agent to transfer SOL and SPL tokens using Privy delegated wallets. The fee_payer wallet sponsors transaction fees, enabling gasless transfers for users.

```python
config = {
    "tools": {
        "privy_transfer": {
            "app_id": "your-privy-app-id", # Required - your Privy application ID
            "app_secret": "your-privy-app-secret", # Required - your Privy application secret
            "signing_key": "wallet-auth:your-signing-key", # Required - your Privy wallet authorization signing key
            "rpc_url": "my-rpc-url", # Required - your RPC URL - Helius is recommended
            "fee_payer": "fee-payer-private-key", # Required - base58 private key for the fee payer wallet
        },
    },
}
```

### Privy Privacy Cash

This plugin enables PrivacyCash operations (deposit, withdraw, transfer, balance) for Privy wallets via cash.solana-agent.com.

```python
config = {
    "tools": {
        "privy_privacy_cash": {
            "api_key": "your-privacycash-api-key", # Required - API key for cash.solana-agent.com
            "base_url": "https://cash.solana-agent.com", # Optional - override base URL
        },
    },
}
```

**Actions:**
- `transfer` - Deposit + withdraw in one call (requires wallet_id, recipient, amount, token)
- `deposit` - Deposit SOL/USDC to PrivacyCash (requires wallet_id, amount, token)
- `withdraw` - Withdraw SOL/USDC from PrivacyCash (requires wallet_id, recipient, amount, token)
- `balance` - Get private balance (requires wallet_id, token)

### Privy Ultra

This plugin enables Solana Agent to swap tokens using Jupiter Ultra API with Privy delegated wallets. Jupiter Ultra automatically handles slippage, priority fees, and transaction landing.

```python
config = {
    "tools": {
        "privy_ultra": {
            "app_id": "your-privy-app-id", # Required - your Privy application ID
            "app_secret": "your-privy-app-secret", # Required - your Privy application secret
            "signing_key": "wallet-auth:your-signing-key", # Required - your Privy wallet authorization signing key
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag
            "rpc_url": "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY", # Required - Helius RPC for reliable tx sending
            "referral_account": "my-referral-account", # Optional - your Jupiter referral account public key for collecting fees
            "referral_fee": 50, # Optional - fee in basis points (50-255 bps, e.g., 50 = 0.5%). Jupiter takes 20% of this fee.
            "payer_private_key": "payer-private-key", # Optional - base58 private key for gasless transactions (integrator pays gas)
        },
    },
}
```

**Features:**
- **Jupiter Ultra API**: Access to competitive pricing with automatic slippage protection
- **Privy Delegated Wallets**: Use Privy's embedded wallets with delegation for seamless user experience
- **Helius RPC**: Transactions sent directly via RPC instead of Jupiter's execute endpoint for reliability
- **Referral Fees**: Optionally collect integrator fees (50-255 bps) via your Jupiter referral account
- **Integrator Gas Payer**: Optionally pay for gas on behalf of users for truly gasless swaps

**RPC URL (Required):**
Transactions are sent directly via your RPC instead of Jupiter's `/execute` endpoint, which can have reliability issues. Helius RPC is recommended (`https://mainnet.helius-rpc.com/?api-key=YOUR_KEY`). Get a free API key at [helius.dev](https://helius.dev).

### Privy Ultra Quote

This plugin enables Solana Agent to preview swap details (amounts, slippage, price impact) before executing using Jupiter Ultra API with Privy delegated wallets. Perfect for showing users the exact impact before they confirm a swap.

```python
config = {
    "tools": {
        "privy_ultra_quote": {
            "app_id": "your-privy-app-id", # Required - your Privy application ID
            "app_secret": "your-privy-app-secret", # Required - your Privy application secret
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag
            "referral_account": "my-referral-account", # Optional
            "referral_fee": 50, # Optional
            "payer_private_key": "payer-private-key", # Optional
        },
    },
}
```

**Features:**
- **Preview Before Execute**: Get exact swap amounts and costs without executing
- **Show Slippage**: Display slippage tolerance in basis points
- **Show Price Impact**: Display price impact percentage
- **No Gas Fees**: Quote calls don't consume gas, safe to preview
- **Privy Delegated Wallets**: Works with Privy's embedded wallets
- **Same Config as Privy Ultra**: Reuses most of the same configuration

**Workflow:**
1. Call `privy_ultra_quote` to preview the swap
2. Show user the in_amount, out_amount, slippage_bps, and price_impact_pct
3. If user approves, call `privy_ultra` to execute the actual swap

### Privy Trigger


This plugin enables Solana Agent to create, cancel, and manage limit orders using Jupiter's Trigger API with Privy delegated wallets.

```python
config = {
    "tools": {
        "privy_trigger": {
            "app_id": "your-privy-app-id", # Required - your Privy application ID
            "app_secret": "your-privy-app-secret", # Required - your Privy application secret
            "signing_key": "wallet-auth:your-signing-key", # Required - your Privy wallet authorization signing key
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag
            "rpc_url": "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY", # Recommended - Helius RPC for reliable tx sending
            "referral_account": "my-referral-account", # Optional - for collecting fees
            "referral_fee": 50, # Optional - fee in basis points (50-255 bps)
            "payer_private_key": "payer-private-key", # Optional - for gasless transactions
        },
    },
}
```

**RPC URL (Recommended):**
If configured, transactions are sent directly via RPC instead of Jupiter's execute endpoint, which can timeout. Helius RPC is recommended for reliable transaction landing.

**Actions:** Same as Jupiter Trigger (create, cancel, cancel_all, list)

### Privy Recurring

This plugin enables Solana Agent to create, cancel, and manage DCA orders using Jupiter's Recurring API with Privy delegated wallets.

```python
config = {
    "tools": {
        "privy_recurring": {
            "app_id": "your-privy-app-id", # Required - your Privy application ID
            "app_secret": "your-privy-app-secret", # Required - your Privy application secret
            "signing_key": "wallet-auth:your-signing-key", # Required - your Privy wallet authorization signing key
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag
            "payer_private_key": "payer-private-key", # Optional - for gasless transactions
        },
    },
}
```

**Actions:** Same as Jupiter Recurring (create, cancel, list)

### Privy Earn

This plugin enables Solana Agent to use Jupiter Earn with Privy delegated wallets for deposits, withdrawals, and share mint/redeem.

```python
config = {
    "tools": {
        "privy_earn": {
            "app_id": "your-privy-app-id", # Required - your Privy application ID
            "app_secret": "your-privy-app-secret", # Required - your Privy application secret
            "signing_key": "wallet-auth:your-signing-key", # Required - your Privy wallet authorization signing key
            "jupiter_api_key": "my-jupiter-api-key", # Required - get free key at portal.jup.ag
            "rpc_url": "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY", # Required - Helius RPC for reliable tx sending
        },
    },
}
```

**Actions:** Same as Jupiter Earn (deposit, withdraw, mint, redeem, tokens, positions, earnings)

**Notes:**
- Only SOL and USDC are supported for earn transactions.
- Transactions are signed via Privy and sent directly via your RPC.

### Privy DFlow Swap

This plugin enables Solana Agent to swap tokens using DFlow's Swap API with Privy delegated wallets. DFlow offers faster swaps compared to Jupiter Ultra with competitive rates.

**Note:** Platform fees are not supported with DFlow. Use Privy Ultra (Jupiter) if you need to collect fees on swaps.

Transactions are signed via Privy and sent via your configured RPC (Helius recommended) for reliable blockhash handling and priority fees.

**Note:** Platform fees are not supported with DFlow. Use Jupiter Ultra (privy_ultra) if you need to collect fees on swaps.

```python
config = {
    "tools": {
        "privy_dflow_swap": {
            "app_id": "your-privy-app-id", # Required - your Privy application ID
            "app_secret": "your-privy-app-secret", # Required - your Privy application secret
            "signing_key": "wallet-auth:your-signing-key", # Required - your Privy wallet authorization signing key
            "rpc_url": "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY", # Required - Helius recommended for priority fees
            "payer_private_key": "payer-private-key", # Optional - for gasless/sponsored transactions
        },
    },
}
```

**Features:**
- **Fast Swaps**: DFlow typically executes faster than Jupiter Ultra
- **Privy Delegated Wallets**: Seamless user experience with embedded wallets
- **Helius Priority Fees**: Uses Helius priority fee estimation for reliable transaction landing
- **Gasless Transactions**: Optionally sponsor gas fees for users via `payer_private_key`

**RPC URL (Required):**
Helius RPC is strongly recommended (`https://mainnet.helius-rpc.com/?api-key=YOUR_KEY`). Helius provides priority fee estimation and better blockhash handling, which significantly improves transaction success rates. Get a free API key at [helius.dev](https://helius.dev).

### Privy Wallet Address

This plugin enables Solana Agent to get the wallet address of a Privy delegated wallet.

```python
config = {
    "tools": {
        "privy_wallet_address": {
            "app_id": "your-privy-app-id", # Required - your Privy application ID
            "app_secret": "your-privy-app-secret", # Required - your Privy application secret
        },
    },
}
```

### Privy Create User

This plugin enables Solana Agent to create a new Privy user with a linked Telegram account. Used for **bot-first** Telegram bot flows where users first interact with the bot and wallets are created server-side.

```python
config = {
    "tools": {
        "privy_create_user": {
            "app_id": "your-privy-app-id", # Required - your Privy application ID
            "app_secret": "your-privy-app-secret", # Required - your Privy application secret
        },
    },
}
```

**Parameters:**
- `telegram_user_id` (required) - The Telegram user ID to link to the new Privy user

**Returns:**
- `user_id` - The Privy user ID (did:privy:...)
- `created_at` - Unix timestamp of when the user was created
- `linked_accounts` - List of linked accounts including the Telegram account

### Privy Create Wallet

This plugin enables Solana Agent to create a new Solana wallet for a Privy user.

```python
config = {
    "tools": {
        "privy_create_wallet": {
            "app_id": "your-privy-app-id", # Required - your Privy application ID
            "app_secret": "your-privy-app-secret", # Required - your Privy application secret
            "owner_id": "your-owner-id", # Optional - set an owner ID rather than assigning to user - see Privy docs
        },
    },
}
```

**Parameters:**
- `user_id` (required) - The Privy user ID (did:privy:...) to create a wallet for
- `chain_type` (optional) - "solana" or "ethereum" (default: "solana")

**Returns:**
- `wallet_id` - The Privy wallet ID
- `address` - The wallet's public address
- `chain_type` - The blockchain type
- `additional_signers` - List of additional signers (including bot if enabled)

### Privy Get User by Telegram

This plugin enables Solana Agent to look up an existing Privy user by their Telegram user ID. Useful for checking if a user already has a Privy account and wallet before creating a new one.

```python
config = {
    "tools": {
        "privy_get_user_by_telegram": {
            "app_id": "your-privy-app-id", # Required - your Privy application ID
            "app_secret": "your-privy-app-secret", # Required - your Privy application secret
        },
    },
}
```

**Parameters:**
- `telegram_user_id` (required) - The Telegram user ID to look up

**Returns:**
- `status` - "success" if found, "not_found" if no user exists
- `user_id` - The Privy user ID (did:privy:...)
- `wallets` - List of embedded wallets with address, chain_type, and delegation status
- `has_wallet` - Boolean indicating if the user has at least one wallet

### DFlow Prediction Market

This plugin enables Solana Agent to discover and trade prediction markets on Solana via DFlow's Prediction Market API. It includes safety-first features to help users avoid scams.

⚠️ **PREDICTION MARKET RISKS:**
Unlike token swaps, prediction markets carry unique risks that cannot be fully detected:
- **Insider trading**: Market creators may have privileged information
- **Resolution risk**: Markets may resolve unfairly or not at all
- **Liquidity traps**: You may not be able to exit your position

This tool applies safety filters and provides warnings, but cannot guarantee market legitimacy. Only bet what you can afford to lose. Prefer established series (major elections, sports).

```python
config = {
    "tools": {
        "dflow_prediction": {
            "private_key": "my-private-key",  # Required for trading - base58 string
            "rpc_url": "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY",  # Required for trading
            
            # Optional - Platform fee collection
            "platform_fee_bps": 50,  # Fee in basis points (0.5%)
            "fee_account": "your-usdc-token-account",  # Account to receive fees
            
            # Optional - Quality filters (defaults shown)
            "min_volume_usd": 1000,  # Minimum market volume
            "min_liquidity_usd": 500,  # Minimum market liquidity
            "include_risky": False,  # Show low-quality markets (with warnings)
        },
    },
}
```

**Features:**
- **Safety Scoring**: Every market gets a safety score (HIGH/MEDIUM/LOW) with warnings
- **Quality Filters**: Low-volume and low-liquidity markets filtered by default
- **Risk Warnings**: Clear warnings about unverified series, new markets, unclear rules
- **Blocking Execution**: Async orders poll internally so agent gets single response
- **Platform Fees**: Collect fees on all trades via Jupiter Referral Program

**Actions:**

Discovery:
- `search` - Search markets by text query (e.g., "trump", "bitcoin")
- `list_events` - List prediction events with filters (status, sort, series)
- `get_event` - Get specific event details with safety score
- `list_markets` - List prediction markets with filters
- `get_market` - Get market details including YES/NO token mints

Trading:
- `buy` - Buy YES or NO outcome tokens with USDC
- `sell` - Sell outcome tokens back to USDC
- `positions` - Get hints for checking prediction market positions

**Safety Scores:**
- **HIGH** (PROCEED): Established market, good volume/liquidity, verified series
- **MEDIUM** (CAUTION): Some warnings (moderate volume, young market)
- **LOW** (AVOID): Multiple red flags (low volume, unclear rules, unknown series)

**Example - Search and Buy:**
```
User: "Search for prediction markets about the 2028 election"
Agent uses dflow_prediction action="search" query="2028 election"

User: "Buy $10 of YES on Kamala Harris winning"
Agent uses dflow_prediction action="buy" market_id="PRES-2028-DEM-HARRIS" side="YES" amount=10
```

### Privy DFlow Prediction

This plugin enables Solana Agent to discover and trade prediction markets on Solana via DFlow's Prediction Market API using Privy delegated wallets. Same features as DFlow Prediction but for Privy embedded wallet users.

```python
config = {
    "tools": {
        "privy_dflow_prediction": {
            "app_id": "your-privy-app-id",  # Required - your Privy application ID
            "app_secret": "your-privy-app-secret",  # Required - your Privy application secret
            "signing_key": "wallet-auth:your-signing-key",  # Required - your Privy wallet authorization signing key
            "rpc_url": "https://mainnet.helius-rpc.com/?api-key=YOUR_KEY",  # Required for trading
            
            # Optional - Platform fee collection
            "platform_fee_bps": 50,  # Fee in basis points (0.5%)
            "fee_account": "your-usdc-token-account",  # Account to receive fees
            
            # Optional - Quality filters (defaults shown)
            "min_volume_usd": 1000,  # Minimum market volume
            "min_liquidity_usd": 500,  # Minimum market liquidity
            "include_risky": False,  # Show low-quality markets (with warnings)
            
            # Optional - Gasless transactions
            "payer_private_key": "payer-private-key",  # For sponsored transactions
        },
    },
}
```

**Features:**
- Same safety scoring and quality filters as DFlow Prediction
- **Privy Delegated Wallets**: Seamless user experience with embedded wallets
- **Gasless Transactions**: Optionally sponsor gas fees for users via `payer_private_key`

**Actions:** Same as DFlow Prediction (search, list_events, get_event, list_markets, get_market, buy, sell, positions)

**Parameters:**
- All DFlow Prediction parameters plus:
- `privy_user_id` (required for trading) - Privy user ID (did:privy:xxx format)

### Rugcheck

This plugin enables Solana Agent to check if a token is a rug. 

No config is needed.

### Vybe

This plugin enables Solana Agent to look up and label known Solana wallet addresses using the Vybe Network API. It identifies CEX wallets, market makers, AMM pools, project treasuries, and influencers - useful for understanding who owns wallets when analyzing top holders or traders.

The tool caches the known accounts list in memory (1 hour TTL) and performs fast bulk lookups.

```python
config = {
    "tools": {
        "vybe": {
            "api_key": "your-vybe-api-key",  # Required - get your API key from vybenetwork.com
        },
    },
    "agents": [
        {
            "name": "wallet_analyst",
            "instructions": "You are an expert at analyzing Solana wallets. When showing top holders or traders, use the vybe tool to identify known accounts like CEX wallets or market makers.",
            "specialization": "Wallet analysis and labeling",
            "tools": ["birdeye", "vybe"],  # Often used together with birdeye
        }
    ]
}
```

**Parameters:**
- `addresses` (required) - Comma-separated list of wallet addresses to look up
- `refresh_cache` (optional) - Force refresh the cached known accounts list

**Returns:**
- Labels for each address (CEX, Exchange, AMM, Market Maker, DeFi, etc.)
- Entity names (Binance, Coinbase, Raydium, Wintermute, etc.)
- Summary of known vs unknown wallets

**Example Use Case:**
When querying top holders of a token via Birdeye, pass the wallet addresses to Vybe to identify which are CEX wallets or market makers vs real traders.

### Birdeye

This plugin enables Solana Agent to access comprehensive Solana token analytics via the Birdeye API. It provides 50 actions covering prices, OHLCV data, trades, wallet analytics, token information, and more.

```python
config = {
    "tools": {
        "birdeye": {
            "api_key": "your-birdeye-api-key",  # Required - get your API key from birdeye.so
            "chain": "solana",  # Optional - lock to a specific chain (default: "solana")
        },
    },
    "agents": [
        {
            "name": "token_analyst",
            "instructions": "You are an expert Solana token analyst. Use the birdeye tool to analyze tokens, wallets, and market trends.",
            "specialization": "Token and market analysis",
            "tools": ["birdeye"],
        }
    ]
}
```

**Available Actions:**

*Price Data:*
- `price` - Get current price of a token
- `multi_price` - Get prices for multiple tokens
- `multi_price_post` - Get prices for multiple tokens (POST)
- `history_price` - Get historical price data
- `historical_price_unix` - Get price at specific unix timestamp
- `price_volume_single` - Get price and volume for single token
- `price_volume_multi` - Get price and volume for multiple tokens

*OHLCV Data:*
- `ohlcv` - Get OHLCV candlestick data for a token
- `ohlcv_pair` - Get OHLCV data for a trading pair
- `ohlcv_base_quote` - Get OHLCV for base/quote pair
- `ohlcv_v3` - Get OHLCV v3 for token
- `ohlcv_pair_v3` - Get OHLCV v3 for pair

*Trade Data:*
- `trades_token` - Get recent trades for a token
- `trades_pair` - Get recent trades for a pair
- `trades_token_seek` - Get trades with time bounds
- `trades_pair_seek` - Get pair trades with time bounds
- `trades_v3` - Get trades v3 with filters
- `trades_token_v3` - Get token trades v3

*Token Information:*
- `token_list` - Get list of tokens
- `token_list_v3` - Get token list v3
- `token_list_scroll` - Get token list with pagination
- `token_overview` - Get detailed token overview
- `token_metadata_single` - Get metadata for single token
- `token_metadata_multiple` - Get metadata for multiple tokens
- `token_market_data` - Get market data for single token
- `token_market_data_multiple` - Get market data for multiple tokens
- `token_trade_data_single` - Get trade data for single token
- `token_trade_data_multiple` - Get trade data for multiple tokens
- `token_holder` - Get token holders
- `token_trending` - Get trending tokens
- `token_new_listing` - Get newly listed tokens
- `token_top_traders` - Get top traders for a token
- `token_markets` - Get markets for a token
- `token_security` - Get token security analysis
- `token_creation_info` - Get token creation information
- `token_mint_burn` - Get mint/burn transactions
- `token_all_time_trades_single` - Get all-time trade stats
- `token_all_time_trades_multiple` - Get all-time trade stats for multiple tokens

*Pair Data:*
- `pair_overview_single` - Get overview for single pair
- `pair_overview_multiple` - Get overview for multiple pairs

*Trader Data:*
- `trader_gainers_losers` - Get top gainers and losers
- `trader_txs_seek` - Get trader transactions with time bounds

*Wallet Data:*
- `wallet_token_list` - Get wallet token holdings
- `wallet_token_balance` - Get specific token balance in wallet
- `wallet_tx_list` - Get wallet transaction history
- `wallet_balance_change` - Get wallet balance changes
- `wallet_pnl_summary` - Get PNL summary for a wallet (realized/unrealized profit, win rate, etc.)
- `wallet_pnl_details` - Get PNL details broken down by token (POST, max 100 tokens)
- `wallet_pnl_multiple` - Get PNL for multiple wallets (max 50)
- `wallet_current_net_worth` - Get current net worth and portfolio
- `wallet_net_worth` - Get historical net worth by dates (hourly/daily)
- `wallet_net_worth_details` - Get asset details on a specific date

*Exit Liquidity:*
- `token_exit_liquidity` - Get exit liquidity for a token (available liquidity to exit position)
- `token_exit_liquidity_multiple` - Get exit liquidity for multiple tokens (max 50)

*Search:*
- `search` - Search for tokens/pairs

*Utilities:*
- `latest_block` - Get latest block info
- `networks` - Get supported networks
- `supported_chains` - Get supported chains

**Multi-Chain Support:**
All actions support a `chain` parameter (defaults to "solana"). Birdeye supports multiple chains including Ethereum, BSC, Arbitrum, etc.

### Internet Search
This plugin enables Solana Agent to search the internet for up-to-date information using Perplexity, OpenAI, or Grok.

Please ensure you include a prompt to instruct the agent to use the tool - otherwise it may not use it.

```python
config = {    
    "tools": {
        "search_internet": {
            "api_key": "your-api-key", # Required - either a Perplexity, Grok, or OpenAI API key
            "provider": "openai", # Optional, defaults to openai - can be "openai', "perplexity", or "grok" - grok also searches X
            "citations": True, # Optional, defaults to True - only applies for Perplexity and Grok
            "model": "gpt-4o-mini-search-preview",  # Optional, defaults to "sonar" for Perple