Fintech Engineering Handbook

E.g. If I ever see a monetary value stored in something else than integers I'm going to run away screaming (thank you Rust decimals represented as JSON floats). It's always integers unless you have a VERY good reason to do otherwise (though exported view can be in anything, even in weird bitcoded formats).

FX exchange. Resolution of FX isn't a point-in-time thing, things like buyer rate-in-time, seller rate-in-time, agreement, agreement tolerance, agreed upon resolution timestamp come in the effect.

Immutability - that's why you want to have event sourcing everywhere that touches money:

    # Resolved stream
    A -> B -> E

    # Actual stream
    A0 -> Edit(A0, A) -> B -> C -> D -> Rollback(B) -> E

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 was CTO of a FinTech where I built the whole software stack from scratch: the lessons in the book are mostly correct. I say mostly, because as always, there is a lot of "it depends" to take into consideration for your particular project. For example, I chose to not use event-sourcing to avoid the whole state computation issue. A standard append-only audit trail can do the job.

You can't guarantee exactly-once delivery but you can construct effectively-once processing, and that is what you really want.

Store every request and response : absolutely, and not only when consuming APIs, but when collecting any information from the outside world (and, if you can, also log every intermediate transformation step within your perimeter). Content-adressed buckets + a relational table are great for this.

The text also does not mention anything about data lineage. What happens if a vendor updates some data mid-day that you absolutely need to be aware of? You need to be able to account for that, while also re-playing computations that used the old values and get the same result. It's not a particularly hard problem to solve, but it takes some thought.

What user xlii said about not storing monetary amounts as floats is a common IEEE 754 issue. And while it's true that financial tracking should be done through immutable logs or event-based records, I don't think every surrounding service needs to be built with event sourcing. I think it's enough to apply it only to core logic like ledgers, settlements, orders, and executions. Looking at xlii's comment, it seems like a technique that only becomes viable when the modeling is successful.

User lxgr's comment points out that it's a minor-unit issue. If JSON numbers are parsed as floats by the language or parser, precision can be lost. Usually people send values with a separate decimal places field. However, I've heard that in HFT, they don't do that because the overhead itself is too costly.

And antonymoose's comment aligns with what many books say. That's why designs like this are common in FX or API contexts. It feels like protocol design, doesn't it?

Putting it all together, everyone's right within their own domain. While I think it'd be great to have someone like xlii as my senior programmer, I also feel like I wouldn't be able to design such a complex system myself. In that sense, everyone's statements are valid, and it's interesting to see how opinions diverge depending on the domain. Is this what expertise looks like

Looking at all this, it seems like you can roughly infer where a programmer is coming from based on their experience. Sometimes programming doesn't feel like finding the right answer, but more like choosing a worldview

Watching how programmers model their domains on HN is always fascinating. Sometimes I click on their profiles and add their domain knowledge to my own personal wiki, thinking I might use it someday

For example the parts talking of retries, idempotency, event ordering, etc. This applies to all systems that require any degree of accuracy, even if no money is directly involved. I've seen so many systems built on the assumption that "we can always retry", but you can only retry if you fail cleanly in the first place, and if the downstream system offers the same level of idempotency that you think it does. Quite often these are not put to the test.

That's putting it politely. Honestly, I think this "handbook" was mostly written by an LLM.

For example, in the immutability section we have this:

   "Separating PII from financial data lets you honor erasure without losing the financial history you’re obliged to keep."

Keeping the financial data whilst trashing the customer names, addresses etc. instantly on-demand before the expiry of the relevant time periods is going to leave your entire organisation with a very bad day in the office if a $lawful_body comes knocking for the data to trace a crime.

People going to work in a Fintech should not be relying on a random "Handbook" written by an unknown person in an unknown jurisdiction.

People going to work in a Fintech should only ever work in accordance with their employer's internal handbooks/guidelines/etc which will have been written in conjunction with their firm's lawyers and compliance people to ensure it complies with the laws and reporting requirements in the jurisdiction(s) in which their employer operates.

Well, in case of a bank it can. And it happens on a daily basis. In fact thats how most private bank money enters the system in the first place either when a bank makes a loan or when it buys any other asset like e.g. a corporate bond (you can conceptualize a loan as an asset purchase as well, the bank buys a promise to pay from the borrower which is recorded as an asset of the bank). Both are a balance sheet extension from a double-entry bookkeeping point of view.

The 4 operations double-entry bookkeeping allows are:

1. balance sheet extension (e.g. making a loan) 2. balance sheet reduction (e.g. loan repayment) 3. asset swap (e.g. a bank buying a government bond with central bank reserves) 4. liability swap (e.g. transferring money from one account to another)

So it may be more accurate to just say that every event that affects the balance sheet must be one of those 4 operations.

Also see "Money creation in the modern economy" - Bank of England Quarterly Bulletin 2014 Q1

I don't care if the balance is one million, before that ACH can process, every single dollar can be (a) wired out, (b) cleared out by yesterday's ACHs (bills, autopay, whatever) and checks, or (c) spent at debit/ATM.

I probably shouldn't tell you why I know that some fintechs don't address this.

I would recommend anyone starting in fintech to take some time to understand accounting principles and the ledger in a bit more depth than just debits vs credits - this is likely what is most unfamiliar to programmers.

Also financial software is very data-heavy and I learned more about databases in my time working in fintech than the 15 years before that. I think going into a bit more detail about even the basics (indexes) will save a lot of headaches.

I'm founding a fintech startup and have been thinking about these things a lot. It is very helpful to have some general validation and guidance to make sure I'm not making huge mistakes.

I really wanted event sourcing, but thought it gets complicated when events have complex validation rules. I ended up with a mix of state and audit logs which works ok for now.

If you're dealing with a party who tracks currency in cents, then tracking currency with more precision than that is going to lead to rounding disagreements. Vice versa if you deal in cents but they deal in tenths of cents. And so on for all the other advice in this document.

I see webhooks documented all the time, but I have yet to use them in practice, nor have my customers requested them. Is the above not true, or are they widely used in some sectors and not others?

The thing for working with currency with doubles is that you have to keep in mind that it can hold 15 digits of precision in total. As long as your numbers don't use more digits than that, like 123456789.01 or 123.456789, you can have perfect decimal precision in your financial math. You just have to always round the result to within 15 digits of precision after each computation, and before each comparison. That's what excel does.

The biggest advantage of doubles is that 1) they're widely supported and 2) you can mix different precision in your system, which will appear if you do international finance or advanced financial products. Some accounting require precision up to the thousandth, some need to be rounded to multiples of 0.25. So at the end of the day you'll never use basic math but some specialised accounting math library and that library can perfectly use float as a backend.

It's refreshing to see someone using the correct phrasing.

The often-seen, stupid way is 'who is this book for'.

P.S. I have no clue how HN works, I posted it myself yesterday and it got 6 points. ¯\_(ツ)_/¯ Anyway, glad for the reach.