Websocket

Connect via WebSocket to receive real-time notifications when your trigger conditions are met.

How Triggers Work

1. Connect — Establish a persistent WebSocket connection to receive notifications

2. Create Triggers — Use the REST API to define triggers with unique identifiers and market conditions

3. Receive Notifications — When a trigger condition is met, a notification is dispatched to your connected client

---

Endpoint

wss://enterprise.guardis.io/v1/triggers/ws

Authentication

Include your API key as a query parameter when connecting.

wss://enterprise.guardis.io/v1/triggers/ws?api_key=your_api_key_here

---

Message Types

Connection Established

{
  "type": "connected",
  "message": "Successfully connected to triggers stream"
}

Trigger Fired

When a trigger's conditions are met, you'll receive a notification with the trigger ID and current pool state:

{
  "type": "trigger_fired",
  "trigger_id": "my-unique-trigger-001",
  "fired_at": "2025-01-15T14:32:08.456Z",
  "pool": {
    "pair_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "token_address": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "sol_amount": "1523.847291635",
    "token_amount": "892847291.847362",
    "number_of_buys": 847,
    "number_of_sells": 234,
    "buy_volume_usd": "284729.47",
    "sell_volume_usd": "94827.33",
    "total_volume_usd": "379556.80"
  }
}

---

Field Reference

Trigger Notification

Field	Type	Description
type	string	Notification type (trigger_fired)
trigger_id	string	Your unique trigger identifier
fired_at	string	ISO 8601 timestamp when the trigger fired
pool	object	Current pool state that triggered the notification

Pool

Field	Type	Description
pair_address	string	The on-chain address of the liquidity pool
token_address	string	The mint address of the token
sol_amount	string	Amount of SOL currently in the pool
token_amount	string	Amount of tokens currently in the pool
number_of_buys	integer	Total buy transactions on the pool
number_of_sells	integer	Total sell transactions on the pool
buy_volume_usd	string	Cumulative buy volume in USD
sell_volume_usd	string	Cumulative sell volume in USD
total_volume_usd	string	Total trading volume in USD

Note: Decimal values are returned as strings to preserve precision.

---

Example Usage

JavaScript:

const socket = new WebSocket(
  "wss://enterprise.guardis.io/v1/triggers/ws?api_key=your_api_key_here"
);

socket.onopen = () => {
  console.log("Connected to triggers stream");
};

socket.onmessage = (event) => {
  const message = JSON.parse(event.data);
  
  if (message.type === "trigger_fired") {
    console.log(`Trigger fired: ${message.trigger_id}`);
    console.log(`Pool: ${message.pool.pair_address}`);
    console.log(`Total Volume: $${message.pool.total_volume_usd}`);
    
    // Handle your trigger logic here
  }
};

socket.onerror = (error) => {
  console.error("WebSocket error:", error);
};

socket.onclose = () => {
  console.log("Connection closed");
};

Python:

import asyncio
import websockets
import json

async def listen_for_triggers():
    uri = "wss://enterprise.guardis.io/v1/triggers/ws?api_key=your_api_key_here"
    
    async with websockets.connect(uri) as socket:
        print("Connected to triggers stream")
        
        async for message in socket:
            data = json.loads(message)
            
            if data["type"] == "trigger_fired":
                print(f"Trigger fired: {data['trigger_id']}")
                print(f"Pool: {data['pool']['pair_address']}")
                print(f"Total Volume: ${data['pool']['total_volume_usd']}")
                
                # Handle your trigger logic here

asyncio.run(listen_for_triggers())

---

Connection Best Practices

• Implement reconnection logic — Network interruptions happen; automatically reconnect with exponential backoff

• Handle heartbeats — Keep your connection alive by responding to ping frames if required by your WebSocket client

• Process messages asynchronously — Don't block on message processing; queue updates if needed