{"openapi":"3.1.0","info":{"title":"Staking Operations API","version":"1.0.0","description":"Audit caller-supplied staking reward allocations for operators, validators, and delegators. No network calls are made. Paid with x402 exact USDC on Base. No account is required.","contact":{"email":"support@brainiac.software"},"x-guidance":"BRAINIAC.software is a pay-per-call API for software agents. No account or API key is required.\nPayment uses the x402 protocol with exact USDC on Base (chain id 8453). Each POST operation has a fixed USD price.\nHow to call an operation:\n1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.\n2. A valid unpaid call returns 402 with the exact amount and payTo.\n3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.\nInclude an Idempotency-Key header of 64 hex characters from 32 random bytes. Reuse that key only for retries of the same operation and request body.\nAll outputs are compliance prechecks, drafts, or data lookups for human review. They are not official determinations, legal advice, identity confirmation, or certified filings. Verify time-sensitive or official data with the cited source before acting."},"servers":[{"url":"https://www.brainiac.software"}],"paths":{"/api/v1/staking-operations/staking-reward-allocation-audit":{"post":{"operationId":"audit_staking_reward_allocation","summary":"Audit staking reward allocation","description":"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.","tags":["staking-operations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"periods":{"minItems":1,"maxItems":24,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":80},"validator":{"type":"string","minLength":1,"maxLength":80},"totalRewards":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"end":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"deductions":{"maxItems":16,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":80},"amount":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"beneficiary":{"type":"string","minLength":1,"maxLength":80}},"required":["id","amount"],"additionalProperties":false}},"commission":{"type":"object","properties":{"beneficiary":{"type":"string","minLength":1,"maxLength":80},"percent":{"type":"string","pattern":"^(100(?:\\.0{1,4})?|(?:0|[1-9]\\d?)(?:\\.\\d{1,4})?)$"},"basis":{"type":"string","enum":["gross","net_after_deductions"]}},"required":["beneficiary","percent","basis"],"additionalProperties":false},"statedCommission":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"shares":{"maxItems":64,"type":"array","items":{"type":"object","properties":{"beneficiary":{"type":"string","minLength":1,"maxLength":80},"role":{"type":"string","enum":["operator","validator","delegator","other"]},"percent":{"type":"string","pattern":"^(100(?:\\.0{1,4})?|(?:0|[1-9]\\d?)(?:\\.\\d{1,4})?)$"}},"required":["beneficiary","role","percent"],"additionalProperties":false}},"rounding":{"type":"string","enum":["floor","ceil","half_up"]},"remainder":{"type":"string","enum":["operator","undistributed","largest_share"]}},"required":["id","validator","totalRewards","commission","shares","rounding","remainder"],"additionalProperties":false}},"distributions":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"periodId":{"type":"string","minLength":1,"maxLength":80},"beneficiary":{"type":"string","minLength":1,"maxLength":80},"amount":{"type":"string","pattern":"^(0|[1-9][0-9]{0,77})$"},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["periodId","beneficiary","amount"],"additionalProperties":false}}},"required":["periods"],"additionalProperties":false},"example":{"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"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"audit_status":{"type":"string"},"total_rewards":{"type":"string"},"total_allocated":{"type":"string"},"undistributed_rewards":{"type":"string"},"operator_allocations":{"type":"array","items":{"type":"object","properties":{"period_id":{"type":"string"},"validator":{"type":"string"},"beneficiary":{"type":"string"},"role":{"type":"string"},"commission_amount":{"type":"string"},"share_amount":{"type":"string"},"remainder_amount":{"type":"string"},"amount":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"delegator_allocations":{"type":"array","items":{"type":"object","properties":{"period_id":{"type":"string"},"validator":{"type":"string"},"beneficiary":{"type":"string"},"role":{"type":"string"},"percent":{"type":"string"},"amount":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"commission_differences":{"type":"array","items":{"type":"object","properties":{"period_id":{"type":"string"},"validator":{"type":"string"},"beneficiary":{"type":"string"},"expected_amount":{"type":"string"},"stated_amount":{"type":"string"},"actual_amount":{"type":"string"},"difference":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"distribution_mismatches":{"type":"array","items":{"type":"object","properties":{"period_id":{"type":"string"},"validator":{"type":"string"},"beneficiary":{"type":"string"},"expected_amount":{"type":"string"},"actual_amount":{"type":"string"},"difference":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"findings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string"},"period_id":{"type":"string"},"beneficiary":{"type":"string"},"detail":{"type":"string"}},"additionalProperties":true}},"limitations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"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."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object: x402Version, resource with the operation description, accepts with the price and network, and extensions.bazaar with the input schema, input example, output schema, and output example."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed before settlement, so no payment is taken. Reuse the same idempotency key to retrieve the stored error without paying again."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.05"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}},"/api/v1/staking-operations/reward-fairness":{"post":{"operationId":"score_staking_reward_fairness","summary":"Score staking reward fairness","description":"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.","tags":["staking-operations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reward":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"shares":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":80},"weight":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"allocated":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","weight","allocated"],"additionalProperties":false}}},"required":["reward","shares"],"additionalProperties":false},"example":{"reward":1000,"shares":[{"id":"a","weight":1,"allocated":400},{"id":"b","weight":1,"allocated":300},{"id":"c","weight":1,"allocated":300}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"allocation_fairness_score":{"type":"number"},"rounding_error_percentage":{"type":"number"}},"additionalProperties":true},"example":{"allocation_fairness_score":87,"rounding_error_percentage":13}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object: x402Version, resource with the operation description, accepts with the price and network, and extensions.bazaar with the input schema, input example, output schema, and output example."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed before settlement, so no payment is taken. Reuse the same idempotency key to retrieve the stored error without paying again."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}