DOCSEARCHbyAlgolia
Submit Docs

Meridian Documentation

repository·main·Indexed 20 days ago

https://github.com/yunus-0x/meridian

An autonomous liquidity management agent for Meteora DLMM pools on Solana. Meridian uses LLMs to screen pools, manage LP positions, and optimize yield and risk based on performance data. It includes a CLI for direct tool invocation, a Discord listener for token signals, and integration with Claude Code for enhanced agent interaction.

Tokens
9.4K
Snippets
27
Records
46
Agent score
71%

What's inside Meridian

  1. Overview of Meridian Architecture

    main

    Meridian is composed of several core modules that manage the lifecycle of an autonomous trading agent:

    • index.js: Main entry point (REPL, cron, Telegram bot).
    • agent.js: The ReAct loop (LLM $\rightarrow$ tool call $\rightarrow$ repeat).
    • config.js: Manages runtime configuration from user-config.json and .env.
    • state.js: Maintains the position registry (state.json).
    • lessons.js: The learning engine that records performance and evolves thresholds.
    • tools/: Contains the execution logic for dlmm, screening, wallet, token, and study.
    • telegram.js: Handles bot notifications and polling.
    • hivemind.js: Manages synchronization with the Agent Meridian network.

  2. Configure HiveMind sync

    main

    HiveMind allows agents to share lessons and strategy presets via Agent Meridian. By default, it uses https://api.agentmeridian.xyz.

    Configuration Fields:

    • agentId: Automatically generated if missing.
    • hiveMindUrl: The API endpoint (defaults to Agent Meridian).
    • hiveMindApiKey: Use a private key if required (set via config).
    • hiveMindPullMode: Set to auto (default) to pull lessons automatically, or manual to disable automatic pulling.

    Privacy Note: Private keys and wallet balances are never sent to HiveMind. Only lessons, performance events, and heartbeat metadata are shared.

  3. Use Claude Code for enhanced agent interaction

    main

    It is recommended to use Claude Code from within the meridian directory. Claude Code utilizes built-in agents and slash commands that interface with the meridian CLI.

    Slash Commands

    CommandWhat it does
    /screenFull AI screening cycle: checks Discord queue, reads config, fetches candidates, runs research, and deploys if a winner is found
    /manageFull AI management cycle: checks positions, evaluates PnL, claims fees, and closes OOR/losing positions
    /balanceCheck wallet SOL and token balances
    /positionsList all open DLMM positions with range status
    /candidatesFetch and enrich top pool candidates (metrics + audit + smart money)
    /study-poolStudy top LPers on a specific pool
    /pool-ohlcvFetch price/volume history for a pool
    /pool-compareCompare Meteora DLMM pools for a token pair by APR, fee/TVL ratio, and volume

    Claude Code Agents

    • screener: Specialist for pool screening, candidate evaluation, and token risk analysis. Accesses Jupiter token audits and smart-wallet checks.
    • manager: Specialist for position management, PnL assessment, and fee claiming.

    You can trigger these agents by describing your intent, e.g., > review all my positions and close anything out of range.

    Loop Mode

    You can run screening or management on a timer inside Claude Code:

    /loop 30m /screen     # screen every 30 minutes
/loop 10m /manage     # manage every 10 minutes
    cd meridian
claude

  4. Install and Setup Meridian

    main

    To install Meridian, clone the repository, navigate to the directory, and install dependencies using npm. After installation, run the setup wizard to configure your environment variables and user configuration files.

    git clone https://github.com/yunus-0x/meridian
cd meridian
npm install
npm run setup

  5. Configure Telegram notifications and commands

    main

    Meridian uses Telegram for automated reports (management/screening cycles, OOR alerts, deployments, and closes) and interactive commands.

    Setup

    1. Create a bot via @BotFather and copy the token.
    2. Add the following to your .env:
      • TELEGRAM_BOT_TOKEN: Your bot token.
      • TELEGRAM_CHAT_ID: Your chat ID (must be set explicitly for safety).
      • TELEGRAM_ALLOWED_USER_IDS: Required for group/supergroup control to restrict commands.

    Note: 401 Unauthorized errors indicate an invalid TELEGRAM_BOT_TOKEN.

    Telegram Commands

    CommandAction
    /positionsList open positions with a progress bar
    /close <n>Close position by list index
    /set <n> <note>Set a note on a position

    You can also use free-form chat via Telegram, similar to the REPL interface.

    TELEGRAM_BOT_TOKEN=<token>
TELEGRAM_CHAT_ID=<your chat id>
TELEGRAM_ALLOWED_USER_IDS=<user id>

  6. Use a local LLM with LM Studio

    main

    To use a local OpenAI-compatible endpoint (like LM Studio), set the following environment variables:

    LLM_BASE_URL=http://localhost:1234/v1
LLM_API_KEY=lm-studio
LLM_MODEL=your-local-model-name

  7. Run the Autonomous Agent via npm start

    main

    To start the full autonomous agent, which includes cron-based screening and management cycles along with an interactive REPL, use the following command. The REPL provides a live countdown to the next scheduled cycle in the prompt format: [manage: Xm Ys | screen: Am Bs] >.

    REPL Commands

    CommandDescription
    /statusWallet balance and open positions
    /candidatesRe-screen and display top pool candidates
    /learnStudy top LPers across all current candidate pools
    /learn <pool_address>Study top LPers for a specific pool
    /thresholdsCurrent screening thresholds and performance stats
    /evolveTrigger threshold evolution from performance data (requires 5+ closed positions)
    /stopGraceful shutdown
    <anything>Free-form chat to ask the agent questions, request actions, or analyze pools
    npm start

  8. Run Meridian in Development or Live Mode

    main

    Use npm run dev to run a dry run where no on-chain transactions are executed. Use npm start to enter live trading mode. On startup, the agent fetches wallet balances, open positions, and pool candidates to begin autonomous cycles.

    npm run dev    # dry run — no on-chain transactions
npm start      # live mode

  9. Deploy Meridian with PM2 for 24/7 Operation

    main

    For VPS or always-on operation, use PM2. It is critical to use the provided ecosystem file rather than starting index.js directly to ensure the working directory is correctly pinned.

    Initial Setup:

    npm install
npm run pm2:start
pm2 save

    Maintenance:

    • Restart after config changes: npm run pm2:restart
    • View logs: npm run pm2:logs
    • Update after git pull: git pull && npm install && npm run pm2:restart && pm2 save

    Resetting a broken PM2 installation: If the process was started incorrectly (e.g., via pm2 start index.js), reset it:

    pm2 delete meridian
npm run pm2:start
pm2 save
    npm run pm2:start

  10. Configure Meridian via the Setup Wizard

    main
    Running npm run setup launches a wizard that populates two files at the repository root: .env for sensitive credentials and user-config.json for strategy and risk parameters. The wizard takes approximately 2 minutes to complete.
    npm run setup

  11. Encrypt Environment Variables

    main

    Meridian supports an encrypted .env flow. You can encrypt your .env file using envrypt. The agent will automatically load encrypted values if an .envrypt file is present.

    cp .env .env.raw
printf "replace-with-a-long-local-key\n" > .envrypt
npm run env:encrypt

  12. Setup and run the Discord listener

    main

    The Discord listener monitors configured channels for Solana token calls and queues them as signals for the screener agent. Signals are written to discord-signals.json.

    Installation

    cd discord-listener
npm install

    Configuration

    Add the following to your root .env file:

    • DISCORD_USER_TOKEN: Your Discord account token (obtained via browser DevTools).
    • DISCORD_GUILD_ID: The ID of the server to monitor.
    • DISCORD_CHANNEL_IDS: Comma-separated list of channel IDs.
    • DISCORD_MIN_FEES_SOL: Minimum pool fees required to pass the pre-check.

    Note: This uses a selfbot (personal account automation). Use responsibly.

    Running

    cd discord-listener
npm start

    Signal Pipeline

    Incoming token addresses undergo these checks:

    1. Dedup: Ignores addresses seen in the last 10 minutes.
    2. Blacklist: Rejects blacklisted token mints.
    3. Pool resolution: Resolves address to a Meteora DLMM pool.
    4. Rug check: Checks deployer against deployer-blacklist.json.
    5. Fees check: Rejects pools below DISCORD_MIN_FEES_SOL.

    Passing signals are queued as pending and prioritized by the screener.

    DISCORD_USER_TOKEN=your_discord_account_token
DISCORD_GUILD_ID=the_server_id
DISCORD_CHANNEL_IDS=channel1,channel2
DISCORD_MIN_FEES_SOL=5