IBRL API Documentation

1. Get Blocks

Endpoint: GET /api/v1/ibrl_blocks

Description: Retrieves a list of blocks with IBRL metrics. Returns up to 2000 blocks, ordered by slot in descending order.

Query Parameters

Parameter	Type	Required	Description
`validator`	`string`	No	Filter blocks by validator identity (leader)
`epoch`	`u32`	No	Filter blocks by epoch. If not provided, uses the latest epoch

Response Structure

{
  "data": [
    {
      "slot": 390095996,
      "epoch": 902,
      "leader": "q9XWcZ7T1wP4bW9SB4XgNNwjnFEJ982nE8aVbbNuwot",
      "total_nonvote_tx": 252,
      "total_vote_tx": 803,
      "total_cu_consumed": 18321998,
      "build_time_score": 100.0,
      "vote_packing_score": 98.52,
      "non_vote_packing_score": 90.9,
      "ibrl_score": 95.99
    },
    {
      "slot": 390095995,
      "epoch": 902,
      "leader": "9jxgosAfHgHzwnxsHw4RAZYaLVokMbnYtmiZBreynGFP",
      "total_nonvote_tx": 270,
      "total_vote_tx": 799,
      "total_cu_consumed": 17652824,
      "build_time_score": 100.0,
      "vote_packing_score": 76.47,
      "non_vote_packing_score": 94.34,
      "ibrl_score": 91.8535
    }
  ],
  "timestamp": 1767212372737,
  "epoch": 902
}

Response Fields

Root Object:

data (Array<BlockStats>): Array of block metrics
timestamp (u64): Unix timestamp in milliseconds when the response was generated
epoch (u32): The epoch used for the query

BlockStats Object:

slot (u64): Solana slot number
epoch (u32): Epoch number
leader (string): Validator identity in base58 encoded format
total_nonvote_tx (u64): Total number of non-vote transactions in the block
total_vote_tx (u64): Total number of vote transactions in the block
total_cu_consumed (u64): Total compute units consumed in the block
build_time_score (f64): Build time performance score (0.0 - 100.0)
vote_packing_score (f64): Vote transaction packing efficiency score (0.0 - 100.0)
non_vote_packing_score (f64): Non-vote transaction packing efficiency score (0.0 - 100.0)
ibrl_score (f64): Overall IBRL score combining all metrics (0.0 - 100.0)

2. Get Block Details

Endpoint: GET /api/v1/ibrl_blocks/:block

Description: Retrieves detailed information about a specific block, including per-tick transaction data.

Path Parameters

Parameter	Type	Required	Description
`block`	`u64`	Yes	The slot number of the block

Response Structure

{
  "data": {
    "slot": 390093998,
    "epoch": 902,
    "leader": "DWvDTSh3qfn88UoQTEKRV2JnLt5jtJAVoiCo3ivtMwXP",
    "total_nonvote_tx": 253,
    "total_vote_tx": 792,
    "total_cu_consumed": 15839063,
    "build_time_score": 72.61,
    "vote_packing_score": 99.32,
    "non_vote_packing_score": 96.74,
    "ibrl_score": 88.9395,
    "ticks": [
      {
        "poh_index": 34,
        "nonvote_tx_count": 3,
        "vote_tx_count": 7,
        "total_cu_used": 539500,
        "tx_sigs": [
          "3RFSxDRCDYiLhRRks1tMKwzQrt2Q8tivuQLntLXYnPcQV8se7QPAmbPjbhrqyNbhabpmhBt4LRxAtvJMwbWEiHz2",
          "5XzszTcPFsfxDBXjaEcE1Gr7Y9w9HcmM3BaQU16SYGgo9JojKg3sTcx1tQRGoHNsdanaRXVnXzLJDFPpFXAfKe7c",
          "QThXc4pRYjP6WDbdwC25ENkcC9FExbxJBWAHrSR97XFcyDV8uH8kTSfuhYxjp6wgCDSYWPcfABgXnZzc7cgG929",
          "24QLU2GJ8E7b6m4AotrosGWFMeP2ZJnaTFjVYCDYCXdQcLQZmqz7Y5v62sxdbLs8T3umM1TSLTzUyaoShmh3PSgY",
          "3PKsX74igJSfjoY86RZ74XZsXTCvnGiCMTcJqq7wEQkWv15oXHv1ZyUwDvGuTRGJnqt7GRiMNYh6yRE1P8GdnDgP",
          "2hMt848F13P3p3hrc6YccXbNpK9fE2RypcEAmU3Js9QRvZcYDFpvGRRujrLHzbghJMUUkjbM7zYoCzmDunuCrVzK",
          "BxUHW7AVV5rxB7X5UeB8Jju4kwSJcwEr3xmRdMsUrTRpUjXujuWhdFTXd9LvuSo8dR5arCzVsUu9ZCbJUHDeo8t",
          "4rKLa7dAPt1cunRca59rg6f5cmvvLXEcVhaeAfCjEosE1PregwRNCNidP4DMMjUhAvCp4zvtiZcEQDhLX1pTA4Kb",
          "7RoCbMpzZqNugBrb6LBt2ya6NxexvpEw7eUWMVjeUtrYXtnPK1MoKobDWYEJ3dgpeyy44Z5m4g8bJHDs7cmPbpJ",
          "2iLdgGWAdY753pk9MqcJ1SUkFuGnyma2ZtfvmRUsSGt1zN2oZ8DWnxwWfuebuTYwNoieV59fnsqQUWa9EXKnbkCc"
        ]
      },
      {
        "poh_index": 35,
        "nonvote_tx_count": 3,
        "vote_tx_count": 6,
        "total_cu_used": 219125,
        "tx_sigs": [
          "2juKXqoJPcUfnzYHBaSQkLGhcxrBbQCQXmhCdUa5MDz2JzLiouvucGyMkDnMvAkExtFdj9gAEtaJ1ueNGWqBitJv",
          "3YXmfuczP9kH8fQp7qLjgEasBU25ajvUgpB52gQKXH8kvFN5V7nZjYUG6YviyMjYB1YYzDLsrhdvGfg12tW4DZcp",
          "3qVqNGcoCZaBgWLqx34VHFyz8ua6va7GTx6YUitWPejVBPLLsroHFHMpZfH6hqmqNjd9u5JE3qFw1ArAwMSd7LRN",
          "5J9QqJr2t8WfadGFVLdTGAYsGU4mYDNzP8ySTguBySZdpuudSfmETRZFScSmnYWvW4UegvKD414SDUcqpE9s4RFe",
          "557M6htaS6pfFrEq3NK8rFQdzNRbcnNjKByiWwiJVoQKn3hMut72WSGWNkgxp8k7rRKosS444j8C4RudMM6qNR6P",
          "434ZUQKwkJByZntBMw4ApnkvqLUYNHcXQ7DHDj9MgX12hrDgsNhsj89D9ep5nDFU5Akm5kFY8EHJRjYTonKyfYjw",
          "2rELGT6KVDNzFqWG9DdfCnf2odhZ6CXvSre7i1sdMutt79D1GjL63CbFG7Lr3DT6B8W2UxxpYVV1vpNL6HHZC7TJ",
          "3ZtXWNqGv4uuMNB7uvznA9ijtzWDJV27wCBe3ZQ3FBsXm1io7qVaSZH1yhwA49NJie3eLJQBe7KDiTreN7YMqoLb",
          "vS2wG5uJSywVRRYo3HqjEqoGWRB5BSydsawMWhBk8Fu9iNEusJoJNyG2QdnQuyUFoSzzim7Mh8dy1Cc7YQu72er"
        ]
      }
    ]
  },
  "timestamp": 1767213334767,
  "epoch": 902
}

Response Fields

Root Object:

data (BlockDetail): Detailed block information
timestamp (u64): Unix timestamp in milliseconds when the response was generated
epoch (u32): The epoch of the block

BlockDetail Object:

All fields from BlockStats (see prior endpoint)
ticks (Array<TickData>): Array of per-tick transaction data

TickData Object:

poh_index (u64): Proof of History tick index within the block
nonvote_tx_count (u64): Number of non-vote transactions in this tick
vote_tx_count (u64): Number of vote transactions in this tick
total_cu_used (u64): Total compute units used in this tick
tx_sigs (Array<string>): Array of transaction signatures (base58 encoded) in this tick

3. Get Validators

Endpoint: GET /api/v1/ibrl_validators

Description: Retrieves a list of all validators with their IBRL scores for a given epoch, ordered by IBRL score in descending order.

Query Parameters

Parameter	Type	Required	Description
`epoch`	`u32`	No	Filter by epoch. If not provided, uses the latest epoch

Response Structure

{
  "data": [
    {
      "identity": "J6etcxDdYjPHrtyvDXrbCkx3q9W1UjMj1vy1jBFPJEbK",
      "build_time_score": 31.4005,
      "vote_packing_score": 0.0276,
      "non_vote_packing_score": 37.1216,
      "ibrl_score": 25.8457,
      "client": 0,
      "scheduler_profile": 0,
      "epoch_trend": 0.3943,
      "blocks_produced": 3623
    },
    {
      "identity": "5LNEDitSMhApT2uFnmtN7FmjCiGuatpnb2uU4f3shrk",
      "build_time_score": 24.1559,
      "vote_packing_score": 9.1241,
      "non_vote_packing_score": 32.0824,
      "ibrl_score": 23.5685,
      "client": 0,
      "scheduler_profile": 0,
      "epoch_trend": 10.1312,
      "blocks_produced": 34
    }
  ],
  "timestamp": 1767213525314,
  "epoch": 902
}

Response Fields

Root Object:

data (Array<ValidatorIBRLScore>): Array of validator scores
timestamp (u64): Unix timestamp in milliseconds when the response was generated
epoch (u32): The epoch used for the query

ValidatorIBRLScore Object:

identity (string): Validator identity in base58 encoded format
build_time_score (f64): Average build time performance score (0.0 - 100.0)
vote_packing_score (f64): Average vote packing efficiency score (0.0 - 100.0)
non_vote_packing_score (f64): Average non-vote packing efficiency score (0.0 - 100.0)
ibrl_score (f64): Overall IBRL score combining all metrics (0.0 - 100.0)
client (u8): Client identifier (currently placeholder, always 0)
scheduler_profile (u8): Scheduler profile identifier (currently placeholder, always 0)
epoch_trend (f64): Change in IBRL score from previous epoch (positive = improvement, negative = decline)
blocks_produced (u64): Number of blocks produced by this validator in the epoch

4. Get Validator Details

Endpoint: GET /api/v1/ibrl_validators/:identity

Description: Retrieves detailed information about a specific validator, including current epoch score, historical epoch performance, and recent blocks.

Path Parameters

Parameter	Type	Required	Description
`identity`	`string`	Yes	Validator identity (base58 encoded public key)

Query Parameters

Parameter	Type	Required	Description
`epoch`	`u32`	No	Filter by epoch. If not provided, uses the latest epoch

Response Structure

{
  "data": {
    "validator_score": {
      "identity": "J6etcxDdYjPHrtyvDXrbCkx3q9W1UjMj1vy1jBFPJEbK",
      "build_time_score": 31.4005,
      "vote_packing_score": 0.0276,
      "non_vote_packing_score": 37.1216,
      "ibrl_score": 25.8457,
      "client": 0,
      "scheduler_profile": 0,
      "epoch_trend": 0.3943,
      "blocks_produced": 3623
    },
    "epoch_history": [
      {
        "epoch": 902,
        "build_time_score": 31.4005,
        "vote_packing_score": 0.0276,
        "non_vote_packing_score": 37.1216,
        "ibrl_score": 25.8457,
        "blocks_produced": 3623
      },
      {
        "epoch": 901,
        "build_time_score": 31.4429,
        "vote_packing_score": 0.051,
        "non_vote_packing_score": 36.084,
        "ibrl_score": 25.4514,
        "blocks_produced": 3919
      }
    ],
    "recent_blocks": [
      {
        "slot": 390089775,
        "epoch": 902,
        "tx_count": 1076,
        "cu_used": 20656965,
        "build_time_score": 23.22,
        "vote_packing_score": 0.0,
        "non_vote_packing_score": 28.32,
        "ibrl_score": 19.455
      },
      {
        "slot": 390089774,
        "epoch": 902,
        "tx_count": 1154,
        "cu_used": 24552433,
        "build_time_score": 22.54,
        "vote_packing_score": 0.0,
        "non_vote_packing_score": 33.14,
        "ibrl_score": 21.145
      }
    ]
  },
  "timestamp": 1767213665790,
  "epoch": 902
}

Response Fields

Root Object:

data (ValidatorIBRLDetail): Detailed validator information
timestamp (u64): Unix timestamp in milliseconds when the response was generated
epoch (u32): The epoch used for the query

ValidatorIBRLDetail Object:

validator_score (ValidatorIBRLScore): Current epoch score (see endpoint 3 for field descriptions)
epoch_history (Array<EpochScore>): Last 10 epochs of historical performance data
recent_blocks (Array<ProducedBlock>): Last 50 blocks produced by this validator in the specified epoch

EpochScore Object:

epoch (u32): Epoch number
build_time_score (f64): Average build time performance score for this epoch (0.0 - 100.0)
vote_packing_score (f64): Average vote packing efficiency score for this epoch (0.0 - 100.0)
non_vote_packing_score (f64): Average non-vote packing efficiency score for this epoch (0.0 - 100.0)
ibrl_score (f64): Overall IBRL score for this epoch (0.0 - 100.0)
blocks_produced (u64): Number of blocks produced in this epoch

ProducedBlock Object:

slot (u64): Solana slot number
epoch (u32): Epoch number
tx_count (u64): Total number of transactions (non-vote + vote)
cu_used (u64): Total compute units consumed
build_time_score (f64): Build time performance score for this block (0.0 - 100.0)
vote_packing_score (f64): Vote packing efficiency score for this block (0.0 - 100.0)
non_vote_packing_score (f64): Non-vote packing efficiency score for this block (0.0 - 100.0)
ibrl_score (f64): Overall IBRL score for this block (0.0 - 100.0)

5. Get IBRL Stats

Endpoint: GET /api/v1/ibrl_stats

Description: Retrieves network-wide IBRL statistics for a given epoch, including average scores and active validator count.

Query Parameters

Parameter	Type	Required	Description
`epoch`	`u32`	No	Filter by epoch. If not provided, uses the latest epoch

Response Structure

{
  "data": {
    "network_ibrl_score": 80.4434,
    "avg_build_time_score": 93.5161,
    "avg_vote_packing_score": 68.6697,
    "avg_non_vote_packing_score": 76.3633,
    "active_validators": 780
  },
  "timestamp": 1767212364884,
  "epoch": 902
}

Response Fields

Root Object:

data (IBRLStats): Network-wide statistics
timestamp (u64): Unix timestamp in milliseconds when the response was generated
epoch (u32): The epoch used for the query

IBRLStats Object:

network_ibrl_score (f64): Average IBRL score across all validators in the epoch (0.0 - 100.0)
avg_build_time_score (f64): Average build time performance score across all blocks (0.0 - 100.0)
avg_vote_packing_score (f64): Average vote packing efficiency score across all blocks (0.0 - 100.0)
avg_non_vote_packing_score (f64): Average non-vote packing efficiency score across all blocks (0.0 - 100.0)
active_validators (u32): Number of distinct validators that produced blocks in the epoch

Error Responses

All endpoints may return standard HTTP error codes:

400 Bad Request: Invalid query parameters or path parameters
404 Not Found: Requested resource not found (e.g., block slot or validator identity doesn't exist)
500 Internal Server Error: Server-side error

Error responses follow this structure:

{
  "error": "Error message description"
}