Bitcoin Exchange API Observations

A new project has prompted me to investigate the trading APIs belonging to a number of Bitcoin exchanges. It’s been a fun few weeks and I’ve learned a lot about an area I’ve never really watched in the past.

Credit has to be given to Vault of Satoshi and justcoin for having particularly well behaved APIs (though justcoin does have to be reverse engineered from their trading platform’s source).

However, as expected it’s not all been rainbows and unicorns. At least one exchange has a public API which does not even pretend to work, and most fall into a series of common traps. Hopefully I can use the following notes to design better APIs myself:

• Documentation and consideration of error handling must be foremost in your mind. A developer needs to know the exact procedure for discovering error scenarios and presenting them to the user. This must be consistent across all calls, in all scenarios; do not drop it for unauthenticated calls.
• If you have any value which represents a time you must include timezone information. This data should not simply be documented as a specific constant timezone so as to allow for future changes or the odd implementation mistake. There are a number of well defined standards which have wide traction. Use them.
• For anything finicky, such as authentication, you should be very very precise in the description of the required algorithm. At a minimum this needs a concrete executable example, and should include a step-by-step description of the whole process.
• Don’t add complexity unless you can outline the specific benefit. Seemingly simple things like an extra base64 encode may not add anything of value, but may provide a sufficient burden to a taxed developer that they may prioritise something else. I’m looking at you BTC China.