Geyser API

The FortiBlox Geyser API provides high-performance REST endpoints for querying historical and real-time X1 Blockchain data. All data is sourced from our TimescaleDB Geyser database, providing fast, indexed access to transactions, blocks, validators, and account data.

What is Geyser API?

Geyser API is FortiBlox's SQL-backed REST API that gives you structured access to complete X1 Blockchain history. Unlike standard RPC nodes that may prune historical data, our Geyser API maintains full historical records optimized for analytics and application queries.

Key Features

• Complete Historical Data: Access transactions, blocks, and account data from genesis
• High Performance: Sub-100ms response times with Redis caching
• Advanced Filtering: Filter transactions by type, program, account, time range, and more
• SQL-Powered: Built on TimescaleDB for time-series optimized queries
• Commitment Levels: Support for processed, confirmed, and finalized data
• Pagination: Efficient cursor-based pagination for large datasets

Use Cases

Transaction Monitoring

Monitor all transactions for specific accounts, programs, or transaction types:

• Track DEX swaps in real-time
• Monitor NFT marketplace activity
• Analyze staking behavior
• Audit account activity

Analytics & Reporting

Build analytics dashboards and reports:

• Calculate transaction volumes by time period
• Analyze fee trends and network activity
• Track validator performance
• Generate historical snapshots

Application Backends

Power your X1 Blockchain applications:

• Transaction history displays
• Portfolio tracking
• DeFi protocol integration
• Block explorers

Research & Development

Academic and research applications:

• Network analysis
• Economic modeling
• Security research
• Protocol development

Authentication

All Geyser API endpoints require authentication via API key. Include your API key using one of these HTTP headers:

X-API-Key Header (Recommended)

curl https://nexus.fortiblox.com/geyser/transactions \
  -H "X-API-Key: YOUR_API_KEY"

Authorization Bearer Header

curl https://nexus.fortiblox.com/geyser/transactions \
  -H "Authorization: Bearer YOUR_API_KEY"

Base URL

https://nexus.fortiblox.com/geyser

All endpoints are prefixed with /geyser.

Rate Limits

Rate limits vary by subscription tier:

When you exceed the rate limit, you'll receive a 429 Too Many Requests response with a Retry-After header.

Credit Costs

Each Geyser API request consumes credits based on complexity:

Commitment Levels

The Geyser API supports X1 Blockchain's standard commitment levels for querying data:

processed

• Speed: Fastest (200-400ms behind current slot)
• Finality: Lowest - transaction may be rolled back
• Use Case: Real-time displays, not financial transactions

confirmed (default)

• Speed: Fast (2-3 seconds behind current slot)
• Finality: Medium - very low chance of rollback (~0.01%)
• Use Case: Most applications, real-time dashboards

finalized

• Speed: Slower (30-45 seconds behind current slot)
• Finality: Highest - guaranteed permanent
• Use Case: Financial applications, permanent records

Specify commitment level using the commitment query parameter:

curl "https://nexus.fortiblox.com/geyser/transactions?commitment=finalized" \
  -H "X-API-Key: YOUR_API_KEY"

Response Format

All Geyser API responses follow a consistent JSON structure:

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "commitment": "confirmed",
  "pagination": {
    "limit": 50,
    "offset": 0
  },
  "meta": {
    "timestamp": "2025-11-24T13:36:07.656Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "cached": false,
    "path": "/geyser/transactions",
    "method": "GET",
    "rateLimit": {
      "remaining": 999,
      "limit": 1000,
      "reset": 1763991540
    }
  }
}

Response Metadata

Every response includes a meta object with:

Error Response

{
  "success": false,
  "error": "Error type",
  "message": "Detailed error message",
  "error_code": "ERROR_CODE"
}

Common Error Codes

Caching Strategy

The Geyser API uses intelligent Redis-based caching to ensure fast response times:

Response Headers

The API returns these HTTP headers with every response:

You can use these headers for monitoring, debugging, and performance tracking.

Pagination

List endpoints support pagination using limit and offset parameters:

# Get first 50 transactions
curl "https://nexus.fortiblox.com/geyser/transactions?limit=50&offset=0" \
  -H "X-API-Key: YOUR_API_KEY"

# Get next 50 transactions
curl "https://nexus.fortiblox.com/geyser/transactions?limit=50&offset=50" \
  -H "X-API-Key: YOUR_API_KEY"

Limits:

• Default: 50
• Maximum: 1000 per request
• Use smaller limits for faster responses

Available Endpoints

Quick Start Example

# Get latest transactions
curl "https://nexus.fortiblox.com/geyser/transactions/latest?limit=10" \
  -H "X-API-Key: $FORTIBLOX_API_KEY"

# Get specific transaction
curl "https://nexus.fortiblox.com/geyser/transaction/5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7" \
  -H "X-API-Key: $FORTIBLOX_API_KEY"

# Get latest block
curl "https://nexus.fortiblox.com/geyser/blocks/latest" \
  -H "X-API-Key: $FORTIBLOX_API_KEY"

const FORTIBLOX_API_KEY = process.env.FORTIBLOX_API_KEY;
const BASE_URL = 'https://nexus.fortiblox.com/geyser';

async function getLatestTransactions() {
  const response = await fetch(
    `${BASE_URL}/transactions/latest?limit=10`,
    {
      headers: {
        'X-API-Key': FORTIBLOX_API_KEY
      }
    }
  );
  const data = await response.json();

  if (data.success) {
    console.log('Latest transactions:', data.data);
  } else {
    console.error('Error:', data.error);
  }
}

async function getTransaction(signature) {
  const response = await fetch(
    `${BASE_URL}/transaction/${signature}`,
    {
      headers: {
        'X-API-Key': FORTIBLOX_API_KEY
      }
    }
  );
  const data = await response.json();

  if (data.success) {
    console.log('Transaction:', data.data);
  } else {
    console.error('Error:', data.error);
  }
}

getLatestTransactions();

import os
import requests

FORTIBLOX_API_KEY = os.getenv('FORTIBLOX_API_KEY')
BASE_URL = 'https://nexus.fortiblox.com/geyser'

def get_latest_transactions(limit=10):
    response = requests.get(
        f'{BASE_URL}/transactions/latest',
        params={'limit': limit},
        headers={'X-API-Key': FORTIBLOX_API_KEY}
    )
    data = response.json()

    if data['success']:
        print('Latest transactions:', data['data'])
    else:
        print('Error:', data['error'])

def get_transaction(signature):
    response = requests.get(
        f'{BASE_URL}/transaction/{signature}',
        headers={'X-API-Key': FORTIBLOX_API_KEY}
    )
    data = response.json()

    if data['success']:
        print('Transaction:', data['data'])
    else:
        print('Error:', data['error'])

get_latest_transactions()

Next Steps

• Transaction Endpoints - Query and search transactions
• Block Endpoints - Access block data
• Validator Endpoints - Get validator information
• Account Endpoints - Query account data

Support

Need help with the Geyser API?

• Discord: discord.gg/fortiblox
• Email: [email protected]
• Documentation: You're already here!
• Status Page: status.fortiblox.com