MtGox API version 2: Unofficial Documentation

[imrer]

I can't believe they don't offer useful documentation about it.

[MusX]

there are more issues with their data/doc info. There is a threshold in the TID field, 4 of the past trades are with 0 amount. It needs to be handled in the volume weighting process. I recommend my scripts described above to fetch it's full and up to date archive.

[xchrix]

I can't believe they don't offer useful documentation about it.

they gox you everytime you have something to do with them for my part i stay far away from mtgox

[alikim]

Hi,

I have a couple of question about connecting to mtgox servers.

I tried to use your ws.client.html file, first of all https://socketio.mtgox.com/socket.io/socket.io.js doesn't seem to be there anymore, so I had to download one from repository. Now I'm trying to connect to ws://echo.websocket.org just for testing and all I got is "Connection timeout message".
I tried ws://echo.websocket.org, http://echo.websocket.org, ws://echo.websocket.org:80/, http://echo.websocket.org:80/ - how exactly do you input the server and the port to connect?

Also I tried to connect to socketio.mtgox.com/mtgox using a C++ program, can't connect to it either.
Can easily connect to ws://echo.websocket.org but not to mtgox one.
Do you know maybe there are some peculiarities in sending the handshake to mtgox, so it would switch to websockets?

Thank you!

[nitrous]

Hi,

I have a couple of question about connecting to mtgox servers.

I tried to use your ws.client.html file, first of all https://socketio.mtgox.com/socket.io/socket.io.js doesn't seem to be there anymore, so I had to download one from repository. Now I'm trying to connect to ws://echo.websocket.org just for testing and all I got is "Connection timeout message".
I tried ws://echo.websocket.org, http://echo.websocket.org, ws://echo.websocket.org:80/, http://echo.websocket.org:80/ - how exactly do you input the server and the port to connect?

Also I tried to connect to socketio.mtgox.com/mtgox using a C++ program, can't connect to it either.
Can easily connect to ws://echo.websocket.org but not to mtgox one.
Do you know maybe there are some peculiarities in sending the handshake to mtgox, so it would switch to websockets?

Thank you!

Hi alikim,

Sorry, my ws.client.html file is specific to socket.io servers. MtGox's socket.io server is unreliable, deprecated and is being phased out in favour of their websocket server (wss://websocket.mtgox.com/mtgox). I believe that it is not difficult to set up websocket access in JS (even using socket.io as your library), however ws.client.html was just a quick little project to play around with the API and I don't really have much free time at the moment to keep it up to date. The reason you could not connect to those servers was because they are purely websocket and my client cannot interface with them.

Perhaps you might have some luck adapting my client or rewriting it using this resource http://www.tutorialspoint.com/html5/html5_websocket.htm? If anyone updates my client to support the websocket protocol I'd be happy to update the documentation with it

Good luck!

[BitcoinLeader]

Anyone knows a PHP Class for the MtGox API v2 ?

Or should I make one?

[nitrous]

Anyone knows a PHP Class for the MtGox API v2 ?

Or should I make one?

All I've seen is this -- https://en.bitcoin.it/wiki/MtGox/API/HTTP#PHP
Not really a fully functional class though, so if you want to then I'd say go for it! I'll link it in my documentation if you want as well

[BitcoinLeader]

Anyone knows a PHP Class for the MtGox API v2 ?

Or should I make one?

All I've seen is this -- https://en.bitcoin.it/wiki/MtGox/API/HTTP#PHP
Not really a fully functional class though, so if you want to then I'd say go for it! I'll link it in my documentation if you want as well

Yeah well that is for v1.

I'm working on a v2 Class now.

Update: I got it up and running, I will post the link when I have implemented all API functions
Update 30 september 2013: I have released v0.1, you can download it here MtGox-PHP-API-V2

[nitrous]

where i can find MTGOX API Key Secret?

Go to https://www.mtgox.com/security and click on 'Advanced API Key Creation'. Enter a name for your key, select the rights you want:

• Get Info - find out your balance, fees, orders, etc
• Trade - buy and sell
• Deposit
• Withdraw
• Merchant - manage merchant services

Then click create key, and you will be given your key and secret. Note down your secret because you will not be able to get it again. If you forget your secret or think someone else is using your key, you can delete the key and make another one. Click on 'Current API Keys'. From here, you can change the rights, and delete the key if necessary using the red cross button. Be careful to only allow the rights you need, you don't want someone else draining your account because you allowed withdrawal rights.

[mfarshada]

Dear nitrous,

First and foremost, thank you for kindly writing the API v2 documentation!

I was just going to add a small update. In my recent tests, the method "money/trades/fetch" with no "since" argument returned all transactions for the past 24 hours. However, when "since" is passed, it behaves as described in your current documentation.

[mfarshada]

Anyone knows a PHP Class for the MtGox API v2 ?

Or should I make one?

All I've seen is this -- https://en.bitcoin.it/wiki/MtGox/API/HTTP#PHP
Not really a fully functional class though, so if you want to then I'd say go for it! I'll link it in my documentation if you want as well

Here is a more complete version of it:
https://github.com/Someguy123/MtGOX-PHP-API/blob/master/Gox.class.php

It is functional and uses v2 authentication method. Most of its functions use still-functioning v0 methods, but very little modification is required to make them v2 compatible. It contains only a POST query function, so if you would like to use GET-only methods such as "fetch", the following seems to work:

Code:

	public function mtgox_query_get($path, array $req = array())
	{
		// generate the GET data string
		$get_data = http_build_query($req, '', '&');
		
		// our curl handle (initialize if required)
		static $ch = null;
		if (is_null($ch))
		{
			$ch = curl_init();
			curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
			curl_setopt($ch, CURLOPT_USERAGENT,
				'Mozilla/4.0 (compatible; MtGox PHP client; ' . php_uname('s') . '; PHP/' .
				phpversion() . ')');
		}
		curl_setopt($ch, CURLOPT_URL, 'https://data.mtgox.com/api/' . $path.'?'.$get_data);

		// run the query
		$res = curl_exec($ch);
		if ($res === false)
			throw new Exception('Could not get reply: ' . curl_error($ch));
		$dec = json_decode($res, true);
		if (!$dec)
			throw new Exception('Invalid data received, please make sure connection is working and requested API exists');
		return $dec;
	}

[nitrous]

Dear nitrous,

First and foremost, thank you for kindly writing the API v2 documentation!

I was just going to add a small update. In my recent tests, the method "money/trades/fetch" with no "since" argument returned all transactions for the past 24 hours. However, when "since" is passed, it behaves as described in your current documentation.

Dear mfarshada,

I'm glad you've found it useful

Thanks for finding this! I've pushed it to the docs now.

[wilfried]

hy,
i cant get this to work, whats wrong? (couldnt find anything on the forum or the net; i just want to get the most recent trades including tid)

https://data.mtgox.com/api/2/BTCUSD/money/trades/fetch?since=1388679721
{"result":"success","data":[]}

i know that <218867 its the tid and after that it should be the unix timestamp with 10 digits, but for everything > 218867 it just returns nothing


thx!

[nitrous]

hy,
i cant get this to work, whats wrong? (couldnt find anything on the forum or the net; i just want to get the most recent trades including tid)

https://data.mtgox.com/api/2/BTCUSD/money/trades/fetch?since=1388679721
{"result":"success","data":[]}

i know that <218867 its the tid and after that it should be the unix timestamp with 10 digits, but for everything > 218867 it just returns nothing


thx!

Hi,

Actually, it needs to be the unix timestamp with 16 digits! After 218867 they switched to micro timestamps, so you need to include the microseconds as well. Try:

https://data.mtgox.com/api/2/BTCUSD/money/trades/fetch?since=1388679721000000

In fact, you're actually supplying the tid after which you want the trades, not the date (though after 218867, they're equivalent). However, if you give too small a tid, the API won't return any results (to try to conserve bandwidth I think). Therefore you need to be within something like 86400000000 of your desired tid in order to get results.

[wilfried]

thanks a lot; it´s especially tricky as the api outputs 10 digits (date:..)..

[nitrous]

thanks a lot; it´s especially tricky as the api outputs 10 digits (date:..)..

No problem To understand it better, have a look at the 'tid' values -- these are what you're passing to the 'since' argument.

[albus]

Hi,
is there a reason why the API uses only POST for private function and never GET ?
The security difference seems small, or is it because GET is cacheable ? In that case they could set the cache reset at a very low value...
Or am I missing something else ?
thanks

[nitrous]

Hi,
is there a reason why the API uses only POST for private function and never GET ?
The security difference seems small, or is it because GET is cacheable ? In that case they could set the cache reset at a very low value...
Or am I missing something else ?
thanks

All respectable secure site use POST with HTTPS because its essential to effectively hide potentially secret information:

• The url and query string of a request are easily accessible and often recorded, so it would undermine the entire point of HTTPS to use GET.
• Another reason is that GET query strings have a maximum length which is quite short, like 1 or 2 kb, so POST makes sense for this reason as well.
• And yet another, as you identified, is the problem of caching; and no, they would never consider setting the cache refresh at a very low value because that would eliminate the whole point of a cache, to reduce server load (which often has been exploited to DDOS MtGox, so I'm pretty sure they don't want to take any chances with this).

Of course, you could argue that a computer program accessing the API probably won't record the URLs and the query strings are likely far less than 1kb and you could control caching for individual resources, but frankly there's little reason to use GET and every to use POST.

Is there some tool or library you're trying to use which doesn't support POST requests?

[albus]

Is there some tool or library you're trying to use which doesn't support POST requests?

Thanks for the answer, it was more a curiosity question.

I am trying write code to access the MtGox API and I was wondering why all exchanges (in the BTC world) use POST everywhere there is authentication, whereas it is not the case in many other APIs like Amazon, Twitter, Twilio etc...

About your first point, isn't it possible to record all the data for a hacker, and not just the URL ? In that case the security improvement is really about using the API in a browser and not showing the request to user or some server recording the requests, but in that case anyway they all use some kind of HMAC. It seems this would protect only against very trivial attacks, that are anyway put off by using SSL+HMAC.
For example a GET on your open orders would show your request (to your browser, but not elsewhere as we are in SSL) but sign it so it cannot be forged to do something else with it.

I am a bit new to HTTP so might be this is not the right way to see it.

[albus]

after searching around a bit (Wikipedia... where I should have started...) I understood your explanation a bit better, what I did not get is that URL does not get encrypted as well when using SSL...

thanks for your explanations !