Skip to main content
Settlement Rules allow you to configure automated fee calculations and distributions for Virtual Account transactions. Automatically deduct fees using fixed amounts, percentages, or tiered pricing models, and send them to specified wallet addresses.
Looking to charge fees for offramps? Visit Developer Fees for more details.

​
How Settlement Rules Work

1

Create settlement rule

Define fee calculation methods and destination wallets. Settlement rules support fixed and tiered pricing models with percentage or flat fee amounts.
2

Apply to virtual account

Associate the rule with a user’s virtual account. Rules must be created on the same blockchain network as the virtual account’s destination chain.
3

Automatic distribution

Fees are automatically calculated and distributed on each transaction. The transaction amount is received, fees are deducted, and payments are sent to specified wallet addresses.

​
Rule Configuration

Settlement rules support two calculation models that can be combined:
  • Fixed: Apply a single rate or value to all transactions
  • Tiered: Apply different rates or values based on transaction amount ranges
For each model, you can use either fixed values (flat fee amounts) or percentage values (percentage of transaction amount). You can also configure whether to include the HIFI platform fee in the calculation.

​
Creating Settlement Rules

Create a settlement rule using the Create Settlement Rule endpoint.

​
Request

curl -X POST "https://sandbox.hifibridge.com/v2/virtual-accounts/settlement-rules" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "chain": "BASE",
    "includeHIFIFee": false,
    "rules": [
      {
        "type": "PERCENTAGE",
        "calculationModel": "FIXED",
        "value": 0.001,
        "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
      },
      {
        "type": "FIXED",
        "calculationModel": "FIXED",
        "value": 0.5,
        "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
      }
    ]
  }'
​
requestId
string
required
Unique identifier for the request (recommend using UUID v4).
​
chain
string
required
Blockchain network for the settlement rule (e.g., BASE, POLYGON, ETHEREUM, SOLANA).
​
includeHIFIFee
boolean
Whether to include HIFI platform fee in the calculation. Defaults to false.
​
rules
array
required
Array of fee rule objects to apply (minimum 1 rule required). Each rule object contains:
Multiple rules can be applied to a single settlement rule configuration. The rules are processed in the order they are defined.

​
Response

{
  "id": "15c786fb-de7a-520c-a4b3-f312d4a122d2",
  "chain": "BASE",
  "includeHIFIFee": false,
  "rules": [
    {
      "type": "PERCENTAGE",
      "calculationModel": "FIXED",
      "value": 0.001,
      "tiers": null,
      "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
    },
    {
      "type": "FIXED",
      "calculationModel": "FIXED",
      "value": 0.5,
      "tiers": null,
      "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
    }
  ]
}
​
id
string
Unique settlement rule ID. Use this when applying the rule to virtual accounts.
​
chain
string
Blockchain network the rule is configured for. Must match the virtual account’s destination chain.
​
includeHIFIFee
boolean
Whether HIFI platform fees are included in fee calculations.
​
rules
array
Array of fee rules with their configuration, including type, calculation model, values, and beneficiary wallets.
For detailed field documentation, see the Create Settlement Rule API reference.

​
Rule Types

Settlement rules support two calculation models that can be combined to create flexible fee structures:
Charge a flat fee amount per transaction regardless of transaction size.
{
  "type": "FIXED",
  "calculationModel": "FIXED",
  "value": 0.5,
  "tiers": null,
  "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
}
Charge a percentage of the transaction amount using a single rate.
{
  "type": "PERCENTAGE",
  "calculationModel": "FIXED",
  "value": 0.001,
  "tiers": null,
  "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
}
Charge a percentage using different rates based on transaction amount ranges. Useful for volume-based pricing.
{
  "type": "PERCENTAGE",
  "calculationModel": "TIERED",
  "value": null,
  "tiers": [
    {
      "min": "",
      "max": "1000",
      "value": 0.0007
    },
    {
      "min": "1000",
      "max": "2000",
      "value": 0.0005
    },
    {
      "min": "2000",
      "max": "",
      "value": 0.0002
    }
  ],
  "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
}
For tiered rules, leave min empty for the first tier and max empty for the last tier to create open-ended ranges.

​
Applying Rules to Virtual Accounts

After creating a settlement rule, associate it with a specific user’s virtual account using the Apply Settlement Rule endpoint.

​
Request

curl -X POST "https://sandbox.hifibridge.com/v2/users/{userId}/virtual-accounts/{accountId}/settlement-rules/{ruleId}" \
  -H "Authorization: Bearer YOUR_API_KEY"
Path Parameters:
  • userId (required): User ID who owns the virtual account
  • accountId (required): Virtual account ID to apply the rule to
  • ruleId (required): Settlement rule ID from the create response
Settlement rules must be created on the same blockchain network as the virtual account’s destination chain. For example, a virtual account configured for POLYGON can only use settlement rules created on POLYGON.

​
How Fee Distribution Works

When a transaction is processed through a virtual account with settlement rules:
1

Transaction received

The transaction amount is received through the virtual account.
2

Fees calculated

Fees are automatically calculated based on the settlement rule configuration.
3

Amounts distributed

The remaining amount is sent to the virtual account’s destination wallet, and fee payments are sent to the specified wallet addresses.

​
Monitoring Fees

Track settlement transactions and fee distributions by monitoring the specified wallet addresses. Each fee distribution includes an on-chain transaction hash for verification.

​
Key Concepts

Settlement rules support two calculation models:Fixed Model:
  • Applies a single rate or value to all transactions
  • Use for consistent pricing regardless of transaction size
  • Example: 0.1% of all transactions or $1 flat fee per transaction
Tiered Model:
  • Applies different rates or values based on transaction amount ranges
  • Use for volume-based pricing (e.g., lower fees for larger transactions)
  • Example: 0.1% for transactions under 1,000,0.051,000, 0.05% for transactions over 1,000
Both models can use either percentage or fixed values.
Each rule can use one of two fee types:Percentage Fees:
  • Calculated as a percentage of the transaction amount
  • Specified as a decimal value (e.g., 0.001 for 0.1%)
  • Example: 0.1% of a 1,000transaction=1,000 transaction = 1
Fixed Fees:
  • Flat amount regardless of transaction size
  • Specified as a number (e.g., 0.5 for $0.50)
  • Example: $1 flat fee per transaction
You can combine multiple rules with different types in a single settlement rule configuration.
The includeHIFIFee parameter controls whether HIFI’s platform fee is included in your fee calculation:
  • false (default): Your fee is calculated on the base transaction amount
  • true: Your fee is calculated on the transaction amount plus HIFI’s fee
Example with includeHIFIFee: true:
  • Transaction: $1,000
  • HIFI fee: $10 (1%)
  • Your fee (0.1%): Calculated on 1,010=1,010 = 1.01
Tiered rules use amount ranges to apply different rates:
{
  "type": "PERCENTAGE",
  "calculationModel": "TIERED",
  "value": null,
  "tiers": [
    {
      "min": "",
      "max": "1000",
      "value": 0.0007
    },
    {
      "min": "1000",
      "max": "2000",
      "value": 0.0005
    },
    {
      "min": "2000",
      "max": "",
      "value": 0.0002
    }
  ]
}
  • Leave min empty for the first tier (0 to max)
  • Leave max empty for the last tier (min and above)
  • Tiers should not overlap and should cover all possible amounts
When multiple rules are specified, they are processed in order:
  1. Each rule is calculated independently
  2. Fees are deducted sequentially
  3. The final amount sent to the destination wallet is the transaction amount minus all fees
Example with two rules (0.1% + $1):
  • Transaction: $1,000
  • Rule 1 (0.1%): $1
  • Rule 2 (1flat):1 flat): 1
  • Total fees: $2
  • Destination receives: $998
Settlement rules must match the virtual account’s blockchain:
  • Create the rule on the same chain as the virtual account’s destination
  • POLYGON virtual accounts require POLYGON settlement rules
  • BASE virtual accounts require BASE settlement rules
  • Attempting to apply an incompatible rule will fail
You can create the same rule configuration on multiple chains if needed.

​
Getting Help