Bitcoin Wiki - User contributions [en]

MtGox/API/Streaming

2012-11-28T20:27:17Z

Terryww:

Real time streaming data may be obtained over the streaming API, implemented in [http://socket.io/ Socket.io]<ref>Socket.io forum announcement by MagicalTux: https://bitcointalk.org/index.php?topic=14412.msg613271#msg613271</ref>. The original WebSocket API<ref>Original WebSocket thread: https://bitcointalk.org/index.php?topic=5855.msg86219</ref> is deprecated as of 11-Nov-2011.

==Connecting==
The following JavaScript code establishes a connection in the browser:
<source lang="javascript">
<script src="https://socketio.mtgox.com/socket.io/socket.io.js"></script>
<script>
var conn = io.connect('https://socketio.mtgox.com/mtgox');
conn.on('message', function(data) {
// Handle incoming data object.
});
</script>
</source>

==the Currency parameter ==
use :
websocket.mtgox.com:80/mtgox?Currency=EUR

and the websocket will give you updates in EUR currency

The session ID expires after 30 seconds

==Handling Events==
Socket.io exposes a simple interface for handling events. Handling <tt>message</tt> events is shown above, but there are other events that may be handled:
<source lang="javascript">
conn.on('connect', onConnect);
conn.on('disconnect', onDisconnect);
conn.on('error', onError);
conn.on('message', onMessage);
</source>

==Incoming Data==
Data arrives as a full object instead of as JSON text, eliminating the need to parse the data in the JavaScript handler. Messages that come across the socket to trigger the <tt>message</tt> event will contain the following minimum components:
<source lang="javascript">
{
"op":<OPERATION_TYPE>
}
</source>

The <tt>OPERATION_TYPE</tt> field may take these values:

:{| class="wikitable"
|-
! OPERATION_TYPE !! Description
|-
| subscribe || Notification that the user is subscribed to a channel
|-
| unsubscribe || Messages will no longer arrive over the channel
|-
| remark || A server message, usually a warning
|-
| private || The operation for depth, trade, and ticker messages
|-
| result || The response for op:call operations
|}

===op:subscribe and op:unsubscribe===
The subscribe and unsubscribe message data are very simple, containing the channel and the operation.
<source lang="javascript">
{
"channel":<CHANNEL_ID>,
"op":"subscribe" OR "unsubscribe"
}
</source>

Some of the channels are:

:{| class="wikitable"
|-
! Channel ID !! Description
|-
| dbf1dee9-4f2e-4a08-8cb7-748919a71b21 || Trades
|-
| d5f06780-30a8-4a48-a2f8-7ed181b4a13f || Ticker
|-
| 24e67e0d-1cad-4cc0-9e7a-f8523ef460fe || Depth
|}

===op:remark===
The remark operation contains message and success fields.
<source lang="javascript">
{
"op":"remark",
"message":<MESSAGE FROM THE SERVER>,
"success":<boolean>
}
</source>

===op:private===
The payloads of the <tt>op:private</tt> messages contain the real time market information. Each message follows this form:

<source lang="javascript">
{
"channel":<CHANNEL_ID>,
"op":"private",
"private":<MESSAGE_TYPE>,
<MESSAGE_TYPE>:<DATA_PAYLOAD>
}
</source>

The <tt>MESSAGE_TYPE</tt> field may take the values:

:{| class="wikitable"
|-
! MESSAGE_TYPE !! Description
|-
| ticker || Ticker messages
|-
| trade || Trades, as they occur
|-
| depth || Orders placed or removed
|-
| result || The result of a websocket-encapsulated [[MtGox/API/HTTP/v1|version 1 HTTP API]] request
|}

====Ticker====
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 <tt>currency</tt>, <tt>display</tt>, <tt>value</tt>, and <tt>value_int</tt> entries.
<source lang="javascript">
{
"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":{...}
}
}
</source>

====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",
"primary":"Y",
"properties":"limit, mixed_currency",
"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
|-
| 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?
|-
|}

====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",
"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"
}</source>

'''depth''' contains the following:

:{| class="wikitable"
|-
! 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

|}

=== op:result ===

Output from [[MtGox/API/HTTP/v1|HTTP API version 1]] requests that were sent over the websocket.

<source lang="javascript">{
"id":<REQUEST ID>,
"op":"result",
"result": {
...
}
}</source>

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

=== Private per-account messages ===

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:

<source lang="javascript">{
"op":"mtgox.subscribe",
"key":<PRIVATE_IDKEY>
}</source>

<PRIVATE_IDKEY> is obtained by sending a request to [[MtGox/API/HTTP/v1#idKey|generic/private/idkey]] in the version 1 API. Either over HTTP or through the websocket using [[#Authenticated_commands|op:call]].

==== user_order ====

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>

{| class="wikitable"
|-
! Name !! Value
|-
| USER CHANNEL GUID || GUID of private user channel
|-
| ORDER GUID || GUID of order
|-
| ORDER STATUS || New status of the order. Valid states are: pending, post-pending, open, executing, invalid, or stop.
|-
| ORDER TYPE || bid or ask
|}

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

==== wallet ====

Updates to the user's wallet balance.

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

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

{| class="wikitable"
|-
! Name !! Value
|-
| USER CHANNEL GUID || GUID of private user channel
|-
| ORDER GUID || GUID of order
|-
| UPDATE SOURCE || Cause of the balance update. Can be: in, out, earned, spent, withdraw, or deposit
|-
| UPDATE INFO || Human readable string describing the update. Same string you see in the account history on mtgox.com
|-
| REFERENCE CODE || Reference code for bank transfers. "null" if this isn't a bank transfer.
|}

Description of the different source types:
{| class="wikitable"
|-
! Source !! Description
|-
| deposit || Account deposits
|-
| withdraw || Account withdrawals
|-
| earned || Amount of USD gained from a trade
|-
| spent || Amount of USD used for a trade
|-
| in || Amount of BTC gained from a trade
|-
| out || Amount of BTC used for a trade
|-
| fee || MtGox fees
|}

==== trade ====

Trades that happen on behalf of a user whose private channel you're subscribed to issue trade messages with the same format as the [[MtGox/API/Streaming#Trade|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

== Outgoing commands==
=== Direct commands ===

Commands that can be sent without authentication

==== unsubscribe ====
Stop receiving messages from a channel

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

Responds with an identical message to confirm
==== mtgox.subscribe ====
Subscribe to a channel to start receiving messages from it.

<source lang="javascript">{
"op": "mtgox.subscribe",
"type": "ticker"
}</source>
"type" can be ticker, trades, or depth.

=== Authenticated commands ===

These commands require an API key and secret pair to sign requests. Any of the [[MtGox/API/HTTP/v1|HTTP API version 1]] methods can be called. Responses are [[MtGox/API/Streaming#op:result|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.

"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|private/info]], or [[#Cancelled_Trades|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>

== examples ==

=== ticker ===
javascript, using hookio :

http://www.youtube.com/watch?v=KD5ljtNK72U

http://github.com/hookio

http://github.com/cronopio/hook.io-mtgox

Another node.js project, using plain websockets (largely based on cronopio's work) :

https://github.com/dlanod/node-mtgox-websocket-client

A python example :
https://github.com/3M3RY/python-mtgox

A Java example:
https://github.com/timmolter/XChange

=== arbitrage ===
https://github.com/goteppo/ArBit

=== websocket tools ===
https://github.com/cronopio/hook.io-ws

https://github.com/dlanod/node-mtgox-websocket-client

https://github.com/progrium/wssh
<source lang="bash">wssh websocket.mtgox.com:80/mtgox | grep depth 1>>depth.txt</source>

==See Also==

* [[MtGox/API/HTTP/v1]]

== References ==
<references></references>

Intersango

2012-11-26T00:07:19Z

Terryww:

A [[currency exchange|exchange]] offering multiple trading markets for trading bitcoins against multiple currencies.

Traders add funds and then place orders to buy and sell. Intersango acts as an escrow. The site charges no trading fees.

[[Bitcoin Consultancy]] operates the exchange.

Intersango has a trading [https://bitcoinconsultancy.com/wiki/index.php/Intersango/API API]

==Trading==
===Buying===

A buy order is executed partially or in full when the price bid can be matched against a sell order that is at or below the bid amount.

===Selling===

A sell order is executed partially or in full when the price asked can be matched against a buy order that is at or above the ask amount.

No Fee (for a limited time).

==Adding Funds==
===BTC===

There are no fees incurred when when transferring bitcoins for deposit. Funds are available once [[confirmation|confirmed]] (4 confirms), a process that can take roughly forty minutes.

===EUR===
The exchange accepts SEPA bank transfers for deposit. A 5 PLN fee is taken by the bank. No additional fees is taken.

===PLN===
The exchange accepts polish bank transfers for deposit. There are no fees.

===GBP===
The exchange no longer supports GBP transfers. There is [https://support.intersango.com/status no ETA] for this feature's return.

==Withdrawing Funds==

===BTC===
Bitcoins may be withdrawn at no charge.

===EUR===
Withdrawals as SEPA transfers. A fee of 5 PLN is taken by the bank. No additional fee is charged.

===PLN===
Withdrawals as standard polish PLN bank transfers.

===GBP===
The exchange no longer supports GBP transfers. There is [https://support.intersango.com/status no ETA] for this feature's return.

==API==

See the [https://intersango.com/api.php API page] for more info.

Streaming API code example:
<source lang="python">
# expected message types are
# "orderbook", "depth", "trade", "ping"
import socket, json

s = socket.create_connection(('db.intersango.com', 1337))
b = ''

while True:
b += s.recv(8192)
while '\r\n' in b:
i = b.find('\r\n')
m = b[:i].strip()
b = b[i+2:]
m = json.loads(m)
print m
</source>

Trading API:
<source lang="python">
import httplib
import urllib
import json

class Intersango:
ORDER_QUEUED = 'queued'
ORDER_OPEN = 'open'
ORDER_EXPIRED = 'expired'
ORDER_CANCELLED = 'cancelled'
ORDER_FULFILLED = 'fulfilled'

BUY = 'false'
SELL = 'true'

def __init__(self, api_key):
self.connection = httplib.HTTPSConnection('intersango.com')
self.api_key = api_key

def make_request(self, page, params={}):
headers = {"Content-type": "application/x-www-form-urlencoded",
"Connection": "Keep-Alive", "Keep-Alive": 30,
"Accept": "text/plain"}
if type(params) == dict:
params['api_key'] = self.api_key
elif type(params) == list:
params.append(('api_key', self.api_key))
else:
raise TypeError('Unknown parameter list type')
params = urllib.urlencode(params)
base_url = '/api/authenticated/v0.1/%s.php'%page
self.connection.request('POST', base_url, params, headers)
response = self.connection.getresponse()
if response.status == 404:
return None
return json.loads(response.read())

def accounts(self):
return self.make_request('listAccounts')

def orders(self, account_id, states=[], last_order_id=None):
params = [('account_id', account_id)]
for state in states:
params.append(('states[]', state))
if last_order_id is not None:
params.append(('last_order_id', last_order_id))
return self.make_request('listOrders', params)

def deposits(self, account_id):
return self.make_request('listDeposits', {'account_id': account_id})

def withdrawals(self, account_id):
return self.make_request('listWithdrawalRequests',
{'account_id': account_id})

def place_limit_order(self, quantity, rate, is_selling, base_id, quote_id):
params = {'quantity': quantity, 'rate': rate, 'selling': is_selling,
'base_account_id': base_id, 'quote_account_id': quote_id}
return self.make_request('placeLimitOrder', params)

def cancel_order(self, account_id, order_id):
params = {'account_id': account_id, 'order_id': order_id}
return self.make_request('requestCancelOrder', params)

def cancel_withdrawal(self, account_id, withdrawal_request_id):
params = {'account_id': account_id,
'withdrawal_request_id': withdrawal_request_id}
return self.make_request('cancelWithdrawalRequest', params)
</source>

Example usage:

<source lang="python">
intersango = Intersango('3223kdkk323h32kj3hkj23233j')
print 'Accounts: ', intersango.accounts()
print 'Orders: ', \
intersango.orders(411289412410,
[Intersango.ORDER_CANCELLED, Intersango.ORDER_FULFILLED])
print 'Deposits: ', intersango.deposits(861502532543)
print 'Withdrawals: ', intersango.withdrawals(702703681384)
intersango.place_limit_order('1', '2.0', Intersango.BUY,
861502521543, 411982412410)
intersango.cancel_order(412989412410, 21724)
</source>

==History==

The service was launched on July 6, 2011<ref>[http://forum.bitcoin.org/index.php?topic=26543.0 Intersango.com EUR exchange is now live]</ref>. The Intersango [[:Category:Open Source|open source]] software that the exchange runs on was announced on March 17, 2011<ref>[https://bitcointalk.org/index.php?topic=4579.0 Free Bitcoin exchange software- Intersango]</ref>. In September, 2011 the exchange began using a new version of the Intersango open source exchange project with two currency markets (BTC/EUR, BTC/USD) live under the Intersango brand and plans made for the third (BTC/GBP) when [[Britcoin]] accounts are migrated at a future date.

On October 9, 2012, the exchange announced imminent plans to shutter its BTC/USD market.

==See Also==

* [[Buying bitcoins]]
* [[Selling bitcoins]]

==External Links==

* [https://intersango.com Intersango] EUR exchange website
* [http://gitorious.org/intersango Intersango] exchange project on Gitorious

==References==
<references/>

[[Category:Exchanges]]
[[Category:eWallets]]