Fintech Engineering Handbook

That way I can debug and have a last resort of compliance, but also save time by not building the first resort of compliance.

I've spent many hours explaining how idempotency is supposed to work, and why it's important. Most teams understand the need for it, but very few thought about it up front.

Many of these predate the widespread knowledge of idempotency, so often idempotency keys are hacked together by joining various, hopefully globally unique fields, except that they never quite are. (You can look behind the curtain sometimes, e.g. when your bank does not let you transfer the same amount to the same recipient account on the same calendar day.)

    I just published Fintech Engineering Handbook distilled from 6 years of tears, sweat and swears. 
    It’s a free ~25-page resource with various hints and patterns around handling money. 
    Tell me what you think!

[0]: https://mas.to/@krever/116814803588993437

[1]: https://github.com/Krever/fintech-engineering-handbook/commi...

Its at least 80% organic artisanal writing and maybe 20% AI when I needed help with grammar, completeness, broader perspective and everything around.

They mostly need replacing with a full stop or a colon.

E.g.

"In practice this means storing the amount as an integer in its smallest unit - €12.34 becomes 1234"

->

"In practice, this means storing the amount as an integer in its smallest unit: €12.34 becomes 1234."

or

"In practice, this means storing the amount as an integer in its smallest unit (e.g., €12.34 becomes 1234)"

I wouldn't have read your comment if it were all lowercase and used zero punctuation, for example.

It seems like a clever idea (fast integer math, no rounding problems for addition and subtraction), but it'll bite you incredibly hard if you ever stumble upon an edge case such as working with a partner that has a different implied number of digits for a given currency. This is especially relevant for stablecoins, which often have a different number of implied decimal digits than the "fiat" currency they represent.

Also, consider representing amounts as a string type in JSON-based APIs. JSON does not specify decimal precision, so you (and all your users/vendors) will always have to make sure your parser/serializer doesn't internally lose precision by going via floating point. This can get ugly fast, and while a string seems conceptually less neat, it completely bypasses that problem. (Some will call this an anti-pattern [1], but I'd rather not fight this particular battle for ideological purity on the shoulders of my users or shareholders.)

[1] https://blog.json-everything.net/posts/numbers-are-numbers-n...

I largely agree with TFA: Round explicitly and consistently whenever you cross a boundary, i.e. database persistence and internal API calls.

Use whatever works for your required business case internally (i.e. inside of procedures calculating some function of one or more input amounts). This can be regular old floats/doubles if you absolutely know what you're doing, or BigDecimal if you aren't and would rather suffer slightly slower performance than having to talk to an auditor about IEEE 754 rounding modes, or even minor-amount integers (yes, even though I just said to not use them – but you'll want to ABSOLUTELY NEVER leak them outside of your system, including your data/analytics pipeline, which might have different ideas about financial amounts than your business logic implementing a nice custom monetary type).

Floating-point precision has too many gotchas for being suitable to store Decimal types, especially for the Currency use case.

  {
    "price": {
      "amount": 1000,
      "decimal_places": 2,
      "currency": "USD"
    }
  }

The semantics for your string “10.00” are complex - is it considered equal to “10”? To “10.000”? To “10.001”?

A user interacting with an API that uses such a string might make all sorts of assumptions about what it supports.

A user interacting with an API that has an explicit decimal places concept is being told ‘decimals matter! They can vary! Here be dragons!’

Yes, but "10 USD" would be a non-canonical representation and you probably serialized incorrectly.

> To “10.000”?

Yes, but same caveat as above applies.

> To “10.001”?

Obviously not, and any system you'd ever want to use in a financial context will tell you so.

[1]: https://msgspec.dev/supported-types#decimal

[2]: e.g. https://getlago.com/docs/api-reference/fees/fee-object#schem..., although they still use `amount_cents` for all currencies as the base rate

In C# e.g., there is type decimal for those computations.

The art is in making those points well-defined and rare enough to not cause large discrepancies, but frequent enough to avoid ballooning arbitrary-precision numbers across databases and services that might not be able to handle them.

Why would that be a problem? You just transform the values when interacting with their API.

Let's say I operate with a 4 decimal expectation and your API expects 6, is there any way to reconcile that outside of documentation and or metadata ? (which would be the same issue I guess whatever representation is used ?)

Still, even if you do: Chances that your users are just going to assume you're conforming to ISO 4217, some national standard, or your competitor that they're already integrated with are pretty high, so I wouldn't take the chance. Pick something that doesn't have to be documented instead.

Refund $1.00

Repeat

Charge Actual $1.00

Refund $1.000

Alternately

Charge $0.995

ERROR CHARGE AMOUNT MUST BE ROUNDED TO NEAREST CENT

You can have the blockchain team be an expert in converting integer cents, or the forex team be an expert in sub-cent conversions. You don't want to require _every team_ to have expertise in float math, by default.

This works for USD, JPY or $MEMECOIN and it scales very well.

For added fun, you can introduce division. Some systems will allow you to sell 12345.55 USD to buy EUR at a rate of 1.12345.

The article’s “no lost data” tenet is not really viable when this sort of division is involved. Are you going to track your account balance is a rational number with an absolutely immense denominator forever?

There is a remarkable amount of disagreement as to whether one should do one’s back office work based on the price or based on the quantity of the counter currency.

> No one has .0000145 cents in their account. Rounding occurs in the real world.

Indeed. But you either need to convince all parties to agree to round the same way or you need to accept small errors

So, yes, everyone has to understand how all their partners are doing rounding and summing.

I would, however, by quite surprised if my personal bank account did this.

When you owe the bank money, they round up.

Exchanges have calculation rules for every type of mark and payment and will always specify rounding.

1. If someone sells me 12345.55 EUR, I hope to end up with 12345.55 EUR.

2. That's the point though. They will sell you a certain amount of EUR at a certain dollar price. This, in turn, implies a rate (which might well have more than 5 digits behind the decimal). This is ideally close to the quoted rate, sure. But what counts is the actual EUR amount and the actual USD amount, not what rate was quoted or with how many digits.

In the HFT space you save some wire space if you can commit to a consistent exponent for some {slice} up front (think instrument/tick-size/asset-class/exchange/feed/server/whatever/...) such that you only need to send the mantissa and your clients can have a hard coded exponent. However, in similar spaces it's often worth the extra uint32 to send a on-the-wire exponent such that things _can_ change and you aren't hamstrung later by earlier "we only need cents now!" design choices when, e.g., you suddenly need to support bitcoin/... prices to full precision. (your users will thank you when they don't have to coordinate a breaking change when you want to adjust your fixed exponent)

https://en.wikipedia.org/wiki/Decimal128_floating-point_form...

What noitpmeder described is just floating point.

Integers have a consistent precision across the entire number line.

That’s essentially the same thing as a String-serialized big decimal, just less readable, no?