Onchain Billing
Onchain Billing ensures seamless, automated reward splits onchain
With Figment's Onchain Billing product, each party receives its accurate share onchain – without the need for any accounting, invoicing or off-chain payment. This is achieved using Figment’s audited and battle-tested fee splitting smart contracts while the assets remain in the customer’s control.
The validator's fee recipient address is the wallet that receives execution layer rewards. For off-chain billing, this is generally equal to the withdrawal address, unless specified otherwise.

For Onchain Billing, we set the validator's fee recipient to a fee splitting smart contract which rewards pass through (but are not held as a balance) and are split N
ways. One fee splitter smart contract is deployed for each withdrawal address.
Activation and Setup
Figment deploys fee splitter contracts according to your business model:
- two-way splitting: Figment + your organization; or
- three-way splitting: Figment + your organization + your end customers
Each contract is audited, non-custodial, and maintains zero balance while acting as a pass-through mechanism. Each customer gets their own contract with no commingling.
In the ETH API endpoints, you'll notice that for each validator, fee_recipient_address
is set to the fee splitter contract, net_fee_payout_address
is set to what the regular fee recipient would be (and is where the validator's net rewards are sent), and withdrawal_address
remains the same.
Important notes:
- For a new withdrawal address, a new fee splitter contract will be deployed once the validator(s) for that address are funded
- The
fee_recipient_address
will change even after you've called Create Validators - Always update your database with the latest addresses from GET /validators after validator deposit
- Monitor
net_fee_payout_address
for actual reward payouts
Example
Here is an example of a three party split, where
- Fee splitter contract address is:
0xE9EB3EEFe4b71C4Ea991869C5B3AE6B3B7907f45
- Net fee payout address is:
0xe3e2ab62ae98a5fc599ff2dee0d9ea1a93b797fb
- Figment's address is:
0xeD488E6cc4B030eb5BfddE3227C3D5da2b9040E8
- Party 3's address is:
0xa1e3b3a77cf01cda4c5c20f88705c7512ceee1af
API Reference
To support automated reward tracking and integrations, Figment provides several ETH rewards APIs. These APIs give you validator-level granularity and are designed to reflect both real-time and settled data.
- Net Rewards API
- Purpose: Returns only rewards that have already been distributed to your wallet via the fee splitter contract
- Use Case: Ideal for accounting, reporting, and validating partner fee flows
- Includes execution layer rewards that have been split and swept to your payout address
- Does not include pending or unclaimed consensus layer rewards
- Primary source for validating actual received rewards
- Gross Rewards API
- Purpose: Provides the full view of validator rewards, including those not yet swept to a wallet
- Use Case: Useful for understanding pending rewards, performance analysis, and forecasting
- Includes accrued consensus layer rewards and execution layer tips and MEV not yet distributed
- This API reflects total earned rewards, not net payouts
- Add Address API
- Purpose: Allows partners to register new staking wallets and configure their effective fee split with Figment
- Use Case: Required when onboarding new customers or wallets into Onchain Billing
- Includes wallet address to be tracked, gross effective fee (%) agreed upon for the account
- Figment uses this API to ensure correct contract setup
Frequently Asked Questions
1. How do I activate Onchain Billing?
Onchain Billing is activated and managed by Figment's backend team. When you confirm that you want to use Onchain Billing as your billing method:
- Figment deploys a unique fee splitter contract specifically for your organization, or for each of your end customers
- Your validators'
fee_recipient_address
is automatically updated to point to this contract after validator deposit - No action is required on your part - the process is handled automatically
2. What happens if I don't use Onchain Billing?
If you opt out of Onchain Billing, Figment will bill you based on the existing percentage fee agreed upon, invoiced monthly. However, this approach is generally not recommended due to potential operational mistakes/delays and it requires manual coordination between both parties.
3. Are there additional fees for Onchain Billing?
No, there are no additional fees for using the Onchain Billing feature. You only pay the standard service fees as per your agreement.
4. How do execution layer (EL) rewards work with Onchain Billing?
- With Onchain Billing: Figment's service fee is automatically deducted from execution layer rewards through the fee splitter contract
- Without Onchain Billing: You are responsible for transferring Figment's portion of total rewards manually as part of monthly billing
5. Can I see my fee splitter contract transactions?
Yes, the fee splitter contract transactions are transparent and can be viewed on Ethereum block explorers like Etherscan. You can search for your fee_recipient_address
to see all reward distributions.
6. What happens if my validator doesn't propose blocks?
If your validator is not selected to propose blocks, there are no execution layer rewards to split, so no fees are charged. You continue to earn 100% of consensus layer rewards from attestations and other validation duties.
Updated 8 days ago