Skip to main content
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., , , , ).
​
includeHIFIFee
boolean
Whether to include HIFI platform fee in the calculation. Defaults to .
​
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

​
Getting Help

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