gRPC

gRPC

Stream proprietary trading indicators for liquidity pools. Indicators are calculated and delivered every 1 minute for pools that have been updated in our system.

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 enterprise.v1;

import "google/protobuf/timestamp.proto";

// IndicatorsService provides real-time indicator streaming for liquidity pools
service IndicatorsService {
  // StreamIndicators streams indicator updates every minute for updated pools
  rpc StreamIndicators(StreamIndicatorsRequest) returns (stream IndicatorUpdate);
}

// Request to start streaming indicators
message StreamIndicatorsRequest {
  // Reserved for future filtering options
}

// An indicator update for a pool
message IndicatorUpdate {
  // Timestamp when the update was generated
  google.protobuf.Timestamp timestamp = 1;
  // Indicator for a pool updated during this interval
  CurrentIndicator indicator = 2;
}

// Current indicator metrics for a liquidity pool
message CurrentIndicator {
  // Identification
  string pair_address = 1;
  string token_address = 2;

  // Wallet metrics
  int64 total_wallets = 3;
  int64 organic_wallets = 4;
  int64 organic_profitable_wallets = 5;
  string organic_to_total_wallets_ratio = 6;
  string bot_to_total_wallets_ratio = 7;
  string profitable_organic_to_total_organic_ratio = 8;

  // Volume metrics
  string total_volume_usd = 9;
  string organic_volume_usd = 10;
  string bot_volume_ratio = 11;
  string organic_volume_ratio = 12;
  string profitable_volume = 13;
  string profitable_volume_total_volume_ratio = 14;

  // Behavioral metrics
  string organic_mean_hold_seconds = 15;
  string organic_mean_trade_frequency_seconds = 16;

  // Smart money metrics
  string smart_money_score = 17;
  string raw_smart_money_score = 18;
  string smart_money_influx_10min = 19;
  string smart_money_outflux_10min = 20;
  string raw_smart_money_influx = 21;
  string raw_smart_money_outflux = 22;
  int64 smart_holders = 23;
  int64 raw_holders = 24;
  string smart_to_raw_holders_ratio = 25;

  // Price & status
  string price_usd = 26;
  string status = 27;
  int32 attempts = 28;
  google.protobuf.Timestamp created_at = 29;
}

---

Request Parameters

StreamIndicatorsRequest

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

---

Response Format

The server streams IndicatorUpdate messages every minute, one per pool that was updated during that interval.

IndicatorUpdate

Field	Type	Description
timestamp	google.protobuf.Timestamp	Timestamp when the update was generated
indicator	CurrentIndicator	Indicator for a pool updated during this interval

CurrentIndicator

Identification

Field	Type	Description
pair_address	string	The on-chain address of the liquidity pool
token_address	string	The mint address of the token

Wallet Metrics

Field	Type	Description
total_wallets	int64	Total number of unique wallets that have traded this token
organic_wallets	int64	Number of wallets classified as organic (non-bot) traders
organic_profitable_wallets	int64	Number of organic wallets currently in profit
organic_to_total_wallets_ratio	string	Ratio of organic wallets to total wallets (0-1)
bot_to_total_wallets_ratio	string	Ratio of bot wallets to total wallets (0-1)
profitable_organic_to_total_organic_ratio	string	Ratio of profitable organic wallets to total organic wallets (0-1)

Volume Metrics

Field	Type	Description
total_volume_usd	string	Total trading volume in USD
organic_volume_usd	string	Trading volume from organic wallets in USD
bot_volume_ratio	string	Ratio of bot volume to total volume (0-1)
organic_volume_ratio	string	Ratio of organic volume to total volume (0-1)
profitable_volume	string	Volume from profitable trades in USD
profitable_volume_total_volume_ratio	string	Ratio of profitable volume to total volume (0-1)

Behavioral Metrics

Field	Type	Description
organic_mean_hold_seconds	string	Average hold time for organic wallets in seconds
organic_mean_trade_frequency_seconds	string	Average time between trades for organic wallets in seconds

Smart Money Metrics

Field	Type	Description
smart_money_score	string	Proprietary score indicating smart money activity (0-100)
raw_smart_money_score	string	Unadjusted smart money score before normalization
smart_money_influx_10min	string	Smart money inflow over the last 10 minutes in USD
smart_money_outflux_10min	string	Smart money outflow over the last 10 minutes in USD
raw_smart_money_influx	string	Unadjusted smart money inflow in USD
raw_smart_money_outflux	string	Unadjusted smart money outflow in USD
smart_holders	int64	Number of wallets classified as smart money
raw_holders	int64	Total number of current holders
smart_to_raw_holders_ratio	string	Ratio of smart money holders to total holders (0-1)

Price & Status

Field	Type	Description
price_usd	string	Current token price in USD
status	string	Processing status of the indicator
attempts	int32	Number of calculation attempts
created_at	google.protobuf.Timestamp	Timestamp when the indicator was first created

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

---

Example Usage

Python:

import grpc
from guardis.indicators.v1 import indicators_pb2, indicators_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 = indicators_pb2_grpc.IndicatorsServiceStub(channel)
    
    request = indicators_pb2.StreamIndicatorsRequest()
    
    for update in stub.StreamIndicators(request, metadata=metadata):
        indicator = update.indicator
        print(f"Update at {update.timestamp}:")
        print(f"{indicator.token_address}:")
        print(f"  Smart Money Score: {indicator.smart_money_score}")
        print(f"  Organic Ratio: {float(indicator.organic_to_total_wallets_ratio) * 100:.1f}%")
        print(f"  10min Influx: ${indicator.smart_money_influx_10min}")

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/indicators/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.NewIndicatorsServiceClient(conn)

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

    request := &pb.StreamIndicatorsRequest{}

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

    for {
        update, err := stream.Recv()
        if err != nil {
            log.Fatalf("Stream error: %v", err)
        }
        
        indicator := update.Indicator
        log.Printf("Update at %v:", update.Timestamp)
        log.Printf("%s:", indicator.TokenAddress)
        log.Printf("  Smart Money Score: %s", indicator.SmartMoneyScore)
        log.Printf("  10min Influx: $%s", indicator.SmartMoneyInflux_10Min)
    }
}

---

Connection Best Practices

• Expect updates every minute — Plan your processing around this cadence

• 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