gRPC

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

How Triggers Work

1. Connect — Establish a persistent gRPC stream 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

enterprise.guardis.io:443

Authentication

Include your API key in the request metadata using the x-api-key field.

x-api-key: your_api_key_here

---

Service Definition

syntax = "proto3";

package guardis.triggers.v1;

import "google/protobuf/timestamp.proto";

service TriggersService {
  // Stream trigger notifications
  rpc StreamTriggers(StreamTriggersRequest) returns (stream TriggerNotification);
}

message StreamTriggersRequest {
  // Reserved for future filtering options
}

message TriggerNotification {
  // Notification type
  string type = 1;
  // Your unique trigger identifier
  string trigger_id = 2;
  // Timestamp when the trigger fired
  google.protobuf.Timestamp fired_at = 3;
  // Current pool state that triggered the notification
  Pool pool = 4;
}

message Pool {
  // The on-chain address of the liquidity pool
  string pair_address = 1;
  // The mint address of the token
  string token_address = 2;
  // Amount of SOL currently in the pool
  string sol_amount = 3;
  // Amount of tokens currently in the pool
  string token_amount = 4;
  // Total buy transactions on the pool
  int32 number_of_buys = 5;
  // Total sell transactions on the pool
  int32 number_of_sells = 6;
  // Cumulative buy volume in USD
  string buy_volume_usd = 7;
  // Cumulative sell volume in USD
  string sell_volume_usd = 8;
  // Total trading volume in USD
  string total_volume_usd = 9;
}

---

Request Parameters

StreamTriggersRequest

Currently accepts no parameters. Future versions may support filtering options.

---

Response Format

TriggerNotification

Field	Type	Description
type	string	Notification type (trigger_fired)
trigger_id	string	Your unique trigger identifier
fired_at	google.protobuf.Timestamp	Timestamp when the trigger fired
pool	Pool	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	int32	Total buy transactions on the pool
number_of_sells	int32	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

Python:

import grpc
from guardis.triggers.v1 import triggers_pb2, triggers_pb2_grpc

metadata = [("x-api-key", "your_api_key_here")]

with grpc.secure_channel("enterprise.guardis.io:443", grpc.ssl_channel_credentials()) as channel:
    stub = triggers_pb2_grpc.TriggersServiceStub(channel)
    
    request = triggers_pb2.StreamTriggersRequest()
    
    for notification in stub.StreamTriggers(request, metadata=metadata):
        if notification.type == "trigger_fired":
            print(f"Trigger fired: {notification.trigger_id}")
            print(f"Pool: {notification.pool.pair_address}")
            print(f"Total Volume: ${notification.pool.total_volume_usd}")
            
            # Handle your trigger logic here

Go:

package main

import (
    "context"
    "log"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/metadata"
    
    pb "github.com/your-org/guardis-go/triggers/v1"
)

func main() {
    creds := credentials.NewTLS(nil)
    conn, err := grpc.Dial("enterprise.guardis.io:443", grpc.WithTransportCredentials(creds))
    if err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    defer conn.Close()

    client := pb.NewTriggersServiceClient(conn)

    ctx := metadata.AppendToOutgoingContext(
        context.Background(),
        "x-api-key", "your_api_key_here",
    )

    request := &pb.StreamTriggersRequest{}

    stream, err := client.StreamTriggers(ctx, request)
    if err != nil {
        log.Fatalf("Failed to stream: %v", err)
    }

    for {
        notification, err := stream.Recv()
        if err != nil {
            log.Fatalf("Stream error: %v", err)
        }
        
        if notification.Type == "trigger_fired" {
            log.Printf("Trigger fired: %s", notification.TriggerId)
            log.Printf("Pool: %s", notification.Pool.PairAddress)
            log.Printf("Total Volume: $%s", notification.Pool.TotalVolumeUsd)
            
            // Handle your trigger logic here
        }
    }
}

---

Connection Best Practices

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

• Use deadlines — Set appropriate deadlines for your streaming calls to handle stale connections

• Handle stream errors gracefully — Check for io.EOF and gRPC status codes to determine if reconnection is needed