> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hifi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settlement Rules

> 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.

<Info>
  Looking to charge fees for offramps? Visit [Developer Fees](/docs/features/developer-fees) for more details.
</Info>

## How Settlement Rules Work

<Steps>
  <Step title="Create settlement rule">
    Define fee calculation methods and destination wallets. Settlement rules support fixed and tiered pricing models with percentage or flat fee amounts.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](https://docs.hifi.com/api-reference/settlement-rules/create-a-settlement-rule) endpoint.

### Request

```bash theme={null}
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"
      }
    ]
  }'
```

<ResponseField name="requestId" type="string" required>
  Unique identifier for the request (recommend using UUID v4).
</ResponseField>

<ResponseField name="chain" type="string" required>
  Blockchain network for the settlement rule (e.g., ,{" "} , , ).
</ResponseField>

<ResponseField name="includeHIFIFee" type="boolean">
  Whether to include HIFI platform fee in the calculation. Defaults to{" "} .
</ResponseField>

<ResponseField name="rules" type="array" required>
  Array of fee rule objects to apply (minimum 1 rule required). Each rule object contains:

  <Expandable title="Rule Object Fields">
    <ResponseField name="type" type="string" required>
      Fee type. Must be  or .
    </ResponseField>

    <ResponseField name="calculationModel" type="string" required>
      Calculation model. Must be  or .
    </ResponseField>

    <ResponseField name="value" type="number" nullable>
      Fee value (required for  model, omit for{" "} ). Use decimal for percentages or a flat amount.
    </ResponseField>

    <ResponseField name="tiers" type="array" nullable>
      Array of tier configurations (required for  model, omit for ). Each tier contains:

      <Expandable title="Tier Object Fields">
        <ResponseField name="min" type="string" required>
          Minimum value for this tier (empty string required for first tier).
        </ResponseField>

        <ResponseField name="max" type="string" required>
          Maximum value for this tier (empty string required for last tier).
        </ResponseField>

        <ResponseField name="value" type="number" required>
          Fee value for this tier.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="walletAddress" type="string" required>
      Beneficiary wallet address to receive the fee.
    </ResponseField>
  </Expandable>
</ResponseField>

<Info>
  Multiple rules can be applied to a single settlement rule configuration. The rules are processed in the order they are defined.
</Info>

### Response

```json theme={null}
{
  "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"
    }
  ]
}
```

<ResponseField name="id" type="string">
  Unique settlement rule ID. Use this when applying the rule to virtual accounts.
</ResponseField>

<ResponseField name="chain" type="string">
  Blockchain network the rule is configured for. Must match the virtual account's destination chain.
</ResponseField>

<ResponseField name="includeHIFIFee" type="boolean">
  Whether HIFI platform fees are included in fee calculations.
</ResponseField>

<ResponseField name="rules" type="array">
  Array of fee rules with their configuration, including type, calculation model, values, and beneficiary wallets.
</ResponseField>

<Info>
  For detailed field documentation, see the [Create Settlement Rule](https://docs.hifi.com/api-reference/settlement-rules/create-a-settlement-rule) API reference.
</Info>

## Rule Types

Settlement rules support two calculation models that can be combined to create flexible fee structures:

<AccordionGroup>
  <Accordion title="Fixed Calculation with Fixed Value">
    Charge a flat fee amount per transaction regardless of transaction size.

    ```json theme={null}
    {
      "type": "FIXED",
      "calculationModel": "FIXED",
      "value": 0.5,
      "tiers": null,
      "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
    }
    ```
  </Accordion>

  <Accordion title="Fixed Calculation with Percentage">
    Charge a percentage of the transaction amount using a single rate.

    ```json theme={null}
    {
      "type": "PERCENTAGE",
      "calculationModel": "FIXED",
      "value": 0.001,
      "tiers": null,
      "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
    }
    ```
  </Accordion>

  <Accordion title="Tiered Calculation with Percentage">
    Charge a percentage using different rates based on transaction amount ranges. Useful for volume-based pricing.

    ```json theme={null}
    {
      "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"
    }
    ```

    <Info>
      For tiered rules, leave `min` empty for the first tier and `max` empty for the last tier to create open-ended ranges.
    </Info>
  </Accordion>
</AccordionGroup>

## Applying Rules to Virtual Accounts

After creating a settlement rule, associate it with a specific user's virtual account using the [Apply Settlement Rule](https://docs.hifi.com/api-reference/settlement-rules/apply-settlement-rule-to-virtual-account) endpoint.

### Request

```bash theme={null}
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

<Warning>
  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.
</Warning>

## How Fee Distribution Works

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

<Steps>
  <Step title="Transaction received">
    The transaction amount is received through the virtual account.
  </Step>

  <Step title="Fees calculated">
    Fees are automatically calculated based on the settlement rule configuration.
  </Step>

  <Step title="Amounts distributed">
    The remaining amount is sent to the virtual account's destination wallet, and fee payments are sent to the specified wallet addresses.
  </Step>
</Steps>

### 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](mailto:support@hifi.com)
* 💬 **Slack:** Message us in our shared Slack channel

## Related Resources

* [Virtual Accounts](/docs/accounts/virtual-accounts) - Set up reusable bank accounts for deposits
* [Developer Fees](/docs/features/developer-fees) - Fee calculation for offramp transactions
* [API Reference](https://docs.hifi.com/api-reference/settlement-rules/create-a-settlement-rule) - Complete endpoint documentation