> Setup

Follow along on Youtube!

Table of Contents

  1. Preparation
  2. Setup

Preparation

There is minimal preparation needed to utilize TezPay, assuming that you have a functioning public baker running.

Preparation Summary

  1. Create a directory (folder) on your desktop (or appropriate location) to store the application files and required config files
  2. Download the Tezpay software, sample configuration, and payout wallet files from github
  3. Create a ‘pay-out’ wallet and store the private key (not baker or hot wallet)

Preparation: Step 1 Create TezPay Directory

Create a new folder on the desktop or in a location that you want to store the necessary files for Tezpay.

Newly created TezPay directory, will contain all files for Tezpay Application.

This folder will eventually contain 3 files:

  1. TezPay Application File
  2. Configuration File
  3. Private-Key File

The TezPay Application File will execute the commands that will run TezPay, the Configuration File will essentially tell the application file how to run and will be edited by the baker (we will cover this later), and the Private-Key File will contain the private key for a wallet you have designated to pay your delegators (we will explain an easy way to get this later as well).

⚠️ WARNING: Private Key File

Do NOT use an existing wallet that contains important assets (NFTs, tokens, etc.). Create a new dedicated wallet that contains only enough Tezos to pay out delegates.

Preparation: Step 2 Download Files

Download the software from Github using the link: https://github.com/tez-capital/tezpay/releases. In this repository, select the correct operating system and system architecture (arm64 or amd64). For this example we will be using arm64

Download options based on operating system for TezPay application.

Note: If you do not know the system architecture you can find out by opening a Terminal and executing the command uname -m, and this will return the system architecturearm64 or amd64.

The example below displays arm64

Command to determine system architecture.

If you would rather utilize CLI to download the application you will need to change directory (cd) to the TezPay directory created in step 1 in the terminal, then use command wget -q https://pay.tez.capital/install -O /tmp/install.sh && sh /tmp/install.sh

See example code below (note: input begins after last ‘%’ character):

Command to dl TezPay application using CLI for Linux.

The above example is an alternative to downloading from the GitHub repository

Next, you will download the sample configuration file & payout_wallet_private.sample.key file from : https://github.com/tez-capital/tezpay/blob/main/docs/configuration/ - or you can open file in GitHub and copy text to a text editor.

Note, there are two choices for the configuration files:

  1. Simple Config file : config.default.hjson (basic arguments to run Tezpay)
  2. Full Config: config.sample.hjson (advanced arguments to run Tezpay)
Repository with configuration Files.

Preparation: Step 3 - Payout Wallet (optional)

Lastly, you will need to download the create a new wallet and retrieve the private key. We will be using the Temple Wallet extension to create a new wallet and to get the private key. If you already have a payout wallet, or know how, skip this section.

  • First, open Temple Wallet and select the icon in upper right
Access Temple Wallet menu.
  • Next, select ’new account’, and input a new (ie Tezpay1)
Name and confirm the new payout wallet.
  • Then, click the icon in the upper right again
Access Temple Wallet menu, again.
  • Then, go to Settings
Select settings in Temple Wallet menu.
  • Then, go to Reveal Private Key
Scroll to Reveal Private Key.
  • Then, you will be prompt to input your password for the account
Input password for the account.

Your private key will be displayed here:

Copy the private key of the payout wallet.

Setup

The next section will review the setup needed for Tezpay. We will review the Configuration File and Payout Wallet files. In this section we will review:

  1. Configuration File (simple)
  2. Configuration File (advanced)
  3. Private-Key File

Setup: Step 1a: Configuration File (simple)

This section will review how to setup the configuration file (simple-version) to be used by the TezPay application.

Note: must have file name config.hjson, case-sensitive

Simple Configuration file for TezPay.

ℹ️ INFO: If you’re familiar with JSON but new to HJSON (Human JSON), you can learn more at https://hjson.github.io/. HJSON is more forgiving than JSON and supports comments.

Yellow is areas you will input data/edit fields
Blue are comments about Configuration File objects

  1. Paste your Baker wallet in between the quotes
  2. Set your Baker fee (ie 0.05 = 5% fee)
  3. Input minimum payout for delegators (ie. 1 = 1 XTZ)
  4. This section allows you to split payments for baking (Bonds) and fees from delegators (Fees) if you want - input Baker wallet address and percentage to split. This example does not split, where 1=100% to baker wallet.
  5. This section refers to network parameters to fetch information about the baker in order to compile rewards and payouts - Do not edit unless you are an experienced user
  6. Over delegation projection prohibits you from over paying beyond your delegation limit - Do not edit unless you are an experience user

This is as basic configuration file for running the TezPay application. The next section will review the advanced configuration file, giving more options and customization to the TezPay application. A user may splice sections from the advanced file to the simple to build a custom file as well - but should be done by experienced users.

Setup: Step 1b: Configuration File (advanced)

This section will review how to setup the configuration file (advanced-version) to be used by the TezPay application.

Note: must have file name config.hjson, case-sensitive

Advanced Configuration file for TezPay.

Yellow is areas you will input data/edit fields Blue are comments about Configuration File objects

💡 TIP: Start Simple

The example below is a more advanced configuration file showcasing several customization features. For most bakers, a simpler configuration is recommended. See TezPay Starter Configuration which works for 90% of bakers.

  1. Paste your Baker wallet in between the quotes
  2. Set your Baker fee (ie 5% = 0.05)
  3. Input minimum payout for delegators (ie. 1 = 1 XTZ)
  4. Input minimum staking balance for delegators
  5. Input delegators wallets that you wish to ignore completely (not often used)
  6. Overrides: These will override global settings for delegators - you may delete/remove specific fields where you want to ignore
    1. Input wallet address for specific delegator you wish to apply overrides for
    2. Input a delegator-specific custom fee (ie 0.5% = 0.005)
    3. Input either true or false where true removes the fee from delegator, and false applies the fee specified in the line above
    4. Input minimum balance override for specified wallet\
    5. If you wish to add multiple wallets for over rides, add another wallet following same format keeping the { } to contain the wallet attribute as shown.
  7. This section allows you to split payments for baking (Bonds), input wallet address and percentage to allocate (see example above for structure of more than 1 wallet. 100%=1.00
  8. This section allows you to split payments for fees collected (Fees), input wallet address and percentage to allocate (see example above for structure of more than 1 wallet. 100%=1.00
  9. Donations refer to donating a specific amount of XTZ to wallets every payout
    1. Input a donation amount in donate field as a percentage (ie 2.5% = 0.025)
    2. Input wallets that you wish to donate to and percentage for each (ie 100% = 1.0)
  10. This section refers to network parameters to fetch information about the baker in order to compile rewards and payouts Do not edit unless you are an experienced user

💡 TIP: Configure Multiple RPCs for Reliability

To avoid RPC failures during payouts, configure multiple RPC endpoints in your config.hjson:

network: {
    rpc_pool: [
        "https://rpc.tzkt.io/mainnet"
        "https://rpc.tzbeta.net/"
        "https://eu.rpc.tez.capital"
        "https://us.rpc.tez.capital"
        "https://prod.tcinfra.net/rpc/mainnet"
    ]
    tzkt_url: "https://api.tzkt.io"
}

TezPay will automatically try the next RPC if one fails.

  1. Over delegation projection prohibits you from over paying beyond your delegation limit Do not edit unless you are an experience user
  2. This section allows for automatic notifications/messages to be sent to specific platforms in order to broadcast messages (ie ‘Bakery has paid 100XTZ in rewards for latest cycle’ We will cover this in a separate section see appendix X and platforms supported are Twitter, Discord, and E-mail

Advanced Configuration Examples

The following examples show common configuration patterns you can add to your config.hjson.

Custom Fees for Specific Delegators

You can set custom fee rates for individual delegators using two methods:

Method A: Full Override

Use delegators.overrides for complete control over a delegator’s settings:

delegators: {
  overrides: {
    tz1YourFriendAddress: {
      fee: 0         // 0% fee - friend pays no fee
    }
    tz1SpecialDelegator: {
      fee: 0.02      // 2% custom fee (lower than your default)
    }
  }
}

Method B: Fee Shortcut

Use delegators.fee_overrides for a simpler syntax when you only need to change fees:

delegators: {
  fee_overrides: {
    0: ["tz1FriendAddress1", "tz1FriendAddress2"]     // 0% fee (no fee)
    0.02: ["tz1LoyalDelegator"]                       // 2% fee
    0.5: ["tz1Address1"]                              // 50% fee
    1: ["tz1CharityAddress"]                          // 100% fee (all to baker)
  }
}

💡 TIP: Use Method B (fee_overrides) when you only need to change fees. Use Method A (overrides) when you also need to change other settings like minimum_balance or maximum_balance for a delegator.

Payment Timing After Cycle Completion

Control when TezPay sends payments after a cycle ends using the payouts section:

payouts: {
  minimum_delay_blocks: 10     // Wait at least 10 blocks after cycle ends
  maximum_delay_blocks: 250    // Pay within 250 blocks maximum
}

Why this matters:

  • TezPay picks a random time between the minimum and maximum delay
  • This spreads out payout transactions across the network
  • Prevents congestion if many bakers pay simultaneously at cycle end

Timing reference (at 6 seconds per block):

Blocks Approximate Time
10 1 minute
50 5 minutes
250 25 minutes

The default values work well for most bakers. Adjust only if you have specific timing requirements.

Other Configuration Options

TezPay has many more options available. Here’s a quick reference to help you know what’s possible:

Payout Mode (payouts.payout_mode):

payouts: {
  payout_mode: ideal    // 'ideal' (default) or 'actual'
}
  • ideal — Pay based on what delegators should have earned (rarely used but availablea)
  • actual — Pay based on what the baker actually earned (accounts for missed blocks/attestations)

Who Pays Transaction Fees (payouts):

payouts: {
  baker_pays_transaction_fee: true      // Baker covers tx fees (default: true)
  baker_pays_allocation_fee: true       // Baker covers allocation fees for new accounts
}

Delegator Filtering (delegators):

delegators: {
  // Only pay these specific addresses (leave empty to pay everyone)
  prefilter: [
    "tz1WhitelistedAddress1"
    "tz1WhitelistedAddress2"
  ]

  // Never pay these addresses (rewards redistributed to others)
  ignore: [
    "tz1BlacklistedAddress"
    "tz1burnburnburnburnburnburnburjAYjjX"
  ]
}

Redirect Payouts to Different Address:

delegators: {
  overrides: {
    tz1OriginalDelegator: {
      recipient: "tz1DifferentPayoutAddress"    // Send their rewards here instead
    }
  }
}

Cap Delegator Balance (Overdelegation Management):

delegators: {
  overrides: {
    tz1LargeDelegator: {
      maximum_balance: 100000    // Only count up to 100k tez of their balance
    }
  }
}

Minimum Balance & Small Reward Handling:

delegators: {
  requirements: {
    minimum_balance: 1                           // Delegators need at least 1 tez
    below_minimum_reward_destination: everyone   // 'everyone' or 'none'
  }
}
  • everyone — Redistribute small rewards to other delegators
  • none — Small rewards go to the baker

Overdelegation Protection:

overdelegation: {
  protect: true    // Prevent paying more than you can cover (recommended)
}

📚 Full Reference: See the complete sample configuration for all available options including notifications, extensions, and network settings.

Setup: Step 2: Private-Key File

The Private Key file is used to sign the transaction(s) that will payout the rewards. From a security perspective, it is recommended NOT to use the Baker private key due to security concerns with the private key being displayed in plain-text in a file. This section will use the new account and private-key that was acquired in Step 3 - Payout Wallet.

  1. Retrieve the private-key of the wallet you wish to use from the payout wallet of your choice
  2. Paste into a text file (or replace the example that was downloaded from the GitHub repository
  3. Save the file with exact file name and extension payout_wallet_private.key - note: the .key is required in this instance (see below)
Format for naming private key file - must be exactly the same.

Setup: Summary

At this point there should be 3 files in the directory tezpay. These three files will be used to run the application and payouts.

Next Steps:

Configuration:

Getting Started with Baking:

Any questions/comments/concerns? Please contact the Tez Capital team on Discord or Telegram