{"id":44643584,"url":"https://github.com/quiknode-labs/hypercore-grpc-examples","last_synced_at":"2026-02-14T19:09:42.589Z","repository":{"id":336360947,"uuid":"1135303558","full_name":"quiknode-labs/hypercore-grpc-examples","owner":"quiknode-labs","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-16T20:18:05.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-04T14:35:06.679Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quiknode-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-15T23:08:01.000Z","updated_at":"2026-01-20T22:56:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/quiknode-labs/hypercore-grpc-examples","commit_stats":null,"previous_names":["quiknode-labs/hypercore-grpc-examples"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/quiknode-labs/hypercore-grpc-examples","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiknode-labs%2Fhypercore-grpc-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiknode-labs%2Fhypercore-grpc-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiknode-labs%2Fhypercore-grpc-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiknode-labs%2Fhypercore-grpc-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quiknode-labs","download_url":"https://codeload.github.com/quiknode-labs/hypercore-grpc-examples/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quiknode-labs%2Fhypercore-grpc-examples/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29452744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T15:52:44.973Z","status":"ssl_error","status_checked_at":"2026-02-14T15:52:11.208Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-14T19:09:42.032Z","updated_at":"2026-02-14T19:09:42.581Z","avatar_url":"https://github.com/quiknode-labs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hyperliquid gRPC Examples\n\ngRPC streaming examples for Hyperliquid with zstd compression support.\n\n## Languages\n\n- **JavaScript** - Node.js with `@grpc/grpc-js`\n- **Python** - `grpcio` with `zstandard`\n- **Go** - `google.golang.org/grpc` with `klauspost/compress`\n- **Rust** - `tonic` with `zstd`\n\n## Proto File\n\nThe proto definition is in `proto/hyperliquid.proto`.\n\n## Stream Types\n\n| Type | Description |\n|------|-------------|\n| `TRADES` | Trade executions |\n| `ORDERS` | Order updates |\n| `EVENTS` | General events |\n| `BOOK_UPDATES` | Order book changes |\n| `TWAP` | TWAP orders |\n| `BLOCKS` | Raw blocks |\n| `WRITER_ACTIONS` | Writer actions |\n\n## Filtering\n\nEach language includes a dedicated `filter_example` file demonstrating server-side filtering.\n\n### Filter Example Files\n\n```bash\n# JavaScript\nnode filter_example.js\n\n# Python\npython filter_example.py\n\n# Go\ngo run filter_example.go\n\n# Rust\ncargo run --bin filter_example\n```\n\n### How Filters Work\n\nFilters are applied server-side via the `filters` field in the subscription request:\n\n```javascript\n// JavaScript example\ncall.write({\n  subscribe: {\n    stream_type: 'TRADES',\n    filters: {\n      coin: { values: ['ETH', 'BTC'] },\n      user: { values: ['0x123...'] }\n    },\n    filter_name: 'my-filter'\n  }\n});\n```\n\n### CLI Filtering (main examples)\n\nThe main examples also support filtering via command line:\n\n```bash\n# JavaScript\nnode index.js TRADES --filter coin=ETH,BTC --filter user=0x123\n\n# Python\npython main.py TRADES --filter coin=ETH,BTC\n\n# Go\ngo run main.go -stream TRADES -filter \"coin=ETH,BTC;user=0x123\"\n\n# Rust\ncargo run --bin main -- -s TRADES -f coin=ETH,BTC -f user=0x123\n```\n\n## Quick Start\n\n### JavaScript\n\n```bash\ncd javascript\nnpm install\n# Edit index.js to set GRPC_ENDPOINT and AUTH_TOKEN\nnode index.js TRADES\n```\n\n### Python\n\n```bash\ncd python\npip install -r requirements.txt\n./generate_proto.sh\n# Edit main.py to set GRPC_ENDPOINT and AUTH_TOKEN\npython main.py TRADES\n```\n\n### Go\n\n```bash\ncd golang\ngo install google.golang.org/protobuf/cmd/protoc-gen-go@latest\ngo install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest\n./generate_proto.sh\ngo mod tidy\n# Edit main.go to set grpcEndpoint and authToken\ngo run main.go -stream TRADES\n```\n\n### Rust\n\n```bash\ncd rust\n# Edit src/main.rs to set GRPC_ENDPOINT and AUTH_TOKEN\ncargo run -- -s TRADES\n```\n\n## Configuration\n\nEach example requires:\n\n1. **GRPC_ENDPOINT** - Your QuickNode endpoint (e.g., `your-endpoint.hype-mainnet.quiknode.pro:10000`)\n2. **AUTH_TOKEN** - Your authentication token\n\n### Connection Requirements\n\n- **Port**: `10000` (gRPC streaming port)\n- **TLS**: Required - all connections must use TLS/SSL\n- **Authentication**: Pass your token via the `x-token` metadata header\n\n## Zstd Compression\n\nAll examples automatically detect and decompress zstd-compressed data by checking for the magic number `0x28 0xB5 0x2F 0xFD`.\n\n## Connection Management\n\ngRPC streams are long-lived connections that can disconnect due to network issues, server restarts, or idle timeouts. Production systems should implement proper connection management.\n\n### Keep-Alive Pings\n\nThe server expects periodic pings to keep the connection alive. The examples send pings every 30 seconds:\n\n```javascript\n// JavaScript\nsetInterval(() =\u003e {\n  call.write({ ping: { timestamp: Date.now() } });\n}, 30000);\n```\n\n```python\n# Python\nyield pb.SubscribeRequest(ping=pb.Ping(timestamp=int(time.time() * 1000)))\n```\n\nThe server responds with a `pong` message. If you stop receiving pongs, the connection may be dead.\n\n### Reconnection Strategy\n\nWhen a disconnect occurs, implement exponential backoff:\n\n```\nAttempt 1: Wait 1s\nAttempt 2: Wait 2s\nAttempt 3: Wait 4s\nAttempt 4: Wait 8s\n...\nMax backoff: 60s\n```\n\n### Handling Missed Blocks\n\nWhen your connection drops, you'll miss blocks. On reconnect:\n\n1. Track the last `block_number` you received\n2. Reconnect with `start_block` set to resume from where you left off\n3. For the `BLOCKS` stream specifically, historical data isn't available via gRPC - see the `replicaCmdsOnS3Example` for backfilling from the Hyperliquid Foundation S3 bucket\n\n### Example Reconnect Flow\n\n```\n1. Connect to gRPC stream\n2. Subscribe with start_block=0 (or last known block)\n3. Process incoming data, track last block_number\n4. Send pings every 30s\n5. On disconnect:\n   - Log last block_number received\n   - Wait with exponential backoff\n   - Reconnect and subscribe with start_block=last_block_number\n6. Repeat\n```\n\n**Note:** These examples are starting points. Production systems should add error handling, metrics, circuit breakers, and dead letter queues based on your reliability requirements.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquiknode-labs%2Fhypercore-grpc-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquiknode-labs%2Fhypercore-grpc-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquiknode-labs%2Fhypercore-grpc-examples/lists"}