MtGox/API/Streaming

The subscribe and unsubscribe message data are very simple, containing the channel and the operation.

{
  "channel":<CHANNEL_ID>,
  "op":"subscribe" OR "unsubscribe"
}

Some of the channels are:

Channel ID	Description
dbf1dee9-4f2e-4a08-8cb7-748919a71b21	Trades
d5f06780-30a8-4a48-a2f8-7ed181b4a13f	Ticker
24e67e0d-1cad-4cc0-9e7a-f8523ef460fe	Depth

The remark operation contains message and success fields.

{
  "op":"remark",
  "message":<MESSAGE FROM THE SERVER>,
  "success":<boolean>
}

The payloads of the op:private messages contain the real time market information. Each message follows this form:

{
  "channel":<CHANNEL_ID>,
  "op":"private",
  "private":<MESSAGE_TYPE>,
  <MESSAGE_TYPE>:<DATA_PAYLOAD>
}

The MESSAGE_TYPE field may take the values:

MESSAGE_TYPE	Description
ticker	Ticker messages
trade	Trades, as they occur
depth	Orders placed or removed
result	The result of a websocket-encapsulated version 1 HTTP API request

Ticker messages contain the current inside Bid and Ask as well as daily highs, lows, and volume. The fields contained in the ticker match those defined in the version 1.0 API above. All fields contain currency, display, value, and value_int entries.

{
  "channel":"d5f06780-30a8-4a48-a2f8-7ed181b4a13f",
  "op":"private",
  "origin":"broadcast",
  "private":"ticker",
  "ticker":{
    "avg":{
      "currency":"USD",
      "display":"$2.26847",
      "value":"2.26847",
      "value_int":"226847"
    },
    "buy":{...},
    "high":{...},
    "last":{..},
    "last_local":{...},
    "last_orig":{...},
    "low":{...},
    "sell":{...},
    "vol":{
      "currency":"BTC",
      "display":"118,696.02104208",
      "value":"118696.02104208",
      "value_int":"11869602104208"
    },
    "vwap":{...}
  }
}

{
  "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",
    "primary":"Y",
    "properties":"limit, mixed_currency",
    "tid":"1310279340877902",
    "trade_type":"bid",
    "type":"trade"
  }
}

trade contains the following:

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
properties	"market": the trade ate the whole order, "limit": the trade ate the order partially - some of the original order still exists
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?

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

{
  "channel":"24e67e0d-1cad-4cc0-9e7a-f8523ef460fe",
  "depth":{
    "currency":"USD",
    "item":"BTC",
    "now":"1323644358437819",
    "price":"14.43",
    "price_int":"1443000",
    "total_volume_int":"849766000",
    "type":1,
    "type_str":"ask",
    "volume":"-2.71",
    "volume_int":"-271000000"
  },
  "op":"private",
  "origin":"broadcast",
  "private":"depth"
}

depth contains the following:

Name	Value
currency	the currency affected
item	the item (BTC)
price	price as a float, deprecated
total_volume_int	total volume at this price, after applying the depth update, can be used as a starting point before applying subsequent updates.
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

Output from HTTP API version 1 requests that were sent over the websocket.

{
    "id":<REQUEST ID>,
    "op":"result",
    "result": {
        ...
    }
}

"result" contains the result of the call the same as if it were called over the HTTP API. <REQUEST ID> is the ID chosen by you when the request was sent.

The streaming API provides a private channel for every user which receives updates for account-related activities like new orders being created. To subscribe, do:

{
    "op":"mtgox.subscribe",
    "key":<PRIVATE_IDKEY>
}

<PRIVATE_IDKEY> is obtained by sending a request to generic/private/idkey in the version 1 API. Either over HTTP or through the websocket using op:call.

user_order is sent when a the status of a user's order is changed.

<source lang="javascript">{ "channel": <USER CHANNEL GUID> "op": "private". "origin": "broadcast", "private": "user_order". "user_order": { "amount": { "currency": "BTC", "display": "1.00000000\U00a0BTC", "value": "1.00000000", "value_int": "100000000" }, "currency": "USD", "date": "1330522328", "item": "BTC", "oid": <ORDER GUID>, "price": { "currency": "USD", "display": "$10.00000", "value": "10.00000", "value_int": "1000000", }; "status": <ORDER STATUS>, "type": <ORDER TYPE>, }; }</source>

When an order is cancelled, the "user_order" field only contains the "oid", and none of the other fields.

Updates to the user's wallet balance.

{
    "channel": <USER CHANNEL GUID>,
    "op": "private",
    "origin": "broadcast",
    "private": "wallet",
    "wallet": {
        "op": <UPDATE SOURCE>,
        "amount": {
            ...
        },
        "info": <UPDATE INFO>,
        "ref": <REFERENCE CODE>,
        "balance": {
            ...
        }
    }
}

"..." values above are normal 'amount' type dictionaries containing "currency", "value", "value_int", and "display".

Description of the different source types:

Trades that happen on behalf of a user whose private channel you're subscribed to issue trade messages with the same format as the public trades channel does. If you're subscribed to both, be careful not to take both into account during calculations, it might cause some hard to track down issues

Commands that can be sent without authentication

Stop receiving messages from a channel

<source lang="javascript">{ "op":"unsubscribe", "channel":<CHANNEL ID> }</source>

Responds with an identical message to confirm

Subscribe to a channel to start receiving messages from it.

{
    "op": "mtgox.subscribe",
    "type": "ticker"
}

"type" can be ticker, trades, or depth.

These commands require an API key and secret pair to sign requests. Any of the HTTP API version 1 methods can be called. Responses are op:result

<source lang="javascript">{ "op":"call", "id":<REQUEST ID>, "call":<BASE-64 ENCODED SIGNED REQUEST>, "context":"mtgox.com" }</source>

<REQUEST ID> can be any string, it's used to identify the response as belonging to this request when an answer comes back. md5'ing your nonce is a good way to get an id.

Find a few explanations about tonce and nonce on : https://en.bitcoin.it/wiki/MtGox/API/HTTP#tonce_and_nonce

"call" must be a base-64 encoded string consisting of, in order: an API key, a signed copy of the request, and the request text itself.

The queries themselves look like: <source lang="javascript">{ "id":<REQUEST ID>, "call":<HTTP API ENDPOINT>, "nonce":<REQUEST NONCE>, "params":<REQUEST PARAMETERS>, "item":"BTC" }</source>

<HTTP API ENDPOINT> is the last two path components of any version 1 API endpoint, for example private/info, or public/cancelledtrades.

<REQUEST PARAMETERS> is optional for any request that doesn't have parameters.

The signing process is similar to the HTTP API, but because we can't send headers in an open websocket, the API key and signed request are simply prepended to the actual query data and base64 encoded. Reference implementations are available at https://github.com/MtGox/websocket

Here's a sample of how to create a valid request in PHP 5.3: <source lang="php">$nonce = explode(' ', microtime(false)); $nonce = $nonce[1].substr($nonce[0], 2, 6); $id = md5($nonce); // id can be anything to recognize this call $query = array('call' => $call, 'params' => $params, 'item' => $item, 'currency' => $currency, 'id' => $id, 'nonce' => $nonce); $query = json_encode($query); // generate signature $sign = hash_hmac('sha512', $query, base64_decode($apiSecret), true); // prefix signature to query $query = pack('H*', str_replace('-','',$apiKey)).$sign.$query; // send query $call = array('op' => 'call', 'call' => base64_encode($query), 'id' => $id, 'context' => 'mtgox.com'); // $call can now be pushed out to the websocket</source>

• https://github.com/ralphtheninja/goxstream (Node.js readable stream)
• https://github.com/ralphtheninja/goxtick (Node.js EventEmitter, works in the browser with browserify)
• https://github.com/cronopio/hook.io-mtgox (Node.js)
• https://github.com/timmolter/XChange (Java)

• https://github.com/cronopio/hook.io-ws (Node.js)
• https://github.com/progrium/wssh (Python)
• https://github.com/sta/websocket-sharp (C#)
• https://github.com/qsnjason/goxsocketjs (Node.js and HTML5 Browsers - High Level Trading API)

• https://github.com/ameen3/node-mtgox-apiv2 (Node.js, supports v2 API)
• https://bitbucket.org/pipe2grep/cryptocoinxchange (C#)

• https://github.com/goteppo/ArBit
• https://github.com/vbmithr/breakbot