MtGox API version 2: Unofficial Documentation

[advanced]

You are welcome, thanks for the good words you used

PS: Today I observed another unexpected behaviour of the APIs. You cannot access the method MONEY/BITCOIN/SEND_SIMPLE if you are using an yubikey. Not even if you gave permissions to the API keys.  This is weird : i mean, i need the yubikey to login into my account, but this is not stopping me to be able to place orders via API. I opened a ticket on mtg.

No problem, it's important to add a spectrum of examples, from quite simple to more sophisticated, to help people get started and then improve their projects, as well as having multiple languages

Thanks, I've updated the docs to note this. Update me if you get an official response, as it does make sense for it to be denied with yubikey enabled, but it is indeed inconsistent.

Here we go :

Hello,

You will have to provide an OTP value with the API. The easiest is to add a TOTP and generate it when calling the API.

Thanks,

MtGox.com Team

[1715344737]

1715344737

[1715344737]

1715344737

[1715344737]

1715344737

[nitrous]

Sorry about that, I may need to contact mtgox and see if they can help.

You don't need to apologize! I'll see if I can get it to work from that date on. Thanks so much.

UPDATE: It seems to be working fine as long as you don't provide a timestamp before 1309108565.

From what I can make out, it seems that there was a database change around 1309108565, as when you use since=0, the tid values are sequential integers, but at 1309108565, they become unix microstamps. Using this, I managed to work out that `since` refers to the tid instead of the date! I have now tested it successfully, and I can get all data from 0 to 1309108565 and beyond by passing in the last tid of the data as the new since value, i.e.:

since=0 gives tids from 1 to 1007
since=1007 gives tids from 1008 to 2007

It also appears that instead of a 24 hour period, the method provides 1000 trades at a time. Passing in the last tid works across the database change boundary as well, so if you pass in since=218500, it will give you tids from 218501 to 218868, and then from 1309108565842636 onwards.

Here we go :

Hello,

You will have to provide an OTP value with the API. The easiest is to add a TOTP and generate it when calling the API.

Thanks,

MtGox.com Team

Thanks advanced, I'll be adding that in to the docs along with the newly found trades/fetch info later today. Do you know what the argument name for the opt value is? Is it just "otp=123456"?

[nitrous]

Ok, I've overhauled the trades/fetch documentation

Here we go :

Hello,

You will have to provide an OTP value with the API. The easiest is to add a TOTP and generate it when calling the API.

Thanks,

MtGox.com Team

Have you been able to find a working argument yet? I tried 'otp', 'totp', 'OTP', 'TOTP' and none of them seemed to work, giving a 403 forbidden error. I don't currently have any funds in my MtGox account, so that might explain why. Perhaps it should be in the header or passed in to the HMAC encryption?

[advanced]

I have no idea.
I'll put it in my backlog. However I just got an answer from the Yubikey team and apparently there is no way whatsoever I can read the OTP from the usb device unless the user physically press the button (i.e., not of much use for my bot ). :/

[pescador]

Is it possible to withdraw USD from MtGox to an OKPAY account using the API? I can't seem to find the commands. However I can assign withdraw rights to an API key, or is that only for withdrawing BTC?

[nitrous]

I have no idea.
I'll put it in my backlog. However I just got an answer from the Yubikey team and apparently there is no way whatsoever I can read the OTP from the usb device unless the user physically press the button (i.e., not of much use for my bot ). :/

You could change only the trade access to google auth, and keep the others on yubikey. There's little reason why someone would hack your account just to make some trades, as all they could do would be to throw away your money. That way, you can generate the codes with your bot, as the google auth algorithm is public I think.

[nitrous]

Is it possible to withdraw USD from MtGox to an OKPAY account using the API? I can't seem to find the commands. However I can assign withdraw rights to an API key, or is that only for withdrawing BTC?

I don't think so. If there is, then there's no information about it. Currently, the withdraw permission only seems to apply to BTC, but as MtGox claim to be overhauling their trade engine and api, it may be possible in the future to perform OKPAY withdraws, amongst others, via the API.

[IIzzII]

I have two random questions:

1) Is there an advantage to using websockets as opposed to POST requests? Are websockets faster? More secure?

2) What does the price on the ticker actually mean? Is it the price of the last trade that was made before the request was received? Is it an average? If you're calculating EMAs and it is at the end of a given time period, is it best to subscribe to the ticker feed and use that value or subscribe to the trades feed and use the value of the last trade?

[nitrous]

I have two random questions:

1) Is there an advantage to using websockets as opposed to POST requests? Are websockets faster? More secure?

2) What does the price on the ticker actually mean? Is it the price of the last trade that was made before the request was received? Is it an average? If you're calculating EMAs and it is at the end of a given time period, is it best to subscribe to the ticker feed and use that value or subscribe to the trades feed and use the value of the last trade?

1) The websocket feed should be faster and less taxing on MtGox, so it's ideal for getting ticker data. As for security, I'm not sure. It may be more reliable, but for trades, info, etc, make sure you're using wss instead of ws, and even then, be careful - if in doubt, POST. Also note that there are two ways to access it, websockets and socket.io, websockets are the currently recommended method (socket.io apparently uses buggy code, while the ws code was rewritten from scratch).

2) The ticker method yields multiple values (see http://bitbucket.org/nitrous/mtgox-api/overview#markdown-header-moneyticker). Most of the values are from the most recent trade (see a more detailed breakdown at the link); however, there is an average available (VWAP), which I believe is for the last 24 hours.

For calculating EMAs, I recommend keeping a local database of all trades as far back as necessary. Information for downloading these is available here. Contact me if you need more detailed information to get this working. Then you can keep it up to date however you want, but I would strongly suggest using websockets. Of course, that depends on how up-to-date you need your database. If you don't need the most recent hour or so of data, then you can just keep accessing `money/trades/fetch` periodically, but if you need to calculate in realtime then definitely use websockets.

[MikeH]

my little app is using data.mtgox v2 with posts, it uses a 15 second time out and it reaches this limit a lot.. how's everyone else dealing with mtgox not responding?  I can just re-try of course but it seems dodgy that this occurs like 10 times / hour.

actually it's not just time outs - it'll run fine for a while then I get a bunch of 502 Bad Gateway's too.

[nitrous]

my little app is using data.mtgox v2 with posts, it uses a 15 second time out and it reaches this limit a lot.. how's everyone else dealing with mtgox not responding?  I can just re-try of course but it seems dodgy that this occurs like 10 times / hour.

actually it's not just time outs - it'll run fine for a while then I get a bunch of 502 Bad Gateway's too.

If you wait 15s between requests you really should be fine. That sounds like MtGox just being overloaded, which can happen fairly often. You can either put in some error handling to fail gracefully in the situation, and just try again (it sounds like you are doing this), or you could try using mtgox's websocket, which is probably more appropriate for a ticker app, although it will use a lot more network bandwidth (and battery, if it's a phone app). What I do in my api for post requests is try the same request repeatedly (up to 10 times) one after another, so you could try that (and just make sure that it doesn't do more than, say, 20 of these in a 15s period, and just sleep the thread until the next 15s window - you'll need to use multithreading to keep the app responsive). You should also change to ticker_fast, as it should be more reliable, and less prone to 502s (plus I think it has no request limit, so no danger of your app being blocked for DDoSing).

[MikeH]

so it's not correct that websocket is on the way out and socket.io's the replacement?  I got that from like a chat session snapshot a while back, I think it was one of the MtGox guys but I hadn't seen mention of it anywhere else.

[nitrous]

so it's not correct that websocket is on the way out and socket.io's the replacement?  I got that from like a chat session snapshot a while back, I think it was one of the MtGox guys but I hadn't seen mention of it anywhere else.

I've got mixed reports - on the one hand macarse got info on irc that websocket was rewritten and socket.io was buggy, but I've also heard that socket.io was replacing websocket, I'm not sure which is the more accurate/current status. If you hear any more recent official statement please tell me so I can update the docs

[btc_lurker]

so it's not correct that websocket is on the way out and socket.io's the replacement?  I got that from like a chat session snapshot a while back, I think it was one of the MtGox guys but I hadn't seen mention of it anywhere else.

I've got mixed reports - on the one hand macarse got info on irc that websocket was rewritten and socket.io was buggy, but I've also heard that socket.io was replacing websocket, I'm not sure which is the more accurate/current status. If you hear any more recent official statement please tell me so I can update the docs

This latter thing you heard seems to come from someone completely unaware of what socket.io is. Socket.IO is mainly a compatibility layer for browsers that do not support Websocket. If you do not rely on a browser to use the Websocket API from MtGox, there is little reason to even consider Socket.IO.

[MikeH]

This latter thing you heard seems to come from someone completely unaware of what socket.io is. Socket.IO is mainly a compatibility layer for browsers that do not support Websocket. If you do not rely on a browser to use the Websocket API from MtGox, there is little reason to even consider Socket.IO.

maybe so but mtgox provided 2 separate streams for them (different IP's) and websocket wasn't working at all most the time for me while the specified server to use for socket.io worked fine.

[btc_lurker]

This latter thing you heard seems to come from someone completely unaware of what socket.io is. Socket.IO is mainly a compatibility layer for browsers that do not support Websocket. If you do not rely on a browser to use the Websocket API from MtGox, there is little reason to even consider Socket.IO.

maybe so but mtgox provided 2 separate streams for them (different IP's) and websocket wasn't working at all most the time for me while the specified server to use for socket.io worked fine.

I'm not sure on how to reply to that, but isn't it possible that you are using some custom websocket implementation that doesn't properly handle the protocol ? RFC 6455 describes the WebSocket protocol.

From my own experience, using MtGox through its socket.io stream with a "quickly-written-library" was causing a lot of disconnects for me. Then I moved on to use only websockets but together with a decent implementation of it. So far the I only get disconnected when requesting huge amounts of data in a short time (like downloading the trade history over several weeks), and even then I readily reconnect and everything is good again.

[nitrous]

This latter thing you heard seems to come from someone completely unaware of what socket.io is. Socket.IO is mainly a compatibility layer for browsers that do not support Websocket. If you do not rely on a browser to use the Websocket API from MtGox, there is little reason to even consider Socket.IO.

maybe so but mtgox provided 2 separate streams for them (different IP's) and websocket wasn't working at all most the time for me while the specified server to use for socket.io worked fine.

I'm not sure on how to reply to that, but isn't it possible that you are using some custom websocket implementation that doesn't properly handle the protocol ? RFC 6455 describes the WebSocket protocol.

From my own experience, using MtGox through its socket.io stream with a "quickly-written-library" was causing a lot of disconnects for me. Then I moved on to use only websockets but together with a decent implementation of it. So far the I only get disconnected when requesting huge amounts of data in a short time (like downloading the trade history over several weeks), and even then I readily reconnect and everything is good again.

I believe that recently they rewrote the websocket server to be more reliable (moreso than their socket.io server), so maybe that could have been responsible for the problems whilst they were switching over?

[MikeH]

Hmm, I don't recall whether this was the problem I was having before but I just noticed the old listentobitcoin code that uses socket.io works without a web server, the websocket version doesn't (in either Safari or Chrome), I need to kick off Apache before it will connect to MtGox.   It does connect to blockchain.info without the web server though, it's weird.

[jekatigr]

Hello everyone,
I haven't found information about,

Through mtgox api I can buy or sell BTC by setting amount in BTC.
Can I buy BTC by setting amount in USD?
For example I'm sending request "price_int=***" and getting (***/market_price) BTC in my account.
Their api support this feature?

[nitrous]

Hello everyone,
I haven't found information about,

Through mtgox api I can buy or sell BTC by setting amount in BTC.
Can I buy BTC by setting amount in USD?
For example I'm sending request "price_int=***" and getting (***/market_price) BTC in my account.
Their api support this feature?

No there you cannot do that, you will have to calculate the (***/market_price) yourself and use that as the amount. For example, if market_price is $120 and you want to sell $600, then you will receive (600/120)=5 btc:

BTCUSD/money/order/add
type=bid
amount_int=500000000
price_int=12000000

The above will deduct $600 from your account and give you 5 btc, minus your fee of course.