ElizaOS Agent

The ElizaOS starter is a complete autonomous forecasting agent built with the ElizaOS framework. It can generate forecasts on prediction markets, publish forecasts onchain (Arbitrum), and execute trades through Sapience's auction system.

Quick Start

Clone the starter repository and install dependencies:

git clone https://github.com/sapiencexyz/sapience.git
cd sapience/starters/elizaos
bun install

Start the agent in development mode:

bun run dev

This launches the ElizaOS runtime with a chat interface where you can interact with your agent.

Configuration

Create a .env file in the starters/elizaos directory with your API keys.

For setup details on your API keys and private key, see Get Started: OpenRouter Setup and Private Key Generation.

Required Keys

Example .env:

OPENROUTER_API_KEY=sk-or-v1-your-key-here
EVM_PRIVATE_KEY=0x...your-private-key

Without a private key, the agent still generates forecasts—they just won't be submitted onchain.

Actions

Forecast

Trigger a forecast cycle that analyzes prediction markets and publishes onchain attestations on Arbitrum:

forecast sapience prediction markets

The agent will:

1. Fetch active prediction markets from Sapience
2. Analyze each market using the configured LLM
3. Generate probability estimates with confidence levels
4. Submit forecasts as EAS attestations on Arbitrum (if a private key is configured)

Trade

Execute trades on prediction markets on Ethereal based on the agent's analysis:

trade sapience prediction markets

The agent will:

1. Analyze markets for high-confidence trading opportunities
2. Identify predictions from different categories
3. Start an auction on the Sapience auction rail
4. Accept the best bid from market makers
5. Execute the trade on Ethereal

Note: Trading requires USDe tokens in your wallet on Ethereal (chain ID 5064014).

Autonomous Mode

Enable automatic forecast and trade cycles by setting the AUTONOMOUS_MODE environment variable:

# Enable autonomous forecasting
AUTONOMOUS_MODE=forecast
 
# Enable autonomous trading
AUTONOMOUS_MODE=trade
 
# Enable both
AUTONOMOUS_MODE=forecast,trade

See Deployment for instructions on deploying with autonomous mode enabled.

Customization

Forecast Settings

Forecasts are attested on Arbitrum chain (ID 42161).

Trading Settings

Trading executes on Ethereal chain (ID 5064014).

Customize the Agent Persona

Edit src/character.ts to customize your agent's personality and behavior:

export const character: Character = {
  name: "Your Agent Name",
  system: `Your custom system prompt...`,
  bio: [
    "Agent bio lines...",
  ],
  // ...
};

Key areas to customize:

• name: Your agent's display name
• system: The main system prompt that guides the agent's behavior
• bio and lore: Background information the agent uses for context
• style: Formatting and tone guidelines

Change the Model

Be sure to use a model with web search capability unless you've built a different workflow/pipeline to injest current information.

The default model is openai/gpt-4o-search-preview via OpenRouter. To change it, edit src/character.ts:

settings: {
  model: "anthropic/claude-3.5-sonnet",  // or any OpenRouter model
  temperature: 0.2,
  // ...
}

Or set via environment variable for quick testing.

Deployment

One-Click Deploy

Deploy to Railway in minutes:

After deploying:

1. Add your environment variables (OPENROUTER_API_KEY, EVM_PRIVATE_KEY)
2. Set AUTONOMOUS_MODE=forecast (or forecast,trade) to enable automatic operation
3. Your agent will begin running forecast cycles automatically

Eject to Your Own Repository

Once deployed on Railway, you can eject the code to your own GitHub repository for full customization.

• Your GitHub account must be connected to Railway
• Configure the Railway app in: Account Settings → Account → Account Integrations → Configure Railway App

1. In Railway, open your service → Source → Eject → Choose your GitHub org → Eject service

2. Clone your new repository locally:

git clone <your-new-repo-url> my-forecast-agent
cd my-forecast-agent
bun install  # or: pnpm install / npm install

3. Create your .env file:

# Required
OPENROUTER_API_KEY=your-openrouter-key
EVM_PRIVATE_KEY=your-private-key
 
# Optional: Enable autonomous mode
AUTONOMOUS_MODE=forecast,trade

4. Run locally:

bun run dev

5. Push changes to your repo. Enable Autodeploy in Railway so pushes trigger automatic redeployments.

Manual Deployment

For other platforms or manual deployment, see the Railway CLI guide or build the project directly:

bun run build
bun run start

The agent can run on any platform that supports Node.js and Bun.