GetFills - Get Fill Data

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "os"
    "time"

    pb "hyperliquid-grpc-client/api/v2"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/metadata"
)

type FillEvent struct {
    Coin          string  `json:"coin"`
    Px            string  `json:"px"`
    Sz            string  `json:"sz"`
    Side          string  `json:"side"`
    Time          int64   `json:"time"`
    StartPosition string  `json:"startPosition"`
    Dir           string  `json:"dir"`
    ClosedPnl     string  `json:"closedPnl"`
    Hash          string  `json:"hash"`
    Oid           int64   `json:"oid"`
    Crossed       bool    `json:"crossed"`
    Fee           string  `json:"fee"`
    Tid           int64   `json:"tid"`
    Cloid         string  `json:"cloid,omitempty"`
    FeeToken      string  `json:"feeToken"`
}

type FillsData struct {
    LocalTime   string          `json:"local_time"`
    BlockTime   string          `json:"block_time"`
    BlockNumber int64           `json:"block_number"`
    Events      [][]interface{} `json:"events"`
}

func getFills(ctx context.Context, client pb.HyperliquidL1GatewayClient, position *pb.Position) (*FillsData, error) {
    ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
    defer cancel()

    response, err := client.GetFills(ctx, position)
    if err != nil {
        return nil, fmt.Errorf("RPC call failed: %v", err)
    }

    fmt.Printf("Response size: %d bytes\n\n", len(response.Data))

    var fills FillsData
    if err := json.Unmarshal(response.Data, &fills); err != nil {
        return nil, fmt.Errorf("failed to parse JSON: %v", err)
    }

    return &fills, nil
}

func main() {
    endpoint := os.Getenv("HYPERLIQUID_ENDPOINT")
    apiKey := os.Getenv("API_KEY")

    if endpoint == "" {
        log.Fatal("Error: HYPERLIQUID_ENDPOINT environment variable is required.")
    }

    if apiKey == "" {
        log.Fatal("Error: API_KEY environment variable is required.")
    }

    fmt.Println("Hyperliquid Go gRPC Client - Get Fills")
    fmt.Println("======================================")
    fmt.Printf("Endpoint: %s\n\n", endpoint)

    creds := credentials.NewTLS(nil)

    opts := []grpc.DialOption{
        grpc.WithTransportCredentials(creds),
        grpc.WithDefaultCallOptions(
            grpc.MaxCallRecvMsgSize(150 * 1024 * 1024),
        ),
    }

    fmt.Println("Connecting to gRPC server...")
    conn, err := grpc.NewClient(endpoint, opts...)
    if err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    defer conn.Close()

    client := pb.NewHyperliquidL1GatewayClient(conn)
    fmt.Println("Connected successfully!\n")

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

    // Request latest fills (empty position)
    request := &pb.Position{}

    // Or request by block height:
    // request := &pb.Position{Position: &pb.Position_BlockHeight{BlockHeight: 676607012}}

    fmt.Println("Fetching fills...\n")

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

    // Display fills information
    fmt.Printf("Block Number: %d\n", fills.BlockNumber)
    fmt.Printf("Block Time: %s\n", fills.BlockTime)
    fmt.Printf("Local Time: %s\n", fills.LocalTime)
    fmt.Printf("Fill Events: %d\n\n", len(fills.Events))

    // Process each fill event
    for i, event := range fills.Events {
        if len(event) >= 2 {
            address := event[0].(string)
            fillData, _ := json.Marshal(event[1])
            var fill FillEvent
            json.Unmarshal(fillData, &fill)

            fmt.Printf("Fill #%d:\n", i+1)
            fmt.Printf("  Address: %s\n", address)
            fmt.Printf("  Coin: %s\n", fill.Coin)
            fmt.Printf("  Side: %s\n", fill.Side)
            fmt.Printf("  Price: %s\n", fill.Px)
            fmt.Printf("  Size: %s\n", fill.Sz)
            fmt.Printf("  Direction: %s\n", fill.Dir)
            fmt.Printf("  Fee: %s %s\n", fill.Fee, fill.FeeToken)
            fmt.Println()
        }
    }
}

import grpc
import json
import sys
import os
from datetime import datetime
from dotenv import load_dotenv
import hyperliquid_pb2
import hyperliquid_pb2_grpc

load_dotenv()

def get_fills(block_height=None, timestamp_ms=None):
    endpoint = os.getenv('HYPERLIQUID_ENDPOINT')
    api_key = os.getenv('API_KEY')

    if not endpoint:
        print("Error: HYPERLIQUID_ENDPOINT environment variable is required.")
        sys.exit(1)

    if not api_key:
        print("Error: API_KEY environment variable is required.")
        sys.exit(1)

    print('Hyperliquid Python gRPC Client - Get Fills')
    print('==========================================')
    print(f'Endpoint: {endpoint}\n')

    credentials = grpc.ssl_channel_credentials()

    options = [
        ('grpc.max_receive_message_length', 150 * 1024 * 1024),
    ]

    metadata = [('x-api-key', api_key)]

    print('Connecting to gRPC server...')
    with grpc.secure_channel(endpoint, credentials, options=options) as channel:
        client = hyperliquid_pb2_grpc.HyperliquidL1GatewayStub(channel)
        print('Connected successfully!\n')

        # Create request based on parameters
        if block_height is not None:
            request = hyperliquid_pb2.Position(block_height=block_height)
            print(f'Requesting fills at block height: {block_height}')
        elif timestamp_ms is not None:
            request = hyperliquid_pb2.Position(timestamp_ms=timestamp_ms)
            print(f'Requesting fills at timestamp: {timestamp_ms}')
        else:
            request = hyperliquid_pb2.Position()
            print('Requesting latest fills')

        print('\nFetching fills...\n')

        try:
            response = client.GetFills(request, metadata=metadata)
            print(f'Response size: {len(response.data)} bytes\n')

            process_fills(response.data)

        except grpc.RpcError as e:
            print(f'RPC error: {e}')
        except Exception as e:
            print(f'Error: {e}')

def process_fills(data):
    try:
        fills = json.loads(data.decode('utf-8'))

        print('FILLS DATA')
        print('==========')

        print(f'Block Number: {fills.get("block_number")}')
        print(f'Block Time: {fills.get("block_time")}')
        print(f'Local Time: {fills.get("local_time")}')

        events = fills.get('events', [])
        print(f'Fill Events: {len(events)}\n')

        # Aggregate statistics
        total_volume = 0
        total_pnl = 0
        coins_traded = set()
        buy_count = 0
        sell_count = 0

        for i, event in enumerate(events):
            if len(event) >= 2:
                address = event[0]
                fill = event[1]

                coins_traded.add(fill.get('coin', ''))

                size = float(fill.get('sz', 0))
                price = float(fill.get('px', 0))
                total_volume += size * price

                pnl = float(fill.get('closedPnl', 0))
                total_pnl += pnl

                if fill.get('side') == 'B':
                    buy_count += 1
                else:
                    sell_count += 1

                # Display first 5 fills in detail
                if i < 5:
                    print(f'Fill #{i + 1}:')
                    print(f'  Address: {address}')
                    print(f'  Coin: {fill.get("coin")}')
                    print(f'  Side: {"Buy" if fill.get("side") == "B" else "Sell"}')
                    print(f'  Price: {fill.get("px")}')
                    print(f'  Size: {fill.get("sz")}')
                    print(f'  Direction: {fill.get("dir")}')
                    print(f'  Closed PnL: {fill.get("closedPnl")}')
                    print(f'  Fee: {fill.get("fee")} {fill.get("feeToken")}')
                    print()

        if len(events) > 5:
            print(f'... and {len(events) - 5} more fills\n')

        # Summary
        print('SUMMARY')
        print('=======')
        print(f'Total Fills: {len(events)}')
        print(f'Buys: {buy_count}, Sells: {sell_count}')
        print(f'Coins Traded: {", ".join(coins_traded)}')
        print(f'Total Volume: ${total_volume:,.2f}')
        print(f'Total Realized PnL: ${total_pnl:,.4f}')

    except json.JSONDecodeError as e:
        print(f'Failed to parse JSON: {e}')
    except Exception as e:
        print(f'Error processing fills: {e}')

if __name__ == '__main__':
    # Get latest fills
    get_fills()

    # Or get by block height:
    # get_fills(block_height=676607012)

    # Or get by timestamp:
    # get_fills(timestamp_ms=1753606210273)

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const path = require('path');
require('dotenv').config();

const PROTO_PATH = path.join(__dirname, 'v2.proto');

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

const proto = grpc.loadPackageDefinition(packageDefinition);

async function getFills(options = {}) {
    const endpoint = process.env.HYPERLIQUID_ENDPOINT;
    const apiKey = process.env.API_KEY;

    if (!endpoint) {
        console.error('Error: HYPERLIQUID_ENDPOINT environment variable is required.');
        process.exit(1);
    }

    if (!apiKey) {
        console.error('Error: API_KEY environment variable is required.');
        process.exit(1);
    }

    console.log('Hyperliquid Node.js gRPC Client - Get Fills');
    console.log('===========================================');
    console.log(`Endpoint: ${endpoint}\n`);

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

    const client = new proto.hyperliquid_l1_gateway.v2.HyperliquidL1Gateway(
        endpoint,
        grpc.credentials.createSsl(),
        {
            'grpc.max_receive_message_length': 150 * 1024 * 1024
        }
    );

    // Build request
    const request = {};
    if (options.blockHeight) {
        request.block_height = options.blockHeight;
        console.log(`Requesting fills at block height: ${options.blockHeight}`);
    } else if (options.timestampMs) {
        request.timestamp_ms = options.timestampMs;
        console.log(`Requesting fills at timestamp: ${options.timestampMs}`);
    } else {
        console.log('Requesting latest fills');
    }

    console.log('\nFetching fills...\n');

    client.GetFills(request, metadata, (error, response) => {
        if (error) {
            console.error('gRPC error:', error.message);
            return;
        }

        try {
            const fills = JSON.parse(response.data);
            console.log(`Response size: ${response.data.length} bytes\n`);

            processFills(fills);

        } catch (error) {
            console.error('Failed to parse response:', error.message);
        }
    });
}

function processFills(fills) {
    console.log('FILLS DATA');
    console.log('==========');

    console.log(`Block Number: ${fills.block_number}`);
    console.log(`Block Time: ${fills.block_time}`);
    console.log(`Local Time: ${fills.local_time}`);

    const events = fills.events || [];
    console.log(`Fill Events: ${events.length}\n`);

    // Aggregate statistics
    let totalVolume = 0;
    let totalPnl = 0;
    const coinsTraded = new Set();
    let buyCount = 0;
    let sellCount = 0;

    for (let i = 0; i < events.length; i++) {
        const event = events[i];
        if (event.length >= 2) {
            const address = event[0];
            const fill = event[1];

            coinsTraded.add(fill.coin || '');

            const size = parseFloat(fill.sz || 0);
            const price = parseFloat(fill.px || 0);
            totalVolume += size * price;

            const pnl = parseFloat(fill.closedPnl || 0);
            totalPnl += pnl;

            if (fill.side === 'B') {
                buyCount++;
            } else {
                sellCount++;
            }

            // Display first 5 fills in detail
            if (i < 5) {
                console.log(`Fill #${i + 1}:`);
                console.log(`  Address: ${address}`);
                console.log(`  Coin: ${fill.coin}`);
                console.log(`  Side: ${fill.side === 'B' ? 'Buy' : 'Sell'}`);
                console.log(`  Price: ${fill.px}`);
                console.log(`  Size: ${fill.sz}`);
                console.log(`  Direction: ${fill.dir}`);
                console.log(`  Closed PnL: ${fill.closedPnl}`);
                console.log(`  Fee: ${fill.fee} ${fill.feeToken}`);
                console.log();
            }
        }
    }

    if (events.length > 5) {
        console.log(`... and ${events.length - 5} more fills\n`);
    }

    // Summary
    console.log('SUMMARY');
    console.log('=======');
    console.log(`Total Fills: ${events.length}`);
    console.log(`Buys: ${buyCount}, Sells: ${sellCount}`);
    console.log(`Coins Traded: ${[...coinsTraded].join(', ')}`);
    console.log(`Total Volume: $${totalVolume.toLocaleString(undefined, { minimumFractionDigits: 2 })}`);
    console.log(`Total Realized PnL: $${totalPnl.toFixed(4)}`);
}

// Get latest fills
getFills();

// Or get by block height:
// getFills({ blockHeight: 676607012 });

// Or get by timestamp:
// getFills({ timestampMs: 1753606210273 });