FortiBlox LogoFortiBlox Docs
NexusGeyser API

Transaction Endpoints

Query and search X1 Blockchain transactions with advanced filtering

Transaction Endpoints

The Geyser API provides powerful endpoints for querying X1 Blockchain transactions with advanced filtering, pagination, and commitment level support.

Endpoints Overview

EndpointMethodDescriptionCredits
/geyser/transactionsGETList recent transactions10
/geyser/transaction/:signatureGETGet transaction by signature5
/geyser/transactions/latestGETGet latest transactions10
/geyser/account/:address/transactionsGETGet transactions for account15
/geyser/transactions/searchPOSTAdvanced transaction search25
/geyser/transactions/batchPOSTBatch transaction lookup50

GET /geyser/transactions

Get a paginated list of recent transactions.

HTTP Method: GET

Endpoint: https://nexus.fortiblox.com/geyser/transactions

Authentication: API key via X-API-Key header or Authorization: Bearer header

Query Parameters

ParameterTypeRequiredDefaultDescription
limitintegerNo50Number of transactions to return (max 1000)
offsetintegerNo0Pagination offset for retrieving subsequent pages
commitmentstringNoconfirmedCommitment level: processed | confirmed | finalized

Response Fields

FieldTypeDescription
successbooleanWhether request succeeded
dataarrayArray of transaction objects
data[].signaturestringBase58-encoded transaction signature (unique identifier)
data[].slotstringSlot number in which transaction was processed
data[].block_timenumberUnix timestamp of block production time
data[].feestringTransaction fee paid in lamports
data[].successbooleanWhether transaction succeeded (true) or failed (false)
data[].errobject | nullError details if transaction failed, null if succeeded
data[].signerstringBase58-encoded public key of transaction signer
data[].num_instructionsnumberTotal number of instructions in transaction
data[].num_accountsnumberNumber of accounts involved in transaction
data[].is_votebooleanWhether this is a validator vote transaction
data[].transaction_typestringType of transaction (transfer, swap, stake, etc.)
data[].program_idstringPrimary program ID involved in the transaction
data[].created_atstringISO 8601 timestamp when transaction was indexed
commitmentstringCommitment level used for query
pagination.limitnumberLimit parameter used
pagination.offsetnumberOffset parameter used
metaobjectResponse metadata (see Response Format section)

Request Example

curl "https://nexus.fortiblox.com/geyser/transactions?limit=50&offset=0&commitment=confirmed" \
  -H "X-API-Key: $FORTIBLOX_API_KEY"
const response = await fetch(
  'https://nexus.fortiblox.com/geyser/transactions?limit=50&offset=0&commitment=confirmed',
  {
    headers: {
      'X-API-Key': process.env.FORTIBLOX_API_KEY
    }
  }
);
const data = await response.json();

if (data.success) {
  data.data.forEach(tx => {
    console.log(`${tx.signature} - Slot: ${tx.slot}`);
  });
}
import requests
import os

response = requests.get(
    'https://nexus.fortiblox.com/geyser/transactions',
    params={
        'limit': 50,
        'offset': 0,
        'commitment': 'confirmed'
    },
    headers={'X-API-Key': os.getenv('FORTIBLOX_API_KEY')}
)
data = response.json()

if data['success']:
    for tx in data['data']:
        print(f"{tx['signature']} - Slot: {tx['slot']}")

Response Schema

{
  "success": true,
  "data": [
    {
      "signature": "5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7",
      "slot": "123456789",
      "block_time": 1699564800,
      "fee": "5000",
      "success": true,
      "err": null,
      "signer": "9B5XszUGdMaxCZ7uSQhPzdks5ZQSmWxrmzCSvtJ6Ns6g",
      "num_instructions": 3,
      "num_accounts": 8,
      "is_vote": false,
      "transaction_type": "transfer",
      "program_id": "11111111111111111111111111111111",
      "created_at": "2025-11-24T13:36:07.656Z"
    }
  ],
  "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
    }
  }
}

GET /geyser/transaction/:signature

Get detailed information about a specific transaction by its signature.

Parameters

ParameterTypeRequiredDefaultDescription
signaturestringYes-Transaction signature (base58)
commitmentstringNoconfirmedCommitment level

Request Example

SIGNATURE="5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7"

curl "https://nexus.fortiblox.com/geyser/transaction/${SIGNATURE}?commitment=finalized" \
  -H "X-API-Key: $FORTIBLOX_API_KEY"
const signature = "5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7";

const response = await fetch(
  `https://nexus.fortiblox.com/geyser/transaction/${signature}?commitment=finalized`,
  {
    headers: {
      'X-API-Key': process.env.FORTIBLOX_API_KEY
    }
  }
);
const data = await response.json();

if (data.success) {
  console.log('Transaction details:', data.data);
}
import requests
import os

signature = "5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7"

response = requests.get(
    f'https://nexus.fortiblox.com/geyser/transaction/{signature}',
    params={'commitment': 'finalized'},
    headers={'X-API-Key': os.getenv('FORTIBLOX_API_KEY')}
)
data = response.json()

if data['success']:
    print('Transaction details:', data['data'])

Response Schema

{
  "success": true,
  "data": {
    "signature": "5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7",
    "slot": "123456789",
    "block_time": 1699564800,
    "fee": "5000",
    "success": true,
    "err": null,
    "signer": "9B5XszUGdMaxCZ7uSQhPzdks5ZQSmWxrmzCSvtJ6Ns6g",
    "num_instructions": 3,
    "num_accounts": 8,
    "is_vote": false,
    "transaction_type": "transfer",
    "program_id": "11111111111111111111111111111111",
    "created_at": "2025-11-24T13:36:07.656Z",
    "recent_blockhash": "EkSnNWid2cvwEVnVx9aBqawnmiCNiDgp3gUdkDPTKN1N",
    "account_keys": [
      "9B5XszUGdMaxCZ7uSQhPzdks5ZQSmWxrmzCSvtJ6Ns6g",
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
    ]
  },
  "commitment": "finalized",
  "meta": {
    "timestamp": "2025-11-24T13:36:07.656Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "cached": true,
    "path": "/geyser/transaction/5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7",
    "method": "GET",
    "rateLimit": {
      "remaining": 998,
      "limit": 1000,
      "reset": 1763991540
    }
  }
}

Error Response (404)

{
  "success": false,
  "error": "Transaction not found",
  "signature": "invalid_signature_here"
}

GET /geyser/transactions/latest

Get the most recent transactions, optimized for real-time displays.

Parameters

ParameterTypeRequiredDefaultDescription
limitintegerNo20Number of transactions (max 100)

Request Example

curl "https://nexus.fortiblox.com/geyser/transactions/latest?limit=20" \
  -H "X-API-Key: $FORTIBLOX_API_KEY"
const response = await fetch(
  'https://nexus.fortiblox.com/geyser/transactions/latest?limit=20',
  {
    headers: {
      'X-API-Key': process.env.FORTIBLOX_API_KEY
    }
  }
);
const data = await response.json();

if (data.success) {
  console.log(`Latest ${data.data.length} transactions:`);
  data.data.forEach(tx => {
    console.log(`  ${tx.signature.substring(0, 20)}... - Fee: ${tx.fee} lamports`);
  });
}
import requests
import os

response = requests.get(
    'https://nexus.fortiblox.com/geyser/transactions/latest',
    params={'limit': 20},
    headers={'X-API-Key': os.getenv('FORTIBLOX_API_KEY')}
)
data = response.json()

if data['success']:
    print(f"Latest {len(data['data'])} transactions:")
    for tx in data['data']:
        print(f"  {tx['signature'][:20]}... - Fee: {tx['fee']} lamports")

This endpoint has a shorter cache TTL (5 seconds) for real-time applications. Vote transactions are excluded by default.


GET /geyser/account/:address/transactions

Get all transactions involving a specific account address.

Parameters

ParameterTypeRequiredDefaultDescription
addressstringYes-X1 Blockchain account address (base58)
limitintegerNo50Number of transactions (max 1000)
offsetintegerNo0Pagination offset
commitmentstringNoconfirmedCommitment level

Request Example

ADDRESS="9B5XszUGdMaxCZ7uSQhPzdks5ZQSmWxrmzCSvtJ6Ns6g"

curl "https://nexus.fortiblox.com/geyser/account/${ADDRESS}/transactions?limit=50&offset=0" \
  -H "X-API-Key: $FORTIBLOX_API_KEY"
const address = "9B5XszUGdMaxCZ7uSQhPzdks5ZQSmWxrmzCSvtJ6Ns6g";

const response = await fetch(
  `https://nexus.fortiblox.com/geyser/account/${address}/transactions?limit=50&offset=0`,
  {
    headers: {
      'X-API-Key': process.env.FORTIBLOX_API_KEY
    }
  }
);
const data = await response.json();

if (data.success) {
  console.log(`Transactions for ${address}:`);
  data.data.forEach(tx => {
    console.log(`  ${tx.signature} - ${new Date(tx.block_time * 1000).toISOString()}`);
  });
}
import requests
import os
from datetime import datetime

address = "9B5XszUGdMaxCZ7uSQhPzdks5ZQSmWxrmzCSvtJ6Ns6g"

response = requests.get(
    f'https://nexus.fortiblox.com/geyser/account/{address}/transactions',
    params={
        'limit': 50,
        'offset': 0
    },
    headers={'X-API-Key': os.getenv('FORTIBLOX_API_KEY')}
)
data = response.json()

if data['success']:
    print(f"Transactions for {address}:")
    for tx in data['data']:
        timestamp = datetime.fromtimestamp(tx['block_time']).isoformat()
        print(f"  {tx['signature']} - {timestamp}")

Use Case: Portfolio Tracker

async function getWalletActivity(address, daysBack = 7) {
  const response = await fetch(
    `https://nexus.fortiblox.com/geyser/account/${address}/transactions?limit=1000`,
    {
      headers: {
        'X-API-Key': process.env.FORTIBLOX_API_KEY
      }
    }
  );
  const data = await response.json();

  if (!data.success) return [];

  const cutoffTime = Date.now() / 1000 - (daysBack * 24 * 60 * 60);
  const recentTxs = data.data.filter(tx => tx.block_time >= cutoffTime);

  return recentTxs;
}

POST /geyser/transactions/search

Advanced transaction search with complex filtering capabilities.

Request Body

ParameterTypeRequiredDescription
filtersobjectYesSearch filters object
filters.transaction_typestringNoTransaction type: transfer, swap, mint, burn, vote, stake, delegation, liquidation
filters.programstringNoProgram ID to filter by
filters.accountstring/arrayNoAccount address(es) to filter by
filters.start_timestring/numberNoISO 8601 timestamp or Unix timestamp (seconds)
filters.end_timestring/numberNoISO 8601 timestamp or Unix timestamp (seconds)
filters.statusstringNosuccess, failed, pending, or all
filters.min_amountstringNoMinimum token amount (in smallest unit)
filters.max_amountstringNoMaximum token amount
filters.token_mintstringNoToken mint address (for amount filtering)
filters.min_feenumberNoMinimum fee in lamports
filters.max_feenumberNoMaximum fee in lamports
filters.limitintegerNoResults per page (1-100, default 50)
filters.offsetintegerNoPagination offset

Request Examples

# Find all successful token transfers in the last 24 hours
curl -X POST "https://nexus.fortiblox.com/geyser/transactions/search?api-key=$FORTIBLOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "transaction_type": "transfer",
      "start_time": "2025-11-20T00:00:00Z",
      "status": "success",
      "limit": 50
    }
  }'

# Find large USDC transfers (> 100 USDC)
curl -X POST "https://nexus.fortiblox.com/geyser/transactions/search?api-key=$FORTIBLOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "transaction_type": "transfer",
      "token_mint": "EPjFWdd5Au17BXwoyS7G5Fj306awm3ibB5mWChip4Z1w",
      "min_amount": "100000000",
      "status": "success"
    }
  }'
// Find all swaps for a specific account
const searchSwaps = async (account) => {
  const response = await fetch(
    `https://nexus.fortiblox.com/geyser/transactions/search?api-key=${process.env.FORTIBLOX_API_KEY}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        filters: {
          transaction_type: 'swap',
          account: account,
          status: 'success',
          limit: 100
        }
      })
    }
  );

  const data = await response.json();
  return data.success ? data.data : [];
};

// Find failed transactions with high fees
const searchHighFeeFailed = async () => {
  const response = await fetch(
    `https://nexus.fortiblox.com/geyser/transactions/search?api-key=${process.env.FORTIBLOX_API_KEY}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        filters: {
          status: 'failed',
          min_fee: 100000,
          limit: 50
        }
      })
    }
  );

  const data = await response.json();
  return data.success ? data.data : [];
};
import requests
import os
from datetime import datetime, timedelta

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

def search_transactions(filters):
    """Search transactions with custom filters"""
    response = requests.post(
        f'{BASE_URL}/transactions/search',
        params={'api-key': API_KEY},
        json={'filters': filters}
    )
    data = response.json()
    return data['data'] if data['success'] else []

# Example 1: Find all DEX swaps on Jupiter
jupiter_swaps = search_transactions({
    'transaction_type': 'swap',
    'program': '9W959DqEETiGZocYRCQPaJ6sBmUzgfxXfqGeTEdp3aQP',
    'status': 'success',
    'limit': 100
})

# Example 2: Find account activity in specific time range
account_activity = search_transactions({
    'account': '9B5XszUGdMaxCZ7uSQhPzdks5ZQSmWxrmzCSvtJ6Ns6g',
    'start_time': (datetime.now() - timedelta(days=7)).isoformat(),
    'end_time': datetime.now().isoformat(),
    'limit': 100
})

# Example 3: Find large stake transactions
large_stakes = search_transactions({
    'transaction_type': 'stake',
    'min_fee': 5000,
    'status': 'success'
})

Response Schema

{
  "success": true,
  "data": {
    "transactions": [
      {
        "signature": "...",
        "slot": 123456789,
        "block_time": 1699564800,
        "fee": 5000,
        "success": true,
        "transaction_type": "transfer"
      }
    ],
    "total": 1234,
    "hasMore": true
  }
}

Performance Note: Complex searches with multiple filters may take longer. Use specific filters to improve query performance.


POST /geyser/transactions/batch

Fetch multiple transactions by signature in a single request.

Request Body

ParameterTypeRequiredDescription
signaturesarrayYesArray of transaction signatures (max 100)
commitmentstringNoCommitment level (default: confirmed)

Request Example

curl -X POST "https://nexus.fortiblox.com/geyser/transactions/batch?api-key=$FORTIBLOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signatures": [
      "5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7",
      "3nqNkT8dpJ7PEqVhFHFqFZQGJhmYhqh8fPzZwqFkjfkj3Z2h1qH6Kz4bXqZ8p2L5MzZ3h2f1gHqY8kZ4bX"
    ],
    "commitment": "finalized"
  }'
const signatures = [
  "5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7",
  "3nqNkT8dpJ7PEqVhFHFqFZQGJhmYhqh8fPzZwqFkjfkj3Z2h1qH6Kz4bXqZ8p2L5MzZ3h2f1gHqY8kZ4bX"
];

const response = await fetch(
  `https://nexus.fortiblox.com/geyser/transactions/batch?api-key=${process.env.FORTIBLOX_API_KEY}`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ signatures, commitment: 'finalized' })
  }
);

const data = await response.json();
if (data.success) {
  data.data.forEach(tx => {
    console.log(`${tx.signature}: ${tx.success ? 'Success' : 'Failed'}`);
  });
}
import requests
import os

signatures = [
    "5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7",
    "3nqNkT8dpJ7PEqVhFHFqFZQGJhmYhqh8fPzZwqFkjfkj3Z2h1qH6Kz4bXqZ8p2L5MzZ3h2f1gHqY8kZ4bX"
]

response = requests.post(
    'https://nexus.fortiblox.com/geyser/transactions/batch',
    params={'api-key': os.getenv('FORTIBLOX_API_KEY')},
    json={'signatures': signatures, 'commitment': 'finalized'}
)

data = response.json()
if data['success']:
    for tx in data['data']:
        status = 'Success' if tx['success'] else 'Failed'
        print(f"{tx['signature']}: {status}")

Best Practices

Do This

  • Use specific filters in search queries to reduce response time
  • Cache results on your application side when possible
  • Use finalized commitment for financial transactions
  • Implement pagination for large result sets
  • Use batch endpoints when fetching multiple specific transactions

Don't Do This

  • Don't poll /transactions/latest more than once per second
  • Don't use limit=1000 if you only need 10 results
  • Don't fetch the same transaction multiple times - cache it
  • Don't use processed commitment for permanent records
  • Don't make sequential requests when batch endpoints are available

Error Handling

async function safeGetTransaction(signature) {
  try {
    const response = await fetch(
      `https://nexus.fortiblox.com/geyser/transaction/${signature}`,
      {
        headers: {
          'X-API-Key': process.env.FORTIBLOX_API_KEY
        }
      }
    );
    const data = await response.json();

    if (!data.success) {
      if (response.status === 404) {
        console.log('Transaction not found');
      } else if (response.status === 429) {
        console.log('Rate limited - retry after', response.headers.get('Retry-After'));
      } else {
        console.error('Error:', data.error);
      }
      return null;
    }

    return data.data;
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
}

Next Steps