Staking Reward Allocation API Documentation

POSThttps://www.brainiac.software/api/v1/staking-operations/staking-reward-allocation-audit$0.05 USDC

Audit staking reward allocation

Calculate staking reward allocations from the supplied commission percent, share percents, penalties, and rounding rule. Share percents must sum to 100%. Commission is that percent of gross rewards or of rewards after penalties. audit_status is balanced, mismatched, invalid, or incomplete. Expected amounts are calculated. Actual amounts come only from distribution records in the request. No staking reward is fetched, and this is not an invoice or stablecoin reconciliation.

Body

Field	Required	Notes
`periods`	Yes	array; Array
`distributions`	No	array; Array

Request exampleJSON

{
  "periods": [
    {
      "id": "2026-01",
      "validator": "validator-a",
      "totalRewards": "1100",
      "start": "2026-01-01T00:00:00Z",
      "end": "2026-02-01T00:00:00Z",
      "deductions": [
        {
          "id": "offline-penalty",
          "amount": "100"
        }
      ],
      "commission": {
        "beneficiary": "operator-a",
        "percent": "10",
        "basis": "net_after_deductions"
      },
      "statedCommission": "90",
      "shares": [
        {
          "beneficiary": "delegator-a",
          "role": "delegator",
          "percent": "50"
        },
        {
          "beneficiary": "delegator-b",
          "role": "delegator",
          "percent": "50"
        }
      ],
      "rounding": "floor",
      "remainder": "undistributed"
    },
    {
      "id": "2026-02",
      "validator": "validator-b",
      "totalRewards": "100",
      "commission": {
        "beneficiary": "operator-b",
        "percent": "10",
        "basis": "gross"
      },
      "shares": [
        {
          "beneficiary": "delegator-c",
          "role": "delegator",
          "percent": "33.3334"
        },
        {
          "beneficiary": "delegator-d",
          "role": "delegator",
          "percent": "33.3333"
        },
        {
          "beneficiary": "delegator-e",
          "role": "delegator",
          "percent": "33.3333"
        }
      ],
      "rounding": "floor",
      "remainder": "undistributed"
    }
  ],
  "distributions": [
    {
      "periodId": "2026-01",
      "beneficiary": "operator-a",
      "amount": "100",
      "at": "2026-01-15T00:00:00Z"
    },
    {
      "periodId": "2026-01",
      "beneficiary": "delegator-a",
      "amount": "400"
    }
  ]
}

Response exampleJSON

{
  "audit_status": "mismatched",
  "total_rewards": "1200",
  "total_allocated": "1098",
  "undistributed_rewards": "2",
  "operator_allocations": [
    {
      "period_id": "2026-01",
      "validator": "validator-a",
      "beneficiary": "operator-a",
      "role": "operator",
      "commission_amount": "100",
      "share_amount": "0",
      "remainder_amount": "0",
      "amount": "100",
      "detail": "Expected commission is the supplied percent of totalRewards after penalties. This is calculated, not taken from a distribution record."
    },
    {
      "period_id": "2026-02",
      "validator": "validator-b",
      "beneficiary": "operator-b",
      "role": "operator",
      "commission_amount": "10",
      "share_amount": "0",
      "remainder_amount": "0",
      "amount": "10",
      "detail": "Expected commission is the supplied percent of totalRewards, before penalties. This is calculated, not taken from a distribution record."
    }
  ],
  "delegator_allocations": [
    {
      "period_id": "2026-01",
      "validator": "validator-a",
      "beneficiary": "delegator-a",
      "role": "delegator",
      "percent": "50",
      "amount": "450",
      "detail": "Expected share of the amount left after penalties and commission. This is calculated, not taken from a distribution record."
    },
    {
      "period_id": "2026-01",
      "validator": "validator-a",
      "beneficiary": "delegator-b",
      "role": "delegator",
      "percent": "50",
      "amount": "450",
      "detail": "Expected share of the amount left after penalties and commission. This is calculated, not taken from a distribution record."
    },
    {
      "period_id": "2026-02",
      "validator": "validator-b",
      "beneficiary": "delegator-c",
      "role": "delegator",
      "percent": "33.3334",
      "amount": "30",
      "detail": "Expected share of the amount left after penalties and commission. This is calculated, not taken from a distribution record."
    },
    {
      "period_id": "2026-02",
      "validator": "validator-b",
      "beneficiary": "delegator-d",
      "role": "delegator",
      "percent": "33.3333",
      "amount": "29",
      "detail": "Expected share of the amount left after penalties and commission. This is calculated, not taken from a distribution record."
    },
    {
      "period_id": "2026-02",
      "validator": "validator-b",
      "beneficiary": "delegator-e",
      "role": "delegator",
      "percent": "33.3333",
      "amount": "29",
      "detail": "Expected share of the amount left after penalties and commission. This is calculated, not taken from a distribution record."
    }
  ],
  "commission_differences": [
    {
      "period_id": "2026-01",
      "validator": "validator-a",
      "beneficiary": "operator-a",
      "expected_amount": "100",
      "stated_amount": "90",
      "actual_amount": "100",
      "difference": "-10",
      "detail": "The stated commission is not the commission calculated from the supplied percent and rounding rule. Distribution records for this beneficiary sum to 100."
    }
  ],
  "distribution_mismatches": [
    {
      "period_id": "2026-01",
      "validator": "validator-a",
      "beneficiary": "delegator-a",
      "expected_amount": "450",
      "actual_amount": "400",
      "difference": "-50",
      "detail": "The summed distribution records do not equal the calculated allocation."
    },
    {
      "period_id": "2026-01",
      "validator": "validator-a",
      "beneficiary": "delegator-b",
      "expected_amount": "450",
      "actual_amount": "0",
      "difference": "-450",
      "detail": "No distribution record was supplied for this expected beneficiary."
    }
  ],
  "findings": [
    {
      "code": "commission_difference",
      "severity": "high",
      "period_id": "2026-01",
      "beneficiary": "operator-a",
      "detail": "The stated commission is not the commission calculated from the supplied percent and rounding rule. Distribution records for this beneficiary sum to 100."
    },
    {
      "code": "distribution_mismatch",
      "severity": "high",
      "period_id": "2026-01",
      "beneficiary": "delegator-a",
      "detail": "The summed distribution records do not equal the calculated allocation."
    },
    {
      "code": "beneficiary_missing",
      "severity": "high",
      "period_id": "2026-01",
      "beneficiary": "delegator-b",
      "detail": "No distribution record was supplied for this expected beneficiary."
    },
    {
      "code": "penalty_applied",
      "severity": "low",
      "period_id": "2026-01",
      "detail": "100 units were removed as supplied penalties before the commission and shares were calculated."
    },
    {
      "code": "rounding_remainder",
      "severity": "low",
      "period_id": "2026-02",
      "detail": "2 units remain after floor rounding and stay undistributed."
    },
    {
      "code": "distribution_not_supplied",
      "severity": "medium",
      "period_id": "2026-02",
      "detail": "No distribution records were supplied for this period, so expected allocations were not compared with actual amounts."
    },
    {
      "code": "calculation_scope",
      "severity": "low",
      "detail": "Expected amounts are calculated from the supplied commission, share, and rounding rules. Actual amounts are taken only from distribution records in the request. No staking reward was fetched."
    }
  ],
  "limitations": [
    "Amounts are integers in the caller-supplied smallest unit. No token decimals or exchange rate is applied.",
    "Commission is the supplied percent of gross rewards, or of rewards after the supplied deductions, rounded with the supplied mode. No protocol commission is assumed.",
    "Share percents apply to the amount left after deductions and commission. They must sum to 100%.",
    "Expected allocations are calculated. Actual amounts come only from distribution records in the request.",
    "This is not an invoice or stablecoin payment reconciliation.",
    "No staking rewards or balances were fetched.",
    "A rounding remainder follows the remainder rule. It is not an extra payment unless that rule assigns it to a beneficiary.",
    "undistributed_rewards is total_rewards minus calculated allocations and deductions that were applied. A period whose rules are invalid is left undistributed. When rounded shares exceed the pool, undistributed_rewards stays 0.",
    "Period boundaries are caller-supplied labels. A distribution timestamp is inside a period when it is at or after start and before end."
  ]
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/staking-operations/staking-reward-allocation-audit" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "periods": [
    {
      "id": "2026-01",
      "validator": "validator-a",
      "totalRewards": "1100",
      "start": "2026-01-01T00:00:00Z",
      "end": "2026-02-01T00:00:00Z",
      "deductions": [
        {
          "id": "offline-penalty",
          "amount": "100"
        }
      ],
      "commission": {
        "beneficiary": "operator-a",
        "percent": "10",
        "basis": "net_after_deductions"
      },
      "statedCommission": "90",
      "shares": [
        {
          "beneficiary": "delegator-a",
          "role": "delegator",
          "percent": "50"
        },
        {
          "beneficiary": "delegator-b",
          "role": "delegator",
          "percent": "50"
        }
      ],
      "rounding": "floor",
      "remainder": "undistributed"
    },
    {
      "id": "2026-02",
      "validator": "validator-b",
      "totalRewards": "100",
      "commission": {
        "beneficiary": "operator-b",
        "percent": "10",
        "basis": "gross"
      },
      "shares": [
        {
          "beneficiary": "delegator-c",
          "role": "delegator",
          "percent": "33.3334"
        },
        {
          "beneficiary": "delegator-d",
          "role": "delegator",
          "percent": "33.3333"
        },
        {
          "beneficiary": "delegator-e",
          "role": "delegator",
          "percent": "33.3333"
        }
      ],
      "rounding": "floor",
      "remainder": "undistributed"
    }
  ],
  "distributions": [
    {
      "periodId": "2026-01",
      "beneficiary": "operator-a",
      "amount": "100",
      "at": "2026-01-15T00:00:00Z"
    },
    {
      "periodId": "2026-01",
      "beneficiary": "delegator-a",
      "amount": "400"
    }
  ]
}
JSON

POSThttps://www.brainiac.software/api/v1/staking-operations/reward-fairness$0.04 USDC

Score staking reward fairness

Compare each supplied allocation with the share of the reward pool its weight implies. The rounding error is the total absolute gap, divided by the reward. Equal weights with uneven payouts lower the fairness score. No reward balance is fetched.

Body

Field	Required	Notes
`reward`	Yes	integer
`shares`	Yes	array; Array

Request exampleJSON

{
  "reward": 1000,
  "shares": [
    {
      "id": "a",
      "weight": 1,
      "allocated": 400
    },
    {
      "id": "b",
      "weight": 1,
      "allocated": 300
    },
    {
      "id": "c",
      "weight": 1,
      "allocated": 300
    }
  ]
}

Response exampleJSON

{
  "allocation_fairness_score": 87,
  "rounding_error_percentage": 13
}

cURL

curl -i -X POST "https://www.brainiac.software/api/v1/staking-operations/reward-fairness" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: <fresh-64-character-random-hex-key>' \
  --data-binary @- <<'JSON'
{
  "reward": 1000,
  "shares": [
    {
      "id": "a",
      "weight": 1,
      "allocated": 400
    },
    {
      "id": "b",
      "weight": 1,
      "allocated": 300
    },
    {
      "id": "c",
      "weight": 1,
      "allocated": 300
    }
  ]
}
JSON