Difference between revisions of "MtGox/API"

From Bitcoin Wiki
Jump to: navigation, search
(Websocket API)
 
(147 intermediate revisions by 20 users not shown)
Line 1: Line 1:
The [[MtGox]] API provides various methods to access different informations from the market, place orders, and more.
+
The [[MtGox]] API provides methods to access information from the market, place orders, and more.
  
Two APIs are available at this point: the HTTP api (available by posting to mtgox.com/code/*) and the websocket API.
+
Two APIs are currently available:  
  
== Legacy API ==
+
* [[MtGox/API/HTTP|HTTP API]]
This API is available in <nowiki>https://mtgox.com/code/*</nowiki>, and provides various informations. It also supports making an order, a withdraw, a deposit, etc.
+
* [[MtGox/API/Pubnub|Streaming Pubnub API]]
 +
* [[MtGox/API/Streaming|Streaming websocket API]]
  
=== Authentication ===
+
__TOC__
Authentication is performed by posting a username and a password in variables "name" and "pass". Some methods do not require authentication.
 
  
=== Methods ===
+
==Number Formats==
  
==== data/getTrades.php ====
+
In the "old API", currency- and amount-values (price, volume,...) were given as '''float'''. These values are likely being deprecated and replaced by fields of the same name with "_int" as suffix. These are '''fixed-decimal''', so you have to move the decimal point yourself (divide). The exponent differs based on the kind of the value.
This allows retrieving all trades which happened in the last 24 hours. The returned data is cached and may not reflect latest activity.
 
  
Parameters:
+
In order to convert the '''int''' to a '''decimal''' you can...
* since: Passing a tid in "since" allows retrieving all trades since that trade. The passed id is may not exist. Ie. to get all trades from the very beginning one would just call https://mtgox.com/code/data/getTrades.php?since=0 . since returns only 100 trades, and you can call the method again by passing the latest trade you have imported in since.
 
  
== Websocket API ==
 
See: http://forum.bitcoin.org/index.php?topic=5855.0 (will be ported here soon)
 
 
==Connecting==
 
 
You can connect via: ws://websocket.mtgox.com/mtgox
 
 
==Channels==
 
 
The websocket will subscribe you to some channels automatically:
 
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Channel ID !! Description
+
! kind of field !! ...divide by !! ...multiply by
 
|-
 
|-
| dbf1dee9-4f2e-4a08-8cb7-748919a71b21 || trades (each time a trade happens, you get something here)
+
| BTC (volume, amount) || 1E8 (100,000,000) || 0.00000001
 
|-
 
|-
| d5f06780-30a8-4a48-a2f8-7ed181b4a13f || the mtgox ticker (lots of updates, with often the same data)
+
| USD, AUD, CAD, CHF, CNY, DKK, EUR, GBP, HKD, NZD, PLN, RUB, SGD, THB, NOK, CZK (price) || 1E5 (100,000) || 0.00001
 
|-
 
|-
| 24e67e0d-1cad-4cc0-9e7a-f8523ef460fe || depth information in realtime (price + amount + type... type=1=Ask, type=2=Bid)
+
| JPY, SEK (price) || 1E3 (1,000) || 0.001
 
|}
 
|}
  
Additionally each user has a "own" channel which streams informations about orders (new order, deleted order, etc) and trades only the user's trades).
+
Implementation advice: it's probably best to use '''int''' or '''Decimal''' (if your language/db offers such a type) in your clients. Using '''float''' will likely lead to nasty rounding problems.
  
Each message is a JSON-encoded object, with at least "op" element. The "op" element contains the operation to be done (for outgoing messages), or the type of message (for incoming messages).
+
== Currency Symbols ==
 +
List of the currency symbols available with the API:
  
==Possible outgoing commands==
+
USD, AUD, CAD, CHF, CNY, DKK, EUR, GBP, HKD, JPY, NZD, PLN, RUB, SEK, SGD, THB, NOK, CZK
  
'''unsubscribe''' Stop receiving messages from a channel (parameter "channel")
+
==Date and time==
  
==Incoming Data==
+
Most dates you will find in mtgox API are UNIX time
  
===Ticker===
+
See http://en.wikipedia.org/wiki/Unix_time
:{"channel":"d5f06780-30a8-4a48-a2f8-7ed181b4a13f","op":"private","origin":"broadcast","private":"ticker","ticker":"buy":0.9515,"high":1,"low":0.91,"sell":0.9697,"vol":34349}}
 
  
===Trade===
+
Most programming languages should have tools for managing those timestamps
:{"channel":"dbf1dee9-4f2e-4a08-8cb7-748919a71b21","op":"private","origin":"broadcast","private":"trade","trade":"amount":2.71,"amount_int":"271000000","date":1310279340,"item":"BTC","price":14.43,"price_currency":"USD","price_int":"1443000","tid":"1310279340877902","trade_type":"bid","type":"trade"}}
 
 
 
:{| class="wikitable"
 
|-
 
! Name !! Value
 
|-
 
| amount || the traded amount in item (BTC), float, deprecated
 
|-
 
| amount_int || the traded amount * 10000
 
|-
 
| date || unix timestamp of trade
 
|-
 
| item || What was this trade about
 
|-
 
| price || price per unit, float, deprecated
 
|-
 
| price_int || price in smallest unit as integer (5 decimals of USD, 3 in case of JPY)
 
|-
 
| price_currency || currency in which trade was completed
 
|-
 
| tid || Trade id (big integer, which is in fact trade timestamp in microseconds)
 
|-
 
| trade_type || Did this trade result from the execution of a bid or a ask?
 
|-
 
|}
 
  
 +
==See Also==
  
=MOLECULAR EDITING...=
+
* [http://bitcointalk.org/index.php?topic=164404.0 MtGox API version 2: Unofficial Documentation]

Latest revision as of 04:19, 15 November 2013

The MtGox API provides methods to access information from the market, place orders, and more.

Two APIs are currently available:

Number Formats

In the "old API", currency- and amount-values (price, volume,...) were given as float. These values are likely being deprecated and replaced by fields of the same name with "_int" as suffix. These are fixed-decimal, so you have to move the decimal point yourself (divide). The exponent differs based on the kind of the value.

In order to convert the int to a decimal you can...

kind of field ...divide by ...multiply by
BTC (volume, amount) 1E8 (100,000,000) 0.00000001
USD, AUD, CAD, CHF, CNY, DKK, EUR, GBP, HKD, NZD, PLN, RUB, SGD, THB, NOK, CZK (price) 1E5 (100,000) 0.00001
JPY, SEK (price) 1E3 (1,000) 0.001

Implementation advice: it's probably best to use int or Decimal (if your language/db offers such a type) in your clients. Using float will likely lead to nasty rounding problems.

Currency Symbols

List of the currency symbols available with the API:

USD, AUD, CAD, CHF, CNY, DKK, EUR, GBP, HKD, JPY, NZD, PLN, RUB, SEK, SGD, THB, NOK, CZK

Date and time

Most dates you will find in mtgox API are UNIX time

See http://en.wikipedia.org/wiki/Unix_time

Most programming languages should have tools for managing those timestamps

See Also