• Getting Started
  • Functions and Executables
  • State Management
  • Workers
  • Agents
  • Using the Logger in Custom Functions
  • Running the Agent
  • Running Agent (without fix interval)
• Installation
• Examples
• Plugins
• Components and Architecture Overview
  • Agent (a.k.a. [high level planner])
  • Worker (a.k.a. [low-level planner])
  • Function
• Chat Agents
• Solana Integration
• Market Prediction Platforms

Solana Agents - AI Trading Framework

Solana Agents is a powerful Node.js framework for building autonomous AI agents that automate trading, predict markets, and interact with Solana DeFi protocols. Built for Solana ecosystem integration with support for Jupiter swaps, Kalshi predictions, Polymarket trading, and more.

Create your own agents - Developers and users can easily create custom Solana trading agents with our flexible SDK and Cloudflare Workers backend.

Key Features

• 🤖 Autonomous Trading Agents: Build AI agents that execute trades on Solana using Jupiter aggregator
• 📊 Market Prediction: Integrate with Kalshi and Polymarket for prediction market trading
• 🔄 DeFi Automation: Automate complex DeFi strategies on Solana
• 🧠 AI-Powered Decision Making: Leverage advanced LLMs for trading decisions
• ⚡ Real-time Execution: Fast execution on Solana's high-performance blockchain
• 🔌 Extensible Plugin System: Easy integration with Solana protocols and services

Getting Started

To get started with Solana Agents, we recommend trying out the fpf-starter project. This project will get you up and running with a working Solana trading agent in minutes.

Head over to the folder's readme for instructions on how to get started!

Usage

This is the github repo for our NPM package.

Self-Hosted Backend

You can deploy your own backend using Cloudflare Workers. See the backend documentation for setup instructions.

API Keys

Request an API key from your deployed backend or use the default endpoint. API keys should start with sa- (Solana Agents).

If you have any trouble, contact support via Discord or Telegram.

1. Functions and Executables

Functions define available actions for the agent:

import {
  FpfFunction,
  ExecutableFpfFunctionResponse,
  ExecutableFpfFunctionStatus,
} from "@solana-agents/sdk";

const swapFunction = new FpfFunction({
  name: "swap_tokens",
  description: "Execute a token swap on Solana using Jupiter aggregator",
  args: [
    { name: "inputToken", type: "string", description: "Input token mint address" },
    { name: "outputToken", type: "string", description: "Output token mint address" },
    { name: "amount", type: "number", description: "Amount to swap" },
  ] as const,
  executable: async (args) => {
    try {
      // Implement Jupiter swap logic here
      return new ExecutableFpfFunctionResponse(
        ExecutableFpfFunctionStatus.Done,
        "Swap executed successfully"
      );
    } catch (e) {
      return new ExecutableFpfFunctionResponse(
        ExecutableFpfFunctionStatus.Failed,
        "Swap failed"
      );
    }
  },
});

Executable functions must return an instance of ExecutableFpfFunctionResponse with:

• ExecutableFpfFunctionStatus
• Feedback message

2. State Management

Easy and flexible way to define the state management, what the agent sees and how that changes.

async function getAgentState(): Promise<Record<string, any>> {
  return {
    solBalance: 10.5,
    tokenHoldings: {
      "SOL": 10.5,
      "USDC": 1000,
      "BONK": 5000000
    },
    openPositions: [],
    tradingHistory: [],
  };
}

For more information on how to use state management, you can check out a simple example here: State Management Example

3. Workers

Workers are simple interactable agents that execute the tasks defined by the user. They can be specialized agents with defined capabilities:

import { FpfWorker } from "@solana-agents/sdk";

const tradingWorker = new FpfWorker({
  id: "trading_worker",
  name: "Trading Worker",
  description: "Specialized worker for executing trades on Solana",
  functions: [swapFunction, checkBalanceFunction, placeOrderFunction],
  getEnvironment: async () => {
    return {
      // environment details
    };
  },
});

Key features:

• Can be shared or unique per worker
• Processes function execution results to update state

4. Agents

Agents are used to autonomously function in an open-ended manner by just providing a general goal. Tasks are generated by the agent itself continuously, and the agent will attempt to complete them. You can provide many workers to the agent, and they will be used to execute the tasks.

import { FpfAgent } from "@solana-agents/sdk";

const tradingAgent = new FpfAgent("your_api_key", {
  name: "Solana Trading Agent",
  goal: "Maximize portfolio value through automated trading on Solana",
  description: "An AI agent specialized in Solana DeFi trading, market analysis, and automated strategy execution",
  getAgentState: agent_state_function,
  workers: [tradingWorker, analysisWorker],
});

// Compile and run
await tradingAgent.init();
await tradingAgent.run();

In this example, the custom logger will print the agent's name followed by the log message to the console. You can customize the logger function to handle log messages in any way you prefer, such as writing them to a file or sending them to a logging service.

Using the Logger in Custom Functions

You can use the logger within your custom functions to log messages. The logger is passed as an argument to the executable function. Here's an example of how to use the logger in a custom function:

const customFunction = new FpfFunction({
  name: "custom_action",
  description: "A custom action with logging",
  args: [{ name: "param", description: "Parameter for the action" }] as const,
  executable: async (args, logger) => {
    try {
      logger(`Executing custom action with param: ${args.param}`);
      // Implement your function logic here
      return new ExecutableFpfFunctionResponse(
        ExecutableFpfFunctionStatus.Done,
        "Custom action completed successfully"
      );
    } catch (e) {
      logger(`Failed to execute custom action: ${e.message}`);
      return new ExecutableFpfFunctionResponse(
        ExecutableFpfFunctionStatus.Failed,
        "Custom action failed"
      );
    }
  },
});

In this example, the logger is used to log messages before and after the execution of the custom action. This helps in tracking the function's execution flow and any errors that occur.

Running the Agent

The agent will initialize and start running, performing actions such as executing trades, analyzing markets, and managing positions at regular intervals.

await agent.init();
// running at a fix interval of 60 seconds
await agent.run(60, {
  /**
   * @property {boolean} verbose - A flag to enable or disable verbose logging.
   *
   * @description
   * The `verbose` property is used to control the verbosity of the logging output.
   * When set to `true`, detailed logs will be generated, which can be useful for
   * debugging and development purposes. When set to `false`, only essential logs
   * will be produced, reducing the amount of log output.
   */
  verbose: true | false,
});

Running Agent (without fix interval)

With the step function app has more control over in interval

await agent.step();

Installation

To install the package, run:

npm install @solana-agents/sdk

Examples

In the examples folder, there are a few self contained examples:

• solana-trading-agent: A Solana trading agent that executes swaps and manages positions.
• market-prediction-agent: An agent that trades on Kalshi and Polymarket prediction markets.
• chat-agent-example: A chat agent that can execute functions and interact with users in a chat.

Just compile with npm run build and npm start to run! (make sure you have an API key first!)

Plugins

In the plugins folder are various plugins that can give your agent more functionality.

Each plugin comes with an example file. Click into the plugin's src folder to run the example.ts file!

Plugins are always open source and we welcome contributions!

Solana Plugins

• Jupiter Plugin: Execute token swaps on Solana using Jupiter aggregator
• Solana Wallet Plugin: Manage Solana wallets and sign transactions
• Raydium Plugin: Interact with Raydium DEX for liquidity and trading
• Orca Plugin: Access Orca DEX for token swaps

Market Prediction Plugins

• Kalshi Plugin: Trade on Kalshi prediction markets
• Polymarket Plugin: Interact with Polymarket for prediction trading

Components and Architecture Overview

At a high level, this SDK allows you to develop your agents powered by the Solana Agents architecture in its most full and flexible form. The SDK is made up of 3 main components (Agent, Worker, function), each with configurable arguments. Our docs expands in greater depth Solana Agents Docs.

Agent (a.k.a. high level planner)

• Takes in a Goal
  • Drives the agent's behavior through the high-level plan which influences the thinking and creation of tasks that would contribute towards this goal
• Takes in a Description
  • Combination of what was previously known as World Info + Agent Description
  • This includes a description of the "world" the agent lives in, and the personality and background of the agent

Worker (a.k.a. low-level planner)

• Takes in a Description
  • Used to control which workers are called by the agent, based on the high-level plan and tasks created to contribute to the goal

Function

• Takes in a Description
  • Used to control which functions are called by the workers, based on each worker's low-level plan
  • This can be any executable

Chat Agents

Chat Agents enable interactive conversations with AI agents that can execute functions. They are simpler to use than full Agents and are ideal for chatbot-like interactions where the agent can perform actions.

To create a chat agent:

// Initialize a chat agent with your API key and a system prompt
const agent = new ChatAgent(
    "your-FPF-api-key-here",
    "<agent description>"
);

// Start a conversation
const response = await agent.chat("<user prompt>");

Note: Chat Agents require a V2 API key that starts with "apt-".

Check out our Chat Agent example directory to see how to implement a chat agent with function execution capabilities and how to integrate chat agents with telegram and discord plugins.

Solana Integration

Jupiter Swaps

Execute token swaps on Solana using the Jupiter aggregator:

import { jupiterSwap } from "@funpumpfun/agents/plugins/jupiter";

const swapFunction = new FpfFunction({
  name: "jupiter_swap",
  description: "Swap tokens on Solana using Jupiter",
  args: [
    { name: "inputMint", type: "string", description: "Input token mint address" },
    { name: "outputMint", type: "string", description: "Output token mint address" },
    { name: "amount", type: "number", description: "Amount in lamports" },
  ] as const,
  executable: async (args) => {
    const result = await jupiterSwap({
      inputMint: args.inputMint,
      outputMint: args.outputMint,
      amount: args.amount,
    });
    return new ExecutableFpfFunctionResponse(
      ExecutableFpfFunctionStatus.Done,
      `Swap completed: ${result.signature}`
    );
  },
});

Market Prediction Platforms

Kalshi Integration

Trade on Kalshi prediction markets:

import { kalshiTrade } from "@funpumpfun/agents/plugins/kalshi";

const kalshiFunction = new FpfFunction({
  name: "kalshi_trade",
  description: "Place a trade on Kalshi prediction market",
  args: [
    { name: "marketId", type: "string", description: "Kalshi market ID" },
    { name: "side", type: "string", description: "YES or NO" },
    { name: "count", type: "number", description: "Number of contracts" },
  ] as const,
  executable: async (args) => {
    const result = await kalshiTrade({
      marketId: args.marketId,
      side: args.side,
      count: args.count,
    });
    return new ExecutableFpfFunctionResponse(
      ExecutableFpfFunctionStatus.Done,
      `Trade placed: ${result.orderId}`
    );
  },
});

Polymarket Integration

Interact with Polymarket for prediction trading:

import { polymarketTrade } from "@funpumpfun/agents/plugins/polymarket";

const polymarketFunction = new FpfFunction({
  name: "polymarket_trade",
  description: "Place a trade on Polymarket",
  args: [
    { name: "marketId", type: "string", description: "Polymarket market ID" },
    { name: "outcome", type: "string", description: "Market outcome" },
    { name: "amount", type: "number", description: "Trade amount" },
  ] as const,
  executable: async (args) => {
    const result = await polymarketTrade({
      marketId: args.marketId,
      outcome: args.outcome,
      amount: args.amount,
    });
    return new ExecutableFpfFunctionResponse(
      ExecutableFpfFunctionStatus.Done,
      `Trade executed: ${result.txHash}`
    );
  },
});

Repository Structure

| Folder | Description | |--------|-------------| | /src | Core SDK source code containing the main Fun Pump Fun Agents framework implementation | | /docs | Images, and additional resources | | /examples | Example implementations and use cases of the Fun Pump Fun Agents framework | | /plugins | Plugins available to use with Solana Agents framework (Jupiter, Kalshi, Polymarket, etc.) | | /fpf-starter | Starter project that gets you up and running with a working Solana trading agent | | /backend/cloudflare | Cloudflare Workers backend API for self-hosting |

License

This project is licensed under the MIT License.