Baking Bad API v2

THE BAKING BAD API IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND. BAKING BAD DOES NOT WARRANT THAT THE API WILL MEET USER’S REQUIREMENTS OR BE UNINTERRUPTED, TIMELY, SECURE, OR ERROR-FREE, ANY THIRD PARTY CONTENT WILL BE TRUTHFUL, ACCURATE, RELIABLE, OR COMPLETE.

API base URI

To access API methods use this base URI:

https://api.baking-bad.org/v2

Get bakers

Returns known public bakers, optionally including additional information such as configs, insurance, and contribution.

Note: if the baker is not found / doesn’t exist you will receive HTTP 204 - No content with an empty body.

// get all known bakers
GET {baseUri}/bakers
// get a baker by the specified address
GET {baseUri}/bakers/{address}

Query parameters (optional)

Parameter	Type	Description
accuracy	string	Filters bakers by payout accuracy. You can pass several values separated by comma, e.g. accuracy=precise,inaccurate,suspicious,no_data.
timing	string	Filters bakers by payout timing. You can pass several values separated by comma, e.g. timing=stable,unstable,suspicious,no_data.
type	string	Filters bakers by service type. You can pass several values separated by comma, e.g. type=tezos_only,multiasset,exchange,tezos_dune.
health	string	Filters bakers by health status. You can pass several values separated by comma, e.g. health=active,closed,dead.
insured	boolean	Filters bakers by insurance status. If true only insured bakers will be returned.
configs	boolean	Specifies whether or not bakers’ configs should be included in the response. By default false.
insurance	boolean	Specifies whether or not the insurance info should be included in the response. By default false.
contribution	boolean	Specifies whether or not the contribution info should be included in the response. By default false.

Example of a baker object:

{
  "address": "tz1WnfXMPaNTBmH7DBPwqCWs9cPDJdkGBTZ8",
  "name": "TezosHODL",
  "logo": "https://services.tzkt.io/v1/avatars/tz1WnfXMPaNTBmH7DBPwqCWs9cPDJdkGBTZ8",
  "balance": 105478.194558,
  "stakingBalance": 813340.978283,
  "stakingCapacity": 1057012.665552,
  "maxStakingBalance": 1057012.665552,
  "freeSpace": 243671.6872690001,
  "fee": 0.08,
  "minDelegation": 10,
  "payoutDelay": 6,
  "payoutPeriod": 1,
  "openForDelegation": true,
  "estimatedRoi": 0.061357,
  "serviceType": "tezos_only",
  "serviceHealth": "active",
  "payoutTiming": "stable",
  "payoutAccuracy": "precise",
  "audit": "5de7d8f6b006b90008a9df9d",
  "insuranceCoverage": 0,
  "config": {},
  "insurance": {},
  "contribution": {}
}

Fields description

Field	Type	Description
address	string	Baker’s address.
name	string	Baker’s name (alias).
logo	string	URL to Baker’s logo. null if there is no logo.
balance	number	Current baker’s balance including deposits, rewards, and fees.
stakingBalance	number	Current baker’s staking balance.
stakingCapacity	number	Maximum staking balance that is covered by baker’s bonds (security deposit).
maxStakingBalance	number	stakingCapacity multiplied by maxStakingThreshold from config.
freeSpace	number	Current baker’s free space available for delegation.
fee	number	Baker’s fee which will be applied if you delegate right now.
minDelegation	number	Minimal amount to delegate.
payoutDelay	number	Delay in cycles before the baker pays rewards.
payoutPeriod	number	Periodicity in cycles of baker’s payouts. 1 - every cycle, 3 - once in three cycles, etc.
openForDelegation	boolean	Specifies whether the baker opened for delegation or not.
estimatedRoi	number	Estimated ROI per year for the delegator who has delegated to this baker.
serviceType	string	Indicates bakers service type. More details…
serviceHealth	string	Indicates bakers service status. More details…
payoutTiming	string	Indicates bakers payouts timing. More details…
payoutAccuracy	string	Indicates bakers payouts accuracy. More details…
audit	string	Shared link to randomly selected delegator used for audit. https://baking-bad.org/shared/{audit}
config	object	Default baker’s config used in the delegators dashboard to audit payouts. More details…
insurance	object	Info about baker’s insurance. null if the baker is not insured. More details…
contribution	object	Info about baker’s contribution. null if the baker is not a contributor. More details…

Service Type

Value	Meaning
tezos_only	Baker runs only tezos node.
multiasset	Baker is a multiasset pool, supporting different assets.
exchange	This type is for exchanges only.
tezos_dune	Baker runs both tezos and dune nodes.

Service Health

Value	Meaning
active	Baker is active.
closed	Baker is closed and deactivated as a delegate in the blockchain.
dead	There were no payouts for a long period of time.

Payout Timing

Value	Meaning
stable	Recent payouts time is in line with declared one.
unstable	Recent payouts time is NOT IN LINE with declared one.
suspicious	Recent payouts were missed for an unknown reason.
no_data	No public payment data.

Payout Accuracy

Value	Meaning
precise	Recent payout amounts are equal to the expected rewards.
inaccurate	Recent payout amounts are NOT EQUAL to the expected rewards.
suspicious	Recent payouts were missed for an unknown reason.
no_data	No public payment data.

Bakers configs

Field baker.config contains default bakers configurations used in the Baking Bad delegators dashboard to audit payouts.

Example of a config object:

{
    "address": "tz1WnfXMPaNTBmH7DBPwqCWs9cPDJdkGBTZ8",
    "fee": [
        { "cycle": 0, "value": 0.08 }
    ],
    "minDelegation": [
        { "cycle": 0, "value": 0.0 }
    ],
    "allocationFee": [
        { "cycle": 0, "value": false }
    ],
    "payoutFee": [
        { "cycle": 0, "value": false }
    ],
    "payoutDelay": [
        { "cycle": 0, "value": 6 }
    ],
    "payoutPeriod": [
        { "cycle": 0, "value": 1 }
    ],
    "minPayout": [
        { "cycle": 0, "value": 0.0 }
    ],
    "rewardStruct": [
        { "cycle": 0, "value": 1023 }
    ],
    "payoutRatio": [
        { "cycle": 0, "value": 666.0 }
    ],
    "maxStakingThreshold": [
        { "cycle": 174, "value": 0.91 }
    ],
    "openForDelegation": [
        { "cycle": 0, "value": true }
    ],
    "ignored": [
        "KT1xxx..."
    ],
    "sources": [
        "KT1yyy..."
    ],
}

Fields description

Field	Type	Description
address	string	Baker’s address.
fee	number	Baker’s fee.
minDelegation	number	Minimal amount to delegate.
allocationFee	boolean	Specifies whether the baker charges an allocation fee or not (when the delegator is emptied).
payoutFee	boolean	Specifies whether the baker charges payout tx fee or not.
payoutDelay	integer	Delay in cycles before the baker pays rewards. 1 - in the next cycle, 6 - when rewards are unfrozen, etc.
payoutPeriod	integer	Periodicity in cycles of baker’s payouts. 1 - every cycle, 3 - once in three cycles, etc.
minPayout	number	Minimal amount of a payout to send to the delegator.
rewardStruct	integer	14-bits number - a set of flags which specify the way to count baker’s total reward. See more details below…
payoutRatio	number	Service field for better payouts matching.
maxStakingThreshold	number	Coefficient limiting the maxStakingBalance value
openForDelegation	boolean	Specifies whether the baker opened for delegation or not.
ignored	string	Service field for better payouts matching, omitted when null.
sources	string	Service field for better payouts matching, omitted when null.

Understanding configs series

As you can see almost all the config’s fields are arrays of objects with cycle and value fields. This is just a time-series that contain changes in the fields.

For example:

"fee": [
    { "cycle": 168, "value": 0.05 },
    { "cycle": 138, "value": 0.025 },
    { "cycle": 0, "value": 0 }
]

This means that from the beginning and up to the 137th cycle the fee was 0%, from the 138th cycle and up to the 167th cycle the fee is 2.5% and after the 168th cycle, the fee will be 5%.

Understanding reward struct

As it said rewards struct is just a set of flags, which can be parsed by this way:

let rewardStruct = 1023;
let extRewardStruct = {
    blocks: (rewardStruct & 1) > 0,
    missedBlocks: (rewardStruct & 2) > 0,
    endorsements: (rewardStruct & 4) > 0,
    missedEndorsements: (rewardStruct & 8) > 0,
    fees: (rewardStruct & 16) > 0,
    missedFees: (rewardStruct & 32) > 0,
    accusationRewards: (rewardStruct & 64) > 0,
    accusationLosses: (rewardStruct & 128) > 0,
    revelationRewards: (rewardStruct & 256) > 0,
    revelationLosses: (rewardStruct & 512) > 0,
}

Bakers insurance

Field baker.insurance contains information about the baker’s insurance status displayed in the Baking Bad rating.

Example of an insurance object:

{
    "address": "tz1P2Po7YM526ughEsRbY4oR9zaUPDZjxFrb",
    "insuranceAddress": "KT1T7fzoxZYACYwYcZn2fjfLoCKu2qRDKhBU",
    "insuranceAmount": 38415.14087,
    "coverage": 1.06
}

Fields description

Field	Type	Description
address	string	Baker’s address.
insuranceAddress	string	Address with insurance deposit used for compensating any insurance case.
insuranceAmount	string	Current insurance deposit.
coverage	number	Share of the current staking balance which is covered (insured). 1.06 means 106%.

Bakers contribution

Field baker.contribution contains information about baker’s contribution displayed in the Baking Bad bakers listing.

Example of a contribution object:

{
  "address": "tz1NortRftucvAkD1J58L32EhSVrQEWJCEnB",
  "title": "Community veteran",
  "link": "https://t.me/Zedrone",
  "icon": "https://baking-bad.org/img/contribs/zed.png"
}

Fields description

Field	Type	Description
address	string	Baker’s address.
title	string	Contribution title
link	string	Contribution link
icon	string	URL path for contribution icon

Get rewards

Get delegation rewards for the specified baker and cycle, including the current payment model, reward split, and amounts to be paid to the delegators.

Notes:

• NOT SUPPORTED: payout models where minimum payout amount is set, or payout period is greater than 1 cycle;
• If the payment model of the baker is not supported you will receive HTTP 400 - Bad request with an error message;
• If the cycle is not valid you will receive HTTP 400 - Bad request with an error message;
• If the baker is not found / doesn’t exist you will receive HTTP 204 - No content with an empty body;

GET {baseUri}/rewards/{address}?cycle={cycle}

Sample response:

{
    "cycle": 165,
    "bakerAddress": "tz1WnfXMPaNTBmH7DBPwqCWs9cPDJdkGBTZ8",
    "stakingBalance": 897324.559942,
    "totalReward": 548.409631,
    "totalPayout": 504.536861,
    "payoutModel": {},
    "rewardSplit": {},
    "payouts": []
}

Fields description

Field	Type	Description
cycle	integer	Cycle number this
bakerAddress	string	Baker’s address.
stakingBalance	number	Baker’s staking balance used in calculations
totalReward	number	Final result after applying reward mask to the reward split
totalPayout	number	Total reward minus baker’s fee
payoutModel	object	Payment scheme baker uses for the requested cycle. More details…
rewardSplit	object	All baker’s rewards and losses for the requested cycle. More details…
payouts	array	Payout info per each delegator with a positive balance. More details…

Payout model

This is actually just a different representation of the baker config data, taken for a particular cycle.

Field	Type	Description
fee	number	Baker’s fee
minDelegation	number	The lowest delegated amount the baker will accept in order to be included in the payouts.
minDelegationStakeDilution	boolean	All the rewards gained for delegations less than the minimum will be withheld by a baker, meaning no share dilution for the rest of delegators. Always false
payoutDelay	integer	Delay in cycles before the baker pays rewards. 1 - in the next cycle, 6 - when rewards are unfrozen, etc.
payoutFrequency	integer	The number of cycles in between payments. The default value of 1 means that the baker pays out every cycle.
minPayout	number	The minimum amount a baker includes in its payouts. The default value of 0 means there is no minimum.
bakerChargesPayoutTransactionFee	boolean	When baker makes a payout, the baker deducts the transaction fees from the payout.
rewardMask	object	Baker self-registry compatible representation of rewardStruct bitmask. More details…

Reward mask

Note that this is not an exact mapping of rewardStruct bits, some of them are inverted.

Field	Type	Description	From reward struct
payForOwnBlocks	boolean	Baker pays out on rewards from own blocks (priority 0, misses excluded)	!!(rs & 1)
payForStolenBlocks	boolean	Baker pays out on rewards from stolen blocks (priority > 0)	!!(rs & 2048)
compensateMissedBlocks	boolean	When baker misses a block, baker still pays out as if it had not been missed	!(rs & 1024)
payForEndorsements	boolean	Baker pays out on rewards from endorsements	!!(rs & 2)
compensateLowPriorityEndorsementLoss	boolean	When baker endorses a block with a priority > 0, baker still pays out as if the block had been priority 0	!(rs & 8192)
compensateMissedEndorsements	boolean	When baker misses an endorsement, baker still pays out as if it had not been missed	!(rs & 4096)
payGainedFees	boolean	Bakers pays out on fees collected from operations included in the blocks	!!(rs & 4)
payForAccusationGains	boolean	Baker pays out on rewards from baking/endorsing accusations	!!(rs & 8)
subtractLostDepositsWhenAccused	boolean	When baker loses deposit from being accused, the baker subtracts this loss from the payout and thus does NOT compensate for this loss	!!(rs & 16)
subtractLostRewardsWhenAccused	boolean	When baker loses rewards from being accused, the baker subtracts this loss from the payout and thus does NOT compensate for this loss	!!(rs & 32)
subtractLostFeesWhenAccused	boolean	When baker loses fees from being accused, the baker subtracts this loss from the payout and thus does NOT compensate for this loss	!!(rs & 48)
payForRevelation	boolean	Baker pays out on rewards from including seed nonce revelation	!!(rs & 128)
subtractLostRewardsWhenMissRevelation	boolean	When baker loses rewards from failing to reveal nonce, the baker subtracts this loss from the payout and thus does NOT compensate for this loss	!!(rs & 256)
subtractLostFeesWhenMissRevelation	boolean	When baker loses fees from failing to reveal nonce, the baker subtracts this loss from the payout and thus does NOT compensate for this loss	!!(rs & 512)

Reward split

Field	Type	Description
ownBlockRewards	number	Rewards from own blocks (priority 0, misses excluded)
stolenBlockRewards	number	Rewards from stolen blocks (priority > 0)
missedBlockRewards	number	Loss of rewards due to missed bakings (any priority)
endorsementRewards	number	Rewards from endorsements
lowPriorityEndorsementLoss	number	Loss of rewards due to the low priority of endorsed blocks (priority > 0)
missedEndorsementRewards	number	Loss of rewards due to missed endorsements
gainedFees	number	Fees for operations included in the baked blocks
accusationRewards	number	Rewards from double baking/endorsement evidence publishing
depositsLostDueAccusation	number	Deposit lost when baker is accused of double baking/endorsement (value <= 0)
rewardsLostDueAccusation	number	Rewards lost when baker is accused of double baking/endorsement (value <= 0)
feesLostDueAccusation	number	Operation fees lost when baker is accused of double baking/endorsement (value <= 0)
revelationRewards	number	Rewards from seed nonce revelations
rewardsLostDueRevelationMiss	number	Rewards lost when baker misses seed nonce revelation (value <= 0)
feesLostDueRevelationMiss	number	Operation fees lost when baker misses seed nonce revelation (value <= 0)

Payout item

Field	Type	Description
address	string	Delegator’s address
amount	number	Payout amount
snapshotBalance	number	Delegator’s snapshotted balance used in calculations

Changelog

• 14.01.2020 - v2 is released;
  • new logos’ base URL;
  • /aliases has been removed. Nevertheless, aliases are available directly in /bakers;
  • /bakers:
    • baker.rating has been removed;
    • baker.config.minBalance has been renamed to baker.config.minDelegation;
    • new fields have been added;
• 08.11.2019 - /v1/rewards endpoint is added;
• 10.09.2019 - v1 is released.