Developer guide

Fees, ledger and reconciliation

4 min read

Quotes and fees

All monetary values use integer base units. A quote separates the ChatterPay service fee, provider fee, sponsored network fee and total debit. The initial policy charges 25 basis points for swaps and cross-chain transfers; provider fees remain explicit components rather than hidden markup.

Whose policy prices an operation

A fee policy is resolved by (partner, chain, operationType), most specific first, and the lookup always terminates on the reference catalog — so a deployment that configures nothing prices exactly as the paragraph above describes. A Partner's own policy is versioned, and the version is frozen into the quote and the operation, so a past fee stays explainable after that Partner renegotiates.

A service fee is expressed either in basis points or as a fixed amount in USD, converted to the operation's asset when the quote is priced. A fixed_usd policy freezes the rate, its source and the instant it was read into the quote; a quote that cannot be priced within the policy's freshness bound is refused by name rather than falling back to a stale rate, to zero, or to basis points.

Charging and collecting are separate

A fee is accrued when the operation is booked: the debit on the payer has a counterpart credit to a collection account per (partner, asset), so the ledger conserves it. It is collected by a sweep — scheduled or triggered by a per-asset threshold — into the Partner's ChatterPay collection wallet, as a durable operation reconciled against its own on-chain evidence.

Sweeping rather than moving the fee inside every operation is deliberate: charging on chain per operation would roughly double its gas for an amount usually smaller than that gas.

The collection wallet is configuration of the Partner, is reported as a platform account of its own role, and is rotatable by an administrative operation that records the previous address, the new one, who ordered it and when. An accrual binds the address in force when it was booked; an in-flight sweep is never silently retargeted.

What the surfaces report

Alongside what an operation cost, the surfaces report the revenue side: the collection wallet's balance per asset, what is accrued and not yet swept, and whether each fee was paid out of the user's balance or absorbed by the Partner.

Append-only ledger

The ledger uses a PostgreSQL ledger_postings table that is insert-only. Corrections use compensating entries, never silent mutation. Runtime balances are a fast read-model cache rebuilt from the ledger, which remains the durable source of truth.

Reconciliation

For direct EVM transfers, reconciliation independently reads the transaction receipt and ERC-20 Transfer event. LI.FI, ERC-4337 and Bitcoin transfers are reconciled against their own on-chain and provider evidence, with durable reservations, fee disaggregation and scheduled discrepancy handling.

Operational rule

An ambiguous broadcast is reconciled before retransmission. Notification delivery can fail without changing the financial outcome.

Capabilities in this area

This area covers the capabilities below. The Roadmap states the current availability of each one.

  • Initial fee catalog and calculation — Each type of operation has its fee defined in a catalog. The quote returns the amount that will be charged and what it corresponds to, calculated before the operation executes.

  • Append-only PostgreSQL ledger — Movements are written as entries that are never modified or deleted. A correction is written as a new entry, so the history shows what was recorded and when it was corrected.

  • EVM reconciliation against receipt and Transfer event — After a transfer, the reconciler reads the transaction receipt and the Transfer event the contract emitted, and compares the amount and the recipient against what was recorded. The operation is completed only when both agree.

  • Partner fee policies, accrual and sweep — A fee is priced by the policy of the Partner, the chain and the operation type, accrued to a collection account when the operation is booked, and swept to the Partner's collection wallet as an operation of its own. Charging on chain per operation would roughly double its gas for an amount usually smaller than that gas.

  • Rotatable collection wallet — The collection address is configuration of the Partner and is replaced by an administrative operation that records the previous address, the new one, who ordered it and when. A rotation for every network rewrites every network that has a destination of its own, and says which ones it kept.

  • Complete financial ledger and durable reservations — The amount committed to an operation in progress is reserved in the database until it settles or fails. A restart between the quote and the settlement finds the reservation there, so the same balance cannot be spent twice.

  • ERC-4337, LI.FI and Bitcoin reconciliation — Each execution path proves settlement in a different way: a UserOperation has its own hash and needs the EntryPoint event, a LI.FI route settles leg by leg, and a Bitcoin spend produces a change output. The reconciler reads each of those forms of evidence.

  • Daily close and per-tenant reports — A daily process closes the period, calculates the balances of each tenant and produces a report with the movements and fees of the day, so the Partner can compare it against its own accounting.