Skip to main content
Looking to charge fees on Offramps instead? See Developer Fees.
A Settlement Rule is a reusable, profile-level resource that describes how to split an incoming Virtual Account deposit across one or more destination wallets - as flat amounts, percentages, or tiered breakpoints based on deposit size. Create it once, then apply it to any Virtual Account on the same chain; every future deposit into that account is split automatically at conversion time.

​
How it works

1

Create a Settlement Rule

Define up to 10 fee rules and their destination wallets. Not tied to any one Virtual Account - it’s a standalone resource you can reuse across accounts on the same chain.
2

Apply it to a Virtual Account

Associate the rule with a specific user’s Virtual Account by ID. The rule’s chain must match the account’s destination chain.
3

Automatic distribution

Each deposit is split the moment it converts: the destination wallet receives the remainder, and each rule’s cut is sent on-chain to its configured wallet.

​
Rule Settings

Each entry in rules (1-10 per Settlement Rule) describes one cut of the deposit:
  • PERCENTAGE : Fee amount is based on a percentage of the ticket size.
  • FIXED : Fee amount is fixed and does not change based on ticket size.
  • FIXED : a single rate/amount for every deposit.
  • TIERED : rate/amount varies by deposit size.
Required when calculationModel is FIXED, omitted when TIERED.
  • PERCENTAGE : a decimal between 0.0001 and 0.5 (0.01%-50%).
  • FIXED : a flat stablecoin amount between 0.01 and 10,000,000.
Required when calculationModel is TIERED, omitted when FIXED. Array of { upTo, value } (up to 10), where value follows the same bounds as above based on the rule’s type. Exactly one tier must have upTo: null - that’s the open-ended top tier covering everything above the highest breakpoint.
upTo is exclusive. For example, below, a $1000 deposit will fall under the 0.0005 band.
Example

​
How the Fee Math Works

1

Flat fees come off first

Every FIXED-type rule deducts its amount directly from the deposit. For TIERED flat rules, the tier is picked using the deposit’s full size, not any already-reduced remainder.
2

Percentage fees are solved against what's left, not the deposit

All PERCENTAGE-type rules’ rates are summed into one combined rate, then the destination wallet’s share is solved so that destinationAmount + (destinationAmount × combined rate) equals the amount remaining after flat fees. Each percentage rule then takes its own rate of that destination share - so a 1% rule doesn’t take 1% of the deposit, it takes 1% of what the destination wallet ends up with. TIERED percentage rules pick their rate the same way as tiered flat fees, off the full deposit size.
3

The destination wallet gets the remainder

Whatever’s left after every flat and percentage cut is sent to the Virtual Account’s destination wallet, on-chain, in the same batch as the fee payouts.

​
Example

A 1,000 USDC deposit with a flat fee of 5 USDC and a percentage fee of 2%:
  1. The flat fee comes off first: 1,000 − 5 = 995 remaining.
  2. The percentage fee is solved against that remainder: destinationAmount = 995 / 1.02 ≈ 975.49, so the percentage-fee wallet receives 995 − 975.49 = 19.51 (2% of the destination’s share, not of the original 995).
  3. Final split: 5 to the flat-fee wallet, 19.51 to the percentage-fee wallet, 975.49 to the Virtual Account’s destination wallet.

​
Create a Settlement Rule

Request
Response

​
Apply a Settlement Rule to a Virtual Account

The Settlement Rule’s chain must match the Virtual Account’s destination chain.
Once applied, the Virtual Account’s settlementRuleId field reflects the active rule - see Virtual Accounts.

​
Remove a Settlement Rule from a Virtual Account

Future deposits stop being split; the Virtual Account’s full deposit amount goes to its destination wallet again.

​
Getting Help

  • 📧 Email: support@hifi.com
  • 💬 Slack: Message us in our shared Slack channel