HIFI Docs

A Settlement Rule splits a Virtual Account’s incoming deposits across multiple destinations by fee tier. The biggest change is the tier shape itself, plus how a rule’s destination is specified. See the platform-wide changes for ID format, pagination, error shape, and idempotency.

Endpoints

v2	v3	Notes
`POST /v2/virtual-accounts/settlement-rules`	`POST /v3/virtual-accounts/settlement-rules`	Request body changed — see below.
`GET /v2/virtual-accounts/settlement-rules/:ruleId`	`GET /v3/virtual-accounts/settlement-rules/:settlementRuleId`
`GET /v2/virtual-accounts/settlement-rules`	`GET /v3/virtual-accounts/settlement-rules`	List envelope changed to the standard `{data, pagination}` shape. Optional `chain` filter.
`POST /v2/.../settlement-rules/:ruleId/update`	`PATCH /v3/virtual-accounts/settlement-rules/:settlementRuleId`	Verb change.
`DELETE /v2/.../settlement-rules/:ruleId`	`DELETE /v3/virtual-accounts/settlement-rules/:settlementRuleId`	Same restriction: fails if the rule is currently applied to a Virtual Account.
`POST /v2/users/:userId/virtual-accounts/:accountId/settlement-rules/:ruleId` (apply)	`PUT /v3/virtual-accounts/:virtualAccountId/settlement-rules` (`settlementRuleId` in body)	Verb changed from `POST` with the rule ID in the path to `PUT` with the rule ID in the request body.
`DELETE /v2/users/:userId/virtual-accounts/:accountId/settlement-rules` (remove)	`DELETE /v3/virtual-accounts/:virtualAccountId/settlement-rules`	Same shape.

Request changes: tiers and destination

v2 — tiers are {min, max, value} strings, with an empty string marking the open end of the first/last tier; destination is a raw wallet address:

{
  "chain": "POLYGON",
  "includeHIFIFee": true,
  "rules": [
    { "type": "PERCENTAGE", "calculationModel": "TIERED", "walletAddress": "0xabc123...",
      "tiers": [
        { "min": "", "max": "1000", "value": 1 },
        { "min": "1000", "max": "", "value": 0.5 }
      ]
    }
  ]
}

v3 — tiers are {upTo, value} with a single ascending breakpoint (exactly one tier has upTo: null for the open-ended top tier); destination is a registered wallet reference:

{
  "requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "chain": "POLYGON",
  "includeHIFIFee": true,
  "nickname": "Standard split",
  "rules": [
    { "type": "PERCENTAGE", "calculationModel": "TIERED", "walletId": "wlt_fkc0E4OsfHWZPNXiPhj4q",
      "tiers": [
        { "upTo": 1000, "value": 1 },
        { "upTo": null, "value": 0.5 }
      ]
    }
  ]
}

v2 field	v3 field	Change
`tiers[].min` / `tiers[].max`	`tiers[].upTo`	Changed shape — `{min, max, value}` strings (`""` marks an open end) become `{upTo, value}`, a single ascending breakpoint per tier (`upTo: null` marks the open top tier)
`walletAddress`	`walletId` / `externalWalletId`	Removed as a raw address — exactly one registered wallet reference required instead
—	`requestId`	New, required
—	`nickname`	New, optional

Known gap, unchanged from v2: applying a rule to a Virtual Account doesn’t verify the rule’s chain matches the Virtual Account’s destination chain, or block Solana. A mismatched apply can silently misroute a fee cut to the wrong chain. Verify the chain yourself before applying a rule.

Response changes

v2

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "chain": "POLYGON",
  "includeHIFIFee": true,
  "rules": [
    {
      "type": "PERCENTAGE",
      "calculationModel": "TIERED",
      "value": null,
      "walletAddress": "0xabc123...",
      "tiers": [
        { "min": "", "max": "1000", "value": 1 },
        { "min": "1000", "max": "", "value": 0.5 }
      ]
    }
  ]
}

v3

{
  "id": "sr_QW1e2r3t4y",
  "requestId": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "nickname": "Standard split",
  "chain": "POLYGON",
  "includeHIFIFee": true,
  "rules": [
    {
      "type": "PERCENTAGE",
      "calculationModel": "TIERED",
      "value": null,
      "walletId": "wlt_fkc0E4OsfHWZPNXiPhj4q",
      "externalWalletId": null,
      "tiers": [
        { "upTo": 1000, "value": 1 },
        { "upTo": null, "value": 0.5 }
      ]
    }
  ],
  "createdAt": "...",
  "updatedAt": "..."
}

Change	Detail
`id`	Raw UUID → prefixed public ID (`sr_...`)
`walletAddress`	Replaced by resolved `walletId`/`externalWalletId` public IDs
`requestId`	New — now included in the response, not just accepted on create
`nickname`	New
`createdAt` / `updatedAt`	New timestamps

ID format

Raw UUID in v2 → sr_... prefixed public ID in v3.

⌘I