Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  1. A User with USD Rail enabled
  2. A Virtual Account configured

​
Step 1: Create Settlement Rule

POST /v2/virtual-accounts/settlement-rules 
curl --request POST \
     --url https://production.hifibridge.com/v2/virtual-accounts/settlement-rules \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
  "chain": "BASE",
  "includeHIFIFee": true,
  "rules": [
    {
      "type": "PERCENTAGE",
      "calculationModel": "FIXED",
      "value": 0.001,
      "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
    },
    {
      "type": "FIXED",
      "calculationModel": "FIXED",
      "value": 0.5,
      "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
    },
    {
      "type": "PERCENTAGE",
      "calculationModel": "TIERED",
      "tiers": [
        {
          "max": "1000",
          "min": "",
          "value": 0.0007
        },
        {
          "max": "2000",
          "min": "1000",
          "value": 0.0005
        },
        {
          "max": "",
          "min": "2000",
          "value": 0.0002
        }
      ],
      "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
    }
  ]
}'
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"
    },
    {
      "type": "PERCENTAGE",
      "calculationModel": "TIERED",
      "value": null,
      "tiers": [
        {
          "max": "1000",
          "min": "",
          "value": 0.0007
        },
        {
          "max": "2000",
          "min": "1000",
          "value": 0.0005
        },
        {
          "max": "",
          "min": "2000",
          "value": 0.0002
        }
      ],
      "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
    }
  ]
}

​
Rule Type Examples

{
  "type": "FIXED",
  "calculationModel": "FIXED",
  "value": 0.5,
  "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
}

{
  "type": "PERCENTAGE",
  "calculationModel": "FIXED",
  "value": 0.001,
  "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
}

{
  "type": "PERCENTAGE",
  "calculationModel": "TIERED",
  "tiers": [
    {
      "max": "1000",
      "min": "",
      "value": 0.0007
    },
    {
      "max": "2000",
      "min": "1000",
      "value": 0.0005
    },
    {
      "max": "",
      "min": "2000",
      "value": 0.0002
    }
  ],
  "walletAddress": "0x15FB50680fEB2f726413416665c25f9B397b047b"
}

​
Step 2: Apply Rule to Virtual Account

Associate the settlement rule with a specific user’s virtual account: POST /v2/users/{userId}/virtual-accounts/{accountId}/settlement-rules/{ruleId} 
curl --request POST \
     --url https://production.hifibridge.com/v2/users/{userId}/virtual-accounts/{accountId}/settlement-rules/{ruleId} \
     --header 'accept: application/json'

​
Step 3: Monitor Settlement Activity

Track settlement transactions and fee distributions by:

​
Check Wallet Balances

Monitor the specified wallet addresses in your settlement rules to see incoming fee payments: 
# Example: Check wallet balance on Base network
# Use your preferred blockchain explorer or wallet interface

​
Look Up Transaction Hashes

When transactions occur, you can look up the transaction hash on the appropriate blockchain explorer: Simply paste the transaction hash into the explorer to view:
  • Transaction details
  • Fee amounts transferred
  • Confirmation status
  • Block information
⌘I