Bitcoin Wiki - User contributions [en]

MtGox/API

2011-07-13T12:00:59Z

MuggenHor: /* Websocket API */ +reference to specific WebSocket version used

The [[MtGox]] API provides various methods to access different informations 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.

==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...

{| class="wikitable"
|-
! kind of field !! ...divide by !! ...multiply by
|-
| BTC (volume, amount) || 1E8 (10,000,000) || 0.00000001
|-
| USD (price) || 1E5 (100,000) || 0.00001
|-
| JPY (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.

== Legacy 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. There is also a [[Finance::MtGox|Perl module]] for interacting with the Legacy API.

=== Authentication ===
Authentication is performed by posting a username and a password in variables "name" and "pass". Some methods do not require authentication.

=== Methods ===

==== data/getTrades.php ====
This allows retrieving all trades which happened in the last 24 hours. The returned data is cached and may not reflect latest activity.

Parameters:
* 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 ==
ported on 7/10/2011 from http://forum.bitcoin.org/index.php?topic=5855.0

===Connecting===

You can connect via: ws://websocket.mtgox.com/mtgox

The WebSocket protocol version used is that described in [http://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-00 draft-ietf-hybi-thewebsocketprotocol-00] (aka draft-00).

===Channels===

The websocket will subscribe you to some channels automatically:

{| class="wikitable"
|-
! Channel ID !! Description
|-
| dbf1dee9-4f2e-4a08-8cb7-748919a71b21 || trades (each time a trade happens, you get something here)
|-
| d5f06780-30a8-4a48-a2f8-7ed181b4a13f || the mtgox ticker (lots of updates, with often the same data)
|-
| 24e67e0d-1cad-4cc0-9e7a-f8523ef460fe || depth information in realtime (price + amount + type... type=1=Ask, type=2=Bid)
|}

Additionally each user has a "own" channel which streams informations about orders (new order, deleted order, etc) and trades only the user's trades).

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).

===Possible outgoing commands===

'''unsubscribe''' Stop receiving messages from a channel (parameter "channel")

===Incoming Data===

====Ticker====
<source lang="javascript">
{
"channel":"d5f06780-30a8-4a48-a2f8-ed181b4a13f",
"op":"private",
"origin":"broadcast",
"private":"ticker",
"ticker":{
"buy":0.9515,
"high":1,
"low":0.91,
"sell":0.9697,
"vol":34349
}
}
</source>

'''ticker''' contains the following:

{| class="wikitable"
|-
! Name !! Value
|-
| buy || lowest bid as float
|-
| sell || highest ask as float
|-
| high || maximum rate since last close as float
|-
| low || minimum rate since last close as float
|-
| vol || traded volume since last close
|}

====Trade====

<source lang="javascript">{
"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"
}
}
</source>

'''trade''' contains the following:

{| class="wikitable"
|-
! Name !! Value
|-
| amount || the traded amount in item (BTC), float, deprecated
|-
| amount_int || the traded amount * 1E8
|-
| 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?
|-
|}

====Depth====

Changes to the market depth data are broadcast so an up-to-date market depth can be kept by clients.

<source lang="javascript">{
"channel":"24e67e0d-1cad-4cc0-9e7a-f8523ef460fe",
"depth":{
"currency":"USD",
"item":"BTC",
"price":"14.43",
"price_int":"1443000",
"type":1,
"type_str":"ask",
"volume":"-2.71",
"volume_int":"-271000000"
},
"op":"private",
"origin":"broadcast",
"private":"depth"
}</source>

'''depth''' contains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| currency || the currency affected
|-
| item || the item (BTC)
|-
| price || price as a float, deprecated
|-
| price_int || the price at which volume change happened (5 decimal for USD, 3 for JPY)
|-
| type || 1=ask, 2=bid. deprecated, use type_str
|-
| type_str || type of order at this depth, either "ask" or "bid"
|-
| volume || the volume change as float, deprecated
|-
| volume_int || volume change * 1E8
|-
| ||
|-
| ||

|}

====Order update (private)====

<source lang="javascript">
{
"channel":"(partial key)",
"op":"private",
"order_upd":{
"amount":1000,
"darkStatus":0,
"date":1302836027,
"oid":"(oid)",
"price":0.9899,"status":1
},
"origin":"broadcast",
"private":"order_upd"
}</source>

'''order_upd''' cointains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| amount || change in volume of the order
|-
| darkStatus ||
|-
| oid || ID of the affected order
|-
| price ||
|-
| status ||
|}

MtGox/API

2011-07-10T13:36:29Z

MuggenHor: /* Number Formats */ postfix -> suffix (grammar-ish)

The [[MtGox]] API provides various methods to access different informations 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.

==Number Formats==

In the "old API", currency- and amount-values (price, volume,...) where 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...

{| class="wikitable"
|-
! kind of field !! ...divide by !! ...multiply by
|-
| BTC (volume, amount) || 1E8 (10,000,000) || 0.00000001
|-
| USD (price) || 1E5 (100,000) || 0.00001
|-
| JPY (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.

== Legacy 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.

=== Authentication ===
Authentication is performed by posting a username and a password in variables "name" and "pass". Some methods do not require authentication.

=== Methods ===

==== data/getTrades.php ====
This allows retrieving all trades which happened in the last 24 hours. The returned data is cached and may not reflect latest activity.

Parameters:
* 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 ==
ported on 7/10/2011 from http://forum.bitcoin.org/index.php?topic=5855.0

===Connecting===

You can connect via: ws://websocket.mtgox.com/mtgox

===Channels===

The websocket will subscribe you to some channels automatically:

{| class="wikitable"
|-
! Channel ID !! Description
|-
| dbf1dee9-4f2e-4a08-8cb7-748919a71b21 || trades (each time a trade happens, you get something here)
|-
| d5f06780-30a8-4a48-a2f8-7ed181b4a13f || the mtgox ticker (lots of updates, with often the same data)
|-
| 24e67e0d-1cad-4cc0-9e7a-f8523ef460fe || depth information in realtime (price + amount + type... type=1=Ask, type=2=Bid)
|}

Additionally each user has a "own" channel which streams informations about orders (new order, deleted order, etc) and trades only the user's trades).

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).

===Possible outgoing commands===

'''unsubscribe''' Stop receiving messages from a channel (parameter "channel")

===Incoming Data===

====Ticker====
<source lang="javascript">
{
"channel":"d5f06780-30a8-4a48-a2f8-ed181b4a13f",
"op":"private",
"origin":"broadcast",
"private":"ticker",
"ticker":{
"buy":0.9515,
"high":1,
"low":0.91,
"sell":0.9697,
"vol":34349
}
}
</source>

'''ticker''' contains the following:

{| class="wikitable"
|-
! Name !! Value
|-
| buy || lowest bid as float
|-
| sell || highest ask as float
|-
| high || maximum rate since last close as float
|-
| low || minimum rate since last close as float
|-
| vol || traded volume since last close
|}

====Trade====

<source lang="javascript">{
"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"
}
}
</source>

'''trade''' contains the following:

{| class="wikitable"
|-
! Name !! Value
|-
| amount || the traded amount in item (BTC), float, deprecated
|-
| amount_int || the traded amount * 1E8
|-
| 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?
|-
|}

====Depth====

Changes to the market depth data are broadcast so an up-to-date market depth can be kept by clients.

<source lang="javascript">{
"channel":"24e67e0d-1cad-4cc0-9e7a-f8523ef460fe",
"depth":{
"currency":"USD",
"item":"BTC",
"price":"14.43",
"price_int":"1443000",
"type":1,
"type_str":"ask",
"volume":"-2.71",
"volume_int":"-271000000"
},
"op":"private",
"origin":"broadcast",
"private":"depth"
}</source>

'''depth''' contains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| currency || the currency affected
|-
| item || the item (BTC)
|-
| price || price as a float, deprecated
|-
| price_int || the price at which volume change happened (5 decimal for USD, 3 for JPY)
|-
| type || 1=ask, 2=bid. deprecated, use type_str
|-
| type_str || type of order at this depth, either "ask" or "bid"
|-
| volume || the volume change as float, deprecated
|-
| volume_int || volume change * 1E8
|-
| ||
|-
| ||

|}

====Order update (private)====

<source lang="javascript">
{
"channel":"(partial key)",
"op":"private",
"order_upd":{
"amount":1000,
"darkStatus":0,
"date":1302836027,
"oid":"(oid)",
"price":0.9899,"status":1
},
"origin":"broadcast",
"private":"order_upd"
}</source>

'''order_upd''' cointains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| amount || change in volume of the order
|-
| darkStatus ||
|-
| oid || ID of the affected order
|-
| price ||
|-
| status ||
|}