Meridian

https://github.com/yunus-0x/meridian
Admin
Meridian is an autonomous liquidity management agent for Meteora DLMM pools on Solana that screens...
Tokens:16,910
Snippets:153
Trust Score:5.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install and Run Setup Wizard

Source: https://context7.com/yunus-0x/meridian/llms.txt

Clone the repository, install dependencies, and run the interactive setup wizard to generate configuration files.

```bash
git clone https://github.com/yunus-0x/meridian
cd meridian
npm install
npm run setup        # interactive wizard: wallet, RPC, API keys, risk preset
```

--------------------------------

### Install and Start with PM2

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Install dependencies and start the Meridian application using PM2. Ensure you are in the correct directory before running these commands.

```bash
npm install
npm run pm2:start
pm2 save
```

--------------------------------

### Discord Listener Setup

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Install dependencies and configure environment variables for the Discord listener. Ensure you use a personal account token responsibly.

```bash
cd discord-listener
npm install
```

```env
DISCORD_USER_TOKEN=your_discord_account_token   # from browser DevTools → Network
DISCORD_GUILD_ID=the_server_id
DISCORD_CHANNEL_IDS=channel1,channel2            # comma-separated
DISCORD_MIN_FEES_SOL=5                           # minimum pool fees to pass pre-check
```

--------------------------------

### Run Setup Wizard

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Execute the setup wizard to configure environment variables and user settings. This process creates the .env and user-config.json files.

```bash
npm run setup
```

--------------------------------

### Install Dependencies

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Clone the repository and install Node.js dependencies using npm.

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

--------------------------------

### Install and Run Meridian CLI

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Install the Meridian CLI globally using npm or run it directly using Node.js. This provides access to all Meridian tools for scripting and automation.

```bash
npm install -g .
meridian <command> [flags]
```

```bash
node cli.js <command> [flags]
```

--------------------------------

### Copy User Configuration

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Copy the example user configuration file to create your own user-config.json. This file stores risk presets, deploy sizes, and thresholds.

```bash
cp user-config.example.json user-config.json
```

--------------------------------

### Encrypted .env Setup

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Optional: Encrypt your .env file for added security. This involves creating a local encryption key and running the encryption script.

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

--------------------------------

### Run Meridian (Live Mode)

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Start Meridian in live mode to begin autonomous liquidity management and on-chain transactions. Ensure all configurations are correct before running.

```bash
npm start
```

--------------------------------

### Setup and Run Discord Listener

Source: https://context7.com/yunus-0x/meridian/llms.txt

Sets up and runs a Discord listener to capture Solana token signals from configured guild channels. Requires environment variables for authentication and channel configuration.

```bash
# Setup
cd discord-listener && npm install

# Add to root .env:
# DISCORD_USER_TOKEN=your_account_token   # from browser DevTools → Network
# DISCORD_GUILD_ID=the_server_id
# DISCORD_CHANNEL_IDS=channel1,channel2   # comma-separated
# DISCORD_MIN_FEES_SOL=5

cd discord-listener && npm start
# Listens in background. Signals appear in discord-signals.json.
# Screener picks them up automatically on next /screen or meridian screen.
```

--------------------------------

### PM2 Deployment

Source: https://context7.com/yunus-0x/meridian/llms.txt

Use PM2 for recommended deployment on a VPS. Commands are provided for starting, saving the process list, updating, and viewing logs.

```bash
npm run pm2:start
pm2 save
# Update:
git pull && npm install && npm run pm2:restart
# Debug crashes:
npm run pm2:logs
```

--------------------------------

### Run Autonomous Agent

Source: https://context7.com/yunus-0x/meridian/llms.txt

Start the agent in autonomous mode for full cron loop operation. Use 'npm run dev' for dry runs (no transactions) or 'npm start' for live trading.

```bash
npm run dev    # DRY_RUN=true — no on-chain transactions
npm start      # live mode
```

--------------------------------

### Run Discord Listener

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Start the Discord listener service. It can be run in a separate terminal and integrates with the main agent for signal processing.

```bash
cd discord-listener
npm start
```

--------------------------------

### Start Autonomous Agent

Source: https://context7.com/yunus-0x/meridian/llms.txt

Initiates the full autonomous trading agent. Supports dry runs to simulate the agent's actions without executing them.

```bash
meridian start --dry-run
```

--------------------------------

### Get Runtime Configuration

Source: https://context7.com/yunus-0x/meridian/llms.txt

Retrieves the complete current runtime configuration of the Meridian CLI.

```bash
meridian config get
```

--------------------------------

### Meridian CLI: Agent Cycle Commands

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Commands to run AI-powered screening and management cycles, or to start the autonomous agent.

```bash
meridian screen [--dry-run] [--silent]   # one AI screening cycle
```

```bash
meridian manage [--dry-run] [--silent]   # one AI management cycle
```

```bash
meridian start [--dry-run]               # start autonomous agent with cron jobs
```

--------------------------------

### Meridian CLI: Config Commands

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Commands to get or set configuration values for Meridian.

```bash
meridian config get
```

```bash
meridian config set <key> <value>
```

--------------------------------

### Run Meridian (Dry Run)

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Start Meridian in dry run mode to test configurations and observe agent behavior without executing on-chain transactions.

```bash
npm run dev
```

--------------------------------

### Get Pool Deployment History

Source: https://context7.com/yunus-0x/meridian/llms.txt

Retrieves the deployment history and performance notes for a specific pool. Requires the pool's address.

```bash
meridian pool-memory --pool AbCd...poolAddress
```

--------------------------------

### Get Token Narrative

Source: https://context7.com/yunus-0x/meridian/llms.txt

Retrieves the origin story and catalyst information for a specific token. Requires the token's mint address.

```bash
meridian token-narrative --mint DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
```

--------------------------------

### Update Existing PM2 Install

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Update the Meridian application by pulling the latest changes, installing new dependencies, and restarting the PM2 process. This is crucial after code updates to ensure the running application reflects the latest version.

```bash
git pull
npm install
npm run pm2:restart
```

--------------------------------

### HiveMind Shared Lessons Example

Source: https://context7.com/yunus-0x/meridian/llms.txt

Illustrates how shared lessons from the HiveMind network appear within the AI's response when using getLessonsForPrompt().

```javascript
// HiveMind sync is automatic — no manual calls needed.
// Shared lessons appear in the HIVEMIND section of getLessonsForPrompt():
// ── HIVEMIND ──
// [GOOD] [2025-01-15 07:30] WORKED: high-vol SOL pairs with bid_ask, bin_step=100 → avg PnL +3.1%
// [BAD]  [2025-01-14 15:00] FAILED: pump.fun tokens < 2h old — 8/10 positions lost money
```

--------------------------------

### Get Detailed Pool Metrics

Source: https://context7.com/yunus-0x/meridian/llms.txt

Fetches detailed metrics for a specific liquidity pool. Requires the pool's address and optionally a timeframe. Useful for in-depth analysis.

```bash
meridian pool-detail --pool AbCd...poolAddress --timeframe 5m
```

--------------------------------

### Get Top Pre-scored Pool Candidates

Source: https://context7.com/yunus-0x/meridian/llms.txt

Lists top pre-scored DeFi pool candidates based on various metrics like token audit, smart wallets, and narrative. Use `--limit` to control the number of results.

```bash
meridian candidates --limit 5
```

--------------------------------

### Get Active Pool Bin and Price

Source: https://context7.com/yunus-0x/meridian/llms.txt

Retrieves the current active bin ID and price for a given liquidity pool. Requires the pool's address.

```bash
meridian active-bin --pool AbCd...poolAddress
```

--------------------------------

### CLI (`meridian`) — Direct Tool Invocation

Source: https://context7.com/yunus-0x/meridian/llms.txt

The `meridian` CLI provides direct access to all tools as subcommands, outputting results in JSON format. It can be installed globally or run directly using `node cli.js`.

```APIDOC
## CLI (`meridian`) — Direct Tool Invocation

The `meridian` CLI exposes every tool as a subcommand with JSON output. Install globally once with `npm install -g .`, or run directly with `node cli.js`.
```

--------------------------------

### List Open DLMM Positions

Source: https://context7.com/yunus-0x/meridian/llms.txt

Displays all currently open DLMM (Dynamic Liquidity Market Maker) positions. Shows details like pool, pair, range status, age, and PnL. No setup required.

```bash
meridian positions
```

--------------------------------

### Get Token Information

Source: https://context7.com/yunus-0x/meridian/llms.txt

Retrieves comprehensive information about a token, including market cap, audit status, and price statistics. Supports querying by symbol or mint address.

```bash
meridian token-info --query BONK
```

```bash
meridian token-info --query DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
```

--------------------------------

### Get Token Holder Distribution

Source: https://context7.com/yunus-0x/meridian/llms.txt

Displays the holder distribution for a given token mint address, including percentage ownership and bundled transactions. Use `--mint` for the token address and `--limit` for the number of holders to display.

```bash
meridian token-holders --mint DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 --limit 20
```

--------------------------------

### Meridian Configuration System

Source: https://github.com/yunus-0x/meridian/blob/main/CLAUDE.md

Explains how the configuration system works, including loading from `user-config.json`, runtime mutations via the `update_config` tool, and persistence. Lists valid configuration keys and their default values.

```text
Valid config keys and their sections:

| Key | Section | Default |
|---|---|---|
| minFeeActiveTvlRatio | screening | 0.05 |
| minTvl / maxTvl | screening | 10k / 150k |
| minVolume | screening | 500 |
| minOrganic | screening | 60 |
| minHolders | screening | 500 |
| minMcap / maxMcap | screening | 150k / 10M |
| minBinStep / maxBinStep | screening | 80 / 125 |
| timeframe | screening | "5m" |
| category | screening | "trending" |
| minTokenFeesSol | screening | 30 |
| maxBundlersPct | screening | 30 |
| maxTop10Pct | screening | 60 |
| blockedLaunchpads | screening | [] |
| deployAmountSol | management | 0.5 |
| maxDeployAmount | risk | 50 |
| maxPositions | risk | 3 |
| gasReserve | management | 0.2 |
| positionSizePct | management | 0.35 |
| minSolToOpen | management | 0.55 |
| outOfRangeWaitMinutes | management | 30 |
| managementIntervalMin | schedule | 10 |
| screeningIntervalMin | schedule | 30 |
| managementModel / screeningModel / generalModel | llm | openrouter/healer-alpha |

**`computeDeployAmount(walletSol)`** — scales position size with wallet balance (compounding). Formula: `clamp(deployable × positionSizePct, floor=deployAmountSol, ceil=maxDeployAmount)`.
```

--------------------------------

### Manual .env Configuration

Source: https://context7.com/yunus-0x/meridian/llms.txt

Configure essential parameters like wallet keys, RPC URLs, and API keys directly in the .env file. Set DRY_RUN to true for testing without live transactions.

```env
WALLET_PRIVATE_KEY=your_base58_private_key
RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
OPENROUTER_API_KEY=sk-or-...
HELIUS_API_KEY=your_helius_key
TELEGRAM_BOT_TOKEN=123456:ABC...
TELEGRAM_CHAT_ID=your_chat_id
TELEGRAM_ALLOWED_USER_IDS=123456789
DRY_RUN=true                            # set false for live trading
```

--------------------------------

### Manual .env Configuration

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Manually create and configure the .env file with your API keys, wallet, and RPC endpoint. Ensure sensitive information like private keys is kept secure.

```env
WALLET_PRIVATE_KEY=your_base58_private_key
RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
OPENROUTER_API_KEY=sk-or-...
HELIUS_API_KEY=your_helius_key          # for wallet balance lookups
TELEGRAM_BOT_TOKEN=123456:ABC...        # optional — for notifications + chat
TELEGRAM_CHAT_ID=
DRY_RUN=true                            # set false for live trading
```

--------------------------------

### Meridian CLI: Deploy and Manage Commands

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Commands for deploying new positions, claiming rewards, closing positions, and managing liquidity.

```bash
meridian deploy --pool <addr> --amount <sol> [--bins-below 69] [--bins-above 0] [--strategy bid_ask|spot|curve] [--dry-run]
```

```bash
meridian claim --position <addr>
```

```bash
meridian close --position <addr> [--skip-swap] [--dry-run]
```

```bash
meridian swap --from <mint> --to <mint> --amount <n> [--dry-run]
```

```bash
meridian add-liquidity --position <addr> --pool <addr> [--amount-x <n>] [--amount-y <n>] [--strategy spot]
```

```bash
meridian withdraw-liquidity --position <addr> --pool <addr> [--bps 10000]
```

--------------------------------

### Add and Retrieve Lessons for Prompt

Source: https://context7.com/yunus-0x/meridian/llms.txt

Manage agent's persistent memory (lessons) by adding, pinning, and retrieving them for system prompts. Requires importing lesson management functions.

```javascript
import { addLesson, getLessonsForPrompt, pinLesson, listLessons } from "./lessons.js";

// Add a manual lesson targeting only the screener
addLesson(
  "PREFER: pools where top LPers hold < 30 min — scalper pools earn fees faster",
  ["scalping", "screening"],
  { pinned: false, role: "SCREENER" }
);

// Add a critical rule that's always injected regardless of cap
addLesson(
  "AVOID: closing when OOR < 30min — price often recovers within the window",
  ["oor", "management"],
  { pinned: true, role: "MANAGER" }
);

// Get formatted prompt injection for a SCREENER cycle
const block = getLessonsForPrompt({ agentType: "SCREENER", maxLessons: 20 });
console.log(block);
// ── PINNED (1) ──
// 📌 [MANUAL] [2025-01-15 09:00] AVOID: closing when OOR < 30min...
//
// ── SCREENER (3) ──
// [GOOD] [2025-01-14 22:10] PREFER: BONK-SOL-type pools (volatility=3.2...) → PnL +4.3%
// [MANUAL] [2025-01-13 18:00] PREFER: pools where top LPers hold < 30 min
// ...
//
// ── HIVEMIND ──
// [GOOD] [2025-01-15 07:30] WORKED: high-vol SOL pairs with bid_ask, bin_step 100 → avg +3.1%

// List lessons with filters
const pinned = listLessons({ pinned: true, role: "MANAGER" });
// → { total: 2, lessons: [{id, rule, tags, outcome, pinned: true, role: "MANAGER", created_at}] }

// Pin an existing lesson by ID
pinLesson(1736942400000); // ID is a timestamp
```

--------------------------------

### Compute Deploy Amount for Dynamic Position Sizing

Source: https://context7.com/yunus-0x/meridian/llms.txt

Scales position size with wallet balance for compounding growth. Uses configurable parameters for gas reserve, position size percentage, and deployment amount limits.

```javascript
import { computeDeployAmount } from "./config.js";

// With defaults: gasReserve=0.2, positionSizePct=0.35, floor=0.5, ceil=50
console.log(computeDeployAmount(0.8));   // → 0.5  (floor: 0.6 * 0.35 = 0.21 → clamp up)
console.log(computeDeployAmount(2.0));   // → 0.63 (1.8 * 0.35 = 0.63)
console.log(computeDeployAmount(3.0));   // → 0.98 (2.8 * 0.35 = 0.98)
console.log(computeDeployAmount(4.0));   // → 1.33 (3.8 * 0.35 = 1.33)
console.log(computeDeployAmount(150.0)); // → 50.0 (ceil)

// Custom config example:
// positionSizePct=0.5, deployAmountSol=1.0, maxDeployAmount=20, gasReserve=0.3
// computeDeployAmount(5.0) → clamp((5.0 - 0.3) * 0.5, 1.0, 20) = clamp(2.35, 1.0, 20) = 2.35
```

--------------------------------

### List Learned Lessons

Source: https://context7.com/yunus-0x/meridian/llms.txt

Displays a list of learned trading lessons, with options to limit the results. Useful for reviewing past trading insights.

```bash
meridian lessons --limit 50
```

--------------------------------

### Add a Manual Lesson to Meridian

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Shows how to manually add a lesson to the agent's learning base. Lessons are concrete pieces of advice derived from past performance that influence future decisions.

```bash
node cli.js lessons add "Never deploy into pump.fun tokens under 2h old"
```

--------------------------------

### Get Position PnL

Source: https://context7.com/yunus-0x/meridian/llms.txt

Fetches the Profit and Loss (PnL) details for a specific DLMM position. Requires the position's address. Useful for performance tracking.

```bash
meridian pnl 5xTrABC...positionAddress
```

--------------------------------

### Meridian CLI: Learning and Memory Commands

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Commands related to managing lessons, performance tracking, and pool memory.

```bash
meridian lessons
```

```bash
meridian lessons add "your lesson text"
```

```bash
meridian performance [--limit 200]
```

```bash
meridian evolve
```

```bash
meridian pool-memory --pool <addr>
```

--------------------------------

### REPL Commands

Source: https://context7.com/yunus-0x/meridian/llms.txt

Interact with the running agent using REPL commands. Available commands include checking status, screening candidates, learning from LPs, and graceful shutdown.

```bash
# REPL commands:
# /status           — wallet balance + open positions
# /candidates       — re-screen top pool candidates
# /learn            — study top LPers across all candidate pools
# /thresholds       — current screening thresholds
# /evolve           — trigger threshold evolution (needs 5+ closed positions)
# /stop             — graceful shutdown
# <anything else>   — free-form chat with the agent
```

--------------------------------

### Deploy a Liquidity Position

Source: https://context7.com/yunus-0x/meridian/llms.txt

Deploys a new liquidity position into a specified pool. Includes safety checks and supports dry runs. Requires pool address, amount, and bin ranges.

```bash
meridian deploy --pool AbCd...poolAddress --amount 0.63 \
  --bins-below 55 --bins-above 0 --strategy bid_ask --dry-run
```

--------------------------------

### View Performance Statistics

Source: https://context7.com/yunus-0x/meridian/llms.txt

Shows performance statistics for closed positions, including PnL, win rate, and total lessons. Use `--limit` to control the number of historical positions displayed.

```bash
meridian performance --limit 200
```

--------------------------------

### Search Pools by Token

Source: https://context7.com/yunus-0x/meridian/llms.txt

Searches for liquidity pools based on a token name or contract address. Use `--query` for the search term and `--limit` for the number of results.

```bash
meridian search-pools --query BONK --limit 10
```

--------------------------------

### Study Top Liquidity Providers on a Pool

Source: https://context7.com/yunus-0x/meridian/llms.txt

Analyzes and displays information about the top liquidity providers (LPs) on a specific pool. Use `--pool` for the pool address and `--limit` for the number of LPs to study.

```bash
meridian study --pool AbCd...poolAddress --limit 4
```

--------------------------------

### Meridian Architecture Overview

Source: https://github.com/yunus-0x/meridian/blob/main/CLAUDE.md

Provides a high-level overview of the Meridian project's file structure and the primary function of each component.

```text
index.js            Main entry: REPL + cron orchestration + Telegram bot polling
agent.js            ReAct loop (OpenRouter/OpenAI-compatible): LLM → tool call → repeat
config.js           Runtime config from user-config.json + .env; exposes config object
prompt.js           Builds system prompt per agent role (SCREENER / MANAGER / GENERAL)
state.js            Position registry (state.json): tracks bin ranges, OOR timestamps, notes
lessons.js          Learning engine: records closed-position perf, derives lessons, evolves thresholds
pool-memory.js      Per-pool deploy history + snapshots (pool-memory.json)
strategy-library.js Saved LP strategies (strategy-library.json)
briefing.js         Daily Telegram briefing (HTML)
telegram.js         Telegram bot: polling, notifications (deploy/close/swap/OOR)
hivemind.js         Agent Meridian HiveMind sync
smart-wallets.js    KOL/alpha wallet tracker (smart-wallets.json)
token-blacklist.js  Permanent token blacklist (token-blacklist.json)
logger.js           Daily-rotating log files + action audit trail

tools/
  definitions.js    Tool schemas in OpenAI format (what LLM sees)
  executor.js       Tool dispatch: name → fn, safety checks, pre/post hooks
  dlmm.js           Meteora DLMM SDK wrapper (deploy, close, claim, positions, PnL)
  screening.js      Pool discovery from Meteora API
  wallet.js         SOL/token balances (Helius) + Jupiter swap
  token.js          Token info/holders/narrative (Jupiter API)
  study.js          Top LPer study via LPAgent API
```

--------------------------------

### Deployer Blacklist Configuration

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Configure the `deployer-blacklist.json` file to automatically reject pools from known rug or farm deployers.

```json
{
  "_note": "Known farm/rug deployers — add addresses to auto-reject their pools",
  "addresses": [
    "WaLLeTaDDressHere"
  ]
}
```

--------------------------------

### Record Performance and Evolve Thresholds

Source: https://context7.com/yunus-0x/meridian/llms.txt

Record performance metrics after closing a position and automatically evolve screening thresholds. Requires importing functions and configuration.

```javascript
import { recordPerformance, evolveThresholds, getPerformanceHistory } from "./lessons.js";
import { config } from "./config.js";

// Called internally by executor.js after close_position succeeds
await recordPerformance({
  position:          "PosAddr...",
  pool:              "AbCd...poolAddress",
  pool_name:         "BONK-SOL",
  base_mint:         "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  strategy:          "bid_ask",
  bin_step:          100,
  volatility:        3.2,
  fee_tvl_ratio:     0.18,
  organic_score:     84,
  amount_sol:        0.63,
  fees_earned_usd:   3.20,
  fees_earned_sol:   0.021,
  final_value_usd:   97.04,
  initial_value_usd: 94.50,
  minutes_in_range:  112,
  minutes_held:      135,
  close_reason:      "trailing take-profit triggered at +4.3%",
  deployed_at:       "2025-01-15T10:00:00Z",
});
// Saves performance entry + auto-derives lesson:
// "[GOOD] [2025-01-15 10:00] PREFER: BONK-SOL-type pools (volatility=3.2, bin_step=100)
//  with strategy=\"bid_ask\" — 82.9% in-range efficiency, PnL +4.3%."

// Manually trigger threshold evolution after 5+ positions
const data = JSON.parse(fs.readFileSync("./lessons.json", "utf8"));
const result = evolveThresholds(data.performance, config);
if (result?.changes) {
  console.log(result.changes);
  // → { minOrganic: 65, minFeeActiveTvlRatio: 0.07 }
  console.log(result.rationale);
  // → { minOrganic: "Winner avg organic 79 vs loser avg 62 — raised from 60 → 65",
  //     minFeeActiveTvlRatio: "Lowest winner fee_tvl=0.085 — raised floor from 0.05 → 0.07" }
}

// Query performance history
const history = getPerformanceHistory({ hours: 168, limit: 50 }); // last 7 days
console.log(history);
// → { hours: 168, count: 12, total_pnl_usd: 14.82, win_rate_pct: 67,
//     positions: [{pool_name, pnl_usd, pnl_pct, fees_earned_usd,
//                  range_efficiency, minutes_held, close_reason, closed_at}] }
```

--------------------------------

### Meridian CLI: Screening Commands

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Utilize these commands for screening potential trading opportunities, including candidate pools and active bins.

```bash
meridian candidates --limit 5
```

```bash
meridian pool-detail --pool <addr> [--timeframe 5m]
```

```bash
meridian active-bin --pool <addr>
```

```bash
meridian search-pools --query <name_or_symbol>
```

```bash
meridian study --pool <addr> [--limit 4]
```

--------------------------------

### Run Core ReAct Agent Loop (`agentLoop`)

Source: https://context7.com/yunus-0x/meridian/llms.txt

Use `agentLoop` to power autonomous cycles or interactive chats. It dynamically builds prompts, filters tools by role, and iterates LLM calls with tool execution. Destructive tools are limited to one execution per session.

```javascript
import { agentLoop } from "./agent.js";

// Single screening cycle — runs as SCREENER role with role-filtered tools
const result = await agentLoop(
  "Screen for new pool opportunities and deploy if you find a strong candidate.",
  20,           // maxSteps
  [],           // sessionHistory (prior messages for multi-turn)
  "SCREENER",   // agentType: SCREENER | MANAGER | GENERAL
  null,         // model override (null = use config.llm.screeningModel)
  null,         // maxOutputTokens override
  {
    interactive: false,
    onToolStart: ({ name, args, step }) => console.log(`[step ${step}] → ${name}`, args),
    onToolFinish: ({ name, result, success }) => console.log(`← ${name}`, success ? "OK" : "FAIL"),
  }
);

console.log(result.content);
// → "Deployed 0.63 SOL into BONK-SOL pool (bid_ask, 55 bins below).
//    Volatility 3.2, fee/TVL 0.18, organic 84."

// Management cycle — MANAGER role only gets close/claim/pnl tools
const mgmtResult = await agentLoop(
  "Review all open positions. Close anything out of range for over 30 minutes.",
  20,
  [],
  "MANAGER"
);

// Free-form GENERAL chat — intent-matched tool subset
const chatResult = await agentLoop(
  "Why did you close the BONK position yesterday?",
  10,
  [],
  "GENERAL"
);
// Uses get_recent_decisions tool automatically

```

--------------------------------

### Run AI Screening Cycle

Source: https://context7.com/yunus-0x/meridian/llms.txt

Executes a single AI-driven screening cycle for potential trading opportunities. Supports dry runs to preview actions.

```bash
meridian screen --dry-run
```

--------------------------------

### Add Manual Lesson

Source: https://context7.com/yunus-0x/meridian/llms.txt

Adds a new manual lesson to the system. This allows users to record specific trading rules or observations.

```bash
meridian lessons add "Never deploy into pump.fun tokens under 2h old"
```

--------------------------------

### Meridian CLI: Positions and PnL Commands

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Commands for retrieving and analyzing current positions and their Profit and Loss (PnL).

```bash
meridian positions
```

```bash
meridian pnl <position_address>
```

```bash
meridian wallet-positions --wallet <addr>
```

--------------------------------

### Navigate to Meridian Directory and Launch Claude

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Change the current directory to 'meridian' and then launch the Claude Code terminal. This is the recommended way to interact with Meridian's advanced features.

```bash
cd meridian
claude
```

--------------------------------

### Local Model Configuration (LM Studio)

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Environment variables for configuring a local language model using an OpenAI-compatible endpoint. Ensure LLM_MODEL is set to your specific model name.

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

--------------------------------

### Execute Tools with Safety Checks (`executeTool`)

Source: https://context7.com/yunus-0x/meridian/llms.txt

Use `executeTool` as the secure interface between the LLM and tool implementations. It performs pre-execution safety checks for write operations, logs actions, sends notifications, and handles post-execution tasks like token swapping.

```javascript
import { executeTool } from "./tools/executor.js";

// Deploy a position — all safety checks run automatically:
// bin_step range, TVL, fee/TVL ratio, volatility > 0, position count,
// no duplicate pool/token, SOL balance check
const deploy = await executeTool("deploy_position", {
  pool_address: "AbCdEf...poolAddress",
  amount_y: 0.63,         // SOL to deposit (single-sided)
  amount_x: 0,            // always 0 for single-sided SOL deploys
  strategy: "bid_ask",
  bins_below: 55,
  bins_above: 0,
  pool_name: "BONK-SOL",
  base_mint: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  bin_step: 100,
  volatility: 3.2,
  fee_tvl_ratio: 0.18,
  organic_score: 84,
  initial_value_usd: 95.0,
});
// → { success: true, position: "Pos1...", pool_name: "BONK-SOL",
//     txs: ["5xTr..."], price_range: { lower: 0.0000210, upper: 0.0000245 },
//     bin_step: 100, base_fee: 1.0 }

// Blocked — safety check fires before on-chain execution:
const blocked = await executeTool("deploy_position", {
  pool_address: "AbCdEf...",
  amount_y: 0.63,
  bins_below: 10,   // below MIN_SAFE_BINS_BELOW (35) → blocked
  bins_above: 0,
  volatility: 2.1,
});
// → { blocked: true, reason: "deploy range 10 total bins is below minimum 35." }

// Close position — auto-swaps base token to SOL after close
const close = await executeTool("close_position", {
  position_address: "PosAddr...",
  reason: "OOR > 30 minutes",
  skip_swap: false,   // true = keep base token after close
});
// → { success: true, pnl_usd: 4.12, pnl_pct: 4.3, txs: [...],
//     base_mint: "DezXAZ...", auto_swapped: true, sol_received: 0.027 }

// Claim fees
const claim = await executeTool("claim_fees", {
  position_address: "PosAddr...",
});
// → { success: true, position: "PosAddr...", txs: ["7yUi..."], base_mint: "DezX..." }

// Swap via Jupiter
const swap = await executeTool("swap_token", {
  input_mint: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",  // BONK
  output_mint: "So11111111111111111111111111111111111111112",     // SOL
  amount: 1500000,
});
// → { success: true, tx: "9kLm...", amount_in: 1500000, amount_out: 0.031 }

// Update config at runtime — persists to user-config.json, restarts cron if intervals change
const cfg = await executeTool("update_config", {
  changes: { stopLossPct: -20, outOfRangeWaitMinutes: 45, screeningModel: "anthropic/claude-opus-4-5" },
  reason: "Tightening stop loss after volatile session",
});
// → { success: true, applied: { stopLossPct: -20, outOfRangeWaitMinutes: 45, ... }, unknown: [] }

```

--------------------------------

### Meridian CLI: Blacklist Commands

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Commands for managing the blacklist of token mint addresses.

```bash
meridian blacklist list
```

```bash
meridian blacklist add --mint <addr> --reason "reason"
```

--------------------------------

### Discord Signal Pre-check Configuration

Source: https://context7.com/yunus-0x/meridian/llms.txt

Defines token addresses to be blacklisted, preventing their pools from being processed. Also shows CLI commands for checking and clearing signal queues.

```json
// deployer-blacklist.json — add known rug deployers:
{
  "_note": "Known farm/rug deployers — add addresses to auto-reject their pools",
  "addresses": [
    "KnownRugWalletAddress1...",
    "KnownRugWalletAddress2..."
  ]
}
```

```bash
// Check signal queue via CLI:
// meridian discord-signals
// → { count: 3, pending: 1, processed: 2,
//     signals: [{id, symbol, pool, author, channel, queued_at, rug_score, status, snippet}]}

// Clear processed signals:
// meridian discord-signals clear
```

--------------------------------

### Inspect PM2 Logs for Errors

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

View logs for PM2-managed processes to diagnose startup errors or repeated restarts. This is essential for troubleshooting issues after updates or configuration changes.

```bash
npm run pm2:logs
```

--------------------------------

### Override LLM Model at Runtime

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Demonstrates how to override the default LLM model for screening cycles at runtime. This is useful for testing different models or adapting to specific needs.

```bash
node cli.js config set screeningModel anthropic/claude-opus-4-5
```

--------------------------------

### Swap Tokens via Jupiter

Source: https://context7.com/yunus-0x/meridian/llms.txt

Executes a token swap using the Jupiter aggregator. Supports dry runs. Requires token mints, amount, and target token.

```bash
meridian swap --from DezXAZ...BONKmint --to SOL --amount 1500000 --dry-run
```

--------------------------------

### Meridian CLI: Token Research Commands

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Commands for researching token information, including general info, holder counts, and narratives.

```bash
meridian token-info --query <mint_or_symbol>
```

```bash
meridian token-holders --mint <addr> [--limit 20]
```

```bash
meridian token-narrative --mint <addr>
```

--------------------------------

### Meridian CLI Commands

Source: https://context7.com/yunus-0x/meridian/llms.txt

Commands for managing token blacklists and Discord signals.

```bash
meridian blacklist add --mint DezX...mint --reason "coordinated wash trading"
```

```bash
meridian blacklist list
```

```bash
meridian discord-signals
```

```bash
meridian discord-signals clear
```

--------------------------------

### user-config.json Defaults

Source: https://context7.com/yunus-0x/meridian/llms.txt

Customize agent behavior, risk parameters, and screening thresholds using the user-config.json file. All fields are optional and have default values.

```json
{
  "deployAmountSol": 0.5,
  "positionSizePct": 0.35,
  "maxDeployAmount": 50,
  "maxPositions": 3,
  "gasReserve": 0.2,
  "minSolToOpen": 0.55,
  "outOfRangeWaitMinutes": 30,
  "stopLossPct": -50,
  "takeProfitPct": 5,
  "trailingTakeProfit": true,
  "trailingTriggerPct": 3,
  "trailingDropPct": 1.5,
  "minFeeActiveTvlRatio": 0.05,
  "minTvl": 10000,
  "maxTvl": 150000,
  "minOrganic": 60,
  "minHolders": 500,
  "minMcap": 150000,
  "maxMcap": 10000000,
  "minBinStep": 80,
  "maxBinStep": 125,
  "minTokenFeesSol": 30,
  "managementIntervalMin": 10,
  "screeningIntervalMin": 30,
  "screeningModel": "openrouter/hunter-alpha",
  "managementModel": "openrouter/healer-alpha",
  "generalModel": "openrouter/healer-alpha"
}
```

--------------------------------

### executeTool — Tool Dispatch with Safety Checks

Source: https://context7.com/yunus-0x/meridian/llms.txt

The `executeTool` function acts as the gateway between the LLM and tool implementations. It performs validation, runs pre-execution safety checks for write operations, executes the tool, logs actions, sends notifications, and handles post-execution tasks like auto-swapping tokens.

```APIDOC
## `executeTool` — Tool Dispatch with Safety Checks

`executeTool` is the gateway between the LLM and every tool implementation. It validates tool existence, runs pre-execution safety checks for write operations (balance, position limits, bin range, TVL, volatility), executes the tool, logs the action, fires Telegram notifications for deploy/close/swap, and auto-swaps base tokens back to SOL after position close.

### Method Signature

```javascript
executeTool(toolName: string, args: object)
```

### Parameters

- **toolName** (string) - Required - The name of the tool to execute.
- **args** (object) - Required - The arguments for the tool.

### Tool: `deploy_position`

#### Description

Deploys a new trading position. Automatically runs safety checks including bin range, TVL, fee/TVL ratio, volatility, position count, duplicate pool/token checks, and SOL balance.

#### Arguments

- **pool_address** (string) - Required - The address of the liquidity pool.
- **amount_y** (number) - Required - The amount of SOL to deposit (single-sided).
- **amount_x** (number) - Required - Always 0 for single-sided SOL deploys.
- **strategy** (string) - Required - The deployment strategy (e.g., "bid_ask").
- **bins_below** (number) - Required - The number of bins below the current price.
- **bins_above** (number) - Required - The number of bins above the current price.
- **pool_name** (string) - Required - The name of the pool (e.g., "BONK-SOL").
- **base_mint** (string) - Required - The mint address of the base token.
- **bin_step** (number) - Required - The bin step size.
- **volatility** (number) - Required - The volatility of the pool.
- **fee_tvl_ratio** (number) - Required - The ratio of fees to Total Value Locked.
- **organic_score** (number) - Required - An organic score for the pool.
- **initial_value_usd** (number) - Required - The initial value of the position in USD.

#### Request Example

```javascript
const deploy = await executeTool("deploy_position", {
  pool_address: "AbCdEf...poolAddress",
  amount_y: 0.63,
  amount_x: 0,
  strategy: "bid_ask",
  bins_below: 55,
  bins_above: 0,
  pool_name: "BONK-SOL",
  base_mint: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  bin_step: 100,
  volatility: 3.2,
  fee_tvl_ratio: 0.18,
  organic_score: 84,
  initial_value_usd: 95.0,
});
```

#### Response Example

```json
{
  "success": true,
  "position": "Pos1...",
  "pool_name": "BONK-SOL",
  "txs": ["5xTr..."],
  "price_range": {"lower": 0.0000210, "upper": 0.0000245},
  "bin_step": 100,
  "base_fee": 1.0
}
```

#### Blocked Example (Safety Check Failure)

```javascript
const blocked = await executeTool("deploy_position", {
  pool_address: "AbCdEf...",
  amount_y: 0.63,
  bins_below: 10, // below MIN_SAFE_BINS_BELOW (35) → blocked
  bins_above: 0,
  volatility: 2.1,
});
// → { blocked: true, reason: "deploy range 10 total bins is below minimum 35." }
```

---

### Tool: `close_position`

#### Description

Closes an existing position. Automatically swaps the base token back to SOL after closing if `skip_swap` is false.

#### Arguments

- **position_address** (string) - Required - The address of the position to close.
- **reason** (string) - Optional - The reason for closing the position.
- **skip_swap** (boolean) - Optional - If true, the base token will not be swapped back to SOL.

#### Request Example

```javascript
const close = await executeTool("close_position", {
  position_address: "PosAddr...",
  reason: "OOR > 30 minutes",
  skip_swap: false,
});
```

#### Response Example

```json
{
  "success": true,
  "pnl_usd": 4.12,
  "pnl_pct": 4.3,
  "txs": [...],
  "base_mint": "DezX...",
  "auto_swapped": true,
  "sol_received": 0.027
}
```

---

### Tool: `claim_fees`

#### Description

Claims accrued fees for a given position.

#### Arguments

- **position_address** (string) - Required - The address of the position.

#### Request Example

```javascript
const claim = await executeTool("claim_fees", {
  position_address: "PosAddr...",
});
```

#### Response Example

```json
{
  "success": true,
  "position": "PosAddr...",
  "txs": ["7yUi..."],
  "base_mint": "DezX..."
}
```

---

### Tool: `swap_token`

#### Description

Swaps one token for another using the Jupiter aggregator.

#### Arguments

- **input_mint** (string) - Required - The mint address of the token to swap from.
- **output_mint** (string) - Required - The mint address of the token to swap to.
- **amount** (number) - Required - The amount of the input token to swap.

#### Request Example

```javascript
const swap = await executeTool("swap_token", {
  input_mint: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",  // BONK
  output_mint: "So11111111111111111111111111111111111111112",     // SOL
  amount: 1500000,
});
```

#### Response Example

```json
{
  "success": true,
  "tx": "9kLm...",
  "amount_in": 1500000,
  "amount_out": 0.031
}
```

---

### Tool: `update_config`

#### Description

Updates the tool's runtime configuration. Changes persist to `user-config.json` and restart the cron job if intervals are modified.

#### Arguments

- **changes** (object) - Required - An object containing the configuration changes.
- **reason** (string) - Optional - The reason for the configuration update.

#### Request Example

```javascript
const cfg = await executeTool("update_config", {
  changes: { stopLossPct: -20, outOfRangeWaitMinutes: 45, screeningModel: "anthropic/claude-opus-4-5" },
  reason: "Tightening stop loss after volatile session",
});
```

#### Response Example

```json
{
  "success": true,
  "applied": {
    "stopLossPct": -20,
    "outOfRangeWaitMinutes": 45,
    "screeningModel": "anthropic/claude-opus-4-5"
  },
  "unknown": []
}
```
```

--------------------------------

### Loop Mode for Screening or Management

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Configure continuous execution of screening or management tasks within Claude Code at specified intervals. Replace '30m' or '10m' with your desired time frame.

```bash
/loop 30m /screen     # screen every 30 minutes
/loop 10m /manage     # manage every 10 minutes
```

--------------------------------

### Meridian CLI: Balance Command

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Command to check the current balance.

```bash
meridian balance
```

--------------------------------

### Configure Telegram Bot

Source: https://github.com/yunus-0x/meridian/blob/main/README.md

Provides the necessary environment variables to set up Telegram integration for notifications and control. Ensure these are added to your .env file.

```env
TELEGRAM_BOT_TOKEN=<token>
TELEGRAM_CHAT_ID=<target chat id>
TELEGRAM_ALLOWED_USER_IDS=<comma-separated Telegram user ids allowed to control the bot>
```

--------------------------------

### Meridian Position Lifecycle

Source: https://github.com/yunus-0x/meridian/blob/main/CLAUDE.md

Details the four main stages of a position's lifecycle within the Meridian agent: Deploy, Monitor, Close, and Learn. It outlines the key actions and components involved in each stage.

```text
1. **Deploy**: `deploy_position` → executor safety checks → `trackPosition()` in state.js → Telegram notify
2. **Monitor**: management cron → `getMyPositions()` → `getPositionPnl()` → OOR detection → pool-memory snapshots
3. **Close**: `close_position` → `recordPerformance()` in lessons.js → auto-swap base token to SOL → Telegram notify
4. **Learn**: `evolveThresholds()` runs on performance data → updates config.screening → persists to user-config.json
```
Tokens:
Raw