Server Events - LaserSell Documentation

Message Types

The server sends messages with a type discriminator. All SDKs parse these into typed objects.

Type	Priority	Description
`hello_ok`	High	Connection accepted, session started.
`pong`	High	Response to client ping.
`error`	High	Server error notification.
`balance_update`	High	Token balance changed for a tracked wallet.
`position_opened`	High	New position detected and tracking started.
`position_closed`	High	Position tracking ended.
`exit_signal_with_tx`	High	Exit threshold met; unsigned tx included.
`mirror_buy_signal`	High	Watched wallet bought; unsigned buy tx for your wallet.
`mirror_buy_failed`	High	Mirror buy could not be executed.
`mirror_wallet_auto_disabled`	High	Watch wallet disabled by consecutive loss breaker.
`pnl_update`	Low	Periodic profit and loss snapshot.
`liquidity_snapshot`	Low	Slippage bands and liquidity trend (Tier 1+).
`trade_tick`	Low	Real-time trade notification for a tracked position.

`hello_ok`

Sent once immediately after the WebSocket opens. Contains the session ID and tier limits.

{
  "type": "hello_ok",
  "session_id": 42,
  "server_time_ms": 1706000000000,
  "limits": {
    "hi_capacity": 1024,
    "pnl_flush_ms": 1000,
    "max_positions_per_session": 100,
    "max_wallets_per_session": 10,
    "max_positions_per_wallet": 20,
    "max_sessions_per_api_key": 5
  }
}

Field	Type	Description
`session_id`	`number`	Unique session identifier.
`server_time_ms`	`number`	Server timestamp in milliseconds.
`limits`	`object`	Tier capacity and rate limits. See Rate Limits.

`pong`

Response to a client ping. Use for latency measurement.

{
  "type": "pong",
  "server_time_ms": 1706000000001
}

Field	Type	Description
`server_time_ms`	`number`	Server timestamp in milliseconds.

`error`

Server side error notification. Check the code to determine severity.

{
  "type": "error",
  "code": "invalid_strategy",
  "message": "target_profit_pct must be >= 0"
}

Field	Type	Description
`code`	`string`	Machine readable error code.
`message`	`string`	Human readable error detail.

`balance_update`

Emitted when a token balance changes in a tracked wallet (new arrivals, transfers, sells).

{
  "type": "balance_update",
  "wallet_pubkey": "Abc123...",
  "mint": "TokenMint...",
  "token_account": "ATA...",
  "token_program": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  "tokens": 5000000,
  "slot": 280000000
}

Field	Type	Description
`wallet_pubkey`	`string`	Wallet that owns the token account.
`mint`	`string`	Token mint address.
`token_account`	`string`	Associated token account address. May be absent.
`token_program`	`string`	Token program ID (SPL Token or Token 2022). May be absent.
`tokens`	`number`	Current balance in atomic units.
`slot`	`number`	Solana slot at which the balance was observed.

`position_opened`

A new position has been detected and tracking has begun.

{
  "type": "position_opened",
  "position_id": 1,
  "wallet_pubkey": "Abc123...",
  "mint": "TokenMint...",
  "token_account": "ATA...",
  "token_program": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  "tokens": 5000000,
  "entry_quote_units": 100000000,
  "market_context": {
    "market_type": "pump_swap",
    "pumpswap": {
      "pool": "PoolAddress..."
    }
  },
  "slot": 280000000
}

Field	Type	Description
`position_id`	`number`	Server assigned position identifier.
`wallet_pubkey`	`string`	Wallet holding the position.
`mint`	`string`	Token mint address.
`token_account`	`string`	Associated token account.
`token_program`	`string`	Token program ID. May be absent.
`tokens`	`number`	Token balance at entry.
`entry_quote_units`	`number`	Entry value in quote asset atomic units.
`market_context`	`object`	Market/pool context. May be absent. See Market Context.
`slot`	`number`	Solana slot at detection.

`position_closed`

A position has been removed from tracking.

{
  "type": "position_closed",
  "position_id": 1,
  "wallet_pubkey": "Abc123...",
  "mint": "TokenMint...",
  "token_account": "ATA...",
  "reason": "stop_loss",
  "slot": 280000100
}

Field	Type	Description
`position_id`	`number`	Position identifier.
`wallet_pubkey`	`string`	Wallet that held the position.
`mint`	`string`	Token mint address.
`token_account`	`string`	Associated token account. May be absent.
`reason`	`string`	Why the position was closed (e.g., `"stop_loss"`, `"target_profit"`, `"trailing_stop"`, `"deadline"`, `"manual"`).
`slot`	`number`	Solana slot at close.

`exit_signal_with_tx`

The most important event. Sent when a position meets your exit criteria. Includes a pre built unsigned transaction ready for signing.

{
  "type": "exit_signal_with_tx",
  "session_id": 42,
  "position_id": 1,
  "wallet_pubkey": "Abc123...",
  "mint": "TokenMint...",
  "token_account": "ATA...",
  "token_program": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  "position_tokens": 5000000,
  "profit_units": 50000000,
  "reason": "target_profit",
  "triggered_at_ms": 1706000005000,
  "market_context": {
    "market_type": "pump_swap",
    "pumpswap": { "pool": "PoolAddress..." }
  },
  "unsigned_tx_b64": "AQAAAA..."
}

Field	Type	Description
`session_id`	`number`	Session that generated this signal.
`position_id`	`number`	Position identifier.
`wallet_pubkey`	`string`	Wallet holding the position.
`mint`	`string`	Token mint address.
`token_account`	`string`	Associated token account. May be absent.
`token_program`	`string`	Token program ID. May be absent.
`position_tokens`	`number`	Tokens held at signal time.
`profit_units`	`number`	Estimated profit in quote asset atomic units.
`reason`	`string`	Trigger reason (e.g., `"target_profit"`, `"stop_loss"`, `"trailing_stop"`, `"deadline"`).
`triggered_at_ms`	`number`	Millisecond timestamp when the signal was generated.
`market_context`	`object`	Market/pool context for the sell route. May be absent.
`unsigned_tx_b64`	`string`	Base64 encoded unsigned `VersionedTransaction`.

`mirror_buy_signal`

Sent when a watched wallet opens a position on a supported market and the stream builds an unsigned buy transaction for your wallet. Sign and submit this transaction to mirror the trade.

{
  "type": "mirror_buy_signal",
  "session_id": 42,
  "watched_wallet": "WatchedWalletPubkey...",
  "mint": "TokenMint...",
  "user_wallet": "YourWalletPubkey...",
  "amount_quote_units": 100000000,
  "input": "SOL",
  "unsigned_tx_b64": "AQAAAA...",
  "slippage_bps": 2500,
  "send_mode": "helius_sender",
  "tip_lamports": 1000,
  "market_context": {
    "market_type": "pump_swap",
    "pumpswap": { "pool": "PoolAddress..." }
  }
}

Field	Type	Description
`session_id`	`number`	Session that generated this signal.
`watched_wallet`	`string`	Public key of the watched wallet that triggered the buy.
`mint`	`string`	Token mint address being purchased.
`user_wallet`	`string`	Your wallet that will execute the buy transaction.
`amount_quote_units`	`number`	Buy amount in quote asset atomic units.
`input`	`string`	Quote asset used for the buy: `"SOL"` or `"USD1"`.
`unsigned_tx_b64`	`string`	Base64 encoded unsigned `VersionedTransaction`.
`slippage_bps`	`number`	Slippage tolerance in basis points.
`send_mode`	`string`	Transaction submission mode. May be absent.
`tip_lamports`	`number`	Priority fee tip in lamports. May be absent.
`market_context`	`object`	Market/pool context for the buy route. May be absent. See Market Context.

`mirror_buy_failed`

Sent when a mirror buy cannot be executed. Common reasons include insufficient balance, no route found, or pool liquidity below the minimum threshold.

{
  "type": "mirror_buy_failed",
  "watched_wallet": "WatchedWalletPubkey...",
  "mint": "TokenMint...",
  "reason": "insufficient_balance"
}

Field	Type	Description
`watched_wallet`	`string`	Public key of the watched wallet that triggered the buy.
`mint`	`string`	Token mint address that was being purchased.
`reason`	`string`	Machine readable reason the buy failed (e.g., `"insufficient_balance"`, `"no_route"`, `"below_min_liquidity"`, `"cooldown_active"`, `"max_positions_reached"`).

`mirror_wallet_auto_disabled`

Sent when a watched wallet is automatically disabled by the consecutive loss breaker. After receiving this event the stream will no longer mirror trades from this wallet until you re-enable it.

{
  "type": "mirror_wallet_auto_disabled",
  "watched_wallet": "WatchedWalletPubkey...",
  "reason": "consecutive_loss_limit_reached",
  "loss_count": 3
}

Field	Type	Description
`watched_wallet`	`string`	Public key of the wallet that was disabled.
`reason`	`string`	Human readable description of why the wallet was disabled.
`loss_count`	`number`	Number of consecutive losing trades that triggered the disable.

`pnl_update`

Periodic profit and loss snapshot for a tracked position.

{
  "type": "pnl_update",
  "position_id": 1,
  "profit_units": 25000000,
  "proceeds_units": 125000000,
  "server_time_ms": 1706000003000
}

Field	Type	Description
`position_id`	`number`	Position identifier.
`profit_units`	`number`	Current estimated profit in quote asset atomic units.
`proceeds_units`	`number`	Current estimated total proceeds.
`server_time_ms`	`number`	Server timestamp in milliseconds.

pnl_update messages are delivered at the interval defined by limits.pnl_flush_ms. When using lane splitting, they flow through the low priority channel.

`liquidity_snapshot`

Tier 1+ only. Liquidity snapshots are delivered to Professional and Advanced tier subscribers. Free tier sessions receive pnl_update messages only.

Real time slippage bands and liquidity trend for a tracked position. Delivered alongside pnl_update at the same flush interval. Use this data to understand how much of a position can be sold at a given slippage threshold and whether pool liquidity is growing, stable, or draining. See the announcement blog post for background and examples.

{
  "type": "liquidity_snapshot",
  "position_id": 1,
  "bands": [
    { "slippage_bps": 100, "max_tokens": 500000, "coverage_pct": 10.0 },
    { "slippage_bps": 200, "max_tokens": 1200000, "coverage_pct": 24.0 },
    { "slippage_bps": 500, "max_tokens": 3000000, "coverage_pct": 60.0 },
    { "slippage_bps": 1000, "max_tokens": 5000000, "coverage_pct": 100.0 }
  ],
  "liquidity_trend": "stable",
  "server_time_ms": 1706000003000
}

Field	Type	Description
`position_id`	`number`	Position identifier.
`bands`	`array`	Slippage bands, each describing how many tokens are sellable within that slippage threshold.
`liquidity_trend`	`string`	Current liquidity direction: `"growing"`, `"stable"`, or `"draining"`.
`server_time_ms`	`number`	Server timestamp in milliseconds.

`SlippageBandMsg`

Each entry in the bands array:

Field	Type	Description
`slippage_bps`	`number`	Slippage threshold in basis points (e.g. `100` = 1%).
`max_tokens`	`number`	Maximum tokens sellable within this slippage band (atomic units).
`coverage_pct`	`number`	Percentage of the full position covered by this band (0 to 100).

Interpreting slippage bands

Slippage bands answer the question: “How much can I sell without exceeding X% slippage?” For example, if the 500 bps band shows max_tokens: 3000000 and coverage_pct: 60.0, you can sell up to 3,000,000 tokens (60% of your position) with no more than 5% price impact. Use session.getSlippageBands(positionId) or session.getMaxSellAtSlippage(positionId, slippageBps) in any SDK to query the latest snapshot.

Liquidity trend

The liquidity_trend field tracks how pool liquidity is changing over recent observations:

"growing": Liquidity is increasing. Sell conditions are improving.
"stable": Liquidity is steady. No significant change.
"draining": Liquidity is decreasing. Consider exiting sooner if selling a large position.

Use session.getLiquidityTrend(positionId) in any SDK to read the trend.

`trade_tick`

Real-time notification when a trade occurs on a tracked position’s token. Useful for monitoring trading activity on tokens you hold.

{
  "type": "trade_tick",
  "position_id": 1,
  "time_ms": 1706000005000,
  "side": "buy",
  "token_amount": 500000,
  "quote_amount": 25000000,
  "price_quote": 50000,
  "maker": "TraderWallet...",
  "tx_signature": "5abc..."
}

Field	Type	Description
`position_id`	`number`	Position identifier.
`time_ms`	`number`	Trade timestamp in milliseconds.
`side`	`string`	Trade direction: `"buy"` or `"sell"`.
`token_amount`	`number`	Token amount traded (atomic units).
`quote_amount`	`number`	Quote asset amount traded (atomic units).
`price_quote`	`number`	Price per token in quote asset (atomic units).
`maker`	`string`	Wallet that initiated the trade. May be absent.
`tx_signature`	`string`	On-chain transaction signature. May be absent.
`watched`	`boolean`	`true` if this trade is from a watched wallet.

​Message Types

​hello_ok

​pong

​error

​balance_update

​position_opened

​position_closed

​exit_signal_with_tx

​mirror_buy_signal

​mirror_buy_failed

​mirror_wallet_auto_disabled

​pnl_update

​liquidity_snapshot

​SlippageBandMsg

​Interpreting slippage bands

​Liquidity trend

​trade_tick

Message Types

`hello_ok`

`pong`

`error`

`balance_update`

`position_opened`

`position_closed`

`exit_signal_with_tx`

`mirror_buy_signal`

`mirror_buy_failed`

`mirror_wallet_auto_disabled`

`pnl_update`

`liquidity_snapshot`

`SlippageBandMsg`

Interpreting slippage bands

Liquidity trend

`trade_tick`