MtGox API version 2: Unofficial Documentation

[nitrous]

Hi there,

I've always been interested in making trading bots, however before I had heard of bitcoins and MtGox, I never ended up doing it because the fees needed to do it always seemed prohibitively high, even for Oanda's forex platform. Now that I have found MtGox however, I am now looking forward to automated trading.

As anyone using MtGox's API will know, documentation is only avaiable on the bitcoin wiki (https://en.bitcoin.it/wiki/MtGox/API/HTTP), and there are three versions:

Version 0 - The first API, currently deprecated, and soon to be dropped
Version 1 - The most widely used and most well documented
Version 2 - The most recent, though information is sparse

Even for version 1, documentation is far from complete or consistent. I have focused my attention of version 2, however, as from what I have read, MtGox is working to overhaul their API, and so I want to start out on the most recent version, so that I won't have to worry about deprecation of version 1 in the near future. For this reason, I have started a project to document version 2. Although there is published documentation, it only lists most of the methods, and most of them don't even have a description, let alone usage information. Details on how to access the API, including the relevance of the nonce value and the rest key and sign needed, are hard to find, and is mostly achieved through example. I'm sure there is more information distributed throughout this forum and available in IRC chatrooms, however I don't think this is an ideal situation.

That is why I have spent the last few days compiling all the information I have found and worked out into an unofficial document. I intend to eventually cover all the API methods consistently, in as much detail as possible, however I also plan to make it brief, comprehensible, and unambiguous. Although I currently have only covered some of the methods, I have made a lot of headway.

https://bitbucket.org/nitrous/mtgox-api/overview

The above is the result of my efforts. As you can see, it explains how the API works, what you need to access it, details of the terms and data used, including currency specifics. I have also given a short example of how to access the API using a key and secret. You will also notice that I have documented the most useful methods for a trading bot. Each method includes a short description, any known arguments it accepts (if applicable), an example of its use if I have been able to obtain one, and bullet points explaining the nuances of each.

I plan to continue extending this as I come across more information, and as I gain experience. I don't currently have any bitcoins in my MtGox account to give examples for the actual trading methods yet (I'm waiting for a significant dip in price), but I'm sure in the near future I will be able to do this as well. Whilst I can't promise regular updates as I am a student and sometimes have a lot of other work, I hope to eventually complete this in its entirety (unless, of course, official documentation comes along with more information, and makes this project obsolete).

Thank you for taking the time to read this, hopefully this will be useful to some of you. Please give me your opinions, and any suggestions for improvements you may have



TLDR: I have started work on unofficial documentation for version 2 of MtGox's API here: https://bitbucket.org/nitrous/mtgox-api/overview. It is not yet complete, but it is freely available for all to use. I welcome your opinions.

[1713593536]

1713593536

[1713593536]

1713593536

[nitrous]

I just received an anonymous donation And I've used it to help update the currently documented methods, notably the actual trading methods, such as adding orders and cancelling them, and getting information on currently open orders. All the currently documented methods should now be complete, however not all the json response key purposes are known. If I have accidentally left any information out, please let me know

I don't currently plan on documenting the other methods listed at the bottom in the near future, as I don't have too much free time currently, however when I do I will endeavour to finish the entire documentation.

A list of the main updates is available near the top of the page, here https://bitbucket.org/nitrous/mtgox-api/overview#markdown-header-updates

[MikeH]

good work, I couldn't even find how to obtain a key due to outdated docs pointing me to the wrong location - got it working in perl, now I just have to make it do something useful.

[nitrous]

good work, I couldn't even find how to obtain a key due to outdated docs pointing me to the wrong location - got it working in perl, now I just have to make it do something useful.

Yeah, the API may be well-featured and easy to use, but it's hard to find reliable usage information. Good luck on your trader, have you got any ideas yet? I'm looking at neural networks currently.

[MikeH]

all I want right now is to monitor and issue a sell order in case of a large drop   kinda weird that isn't a standard feature yet through the web interface.

[nitrous]

all I want right now is to monitor and issue a sell order in case of a large drop   kinda weird that isn't a standard feature yet through the web interface.

Yeah, it's weird that the big exchanges don't support standard exchange features such as order limits, short selling and margin trading. I assume the market just isn't deep enough and volumes aren't big enough to warrant it at the moment. Strange though, as MtGox has a monthly volume in the millions of bitcoins, maybe the features just aren't requested enough by users.

[advanced]

Thank you so much! What do you think are the advantages of starting a production-project using the v2 versus using the v1 ?

For instance: during periods of DDoS, do they perform the same way?

[nitrous]

Thank you so much! What do you think are the advantages of starting a production-project using the v2 versus using the v1 ?

For instance: during periods of DDoS, do they perform the same way?

I think that, when starting any project, it is important to make use of the latest versions:

• It is based off of the experience of previous versions, so is likely to be more reliable and robust
• When previous versions are deprecated, you won't need to update your code as often
• Each new version should be more scalable, so you should see performance benefits

As for DDoS periods, I can't be sure, but I would think it would be better able to function. This is because I don't believe many people are using version 2 currently due to the previous lack of documentation, so there is less load and less incentive to perform a DDoS on the version 2 api. So, assuming that MtGox is running each API on a separate server, it would seem that version 2 will be more resilient.

[advanced]

Thank you, I started right away today. When I'm done I'll be happy to contribute with some code snippets.

My application is in Java and I'm having trouble with SSL.  Could you try to help me?

When I run a simple query I got an exception :

Code:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

with google and stackoverflow I understand what the problem was (maybe) . I should "say" to the java virtual machine to trust mtgox's certificate. In order to do so I :

• downloaded mtgox certificate (file.cer)
• created a keyStore.ks file with keytool -import -alias mtg -file mtgox.com.cer -keystore goxkeystore.ks
• set the parameter to the IDE to run the JVM with the option -Djavax.net.ssl.keyStore=goxkeystore.ks

unfortunately when running the application I still got the same exception. Setting the debug channel on SSL I captured the output. Might be useful?
http://pastebin.com/AwXVFZQ9



OT: I didn't want to start from scratch and to build the client I re-used the code from an example of the v1 : https://gist.github.com/christopherobin/2396722 . My assumption is that the method to sign is the same as before. Am I right?

[nitrous]

Thank you, I started right away today. When I'm done I'll be happy to contribute with some code snippets.

My application is in Java and I'm having trouble with SSL.  Could you try to help me?

When I run a simple query I got an exception :

Code:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

with google and stackoverflow I understand what the problem was (maybe) . I should "say" to the java virtual machine to trust mtgox's certificate. In order to do so I :

• downloaded mtgox certificate (file.cer)
• created a keyStore.ks file with keytool -import -alias mtg -file mtgox.com.cer -keystore goxkeystore.ks
• set the parameter to the IDE to run the JVM with the option -Djavax.net.ssl.keyStore=goxkeystore.ks

unfortunately when running the application I still got the same exception. Setting the debug channel on SSL I captured the output. Might be useful?
http://pastebin.com/AwXVFZQ9



OT: I didn't want to start from scratch and to build the client I re-used the code from an example of the v1 : https://gist.github.com/christopherobin/2396722 . My assumption is that the method to sign is the same as before. Am I right?

MtGox has changed the signing method very slightly, you have to prepend the post-data with a specific part of the URL (the part that follows the version number, so in 'https://data.mtgox.com/api/2/BTCUSD/money/ticker', it's 'BTCUSD/money/ticker'), followed by the null character, you can fix the signing just by adding a single line and changing one other:

Code:

    public String query(String path, HashMap<String, String> args) {
        try {
            // add nonce and build arg list
            args.put("nonce", String.valueOf(System.currentTimeMillis()));
            String post_data = this.buildQueryString(args);
            
                // new line
                String post_data_mac = path.substring(2) + "\0" + post_data
            
            // args signature
            Mac mac = Mac.getInstance("HmacSHA512");
            SecretKeySpec secret_spec = new SecretKeySpec((new BASE64Decoder()).decodeBuffer(this.secret), "HmacSHA512");
            mac.init(secret_spec);
            
                // changed line
                String signature = (new BASE64Encoder()).encode(mac.doFinal(post_data_mac.getBytes()));

You still need the original post_data as this will be sent as normal in the request.

Try it, hopefully it will fix your SSL problem If not, I'll have another look.

EDIT:
Also, make sure that your base url is "https://data.mtgox.com/api/", not "https://mtgox.com/api/", it changed very recently. Additionally, in version 1, the "private/" bit in the URL has been deprecated, but if you're switching to version 2 that doesn't matter.

The change of the base URL should definitely fix your SSL problem, make sure you have the SSL certificate for data.mtgox.com as well though, just in case they differ.

[nitrous]

Thank you, I started right away today. When I'm done I'll be happy to contribute with some code snippets.

That would be great I've just set up a directory for example implementations here: https://bitbucket.org/nitrous/mtgox-api/src/master/examples, and a Java example would be very useful to include. Hopefully at some point there can be a variety of languages to point everyone in the right direction with their respective languages

[advanced]

Thank you a lot for helping Can't wait to get it working asap!

I did the modifications and still got the same error ... Here is the complete code :

http://pastebin.com/4mBrc83n

To test it I'm trying to get my current balance and I call the function without any query_args :

Code:

 GoxJavaExample client = new GoxJavaExample(
                        apyKeys.getApiKey(),
                        apyKeys.getPrivateKey()
                );
                HashMap<String, String> query_args = new HashMap<>();
                client.query("BTCUSD/money/info", query_args);

It might be related with the Hash function not working properly in java?
The SSL error apparently is :

Code:

% Invalidated:  [Session-1, TLS_ECDHE_RSA_WITH_RC4_128_SHA]
JavaFX Application Thread, SEND TLSv1 ALERT:  fatal, description = certificate_unknown
JavaFX Application Thread, WRITE: TLSv1 Alert, length = 2
JavaFX Application Thread, called closeSocket()
JavaFX Application Thread, handling exception: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Plus, while building I'm receiving the following warning related to the Obsolescence of the BASE64Decoder package :

Code:

/Users/advanced/Dropbox/Botcoin.io/development/Botcoin/src/io/botcoin/api/GoxJavaExample.java:12: warning: BASE64Decoder is internal proprietary API and may be removed in a future release
import sun.misc.BASE64Decoder;
/Users/advanced/Dropbox/Botcoin.io/development/Botcoin/src/io/botcoin/api/GoxJavaExample.java:13: warning: BASE64Encoder is internal proprietary API and may be removed in a future release
import sun.misc.BASE64Encoder;
/Users/advanced/Dropbox/Botcoin.io/development/Botcoin/src/io/botcoin/api/GoxJavaExample.java:55: warning: BASE64Decoder is internal proprietary API and may be removed in a future release
            SecretKeySpec secret_spec = new SecretKeySpec((new BASE64Decoder()).decodeBuffer(this.secret), "HmacSHA512");
/Users/advanced/Dropbox/Botcoin.io/development/Botcoin/src/io/botcoin/api/GoxJavaExample.java:58: warning: BASE64Encoder is internal proprietary API and may be removed in a future release
            String signature = (new BASE64Encoder()).encode(mac.doFinal(post_data_mac.getBytes()));
4 warnings

[nitrous]

Thank you a lot for helping Can't wait to get it working asap!

I did the modifications and still got the same error ... Here is the complete code :

http://pastebin.com/4mBrc83n

To test it I'm trying to get my current balance and I call the function without any query_args :

First, now that you've moved the api version into the BASE_URL, path.substring(2) should now just be path (I used substring to trim the '1/' off in your original code).

It might be related with the Hash function not working properly in java?
The SSL error apparently is :

I'm not really sure why you're getting this SSL error, but I haven't used Java in a while. Try -Djavax.net.ssl.trustStore instead of .keyStore.

Plus, while building I'm receiving the following warning related to the Obsolescence of the BASE64Decoder package :

For the base 64 code, apparently sun.misc functions are indeed deprecated, try replacing your base64 calls with the equivalents from here: http://commons.apache.org/proper/commons-codec/

[advanced]

Thanks again.

Ok so , i got rid of the .substring()

Code:

String post_data_mac = path + "\0" + post_data;

 I run the JVM with the trustStore instead of keyStore

Code:

-Djavax.net.ssl.trustStore=resources/goxkeystore.ks -Djavax.net.ssl.trustStorePassword=xxx -Djavax.net.debug=ssl 

,

 and I replaced the Base64 functions with apache's ones

Code:

     // add nonce and build arg list
            args.put("nonce", String.valueOf(System.currentTimeMillis()));
            String post_data = this.buildQueryString(args);
            String post_data_mac = path + "\0" + post_data;
        
            // args signature
            Mac mac = Mac.getInstance("HmacSHA512");
            SecretKeySpec secret_spec = new SecretKeySpec(Base64.decodeBase64(this.secret), "HmacSHA512");
            mac.init(secret_spec);
            String signature = Base64.encodeBase64String(mac.doFinal(post_data_mac.getBytes()));
 
            // build URL
            URL queryUrl = new URL(BASE_URL + path);

Still got the same SSL error... it has to be related to the certificate I downloaded from mtgox.com with chrome. Maybe they use a different one for the data.mtgox.com ?

[nitrous]

Thanks again.

Ok so , i got rid of the .substring()

Code:

String post_data_mac = path + "\0" + post_data;

 I run the JVM with the trustStore instead of keyStore

Code:

-Djavax.net.ssl.trustStore=resources/goxkeystore.ks -Djavax.net.ssl.trustStorePassword=xxx -Djavax.net.debug=ssl 

,

 and I replaced the Base64 functions with apache's ones

Code:

     // add nonce and build arg list
            args.put("nonce", String.valueOf(System.currentTimeMillis()));
            String post_data = this.buildQueryString(args);
            String post_data_mac = path + "\0" + post_data;
        
            // args signature
            Mac mac = Mac.getInstance("HmacSHA512");
            SecretKeySpec secret_spec = new SecretKeySpec(Base64.decodeBase64(this.secret), "HmacSHA512");
            mac.init(secret_spec);
            String signature = Base64.encodeBase64String(mac.doFinal(post_data_mac.getBytes()));
 
            // build URL
            URL queryUrl = new URL(BASE_URL + path);

Still got the same SSL error... it has to be related to the certificate I downloaded from mtgox.com with chrome. Maybe they use a different one for the data.mtgox.com ?

Ah yes, that must be it, I just checked and mtgox.com is signed by VeriSign, whereas data.mtgox.com is signed by StartCom - two different certificates unfortunately. Go to https://data.mtgox.com and you should be able to get the correct certificate, it might be useful adding it to the same keystore as well, just in case it ever needs both. Hopefully this will finally fix it

[MikeH]

hey do you know whether these chart sites, listentobitcoins etc that use websockets relay data from mtgox or just redirect people to mtgox?

if the latter I'm thinking it must be pretty taxing to their bandwidth.

[Grover]

all I want right now is to monitor and issue a sell order in case of a large drop   kinda weird that isn't a standard feature yet through the web interface.

Yeah, it's weird that the big exchanges don't support standard exchange features such as order limits, short selling and margin trading. I assume the market just isn't deep enough and volumes aren't big enough to warrant it at the moment. Strange though, as MtGox has a monthly volume in the millions of bitcoins, maybe the features just aren't requested enough by users.

This one has those features.

https://www.kraken.com/
https://bitcointalk.org/index.php?topic=159974.0;topicseen

[nitrous]

all I want right now is to monitor and issue a sell order in case of a large drop   kinda weird that isn't a standard feature yet through the web interface.

Yeah, it's weird that the big exchanges don't support standard exchange features such as order limits, short selling and margin trading. I assume the market just isn't deep enough and volumes aren't big enough to warrant it at the moment. Strange though, as MtGox has a monthly volume in the millions of bitcoins, maybe the features just aren't requested enough by users.

This one has those features.

https://www.kraken.com/
https://bitcointalk.org/index.php?topic=159974.0;topicseen

Kraken looks quite promising, but are you sure it's legitimate? The information on the front page is filled with lorem ipsum text, and its FAQ is not complete yet either. Plus, their price and volume data look suspiciously similar to MtGox's. It might just be that they're still in beta, but I'll definitely follow them if they prove to be trustworthy. Do you know if they have/plan to have an API?

[nitrous]

hey do you know whether these chart sites, listentobitcoins etc that use websockets relay data from mtgox or just redirect people to mtgox?

if the latter I'm thinking it must be pretty taxing to their bandwidth.

Listentobitcoins is nice, never heard of it before I checked their source, and the mtgox connection is client-side, but you have to click the checkbox first, so it probably isn't too taxing at the moment. I also checked bitcoinity, and it appears to cache it server-side for the website to collect by JSON (though in the source, there is reference to websockets, but I don't think it actually connects to MtGox). It depends on the site I guess, but MtGox can cope with it I think, especially as they have anti-DDoS filters in place in case the load gets too taxing. Their main issue is with their trading engine, which they are trying to improve currently.

[MikeH]

yea I downloaded the source to listentobitcoins too, it only shows transactions from blockchain for me, can't get it to show trades for some reason, it connects but nothing comes through.

I was thinking of using it as a starting point for another little project but don't really want to convert it to socket.io just cos mtgox websocket maybe temporarily dodgy.


---
edit:  never mind just spotted this:

<shockdiode> websocket is officially deprecated now?
<MagicalTux> shockdiode: yep, replaced by socket.io server