gRPC

Stream real-time new token data and supply updates. Events are emitted when new tokens are created with liquidity or when token supplies change.

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";

service NewTokenService {
  // Stream new token data and supply updates to connected clients
  rpc StreamNewTokens(StreamNewTokensRequest) returns (stream NewTokenUpdate);
}

message StreamNewTokensRequest {
  // Reserved for future filtering options
}

message NewTokenUpdate {
  // Timestamp when this update was generated
  google.protobuf.Timestamp timestamp = 1;
  // The update payload - either new token data or supply update
  oneof payload {
    NewTokenData new_token_data = 2;
    TokenSupplyUpdate token_supply_update = 3;
  }
}

message NewTokenData {
  // Core token information
  TokenInfo token = 1;
  // Token metadata from on-chain metadata account
  TokenMetadata metadata = 2;
  // Initial liquidity event information
  LiquidityEvent liquidity_event = 3;
  // Social media links and their verification status
  repeated SocialLink social_links = 4;
  // Image hash information for duplicate detection (optional)
  optional ImageHash image_hash = 5;
}

message TokenInfo {
  // The token mint address
  string token_address = 1;
  // Address of the token creator
  string creator_address = 2;
  // Total supply of the token (as string to preserve precision)
  string total_supply = 3;
  // Token name
  string name = 4;
  // Token symbol
  string symbol = 5;
  // Number of decimal places
  uint32 decimals = 6;
  // Mint authority address (empty if revoked)
  optional string mint_authority_address = 7;
  // Freeze authority address (empty if revoked)
  optional string freeze_authority_address = 8;
  // Solana slot number when token was created
  uint64 creation_slot = 9;
  // Timestamp when token was created
  google.protobuf.Timestamp created_at = 10;
}

message TokenMetadata {
  // Address that can update the metadata
  string update_authority_address = 1;
  // URI pointing to off-chain metadata (usually Arweave or IPFS)
  string uri = 2;
  // Parsed metadata from the URI (optional)
  optional UriMetadata uri_metadata = 3;
  // List of creators with their share percentages
  repeated Creator creators = 4;
  // Whether the primary sale has happened
  bool primary_sale_happened = 5;
  // Whether the metadata is mutable
  bool is_mutable = 6;
  // Edition nonce for master editions (optional)
  optional uint32 edition_nonce = 7;
  // Token standard (e.g., "Fungible", "NonFungible")
  optional string token_standard = 8;
  // Collection address if part of a collection
  optional string collection = 9;
  // Uses information for limited use tokens
  optional string uses = 10;
  // Collection details for collection parent tokens
  optional string collection_details = 11;
  // Programmable config for pNFTs
  optional string programmable_config = 12;
  // Seller fee basis points (royalties, 0-10000)
  uint32 seller_fee_basis_points = 13;
}

message UriMetadata {
  // Token name from URI
  string name = 1;
  // Token symbol from URI
  string symbol = 2;
  // Token description (optional)
  optional string description = 3;
  // Image URL (optional)
  optional string image = 4;
}

message Creator {
  // Creator's wallet address
  string address = 1;
  // Whether the creator has verified this token
  bool verified = 2;
  // Percentage share of royalties (0-100)
  uint32 share = 3;
}

message LiquidityEvent {
  // The liquidity pool pair address
  string pair_address = 1;
  // Initial SOL amount added to the pool (as string to preserve precision)
  string initial_liquidity_solana_amount = 2;
  // Initial token amount added to the pool (as string to preserve precision)
  string initial_liquidity_token_amount = 3;
  // Initial liquidity value in USD (as string to preserve precision)
  string initial_liquidity_value_usd = 4;
  // Solana slot when liquidity was added
  uint64 initial_liquidity_add_slot_number = 5;
  // Timestamp when liquidity was added
  google.protobuf.Timestamp initial_liquidity_add_slot_timestamp = 6;
  // Block time at liquidity add
  google.protobuf.Timestamp block_time_at = 7;
}

message SocialLink {
  // Platform name (e.g., "twitter", "telegram", "website")
  string platform = 1;
  // URL of the social link
  string url = 2;
  // HTTP status code from verification check
  uint32 status_code = 3;
}

message ImageHash {
  // 32-bit perceptual hash
  string phash_32 = 1;
  // 64-bit perceptual hash
  string phash_64 = 2;
  // Timestamp when the hash was computed
  google.protobuf.Timestamp created_at = 3;
}

message TokenSupplyUpdate {
  // The token mint address
  string token_address = 1;
  // New total supply value (as string to preserve precision)
  string new_supply = 2;
}

---

Request Parameters

StreamNewTokensRequest

Field	Type	Required	Description
—	—	—	No parameters required. Reserved for future filtering options.

---

Response Format

The server streams NewTokenUpdate messages. Each message contains either new token data or a supply update.

NewTokenUpdate

Field	Type	Description
timestamp	google.protobuf.Timestamp	ISO 8601 timestamp when the update was generated
new_token_data	NewTokenData	Full token data (when a new token is created)
token_supply_update	TokenSupplyUpdate	Supply update (when a token's supply changes)

Note: The payload field is a oneof — each message contains either new_token_data OR token_supply_update, never both.

NewTokenData

Field	Type	Description
token	TokenInfo	Core token information
metadata	TokenMetadata	Token metadata from on-chain metadata account
liquidity_event	LiquidityEvent	Initial liquidity event information
social_links	repeated SocialLink	Social media links and their verification status
image_hash	ImageHash (optional)	Image hash information for duplicate detection

TokenInfo

Field	Type	Description
token_address	string	The token mint address
creator_address	string	Address of the token creator
total_supply	string	Total supply of the token
name	string	Token name
symbol	string	Token symbol
decimals	uint32	Number of decimal places
mint_authority_address	string (optional)	Mint authority address (empty if revoked)
freeze_authority_address	string (optional)	Freeze authority address (empty if revoked)
creation_slot	uint64	Solana slot number when token was created
created_at	google.protobuf.Timestamp	Timestamp when token was created

TokenMetadata

Field	Type	Description
update_authority_address	string	Address that can update the metadata
uri	string	URI pointing to off-chain metadata
uri_metadata	UriMetadata (optional)	Parsed metadata from the URI
creators	repeated Creator	List of creators with their share percentages
primary_sale_happened	bool	Whether the primary sale has happened
is_mutable	bool	Whether the metadata is mutable
edition_nonce	uint32 (optional)	Edition nonce for master editions
token_standard	string (optional)	Token standard (e.g., "Fungible", "NonFungible")
collection	string (optional)	Collection address if part of a collection
uses	string (optional)	Uses information for limited use tokens
collection_details	string (optional)	Collection details for collection parent tokens
programmable_config	string (optional)	Programmable config for pNFTs
seller_fee_basis_points	uint32	Seller fee basis points (royalties, 0-10000)

UriMetadata

Field	Type	Description
name	string	Token name from URI
symbol	string	Token symbol from URI
description	string (optional)	Token description
image	string (optional)	Image URL

Creator

Field	Type	Description
address	string	Creator's wallet address
verified	bool	Whether the creator has verified this token
share	uint32	Percentage share of royalties (0-100)

LiquidityEvent

Field	Type	Description
pair_address	string	The liquidity pool pair address
initial_liquidity_solana_amount	string	Initial SOL amount added to the pool
initial_liquidity_token_amount	string	Initial token amount added to the pool
initial_liquidity_value_usd	string	Initial liquidity value in USD
initial_liquidity_add_slot_number	uint64	Solana slot when liquidity was added
initial_liquidity_add_slot_timestamp	google.protobuf.Timestamp	Timestamp when liquidity was added
block_time_at	google.protobuf.Timestamp	Block time at liquidity add

SocialLink

Field	Type	Description
platform	string	Platform name (e.g., "twitter", "telegram", "website")
url	string	URL of the social link
status_code	uint32	HTTP status code from verification check

ImageHash

Field	Type	Description
phash_32	string	32-bit perceptual hash
phash_64	string	64-bit perceptual hash
created_at	google.protobuf.Timestamp	Timestamp when the hash was computed

TokenSupplyUpdate

Field	Type	Description
token_address	string	The token mint address
new_supply	string	New total supply value

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

---

Example Usage

Python:

import grpc
from enterprise.v1 import new_tokens_pb2, new_tokens_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 = new_tokens_pb2_grpc.NewTokenServiceStub(channel)

    request = new_tokens_pb2.StreamNewTokensRequest()

    for update in stub.StreamNewTokens(request, metadata=metadata):
        if update.HasField("new_token_data"):
            token = update.new_token_data.token
            liquidity = update.new_token_data.liquidity_event
            print(f"New Token: {token.name} ({token.symbol})")
            print(f"  Address: {token.token_address}")
            print(f"  Supply: {token.total_supply}")
            print(f"  Decimals: {token.decimals}")
            print(f"  Pool: {liquidity.pair_address}")
            print(f"  Initial Liquidity: ${liquidity.initial_liquidity_value_usd}")

            for social in update.new_token_data.social_links:
                print(f"  {social.platform}: {social.url} (status: {social.status_code})")

        elif update.HasField("token_supply_update"):
            supply_update = update.token_supply_update
            print(f"Supply Update: {supply_update.token_address}")
            print(f"  New Supply: {supply_update.new_supply}")

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/enterprise/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.NewNewTokenServiceClient(conn)

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

    request := &pb.StreamNewTokensRequest{}

    stream, err := client.StreamNewTokens(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)
        }

        switch payload := update.Payload.(type) {
        case *pb.NewTokenUpdate_NewTokenData:
            token := payload.NewTokenData.Token
            liquidity := payload.NewTokenData.LiquidityEvent

            log.Printf("New Token: %s (%s)", token.Name, token.Symbol)
            log.Printf("  Address: %s", token.TokenAddress)
            log.Printf("  Supply: %s", token.TotalSupply)
            log.Printf("  Pool: %s", liquidity.PairAddress)
            log.Printf("  Initial Liquidity: $%s", liquidity.InitialLiquidityValueUsd)

            for _, social := range payload.NewTokenData.SocialLinks {
                log.Printf("  %s: %s (status: %d)", social.Platform, social.Url, social.StatusCode)
            }

        case *pb.NewTokenUpdate_TokenSupplyUpdate:
            supplyUpdate := payload.TokenSupplyUpdate
            log.Printf("Supply Update: %s -> %s", supplyUpdate.TokenAddress, supplyUpdate.NewSupply)
        }
    }
}

Node.js:

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const packageDefinition = protoLoader.loadSync('new_tokens.proto', {
    keepCase: true,
    longs: String,
    enums: String,
    defaults: true,
    oneofs: true
});

const proto = grpc.loadPackageDefinition(packageDefinition).enterprise.v1;

const client = new proto.NewTokenService(
    'enterprise.guardis.io:443',
    grpc.credentials.createSsl()
);

const metadata = new grpc.Metadata();
metadata.add('x-api-key', 'your_api_key_here');

const stream = client.StreamNewTokens({}, metadata);

stream.on('data', (update) => {
    if (update.new_token_data) {
        const token = update.new_token_data.token;
        const liquidity = update.new_token_data.liquidity_event;

        console.log(`New Token: ${token.name} (${token.symbol})`);
        console.log(`  Address: ${token.token_address}`);
        console.log(`  Supply: ${token.total_supply}`);
        console.log(`  Pool: ${liquidity.pair_address}`);
        console.log(`  Initial Liquidity: $${liquidity.initial_liquidity_value_usd}`);

        for (const social of update.new_token_data.social_links) {
            console.log(`  ${social.platform}: ${social.url} (status: ${social.status_code})`);
        }
    } else if (update.token_supply_update) {
        const supplyUpdate = update.token_supply_update;
        console.log(`Supply Update: ${supplyUpdate.token_address} -> ${supplyUpdate.new_supply}`);
    }
});

stream.on('error', (err) => {
    console.error('Stream error:', err);
});

stream.on('end', () => {
    console.log('Stream ended');
});

---

Event Types

This stream provides two types of events:

1. New Token Data (new_token_data)

Emitted when a new token is created with liquidity. Contains comprehensive information about the token including:

• Token Information: Address, name, symbol, supply, decimals, authorities

• Metadata: On-chain metadata including URI, creators, mutability settings

• Liquidity Event: Initial pool information with SOL and token amounts

• Social Links: Verified social media links (Twitter, Telegram, website)

• Image Hash: Perceptual hash for duplicate image detection (when available)

2. Token Supply Update (token_supply_update)

Emitted when a token's supply changes (mint/burn events). Contains:

• Token Address: The token that was updated

• New Supply: The updated total supply

---

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

• Process both event types — Always check which payload variant is present in each NewTokenUpdate

• Handle optional fields — Many metadata fields are optional; check for presence before accessing