Bitcoin Wiki - User contributions [en]

Real Time Bitcoin Market Data

2013-05-28T20:23:19Z

Clark: /* External Links */ Removed defunct links

==Bitcoin Data Platform by Clark Moody==
A financial information service that provides a real-time display of data from the [[MtGox]] exchange.

* Combined - Includes all of the services listed below
* Time Sales - Time price and volume for each trade executed
* Ticker - Current best ask / best bid, day's high, day's low, volume and last trade for all MtGox currencies. The site also displays a synthetic forex grid, based on the immediate exchange rates between non-zero volume currencies.
* Order Book - The buy (bid) and sell (ask) orders along with real time trade calculators

The Ticker and Time Sales services were announced on June 03, 2011<ref>[http://forum.bitcoin.org/index.php?topic=11560.0 Realtime MtGox Time and Sales with WebSockets]</ref> and the Order Book was announced on June 10, 2011<ref>[http://forum.bitcoin.org/index.php?topic=14412.0 Real Time Order Book with WebSockets]</ref>. The combined information view was announced on September 11, 2011<ref>[https://bitcointalk.org/index.php?topic=43514.0 Combined Order Book and Time & Sales]</ref>.

==Bitcoin-Analytics.com==
Relatively new financial information analytical service which provides real-time display of data from multiple bitcoin exchanges. The service was announced on May 21, 2012<ref>[https://bitcointalk.org/index.php?topic=82768.0 Bitcoin-Analytics.com]</ref>.

===Supported Markets===
* USD - mtgoxUSD, btceUSD, cbxUSD, cryptoxUSD, intrsngUSD, bitstampUSD, bitmarketUSD, bcLRUSD, vcxUSD, btc24USD, <strike>bitfloorUSD</strike>
* EUR - mtgoxEUR, bitmarketEUR, vcxEUR, intrsngEUR, bcEUR, bcLREUR, bitcurexEUR, btc24EUR
* CNY - btcnCNY, mtgoxCNY

===Displayed Charts===
* Order Book Volume Chart
* MKT Execution Price Chart
* Time Last 1000? BTC Traded Chart
* VWAP Last 1000? BTC Traded Chart
* Trade Volume Chart

===Arbitrage Table===
Service provides arbitrage tables for all supported currency markets.

===Consolidated Order Books===
Also service provides unique data - consolidated order books (all order books for the same currency are merged and all orders are sorted). Thus for each currency there is additional consolidated currency market: one for USD allUSD, for EUR allEUR, and for CNY allCNY.

Consolidated order books data can help represent the behavior of the whole market.
For example consolidated order book charts clearly displays whether arbitrage opportunity is present among different exchanges and for how long it is present, and at what extent. Also comparing charts for different exchanges it is possible to see quickly between which exchanges this particular arbitrage apportunity currently exists.

==External Links==

* [http://bitcoin.clarkmoody.com/ Combined Order Book, Time & Sales, and Historical Chart] web page
* [http://bitcoin.clarkmoody.com/ticker Ticker] web page
* [http://bitcoin-analytics.com Bitcoin-Analytics.com - Multiple Exchanges Consolidated Order Books and Trades Real Time Charts] subscribtion service web page

==References==
<references />

[[Category:Financial]]

MtGox/API/HTTP/v1

2012-03-06T21:35:24Z

Clark: Added section on trade history

== HTTP API version 1 methods ==

=== Multi Currency Ticker ===

https://mtgox.com/api/1/BTCUSD/public/ticker
https://mtgox.com/api/1/BTCEUR/public/ticker

returns the current ticker for the selected currency :

<source lang="php">
{
"result":"success",
"return":
{
"high": {"value":"5.70653","value_int":"570653","display":"$5.70653","currency":"USD"},
"low": {"value":"5.4145","value_int":"541450","display":"$5.41450","currency":"USD"},
"avg": {"value":"5.561119626","value_int":"556112","display":"$5.56112","currency":"USD"},
"vwap": {"value":"5.610480461","value_int":"561048","display":"$5.61048","currency":"USD"},
"vol":
{
"value":"55829.58960346",
"value_int":"5582958960346",
"display":"55,829.58960346\u00a0BTC",
"currency":"BTC"
},
"last_local":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"last_orig":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"last":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"buy":{"value":"5.53587","value_int":"553587","display":"$5.53587","currency":"USD"},
"sell":{"value":"5.56031","value_int":"556031","display":"$5.56031","currency":"USD"}
}
</source>

note : last_local include only the last trade in the selected currency, last_orig include data of the original last trade ( currency,price in currency . . . ),last can be a conversion of the last trde in another currency

=== Multi Currency depth ===

https://mtgox.com/api/1/BTCPLN/public/depth?raw

https://mtgox.com/api/1/BTCAUD/public/depth?raw

=== Multi currency trades ===

https://mtgox.com/api/1/BTCUSD/public/trades?raw

https://mtgox.com/api/1/BTCPLN/public/trades?raw

https://mtgox.com/api/1/BTCAUD/public/trades?raw

to get only the trades since a given trade id, you can add the parameter since=<trade_id>

https://mtgox.com/api/1/BTCUSD/public/trades?since=0

https://mtgox.com/api/1/BTCEUR/public/trades?since=1316312781670700

For multi currency,also returns the primary value,"Y" or "N", the primary currency is always the buyers currency

A trade can appear in more than one currency, to ignore duplicates, use only the trades having primary =Y

example of returned data :
<source lang="php">
{"date":1316312781,
"price":"3.5599",
"amount":"3.6900096",
"price_int":"355990",
"amount_int":"369000960",
"tid":"1316312781670700",
"price_currency":"EUR",
"item":"BTC",
"trade_type":"bid",
"primary":"Y",
"properties":"limit,mixed_currency"
}
</source>

=== Cancelled Trades ===

https://mtgox.com/api/1/BTCUSD/public/cancelledtrades

returns a list of all the cancelled trades this last month, list of trade ids in json format .

=== Full Depth ===

https://mtgox.com/api/1/BTCUSD/public/fulldepth

returns full depth

=== Private info ===

https://mtgox.com/api/1/generic/private/info

returns information about your account, funds, fees, API privileges, withdraw limits . . .

=== idKey ===

https://mtgox.com/api/1/generic/private/idkey

Returns the idKey used to subscribe to a user's private updates channel in the websocket API. The key is valid for 24 hours.

=== Your open orders ===

https://mtgox.com/api/1/generic/private/orders

Returns information about your current open orders. Valid order statuses are: pending, executing, post-pending, open, stop, and invalid.

=== Your trade history ===

https://mtgox.com/api/1/generic/private/trades

Returns all of your trades. Does not include fees.

=== Submit an order ===

https://mtgox.com/api/1/BTCUSD/private/order/add

parameters:
* type (bid|ask) (easier to remember: '''b'''id == '''b'''uy, ask == sell)
* amount_int <amount as int>
* price_int <price as int> (can be omitted to place market order)

submits an order and returns info about success or error

=== Currency information ===

https://mtgox.com/api/1/generic/public/currency

pass parameter ?currency=<currency_symbol>

returns information about a currency ( number of decimals . . . )

=== HOTP key ===

https://mtgox.com/api/1/generic/public/hotp_gen

used to generate a new HOTP key ( useful for developers )

=== Merchant System ===

==== Order Creation ====

https://mtgox.com/api/1/generic/private/merchant/order/create

===== Required Parameters: =====
* '''currency''': ''<currency>'' (for now only BTC is supported)
* '''amount''': ''<amount as float>''
or
* '''amount_int''': ''<amount as int>''
* '''return_success''': ''<string>'' Where to redirect the user on payment success
* '''return_failure''': ''<string>'' Where to redirect the user on cancellation

===== Optional Parameters: =====
* '''description''': ''<string>'' A small description that will appear on the payment page (defaults to "Payment to <user_login>")
* '''ipn''': ''<string>'' URL that will be called by our services once the payment is complete (more below)
* '''data''': ''<string>'' Custom data returned by the IPN

===== Returns =====
* '''transaction''': ''<uuid>'' A unique transaction ID
* '''payment_url''': ''<string>'' URL on which to redirect the user

==== IPN ====
The IPN (Instant payment notification) is a mechanism that POST data about a successful payment an a custom URL located on your website right after the payment as been validated.
Your website is supposed then to either acknowledge the IPN by returning "[OK]" as is. Anything else will be counted as an error and the system will try sending the IPN back every 30 minutes until it succeed.

===== Content =====
The IPN POST data will always contain the following:
* '''id''': ''<uuid>'' The transaction ID generated by the initial call
* '''payment_id''': ''<uuid>'' The payment ID
* '''status''': ''<enum>'' Either '''paid''', '''cancelled''' or '''closed''' (3rd one shouldn't happen)

If the transaction was successfully paid:
* '''amount''': ''<amount as int>'' The amount paid by the user
* '''currency''': ''<currency>'' The currency used to pay (should always be BTC for now)
* '''method''': ''<enum>'' The payment method, for now MTGOXBTC
* '''date''': ''<date>'' The payment date

If data was provided in the initial call:
* '''data''': ''<string>'' The data provided when creating the transaction

== Examples ==

=== bitcoin_dealer (trading script) ===

python (django) : https://github.com/rokj/bitcoin_dealer

MtGox/API

2011-12-11T23:21:44Z

Clark: /* Depth */

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

Two APIs are currently available: 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.

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

== HTTP API ==
This API is available in <nowiki>https://mtgox.com/api/*</nowiki>, and provides various informations. It also supports making an order, a withdraw, a deposit, etc. There is also a [https://rubygems.org/gems/mtgox Ruby gem] and [[Finance::MtGox|Perl module]] for interacting with the HTTP API.

=== Authentication ===

Authentication is performed by signing each request using HMAC-SHA512. The request must contain an extra value "nonce" which must be an always incrementing numeric value. A reference implementation is provided here:
<source lang="php">
<?php

function mtgox_query($path, array $req = array()) {
// API settings
$key = '';
$secret = '';

// generate a nonce as microtime, with as-string handling to avoid problems with 32bits systems
$mt = explode(' ', microtime());
$req['nonce'] = $mt[1].substr($mt[0], 2, 6);

// generate the POST data string
$post_data = http_build_query($req, '', '&');

// generate the extra headers
$headers = array(
'Rest-Key: '.$key,
'Rest-Sign: '.base64_encode(hash_hmac('sha512', $post_data, base64_decode($secret), true)),
);

// our curl handle (initialize if required)
static $ch = null;
if (is_null($ch)) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; MtGox PHP client; '.php_uname('s').'; PHP/'.phpversion().')');
}
curl_setopt($ch, CURLOPT_URL, 'https://mtgox.com/api/'.$path);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// run the query
$res = curl_exec($ch);
if ($res === false) throw new Exception('Could not get reply: '.curl_error($ch));
$dec = json_decode($res, true);
if (!$dec) throw new Exception('Invalid data received, please make sure connection is working and requested API exists');
return $dec;
}

// example 1: get infos about the account, plus the list of rights we have access to
var_dump(mtgox_query('0/info.php'));

// old api (get funds)
var_dump(mtgox_query('0/getFunds.php'));

// trade example
// var_dump(mtgox_query('0/buyBTC.php', array('amount' => 1, 'price' => 15)));
</source>

Python version here: https://bitcointalk.org/index.php?topic=49789.msg592388#msg592388

=== Cache ===

All of the API methods below have cached results, ticker, depth . . . have a 10 seconds cache .
No need to poll more often, you wont have more results, you could just be blocked by the prolexic anti ddos features.

=== Methods API version 0===

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

* data is returned in standard json format like :
<source lang="php">
[
{"date":1279408157,
"price":"0.04951",
"amount":"20",
"price_int":"4951",
"amount_int":"2000000000",
"tid":"1",
"price_currency":"USD",
"item":"BTC",
"trade_type":""
"primary":"Y"
},
{"date":1279424586,"price":"0.05941","amount":"50.01","price_int":"5941","amount_int":"5001000000","tid":"2","price_currency":"USD","item":"BTC","trade_type":""}]
</source>

==== 0/getDepth.php ====
Get the current Market depth

https://mtgox.com/api/0/data/getDepth.php?Currency=PLN

https://mtgox.com/api/0/data/getDepth.php?Currency=AUD

https://mtgox.com/api/0/data/getDepth.php?Currency=USD

==== 0/getFunds.php ====
Get your current balance

https://mtgox.com/api/0/getFunds.php

getfunds is now deprecated since multi currency, please use info.php

==== 0/buyBTC.php ====
Place an order to Buy BTC

https://mtgox.com/api/0/buyBTC.php

POST data: amount=#&price=#&Currency=PLN

returns a list of your open orders

you can omit the price to do a market order

==== 0/sellBTC.php ====
Place an order to Sell BTC

https://mtgox.com/api/0/sellBTC.php

POST data: &amount=#&price=#&Currency=PLN

returns a list of your open orders

you can omit the price to do a market order

==== 0/getOrders.php ====
Fetch a list of your open Orders

https://mtgox.com/api/0/getOrders.php

oid: Order ID

type: 1 for sell order or 2 for buy order

status: 1 for active, 2 for not enough funds

==== 0/cancelOrder.php ====
Cancel an order

https://mtgox.com/api/0/cancelOrder.php

POST data: oid=#&type=#

oid: Order ID

type: 1 for sell order or 2 for buy order

==== 0/redeemCode.php ====
Used to redeem a mtgox coupon code

https://mtgox.com/api/0/redeemCode.php

* call with a post parameter "code" containing the code to redeem

* it will return an array with amount (float amount value of code), currency (3 letters, BTC or USD), reference (the transaction id), and status

==== 0/withdraw.php ====
withdraw / Send BTC

https://mtgox.com/api/0/withdraw.php

POST data: group1=BTC&btca=bitcoin_address_to_send_to&amount=#

* pass btca parameter to withdraw to a btc adress

* pass group1 for a coupon : BTC2CODE or USD2CODE

* pass group1=DWUSD&dwaccount=XXX-XXX-XXXX (no btca=xxxxxxx) for a dwolla withdraw

* pass green=1 to use the new greenaddress feature ( see [[GreenAddress]] )
* return code and status if successful

To make a withdraw in another Currency , use group1=USD2CODE and add a Currency parameter ( example Currency=EUR to get a mtgox EUR coupon )

==== 0/btcAddress.php ====
get a bitcoin deposit adress for your account

https://mtgox.com/api/0/btcAddress.php

* pass POST data "description" to add a description that will appear in your history when this BTC address receive a deposit

* returns a bitcoin deposit address

==== 0/history_[CUR].csv ====

Allows downloading your activity history for a given currency (BTC or USD for now).

https://mtgox.com/api/0/history_BTC.csv

https://mtgox.com/api/0/history_USD.csv

==== 0/info.php ====

https://mtgox.com/api/0/info.php

returns info about your account, funds, fees, API privileges, withdraw limits . . .

==== 0/ticker ====

http://mtgox.com/api/0/data/ticker.php

returns the current ticker :

<source lang="php">
{"ticker":
{
"high":5.70653,
"low":5.4145,
"avg":5.561388723,
"vwap":5.610932845,
"vol":55698,
"last":5.56915,
"buy":5.51326,
"sell":5.5672
}
}
</source>

the time frame for high, low, vol, avg, vwap . . . is sliding 24 hours

what is vwap ?

please see http://en.wikipedia.org/wiki/VWAP

=== API version 0 examples ===

==== all api shell type CLI ====

python : http://www.goxsh.info/

perl : http://pastebin.com/vEpgw5nW

==== other ====

https : http://stackoverflow.com/questions/7046370/https-request-with-boost-asio-and-openssl

https://github.com/sje397/mtgox-plasmoid

module perl : http://search.cpan.org/~mndrix/Finance-MtGox-0.02/

==== gather data ====

https://github.com/Lexiks/MyBitBoard

==== gettrade ====

bash : https://bitcointalk.org/index.php?topic=39402.0

perl : http://pastebin.com/raw.php?i=pmhMXZJu

==== ticker ====

http://pastebin.com/pd0ZR4WY

=== Methods API version 1===

==== Multi Currency Ticker ====

https://mtgox.com/api/1/BTCUSD/public/ticker
https://mtgox.com/api/1/BTCEUR/public/ticker

returns the current ticker for the selected currency :

<source lang="php">
{
"result":"success",
"return":
{
"high": {"value":"5.70653","value_int":"570653","display":"$5.70653","currency":"USD"},
"low": {"value":"5.4145","value_int":"541450","display":"$5.41450","currency":"USD"},
"avg": {"value":"5.561119626","value_int":"556112","display":"$5.56112","currency":"USD"},
"vwap": {"value":"5.610480461","value_int":"561048","display":"$5.61048","currency":"USD"},
"vol":
{
"value":"55829.58960346",
"value_int":"5582958960346",
"display":"55,829.58960346\u00a0BTC",
"currency":"BTC"
},
"last_local":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"last_orig":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"last":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"buy":{"value":"5.53587","value_int":"553587","display":"$5.53587","currency":"USD"},
"sell":{"value":"5.56031","value_int":"556031","display":"$5.56031","currency":"USD"}
}
</source>

note : last_local include only the last trade in the selected currency, last_orig include data of the original last trade ( currency,price in currency . . . ),last can be a conversion of the last trde in another currency

==== Multi Currency depth ====

https://mtgox.com/api/1/BTCPLN/public/depth?raw

https://mtgox.com/api/1/BTCAUD/public/depth?raw

==== Multi currency trades ====

https://mtgox.com/api/1/BTCPLN/public/trades?raw

https://mtgox.com/api/1/BTCAUD/public/trades?raw

to get only the trades since a given trade id, you can add the parameter since=<trade_id>

https://mtgox.com/api/1/BTCUSD/public/trades?since=0

https://mtgox.com/api/1/BTCEUR/public/trades?since=1316312781670700

For multi currency,also returns the primary value,"Y" or "N", the primary currency is always the buyers currency

A trade can appear in more than one currency, to ignore duplicates, use only the trades having primary =Y

example of returned data :
<source lang="php">
{"date":1316312781,
"price":"3.5599",
"amount":"3.6900096",
"price_int":"355990",
"amount_int":"369000960",
"tid":"1316312781670700",
"price_currency":"EUR",
"item":"BTC",
"trade_type":"bid",
"primary":"Y",
"properties":"limit,mixed_currency"
}
</source>

==== Cancelled Trades ====

https://mtgox.com/api/1/BTCUSD/public/cancelledtrades

returns a list of all the cancelled trades this last month, list of trade ids in json format .

==== Full Depth ====

https://mtgox.com/api/1/BTCUSD/public/fulldepth

returns full depth

==== Private info ====

https://mtgox.com/api/1/generic/private/info

returns information about your account, funds, fees, API privileges, withdraw limits . . .

==== Your open orders ====

https://mtgox.com/api/1/generic/private/orders

returns information about your current open orders

==== Currency information ====

https://mtgox.com/api/1/generic/public/currency

pass parameter ?currency=<currency_symbol>

returns information about a currency ( number of decimals . . . )

==== HOTP key ====

https://mtgox.com/api/1/generic/public/hotp_gen

used to generate a new HOTP key ( useful for developpers )

== Streaming API ==
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 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
|}

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

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

|}

===Possible outgoing commands===
'''unsubscribe''' Stop receiving messages from a channel (parameter "channel")

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

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

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

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

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

MtGox/API

2011-12-11T23:21:32Z

Clark: /* Trade */

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

Two APIs are currently available: 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.

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

== HTTP API ==
This API is available in <nowiki>https://mtgox.com/api/*</nowiki>, and provides various informations. It also supports making an order, a withdraw, a deposit, etc. There is also a [https://rubygems.org/gems/mtgox Ruby gem] and [[Finance::MtGox|Perl module]] for interacting with the HTTP API.

=== Authentication ===

Authentication is performed by signing each request using HMAC-SHA512. The request must contain an extra value "nonce" which must be an always incrementing numeric value. A reference implementation is provided here:
<source lang="php">
<?php

function mtgox_query($path, array $req = array()) {
// API settings
$key = '';
$secret = '';

// generate a nonce as microtime, with as-string handling to avoid problems with 32bits systems
$mt = explode(' ', microtime());
$req['nonce'] = $mt[1].substr($mt[0], 2, 6);

// generate the POST data string
$post_data = http_build_query($req, '', '&');

// generate the extra headers
$headers = array(
'Rest-Key: '.$key,
'Rest-Sign: '.base64_encode(hash_hmac('sha512', $post_data, base64_decode($secret), true)),
);

// our curl handle (initialize if required)
static $ch = null;
if (is_null($ch)) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; MtGox PHP client; '.php_uname('s').'; PHP/'.phpversion().')');
}
curl_setopt($ch, CURLOPT_URL, 'https://mtgox.com/api/'.$path);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// run the query
$res = curl_exec($ch);
if ($res === false) throw new Exception('Could not get reply: '.curl_error($ch));
$dec = json_decode($res, true);
if (!$dec) throw new Exception('Invalid data received, please make sure connection is working and requested API exists');
return $dec;
}

// example 1: get infos about the account, plus the list of rights we have access to
var_dump(mtgox_query('0/info.php'));

// old api (get funds)
var_dump(mtgox_query('0/getFunds.php'));

// trade example
// var_dump(mtgox_query('0/buyBTC.php', array('amount' => 1, 'price' => 15)));
</source>

Python version here: https://bitcointalk.org/index.php?topic=49789.msg592388#msg592388

=== Cache ===

All of the API methods below have cached results, ticker, depth . . . have a 10 seconds cache .
No need to poll more often, you wont have more results, you could just be blocked by the prolexic anti ddos features.

=== Methods API version 0===

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

* data is returned in standard json format like :
<source lang="php">
[
{"date":1279408157,
"price":"0.04951",
"amount":"20",
"price_int":"4951",
"amount_int":"2000000000",
"tid":"1",
"price_currency":"USD",
"item":"BTC",
"trade_type":""
"primary":"Y"
},
{"date":1279424586,"price":"0.05941","amount":"50.01","price_int":"5941","amount_int":"5001000000","tid":"2","price_currency":"USD","item":"BTC","trade_type":""}]
</source>

==== 0/getDepth.php ====
Get the current Market depth

https://mtgox.com/api/0/data/getDepth.php?Currency=PLN

https://mtgox.com/api/0/data/getDepth.php?Currency=AUD

https://mtgox.com/api/0/data/getDepth.php?Currency=USD

==== 0/getFunds.php ====
Get your current balance

https://mtgox.com/api/0/getFunds.php

getfunds is now deprecated since multi currency, please use info.php

==== 0/buyBTC.php ====
Place an order to Buy BTC

https://mtgox.com/api/0/buyBTC.php

POST data: amount=#&price=#&Currency=PLN

returns a list of your open orders

you can omit the price to do a market order

==== 0/sellBTC.php ====
Place an order to Sell BTC

https://mtgox.com/api/0/sellBTC.php

POST data: &amount=#&price=#&Currency=PLN

returns a list of your open orders

you can omit the price to do a market order

==== 0/getOrders.php ====
Fetch a list of your open Orders

https://mtgox.com/api/0/getOrders.php

oid: Order ID

type: 1 for sell order or 2 for buy order

status: 1 for active, 2 for not enough funds

==== 0/cancelOrder.php ====
Cancel an order

https://mtgox.com/api/0/cancelOrder.php

POST data: oid=#&type=#

oid: Order ID

type: 1 for sell order or 2 for buy order

==== 0/redeemCode.php ====
Used to redeem a mtgox coupon code

https://mtgox.com/api/0/redeemCode.php

* call with a post parameter "code" containing the code to redeem

* it will return an array with amount (float amount value of code), currency (3 letters, BTC or USD), reference (the transaction id), and status

==== 0/withdraw.php ====
withdraw / Send BTC

https://mtgox.com/api/0/withdraw.php

POST data: group1=BTC&btca=bitcoin_address_to_send_to&amount=#

* pass btca parameter to withdraw to a btc adress

* pass group1 for a coupon : BTC2CODE or USD2CODE

* pass group1=DWUSD&dwaccount=XXX-XXX-XXXX (no btca=xxxxxxx) for a dwolla withdraw

* pass green=1 to use the new greenaddress feature ( see [[GreenAddress]] )
* return code and status if successful

To make a withdraw in another Currency , use group1=USD2CODE and add a Currency parameter ( example Currency=EUR to get a mtgox EUR coupon )

==== 0/btcAddress.php ====
get a bitcoin deposit adress for your account

https://mtgox.com/api/0/btcAddress.php

* pass POST data "description" to add a description that will appear in your history when this BTC address receive a deposit

* returns a bitcoin deposit address

==== 0/history_[CUR].csv ====

Allows downloading your activity history for a given currency (BTC or USD for now).

https://mtgox.com/api/0/history_BTC.csv

https://mtgox.com/api/0/history_USD.csv

==== 0/info.php ====

https://mtgox.com/api/0/info.php

returns info about your account, funds, fees, API privileges, withdraw limits . . .

==== 0/ticker ====

http://mtgox.com/api/0/data/ticker.php

returns the current ticker :

<source lang="php">
{"ticker":
{
"high":5.70653,
"low":5.4145,
"avg":5.561388723,
"vwap":5.610932845,
"vol":55698,
"last":5.56915,
"buy":5.51326,
"sell":5.5672
}
}
</source>

the time frame for high, low, vol, avg, vwap . . . is sliding 24 hours

what is vwap ?

please see http://en.wikipedia.org/wiki/VWAP

=== API version 0 examples ===

==== all api shell type CLI ====

python : http://www.goxsh.info/

perl : http://pastebin.com/vEpgw5nW

==== other ====

https : http://stackoverflow.com/questions/7046370/https-request-with-boost-asio-and-openssl

https://github.com/sje397/mtgox-plasmoid

module perl : http://search.cpan.org/~mndrix/Finance-MtGox-0.02/

==== gather data ====

https://github.com/Lexiks/MyBitBoard

==== gettrade ====

bash : https://bitcointalk.org/index.php?topic=39402.0

perl : http://pastebin.com/raw.php?i=pmhMXZJu

==== ticker ====

http://pastebin.com/pd0ZR4WY

=== Methods API version 1===

==== Multi Currency Ticker ====

https://mtgox.com/api/1/BTCUSD/public/ticker
https://mtgox.com/api/1/BTCEUR/public/ticker

returns the current ticker for the selected currency :

<source lang="php">
{
"result":"success",
"return":
{
"high": {"value":"5.70653","value_int":"570653","display":"$5.70653","currency":"USD"},
"low": {"value":"5.4145","value_int":"541450","display":"$5.41450","currency":"USD"},
"avg": {"value":"5.561119626","value_int":"556112","display":"$5.56112","currency":"USD"},
"vwap": {"value":"5.610480461","value_int":"561048","display":"$5.61048","currency":"USD"},
"vol":
{
"value":"55829.58960346",
"value_int":"5582958960346",
"display":"55,829.58960346\u00a0BTC",
"currency":"BTC"
},
"last_local":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"last_orig":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"last":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"buy":{"value":"5.53587","value_int":"553587","display":"$5.53587","currency":"USD"},
"sell":{"value":"5.56031","value_int":"556031","display":"$5.56031","currency":"USD"}
}
</source>

note : last_local include only the last trade in the selected currency, last_orig include data of the original last trade ( currency,price in currency . . . ),last can be a conversion of the last trde in another currency

==== Multi Currency depth ====

https://mtgox.com/api/1/BTCPLN/public/depth?raw

https://mtgox.com/api/1/BTCAUD/public/depth?raw

==== Multi currency trades ====

https://mtgox.com/api/1/BTCPLN/public/trades?raw

https://mtgox.com/api/1/BTCAUD/public/trades?raw

to get only the trades since a given trade id, you can add the parameter since=<trade_id>

https://mtgox.com/api/1/BTCUSD/public/trades?since=0

https://mtgox.com/api/1/BTCEUR/public/trades?since=1316312781670700

For multi currency,also returns the primary value,"Y" or "N", the primary currency is always the buyers currency

A trade can appear in more than one currency, to ignore duplicates, use only the trades having primary =Y

example of returned data :
<source lang="php">
{"date":1316312781,
"price":"3.5599",
"amount":"3.6900096",
"price_int":"355990",
"amount_int":"369000960",
"tid":"1316312781670700",
"price_currency":"EUR",
"item":"BTC",
"trade_type":"bid",
"primary":"Y",
"properties":"limit,mixed_currency"
}
</source>

==== Cancelled Trades ====

https://mtgox.com/api/1/BTCUSD/public/cancelledtrades

returns a list of all the cancelled trades this last month, list of trade ids in json format .

==== Full Depth ====

https://mtgox.com/api/1/BTCUSD/public/fulldepth

returns full depth

==== Private info ====

https://mtgox.com/api/1/generic/private/info

returns information about your account, funds, fees, API privileges, withdraw limits . . .

==== Your open orders ====

https://mtgox.com/api/1/generic/private/orders

returns information about your current open orders

==== Currency information ====

https://mtgox.com/api/1/generic/public/currency

pass parameter ?currency=<currency_symbol>

returns information about a currency ( number of decimals . . . )

==== HOTP key ====

https://mtgox.com/api/1/generic/public/hotp_gen

used to generate a new HOTP key ( useful for developpers )

== Streaming API ==
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 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
|}

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

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

|}

===Possible outgoing commands===
'''unsubscribe''' Stop receiving messages from a channel (parameter "channel")

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

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

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

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

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

MtGox/API

2011-12-11T23:03:53Z

Clark: /* Depth */ Message content

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

Two APIs are currently available: 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.

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

== HTTP API ==
This API is available in <nowiki>https://mtgox.com/api/*</nowiki>, and provides various informations. It also supports making an order, a withdraw, a deposit, etc. There is also a [https://rubygems.org/gems/mtgox Ruby gem] and [[Finance::MtGox|Perl module]] for interacting with the HTTP API.

=== Authentication ===

Authentication is performed by signing each request using HMAC-SHA512. The request must contain an extra value "nonce" which must be an always incrementing numeric value. A reference implementation is provided here:
<source lang="php">
<?php

function mtgox_query($path, array $req = array()) {
// API settings
$key = '';
$secret = '';

// generate a nonce as microtime, with as-string handling to avoid problems with 32bits systems
$mt = explode(' ', microtime());
$req['nonce'] = $mt[1].substr($mt[0], 2, 6);

// generate the POST data string
$post_data = http_build_query($req, '', '&');

// generate the extra headers
$headers = array(
'Rest-Key: '.$key,
'Rest-Sign: '.base64_encode(hash_hmac('sha512', $post_data, base64_decode($secret), true)),
);

// our curl handle (initialize if required)
static $ch = null;
if (is_null($ch)) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; MtGox PHP client; '.php_uname('s').'; PHP/'.phpversion().')');
}
curl_setopt($ch, CURLOPT_URL, 'https://mtgox.com/api/'.$path);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// run the query
$res = curl_exec($ch);
if ($res === false) throw new Exception('Could not get reply: '.curl_error($ch));
$dec = json_decode($res, true);
if (!$dec) throw new Exception('Invalid data received, please make sure connection is working and requested API exists');
return $dec;
}

// example 1: get infos about the account, plus the list of rights we have access to
var_dump(mtgox_query('0/info.php'));

// old api (get funds)
var_dump(mtgox_query('0/getFunds.php'));

// trade example
// var_dump(mtgox_query('0/buyBTC.php', array('amount' => 1, 'price' => 15)));
</source>

Python version here: https://bitcointalk.org/index.php?topic=49789.msg592388#msg592388

=== Cache ===

All of the API methods below have cached results, ticker, depth . . . have a 10 seconds cache .
No need to poll more often, you wont have more results, you could just be blocked by the prolexic anti ddos features.

=== Methods API version 0===

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

* data is returned in standard json format like :
<source lang="php">
[
{"date":1279408157,
"price":"0.04951",
"amount":"20",
"price_int":"4951",
"amount_int":"2000000000",
"tid":"1",
"price_currency":"USD",
"item":"BTC",
"trade_type":""
"primary":"Y"
},
{"date":1279424586,"price":"0.05941","amount":"50.01","price_int":"5941","amount_int":"5001000000","tid":"2","price_currency":"USD","item":"BTC","trade_type":""}]
</source>

==== 0/getDepth.php ====
Get the current Market depth

https://mtgox.com/api/0/data/getDepth.php?Currency=PLN

https://mtgox.com/api/0/data/getDepth.php?Currency=AUD

https://mtgox.com/api/0/data/getDepth.php?Currency=USD

==== 0/getFunds.php ====
Get your current balance

https://mtgox.com/api/0/getFunds.php

getfunds is now deprecated since multi currency, please use info.php

==== 0/buyBTC.php ====
Place an order to Buy BTC

https://mtgox.com/api/0/buyBTC.php

POST data: amount=#&price=#&Currency=PLN

returns a list of your open orders

you can omit the price to do a market order

==== 0/sellBTC.php ====
Place an order to Sell BTC

https://mtgox.com/api/0/sellBTC.php

POST data: &amount=#&price=#&Currency=PLN

returns a list of your open orders

you can omit the price to do a market order

==== 0/getOrders.php ====
Fetch a list of your open Orders

https://mtgox.com/api/0/getOrders.php

oid: Order ID

type: 1 for sell order or 2 for buy order

status: 1 for active, 2 for not enough funds

==== 0/cancelOrder.php ====
Cancel an order

https://mtgox.com/api/0/cancelOrder.php

POST data: oid=#&type=#

oid: Order ID

type: 1 for sell order or 2 for buy order

==== 0/redeemCode.php ====
Used to redeem a mtgox coupon code

https://mtgox.com/api/0/redeemCode.php

* call with a post parameter "code" containing the code to redeem

* it will return an array with amount (float amount value of code), currency (3 letters, BTC or USD), reference (the transaction id), and status

==== 0/withdraw.php ====
withdraw / Send BTC

https://mtgox.com/api/0/withdraw.php

POST data: group1=BTC&btca=bitcoin_address_to_send_to&amount=#

* pass btca parameter to withdraw to a btc adress

* pass group1 for a coupon : BTC2CODE or USD2CODE

* pass group1=DWUSD&dwaccount=XXX-XXX-XXXX (no btca=xxxxxxx) for a dwolla withdraw

* pass green=1 to use the new greenaddress feature ( see [[GreenAddress]] )
* return code and status if successful

To make a withdraw in another Currency , use group1=USD2CODE and add a Currency parameter ( example Currency=EUR to get a mtgox EUR coupon )

==== 0/btcAddress.php ====
get a bitcoin deposit adress for your account

https://mtgox.com/api/0/btcAddress.php

* pass POST data "description" to add a description that will appear in your history when this BTC address receive a deposit

* returns a bitcoin deposit address

==== 0/history_[CUR].csv ====

Allows downloading your activity history for a given currency (BTC or USD for now).

https://mtgox.com/api/0/history_BTC.csv

https://mtgox.com/api/0/history_USD.csv

==== 0/info.php ====

https://mtgox.com/api/0/info.php

returns info about your account, funds, fees, API privileges, withdraw limits . . .

==== 0/ticker ====

http://mtgox.com/api/0/data/ticker.php

returns the current ticker :

<source lang="php">
{"ticker":
{
"high":5.70653,
"low":5.4145,
"avg":5.561388723,
"vwap":5.610932845,
"vol":55698,
"last":5.56915,
"buy":5.51326,
"sell":5.5672
}
}
</source>

the time frame for high, low, vol, avg, vwap . . . is sliding 24 hours

what is vwap ?

please see http://en.wikipedia.org/wiki/VWAP

=== API version 0 examples ===

==== all api shell type CLI ====

python : http://www.goxsh.info/

perl : http://pastebin.com/vEpgw5nW

==== other ====

https : http://stackoverflow.com/questions/7046370/https-request-with-boost-asio-and-openssl

https://github.com/sje397/mtgox-plasmoid

module perl : http://search.cpan.org/~mndrix/Finance-MtGox-0.02/

==== gather data ====

https://github.com/Lexiks/MyBitBoard

==== gettrade ====

bash : https://bitcointalk.org/index.php?topic=39402.0

perl : http://pastebin.com/raw.php?i=pmhMXZJu

==== ticker ====

http://pastebin.com/pd0ZR4WY

=== Methods API version 1===

==== Multi Currency Ticker ====

https://mtgox.com/api/1/BTCUSD/public/ticker
https://mtgox.com/api/1/BTCEUR/public/ticker

returns the current ticker for the selected currency :

<source lang="php">
{
"result":"success",
"return":
{
"high": {"value":"5.70653","value_int":"570653","display":"$5.70653","currency":"USD"},
"low": {"value":"5.4145","value_int":"541450","display":"$5.41450","currency":"USD"},
"avg": {"value":"5.561119626","value_int":"556112","display":"$5.56112","currency":"USD"},
"vwap": {"value":"5.610480461","value_int":"561048","display":"$5.61048","currency":"USD"},
"vol":
{
"value":"55829.58960346",
"value_int":"5582958960346",
"display":"55,829.58960346\u00a0BTC",
"currency":"BTC"
},
"last_local":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"last_orig":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"last":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"buy":{"value":"5.53587","value_int":"553587","display":"$5.53587","currency":"USD"},
"sell":{"value":"5.56031","value_int":"556031","display":"$5.56031","currency":"USD"}
}
</source>

note : last_local include only the last trade in the selected currency, last_orig include data of the original last trade ( currency,price in currency . . . ),last can be a conversion of the last trde in another currency

==== Multi Currency depth ====

https://mtgox.com/api/1/BTCPLN/public/depth?raw

https://mtgox.com/api/1/BTCAUD/public/depth?raw

==== Multi currency trades ====

https://mtgox.com/api/1/BTCPLN/public/trades?raw

https://mtgox.com/api/1/BTCAUD/public/trades?raw

to get only the trades since a given trade id, you can add the parameter since=<trade_id>

https://mtgox.com/api/1/BTCUSD/public/trades?since=0

https://mtgox.com/api/1/BTCEUR/public/trades?since=1316312781670700

For multi currency,also returns the primary value,"Y" or "N", the primary currency is always the buyers currency

A trade can appear in more than one currency, to ignore duplicates, use only the trades having primary =Y

example of returned data :
<source lang="php">
{"date":1316312781,
"price":"3.5599",
"amount":"3.6900096",
"price_int":"355990",
"amount_int":"369000960",
"tid":"1316312781670700",
"price_currency":"EUR",
"item":"BTC",
"trade_type":"bid",
"primary":"Y",
"properties":"limit,mixed_currency"
}
</source>

==== Cancelled Trades ====

https://mtgox.com/api/1/BTCUSD/public/cancelledtrades

returns a list of all the cancelled trades this last month, list of trade ids in json format .

==== Full Depth ====

https://mtgox.com/api/1/BTCUSD/public/fulldepth

returns full depth

==== Private info ====

https://mtgox.com/api/1/generic/private/info

returns information about your account, funds, fees, API privileges, withdraw limits . . .

==== Your open orders ====

https://mtgox.com/api/1/generic/private/orders

returns information about your current open orders

==== Currency information ====

https://mtgox.com/api/1/generic/public/currency

pass parameter ?currency=<currency_symbol>

returns information about a currency ( number of decimals . . . )

==== HOTP key ====

https://mtgox.com/api/1/generic/public/hotp_gen

used to generate a new HOTP key ( useful for developpers )

== Streaming API ==
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 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
|}

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

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

|}

===Possible outgoing commands===
'''unsubscribe''' Stop receiving messages from a channel (parameter "channel")

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

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

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

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

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

Talk:Mt. Gox/API

2011-11-18T00:26:53Z

Clark: /* More channels in the socket.io connection */

I believe some of the inexperienced api users may have unintentionally compromised the Authentication section and examples by removing the details regarding api key & secret as recommended by MtGox at https://mtgox.com/support/tradeAPI.
The change now describes the need for user name and password. Though this old model still works in the new api model, it is not the recommended strategy because it gives applications information which would compromise the user's private account. The application SHOULD ONLY have access to the the api calls as granted by them by the user's specified api rights associated to the api key and secret.

[[User:Automtgox|Automtgox]] 00:18, 22 September 2011 (GMT)

== More channels in the socket.io connection ==

Instead of the 3 channels listed in the original WebSocket connection list, I am seeing many more that I have no idea about:

:{| class="wikitable"
|-
! Channel !! Description
|-
| d5f06780-30a8-4a48-a2f8-7ed181b4a13f || Ticker
|-
| dbf1dee9-4f2e-4a08-8cb7-748919a71b21 || Trades
|-
| 24e67e0d-1cad-4cc0-9e7a-f8523ef460fe || Depth
|-
| 5b234cc3-a7c1-47ce-854f-27aee4cdbda5 || ?
|-
| 113fec5f-294d-4929-86eb-8ca4c3fd1bed || ?
|-
| 0d1ecad8-e20f-459e-8bed-0bdcf927820f || ?
|-
| 9219abb0-b50c-4007-b4d2-51d1711ab19c || ?
|-
| 057bdc6b-9f9c-44e4-bc1a-363e4443ce87 || ?
|-
| 60c3af1b-5d40-4d0e-b9fc-ccab433d2e9c || ?
|-
| 049f65dc-3af3-4ffd-85a5-aac102b2a579 || ?
|-
| 94483e07-d797-4dd4-bc72-dc98f1fd39e3 || ?
|-
| 66da7fb4-6b0c-4a10-9cb7-e2944e046eb5 || ?
|-
| cedf8730-bce6-4278-b6fe-9bee42930e95 || ?
|-
| e4ff055a-f8bf-407e-af76-676cad319a21 || ?
|-
| d6412ca0-b686-464c-891a-d1ba3943f3c6 || ?
|-
| 8f1fefaa-7c55-4420-ada0-4de15c1c38f3 || ?
|-
| 41e5c243-3d44-4fad-b690-f39e1dbb86a8 || ?
|-
| 67879668-532f-41f9-8eb0-55e7593a5ab8 || ?
|}

And more...

--[[User:Clark|Clark]] 00:26, 18 November 2011 (GMT)

Talk:Mt. Gox/API

2011-11-18T00:26:30Z

Clark: /* More channels in the socket.io connection */ new section

MtGox/API

2011-11-18T00:19:49Z

Clark: /* Websocket API */ Heavy update of streaming data section to include socket.io

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.

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

== HTTP API ==
This API is available in <nowiki>https://mtgox.com/api/*</nowiki>, and provides various informations. It also supports making an order, a withdraw, a deposit, etc. There is also a [https://rubygems.org/gems/mtgox Ruby gem] and [[Finance::MtGox|Perl module]] for interacting with the HTTP API.

=== Authentication ===

Authentication is performed by signing each request using HMAC-SHA512. The request must contain an extra value "nonce" which must be an always incrementing numeric value. A reference implementation is provided here:
<source lang="php">
<?php

function mtgox_query($path, array $req = array()) {
// API settings
$key = '';
$secret = '';

// generate a nonce as microtime, with as-string handling to avoid problems with 32bits systems
$mt = explode(' ', microtime());
$req['nonce'] = $mt[1].substr($mt[0], 2, 6);

// generate the POST data string
$post_data = http_build_query($req, '', '&');

// generate the extra headers
$headers = array(
'Rest-Key: '.$key,
'Rest-Sign: '.base64_encode(hash_hmac('sha512', $post_data, base64_decode($secret), true)),
);

// our curl handle (initialize if required)
static $ch = null;
if (is_null($ch)) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; MtGox PHP client; '.php_uname('s').'; PHP/'.phpversion().')');
}
curl_setopt($ch, CURLOPT_URL, 'https://mtgox.com/api/'.$path);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// run the query
$res = curl_exec($ch);
if ($res === false) throw new Exception('Could not get reply: '.curl_error($ch));
$dec = json_decode($res, true);
if (!$dec) throw new Exception('Invalid data received, please make sure connection is working and requested API exists');
return $dec;
}

// example 1: get infos about the account, plus the list of rights we have access to
var_dump(mtgox_query('0/info.php'));

// old api (get funds)
var_dump(mtgox_query('0/getFunds.php'));

// trade example
// var_dump(mtgox_query('0/buyBTC.php', array('amount' => 1, 'price' => 15)));
</source>

Python version here: https://bitcointalk.org/index.php?topic=49789.msg592388#msg592388

=== Cache ===

All of the API methods below have cached results, ticker, depth . . . have a 10 seconds cache .
No need to poll more often, you wont have more results, you could just be blocked by the prolexic anti ddos features.

=== Methods API version 0===

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

* data is returned in standard json format like :
<source lang="php">
[
{"date":1279408157,
"price":"0.04951",
"amount":"20",
"price_int":"4951",
"amount_int":"2000000000",
"tid":"1",
"price_currency":"USD",
"item":"BTC",
"trade_type":""
"primary":"Y"
},
{"date":1279424586,"price":"0.05941","amount":"50.01","price_int":"5941","amount_int":"5001000000","tid":"2","price_currency":"USD","item":"BTC","trade_type":""}]
</source>

==== 0/getDepth.php ====
Get the current Market depth

https://mtgox.com/api/0/data/getDepth.php?Currency=PLN

https://mtgox.com/api/0/data/getDepth.php?Currency=AUD

https://mtgox.com/api/0/data/getDepth.php?Currency=USD

==== 0/getFunds.php ====
Get your current balance

https://mtgox.com/api/0/getFunds.php

getfunds is now deprecated since multi currency, please use info.php

==== 0/buyBTC.php ====
Place an order to Buy BTC

https://mtgox.com/api/0/buyBTC.php

POST data: amount=#&price=#&Currency=PLN

returns a list of your open orders

you can omit the price to do a market order

==== 0/sellBTC.php ====
Place an order to Sell BTC

https://mtgox.com/api/0/sellBTC.php

POST data: &amount=#&price=#&Currency=PLN

returns a list of your open orders

you can omit the price to do a market order

==== 0/getOrders.php ====
Fetch a list of your open Orders

https://mtgox.com/api/0/getOrders.php

oid: Order ID

type: 1 for sell order or 2 for buy order

status: 1 for active, 2 for not enough funds

==== 0/cancelOrder.php ====
Cancel an order

https://mtgox.com/api/0/cancelOrder.php

POST data: oid=#&type=#

oid: Order ID

type: 1 for sell order or 2 for buy order

==== 0/redeemCode.php ====
Used to redeem a mtgox coupon code

https://mtgox.com/api/0/redeemCode.php

* call with a post parameter "code" containing the code to redeem

* it will return an array with amount (float amount value of code), currency (3 letters, BTC or USD), reference (the transaction id), and status

==== 0/withdraw.php ====
withdraw / Send BTC

https://mtgox.com/api/0/withdraw.php

POST data: group1=BTC&btca=bitcoin_address_to_send_to&amount=#

* pass btca parameter to withdraw to a btc adress

* pass group1 for a coupon : BTC2CODE or USD2CODE

* pass group1=DWUSD for a dwolla withdraw

* pass green=1 to use the new greenaddress feature ( see [[GreenAddress]] )
* return code and status if successful

To make a withdraw in another Currency , use group1=USD2CODE and add a Currency parameter ( example Currency=EUR to get a mtgox EUR coupon )

==== 0/btcAddress.php ====
get a bitcoin deposit adress for your account

https://mtgox.com/api/0/btcAddress.php

* pass POST data "description" to add a description that will appear in your history when this BTC address receive a deposit

* returns a bitcoin deposit address

==== 0/history_[CUR].csv ====

Allows downloading your activity history for a given currency (BTC or USD for now).

https://mtgox.com/api/0/history_BTC.csv

https://mtgox.com/api/0/history_USD.csv

==== 0/info.php ====

https://mtgox.com/api/0/info.php

returns info about your account, funds, fees, API privileges . . .

==== 0/ticker ====

http://mtgox.com/api/0/data/ticker.php

returns the current ticker :

<source lang="php">
{"ticker":
{
"high":5.70653,
"low":5.4145,
"avg":5.561388723,
"vwap":5.610932845,
"vol":55698,
"last":5.56915,
"buy":5.51326,
"sell":5.5672
}
}
</source>

the time frame for high, low, vol, avg, vwap . . . is sliding 24 hours

what is vwap ?

please see http://en.wikipedia.org/wiki/VWAP

=== API version 0 examples ===

==== all api shell type CLI ====

python : http://www.goxsh.info/

perl : http://pastebin.com/vEpgw5nW

==== other ====

https : http://stackoverflow.com/questions/7046370/https-request-with-boost-asio-and-openssl

https://github.com/sje397/mtgox-plasmoid

module perl : http://search.cpan.org/~mndrix/Finance-MtGox-0.02/

==== gather data ====

https://github.com/Lexiks/MyBitBoard

==== gettrade ====

bash : https://bitcointalk.org/index.php?topic=39402.0

perl : http://pastebin.com/raw.php?i=pmhMXZJu

==== ticker ====

http://pastebin.com/pd0ZR4WY

=== Methods API version 1===

==== Multi Currency Ticker ====

https://mtgox.com/api/1/BTCUSD/public/ticker
https://mtgox.com/api/1/BTCEUR/public/ticker

returns the current ticker for the selected currency :

<source lang="php">
{
"result":"success",
"return":
{
"high": {"value":"5.70653","value_int":"570653","display":"$5.70653","currency":"USD"},
"low": {"value":"5.4145","value_int":"541450","display":"$5.41450","currency":"USD"},
"avg": {"value":"5.561119626","value_int":"556112","display":"$5.56112","currency":"USD"},
"vwap": {"value":"5.610480461","value_int":"561048","display":"$5.61048","currency":"USD"},
"vol":
{
"value":"55829.58960346",
"value_int":"5582958960346",
"display":"55,829.58960346\u00a0BTC",
"currency":"BTC"
},
"last_local":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"last_orig":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"last":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"buy":{"value":"5.53587","value_int":"553587","display":"$5.53587","currency":"USD"},
"sell":{"value":"5.56031","value_int":"556031","display":"$5.56031","currency":"USD"}
}
</source>

note : last_local include only the last trade in the selected currency, last_orig include data of the original last trade ( currency,price in currency . . . ),last can be a conversion of the last trde in another currency

==== Multi Currency depth ====

https://mtgox.com/api/1/BTCPLN/public/depth?raw

https://mtgox.com/api/1/BTCAUD/public/depth?raw

==== Multi currency trades ====

https://mtgox.com/api/1/BTCPLN/public/trades?raw

https://mtgox.com/api/1/BTCAUD/public/trades?raw

to get only the trades since a given trade id, you can add the parameter since=<trade_id>

https://mtgox.com/api/1/BTCUSD/public/trades?since=0

https://mtgox.com/api/1/BTCEUR/public/trades?since=1316312781670700

For multi currency,also returns the primary value,"Y" or "N", the primary currency is always the buyers currency

A trade can appear in more than one currency, to ignore duplicates, use only the trades having primary =Y

example of returned data :
<source lang="php">
{"date":1316312781,
"price":"3.5599",
"amount":"3.6900096",
"price_int":"355990",
"amount_int":"369000960",
"tid":"1316312781670700",
"price_currency":"EUR",
"item":"BTC",
"trade_type":"bid",
"primary":"Y",
"properties":"limit,mixed_currency"
}
</source>

==== Cancelled Trades ====

https://mtgox.com/api/1/BTCUSD/public/cancelledtrades

returns a list of all the cancelled trades this last month, list of trade ids in json format .

==== Full Depth ====

https://mtgox.com/api/1/BTCUSD/public/fulldepth

returns full depth

== Streaming API ==
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>

===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 a few 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
|}

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

====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",
"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

|}

===Possible outgoing commands===
'''unsubscribe''' Stop receiving messages from a channel (parameter "channel")

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

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

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

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

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

MtGox/API

2011-11-17T21:10:29Z

Clark: /* currency symbols */ Formatting

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.

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

== HTTP API ==
This API is available in <nowiki>https://mtgox.com/api/*</nowiki>, and provides various informations. It also supports making an order, a withdraw, a deposit, etc. There is also a [https://rubygems.org/gems/mtgox Ruby gem] and [[Finance::MtGox|Perl module]] for interacting with the HTTP API.

=== Authentication ===

Authentication is performed by signing each request using HMAC-SHA512. The request must contain an extra value "nonce" which must be an always incrementing numeric value. A reference implementation is provided here:
<source lang="php">
<?php

function mtgox_query($path, array $req = array()) {
// API settings
$key = '';
$secret = '';

// generate a nonce as microtime, with as-string handling to avoid problems with 32bits systems
$mt = explode(' ', microtime());
$req['nonce'] = $mt[1].substr($mt[0], 2, 6);

// generate the POST data string
$post_data = http_build_query($req, '', '&');

// generate the extra headers
$headers = array(
'Rest-Key: '.$key,
'Rest-Sign: '.base64_encode(hash_hmac('sha512', $post_data, base64_decode($secret), true)),
);

// our curl handle (initialize if required)
static $ch = null;
if (is_null($ch)) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERAGENT, 'Mozilla/4.0 (compatible; MtGox PHP client; '.php_uname('s').'; PHP/'.phpversion().')');
}
curl_setopt($ch, CURLOPT_URL, 'https://mtgox.com/api/'.$path);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// run the query
$res = curl_exec($ch);
if ($res === false) throw new Exception('Could not get reply: '.curl_error($ch));
$dec = json_decode($res, true);
if (!$dec) throw new Exception('Invalid data received, please make sure connection is working and requested API exists');
return $dec;
}

// example 1: get infos about the account, plus the list of rights we have access to
var_dump(mtgox_query('0/info.php'));

// old api (get funds)
var_dump(mtgox_query('0/getFunds.php'));

// trade example
// var_dump(mtgox_query('0/buyBTC.php', array('amount' => 1, 'price' => 15)));
</source>

Python version here: https://bitcointalk.org/index.php?topic=49789.msg592388#msg592388

=== Cache ===

All of the API methods below have cached results, ticker, depth . . . have a 10 seconds cache .
No need to poll more often, you wont have more results, you could just be blocked by the prolexic anti ddos features.

=== Methods API version 0===

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

* data is returned in standard json format like :
<source lang="php">
[
{"date":1279408157,
"price":"0.04951",
"amount":"20",
"price_int":"4951",
"amount_int":"2000000000",
"tid":"1",
"price_currency":"USD",
"item":"BTC",
"trade_type":""
"primary":"Y"
},
{"date":1279424586,"price":"0.05941","amount":"50.01","price_int":"5941","amount_int":"5001000000","tid":"2","price_currency":"USD","item":"BTC","trade_type":""}]
</source>

==== 0/getDepth.php ====
Get the current Market depth

https://mtgox.com/api/0/data/getDepth.php?Currency=PLN

https://mtgox.com/api/0/data/getDepth.php?Currency=AUD

https://mtgox.com/api/0/data/getDepth.php?Currency=USD

==== 0/getFunds.php ====
Get your current balance

https://mtgox.com/api/0/getFunds.php

getfunds is now deprecated since multi currency, please use info.php

==== 0/buyBTC.php ====
Place an order to Buy BTC

https://mtgox.com/api/0/buyBTC.php

POST data: amount=#&price=#&Currency=PLN

returns a list of your open orders

you can omit the price to do a market order

==== 0/sellBTC.php ====
Place an order to Sell BTC

https://mtgox.com/api/0/sellBTC.php

POST data: &amount=#&price=#&Currency=PLN

returns a list of your open orders

you can omit the price to do a market order

==== 0/getOrders.php ====
Fetch a list of your open Orders

https://mtgox.com/api/0/getOrders.php

oid: Order ID

type: 1 for sell order or 2 for buy order

status: 1 for active, 2 for not enough funds

==== 0/cancelOrder.php ====
Cancel an order

https://mtgox.com/api/0/cancelOrder.php

POST data: oid=#&type=#

oid: Order ID

type: 1 for sell order or 2 for buy order

==== 0/redeemCode.php ====
Used to redeem a mtgox coupon code

https://mtgox.com/api/0/redeemCode.php

* call with a post parameter "code" containing the code to redeem

* it will return an array with amount (float amount value of code), currency (3 letters, BTC or USD), reference (the transaction id), and status

==== 0/withdraw.php ====
withdraw / Send BTC

https://mtgox.com/api/0/withdraw.php

POST data: group1=BTC&btca=bitcoin_address_to_send_to&amount=#

* pass btca parameter to withdraw to a btc adress

* pass group1 for a coupon : BTC2CODE or USD2CODE

* pass group1=DWUSD for a dwolla withdraw

* pass green=1 to use the new greenaddress feature ( see [[GreenAddress]] )
* return code and status if successful

To make a withdraw in another Currency , use group1=USD2CODE and add a Currency parameter ( example Currency=EUR to get a mtgox EUR coupon )

==== 0/btcAddress.php ====
get a bitcoin deposit adress for your account

https://mtgox.com/api/0/btcAddress.php

* pass POST data "description" to add a description that will appear in your history when this BTC address receive a deposit

* returns a bitcoin deposit address

==== 0/history_[CUR].csv ====

Allows downloading your activity history for a given currency (BTC or USD for now).

https://mtgox.com/api/0/history_BTC.csv

https://mtgox.com/api/0/history_USD.csv

==== 0/info.php ====

https://mtgox.com/api/0/info.php

returns info about your account, funds, fees, API privileges . . .

==== 0/ticker ====

http://mtgox.com/api/0/data/ticker.php

returns the current ticker :

<source lang="php">
{"ticker":
{
"high":5.70653,
"low":5.4145,
"avg":5.561388723,
"vwap":5.610932845,
"vol":55698,
"last":5.56915,
"buy":5.51326,
"sell":5.5672
}
}
</source>

the time frame for high, low, vol, avg, vwap . . . is sliding 24 hours

what is vwap ?

please see http://en.wikipedia.org/wiki/VWAP

=== API version 0 examples ===

==== all api shell type CLI ====

python : http://www.goxsh.info/

perl : http://pastebin.com/vEpgw5nW

==== other ====

https : http://stackoverflow.com/questions/7046370/https-request-with-boost-asio-and-openssl

https://github.com/sje397/mtgox-plasmoid

module perl : http://search.cpan.org/~mndrix/Finance-MtGox-0.02/

==== gather data ====

https://github.com/Lexiks/MyBitBoard

==== gettrade ====

bash : https://bitcointalk.org/index.php?topic=39402.0

perl : http://pastebin.com/raw.php?i=pmhMXZJu

==== ticker ====

http://pastebin.com/pd0ZR4WY

=== Methods API version 1===

==== Multi Currency Ticker ====

https://mtgox.com/api/1/BTCUSD/public/ticker
https://mtgox.com/api/1/BTCEUR/public/ticker

returns the current ticker for the selected currency :

<source lang="php">
{
"result":"success",
"return":
{
"high": {"value":"5.70653","value_int":"570653","display":"$5.70653","currency":"USD"},
"low": {"value":"5.4145","value_int":"541450","display":"$5.41450","currency":"USD"},
"avg": {"value":"5.561119626","value_int":"556112","display":"$5.56112","currency":"USD"},
"vwap": {"value":"5.610480461","value_int":"561048","display":"$5.61048","currency":"USD"},
"vol":
{
"value":"55829.58960346",
"value_int":"5582958960346",
"display":"55,829.58960346\u00a0BTC",
"currency":"BTC"
},
"last_local":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"last_orig":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"last":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"buy":{"value":"5.53587","value_int":"553587","display":"$5.53587","currency":"USD"},
"sell":{"value":"5.56031","value_int":"556031","display":"$5.56031","currency":"USD"}
}
</source>

note : last_local include only the last trade in the selected currency, last_orig include data of the original last trade ( currency,price in currency . . . ),last can be a conversion of the last trde in another currency

==== Multi Currency depth ====

https://mtgox.com/api/1/BTCPLN/public/depth?raw

https://mtgox.com/api/1/BTCAUD/public/depth?raw

==== Multi currency trades ====

https://mtgox.com/api/1/BTCPLN/public/trades?raw

https://mtgox.com/api/1/BTCAUD/public/trades?raw

to get only the trades since a given trade id, you can add the parameter since=<trade_id>

https://mtgox.com/api/1/BTCUSD/public/trades?since=0

https://mtgox.com/api/1/BTCEUR/public/trades?since=1316312781670700

For multi currency,also returns the primary value,"Y" or "N", the primary currency is always the buyers currency

A trade can appear in more than one currency, to ignore duplicates, use only the trades having primary =Y

example of returned data :
<source lang="php">
{"date":1316312781,
"price":"3.5599",
"amount":"3.6900096",
"price_int":"355990",
"amount_int":"369000960",
"tid":"1316312781670700",
"price_currency":"EUR",
"item":"BTC",
"trade_type":"bid",
"primary":"Y",
"properties":"limit,mixed_currency"
}
</source>

==== Cancelled Trades ====

https://mtgox.com/api/1/BTCUSD/public/cancelledtrades

returns a list of all the cancelled trades this last month, list of trade ids in json format .

==== Full Depth ====

https://mtgox.com/api/1/BTCUSD/public/fulldepth

returns full depth

== 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-7ed181b4a13f",
"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 || highest bid as float
|-
| sell || lowest 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

|}

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

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

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

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

Real Time Bitcoin Market Data

2011-10-31T19:41:51Z

Clark:

A financial information service that provides a real-time display of data from the [[MtGox]] exchange.

* Combined - Includes all of the services listed below
* Time Sales - Time price and volume for each trade executed
* Ticker - Current best ask / best bid, day's high, day's low, volume and last trade for all MtGox currencies. The site also displays a synthetic forex grid, based on the immediate exchange rates between non-zero volume currencies.
* Order Book - The buy (bid) and sell (ask) orders along with real time trade calculators

The Ticker and Time Sales services were announced on June 03, 2011<ref>[http://forum.bitcoin.org/index.php?topic=11560.0 Realtime MtGox Time and Sales with WebSockets]</ref> and the Order Book was announced on June 10, 2011<ref>[http://forum.bitcoin.org/index.php?topic=14412.0 Real Time Order Book with WebSockets]</ref>. The combined information view was announced on September 11, 2011<ref>[https://bitcointalk.org/index.php?topic=43514.0 Combined Order Book and Time & Sales]</ref>.

==External Links==

* [http://bitcoin.clarkmoody.com/ Combined] web page
* [http://bitcoin.clarkmoody.com/time-sales Time Sales] web page
* [http://bitcoin.clarkmoody.com/ticker Ticker] web page
* [http://bitcoin.clarkmoody.com/order-book Order Book] web page

==References==
<references />

[[Category:Financial]]

Real Time Bitcoin Market Data

2011-09-12T19:54:02Z

Clark:

A financial information service that provides a real-time display of data from the [[MtGox]] exchange.

* Combined - Includes all of the services listed below
* Time Sales - Time price and volume for each trade executed
* Ticker - Current best ask / best bid, day's high, day's low, volume and last trade
* Order Book - The buy (bid) and sell (ask) orders along with real time trade calculators

The Ticker and Time Sales services were announced on June 03, 2011<ref>[http://forum.bitcoin.org/index.php?topic=11560.0 Realtime MtGox Time and Sales with WebSockets]</ref> and the Order Book was announced on June 10, 2011<ref>[http://forum.bitcoin.org/index.php?topic=14412.0 Real Time Order Book with WebSockets]</ref>. The combined information view was announced on September 11, 2011<ref>[https://bitcointalk.org/index.php?topic=43514.0 Combined Order Book and Time & Sales]</ref>.

==External Links==

* [http://bitcoin.clarkmoody.com/ Combined] web page
* [http://bitcoin.clarkmoody.com/time-sales Time Sales] web page
* [http://bitcoin.clarkmoody.com/ticker Ticker] web page
* [http://bitcoin.clarkmoody.com/order-book Order Book] web page

==References==
<references />

[[Category:Financial]]

Mini private key format

2011-09-08T18:54:46Z

Clark: Added length check in Python code CheckShortKey()

The '''mini private key format''' is a method of encoding a Bitcoin private key in 22 characters so that it can be embedded in a small space. This private key format was first used in Casascius physical bitcoins, and is also favorable for use in QR codes. The fewer characters encoded in a QR code, the lower dot density can be used, as well as more dots allocated to error correcting codes, and hence a QR code that is easier for a machine to read. The mini private key format offers its own built-in check code as a small margin of protection against typos.

An example key using this encoding is '''S4b3N3oGqDqR5jNuxEvDwf'''.

The way it might appear within a physical bitcoin is on a round card printed as follows:

<center>S4b3N<br/>3oGqDq<br/>R5jNux<br/>EvDwf</center>

==Decoding==
The private key encoding consists of 22 alphanumeric characters from the [[base58]] alphabet used in Bitcoin. The first of the 22 characters is always the uppercase letter S.

To obtain the full 256-bit private key, simply take the SHA256 hash of the entire string. There is no encoding for breaks in the string even if printed that way - the SHA256 should be taken of exactly twenty-two bytes.

SHA256("S4b3N3oGqDqR5jNuxEvDwf") = 0C28FCA386C7A227600B2FE50B7CAE11EC86D3BF1FBE471BE89827E19D72AA1D

==Check code==
The check code is designed to be simple, but relatively computationally expensive so that it cannot be used to quickly reduce the key space in a brute force attack. It offers seven bits worth of error protection (or, in other words, in the event of a typo, the typo will be caught about 127 out of 128 times, or over 99%).

To determine whether a string passes the check code, follow these steps:
# Ensure it is well-formed (22 characters, base58 alphabet, starts with S).
# Add a question mark to the end of the string, and take the SHA256 of that. If the SHA256 starts with eight zero bits (hex 00), then the string passes the check code.
# If it does not, then with the same string (ending in a question mark), do 717 (seven hundred seventeen) rounds of SHA256 on the string. If the result after the 717th round starts with eight zero bits (hex 00), then the string passes the check code.
# If the results of SHA256 after both tests don't start with eight zero bits, then the check fails.

==Creating mini private keys==
Creating mini private keys is relatively simple. One program which can create such keys is [[Casascius Bitcoin Utility]].

Mini private keys must be created "from scratch", as the conversion from mini private key to full-size private key is one-way. In other words, there is no way to convert an existing full-size private key into a mini private key.

To create mini private keys, simply create random strings that satisfy the well-formedness requirement, and then eliminate the ones that do not pass the typo check. (This means eliminating more than 99% of the candidates.) Then use SHA256 to compute the corresponding private key, and in turn, the matching Bitcoin address. The Bitcoin address can always be computed from just the private key.

In all cases, you should use a secure cryptographic random number generator to eliminate risks of predictability of the random strings. Also, for stronger security, accept only the strings that pass the typo check on the 717th round rather than the first.

==Python Code==
<source lang="python">
import random
import hashlib

BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'

def Candidate():
"""
Generate a random, well-formed mini private key.
"""
return('%s%s' % ('S', ''.join(
[BASE58[ random.randrange(0,len(BASE58)) ] for i in range(21)])))

def GenerateKeys(numKeys = 10, additionalSecurity = False):
"""
Generate mini private keys and output the mini key as well as the full
private key. numKeys is The number of keys to generate, and
additionalSecurity controls whether to do 717 rounds of SHA256
"""
keysGenerated = 0
totalCandidates = 0
while keysGenerated < numKeys:
try:
cand = Candidate()
# Do typo check
t = '%s?' % cand
# Take one round of SHA256
candHash = hashlib.sha256(t).digest()
if additionalSecurity:
# Do the other 716 rounds for additional security
for i in range(716):
candHash = hashlib.sha256(candHash).digest()
# Check if the first eight bits of the hash are 0
if candHash[0] == '\x00':
privateKey = GetPrivateKey(cand)
print('\n%s\nSHA256( ): %s\nsha256(?): %s' %
(cand, privateKey, candHash.encode('hex_codec')))
if CheckShortKey(cand):
print('Validated.')
else:
print('Invalid!')
keysGenerated += 1
totalCandidates += 1
except KeyboardInterrupt:
break
print('\n%s: %i\n%s: %i\n%s: %r\n%s: %.1f' %
('Keys Generated', keysGenerated,
'Total Candidates', totalCandidates,
'Additional Security', additionalSecurity,
'Reject Percentage',
100*(1.0-keysGenerated/float(totalCandidates))))

def GetPrivateKey(shortKey):
"""
Returns the hexadecimal representation of the private key corresponding
to the given short key.
"""
if CheckShortKey(shortKey):
return hashlib.sha256(shortKey).hexdigest()
else:
print('Typo detected in private key!')
return None

def CheckShortKey(shortKey):
"""
Checks for typos in the short key.
"""
if len(shortKey) != 22:
return False
t = '%s?' % shortKey
tHash = hashlib.sha256(t).digest()
# Check to see that first byte is \x00
if tHash[0] == '\x00':
return True
else:
# Do an additional 716 rounds
for i in range(716):
tHash = hashlib.sha256(tHash).digest()
# Check again for \x00
if tHash[0] == '\x00':
return True
return False
</source>

Mini private key format

2011-09-08T18:24:10Z

Clark: Added Python code

The '''mini private key format''' is a method of encoding a Bitcoin private key in 22 characters so that it can be embedded in a small space. This private key format was first used in Casascius physical bitcoins, and is also favorable for use in QR codes. The fewer characters encoded in a QR code, the lower dot density can be used, as well as more dots allocated to error correcting codes, and hence a QR code that is easier for a machine to read. The mini private key format offers its own built-in check code as a small margin of protection against typos.

An example key using this encoding is '''S4b3N3oGqDqR5jNuxEvDwf'''.

The way it might appear within a physical bitcoin is on a round card printed as follows:

<center>S4b3N<br/>3oGqDq<br/>R5jNux<br/>EvDwf</center>

==Decoding==
The private key encoding consists of 22 alphanumeric characters from the [[base58]] alphabet used in Bitcoin. The first of the 22 characters is always the uppercase letter S.

To obtain the full 256-bit private key, simply take the SHA256 hash of the entire string. There is no encoding for breaks in the string even if printed that way - the SHA256 should be taken of exactly twenty-two bytes.

SHA256("S4b3N3oGqDqR5jNuxEvDwf") = 0C28FCA386C7A227600B2FE50B7CAE11EC86D3BF1FBE471BE89827E19D72AA1D

==Check code==
The check code is designed to be simple, but relatively computationally expensive so that it cannot be used to quickly reduce the key space in a brute force attack. It offers seven bits worth of error protection (or, in other words, in the event of a typo, the typo will be caught about 127 out of 128 times, or over 99%).

To determine whether a string passes the check code, follow these steps:
# Ensure it is well-formed (22 characters, base58 alphabet, starts with S).
# Add a question mark to the end of the string, and take the SHA256 of that. If the SHA256 starts with eight zero bits (hex 00), then the string passes the check code.
# If it does not, then with the same string (ending in a question mark), do 717 (seven hundred seventeen) rounds of SHA256 on the string. If the result after the 717th round starts with eight zero bits (hex 00), then the string passes the check code.
# If the results of SHA256 after both tests don't start with eight zero bits, then the check fails.

==Creating mini private keys==
Creating mini private keys is relatively simple. One program which can create such keys is [[Casascius Bitcoin Utility]].

Mini private keys must be created "from scratch", as the conversion from mini private key to full-size private key is one-way. In other words, there is no way to convert an existing full-size private key into a mini private key.

To create mini private keys, simply create random strings that satisfy the well-formedness requirement, and then eliminate the ones that do not pass the typo check. (This means eliminating more than 99% of the candidates.) Then use SHA256 to compute the corresponding private key, and in turn, the matching Bitcoin address. The Bitcoin address can always be computed from just the private key.

In all cases, you should use a secure cryptographic random number generator to eliminate risks of predictability of the random strings. Also, for stronger security, accept only the strings that pass the typo check on the 717th round rather than the first.

==Python Code==
<source lang="python">
import random
import hashlib

BASE58 = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'

def Candidate():
"""
Generate a random, well-formed mini private key.
"""
return('%s%s' % ('S', ''.join(
[BASE58[ random.randrange(0,len(BASE58)) ] for i in range(21)])))

def GenerateKeys(numKeys = 10, additionalSecurity = False):
"""
Generate mini private keys and output the mini key as well as the full
private key. numKeys is The number of keys to generate, and
additionalSecurity controls whether to do 717 rounds of SHA256
"""
keysGenerated = 0
totalCandidates = 0
while keysGenerated < numKeys:
try:
cand = Candidate()
# Do typo check
t = '%s?' % cand
# Take one round of SHA256
candHash = hashlib.sha256(t).digest()
if additionalSecurity:
# Do the other 716 rounds for additional security
for i in range(716):
candHash = hashlib.sha256(candHash).digest()
# Check if the first eight bits of the hash are 0
if candHash[0] == '\x00':
privateKey = GetPrivateKey(cand)
print('\n%s\nSHA256( ): %s\nsha256(?): %s' %
(cand, privateKey, candHash.encode('hex_codec')))
if CheckShortKey(cand):
print('Validated.')
else:
print('Invalid!')
keysGenerated += 1
totalCandidates += 1
except KeyboardInterrupt:
break
print('\n%s: %i\n%s: %i\n%s: %r\n%s: %.1f' %
('Keys Generated', keysGenerated,
'Total Candidates', totalCandidates,
'Additional Security', additionalSecurity,
'Reject Percentage',
100*(1.0-keysGenerated/float(totalCandidates))))

def GetPrivateKey(shortKey):
"""
Returns the hexadecimal representation of the private key corresponding
to the given short key.
"""
if CheckShortKey(shortKey):
return hashlib.sha256(shortKey).hexdigest()
else:
print('Typo detected in private key!')
return None

def CheckShortKey(shortKey):
"""
Checks for typos in the short key.
"""
t = '%s?' % shortKey
tHash = hashlib.sha256(t).digest()
# Check to see that first byte is \x00
if tHash[0] == '\x00':
return True
else:
# Do an additional 716 rounds
for i in range(716):
tHash = hashlib.sha256(tHash).digest()
# Check again for \x00
if tHash[0] == '\x00':
return True
return False
</source>

How bitcoin works

2011-09-08T16:30:36Z

Clark: Typo correction

This page explains the basic framework of Bitcoin's functionality.

==Cryptography==

There are several cryptographic technologies that make up the essence of Bitcoin.

First is [http://en.wikipedia.org/wiki/Public-key_cryptography public key cryptography]. Each coin is associated with its current owner's public [http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA] key. When you send some bitcoins to someone, you create a message ([[transaction]]), attaching the new owner's public key to this amount of coins, and sign it with your private key. When this transaction is broadcast to the bitcoin network, this lets everyone know that the new owner of these coins is the owner of the new key. Your signature on the message verifies for everyone that the message is authentic. The complete history of transactions is kept by everyone, so anyone can verify who is the current owner of any particular group of coins.

This complete record of transactions is kept in the [[block chain]], which is a sequence of records called [[block|blocks]]. All computers in the network have a copy of the block chain, which they keep updated by passing along new blocks to each other. Each block contains a group of transactions that have been sent since the previous block. In order to preserve the integrity of the block chain, each block in the chain confirms the integrity of the previous one, all the way back to the first one, the [[genesis block]]. Record insertion is costly because each block must meet certain requirements that make it [[difficulty|difficult]] to generate a valid block. This way, no party can overwrite previous records by just forking the chain.

Both the chaining, and the difficulty, are achieved via the [http://en.wikipedia.org/wiki/SHA-2 SHA256] [http://en.wikipedia.org/wiki/Cryptographic_hash_function cryptographic hash function]. The hash function essentially takes a block of data, and transforms it, in an effectively-impossible to reverse or to predict way, into a large integer. Making the slightest change to a block of data changes its hash unpredictably, so nobody can create a different block of data that gives exactly the same hash. Therefore, by being given a short hash, you can confirm that it matches only a particular long block of data. This way, Bitcoin blocks don't have to contain serial numbers, as blocks can be identified by their hash, which serves the dual purpose of identification as well as integrity verification.

The [[difficulty]] factor is achieved by requiring that this integer is below a certain threshold - the data in the block is perturbed by a [[nonce]] value, until the data in the block hashes to produce an integer below the threshold - which takes a lot of processing power. This low hash value for the block serves as an easily-verifiable [[proof of work]] - every node on the network can instantly verify that the block meets the required criteria.

With this framework, we are able to achieve the essential functions of the Bitcoin system. We have verifiable ownership of bitcoins, and a distributed database of all transactions, which prevents [[#Double_spending|double spending]].

==Bitcoin mining==

We have mentioned in the previous section that adding a block to the block chain is difficult, requiring time and processing power to accomplish. So what incentive does anyone have to spend the effort to produce a block, if it takes up all these resources? The answer is that the person who manages to produce a block gets a reward. This reward is two-fold. First, the block producer gets a bounty of some number of bitcoins, which is agreed-upon by the network. (Currently this bounty is 50 bitcoins; this value will halve every 210,000 blocks.) Second, any [[transaction fees]] that may be present in the transactions included in the block, get claimed by the block producer.

This gives rise to the activity known as "bitcoin mining" - using processing power to try to produce a valid block, and as a result 'mine' some bitcoins. The network rules are such that the [[difficulty]] is adjusted to keep block production to approximately 1 block per 10 minutes. Thus, the more miners engage in the mining activity, the more difficult it becomes for each individual miner to produce a block. The higher the total difficulty, the harder it is for an attacker to overwrite the tip of the block chain with his own blocks (which enables him to double-spend his coins. See the [[weaknesses]] page for more details).

Besides being important for maintaining the transaction database, mining is also the mechanism by which bitcoins get created and distributed among the people in the bitcoin economy. The network rules are such that over the next hundred years, give or take a few decades, a total of 21 million bitcoins will be created. Rather than dropping money out of a helicopter, the bitcoins are awarded to those who contribute to the network by creating [[block]]s in the [[block chain]].

For those who want to get into mining without much difficulty, click [http://www.iscyspace.com Here] for a free 10 step guide on iscyspace.

==Double spending==

The block chain which is constantly being generated by the Bitcoin network works as a common agreement about the order in which bitcoin transactions have taken place. Placing the transactions in a sequence is necessary so that things like the double-spending of coins and negative balances can be avoided. Simply announcing each transaction is not enough to establish the order of the transactions, because different computers may receive the announcement at different times.

Unlike conventional banking systems, there is no central place where this "log" of transactions is stored. What happens is the broadcasting of small pieces (the blocks), each stating that it is a continuation of a previous block. Thus, it is possible for many proposed continuations to the block chain to exist at the same time. There can also be multiple continuations to each of these continuations, forming many branches and sub-branches, like a tree. When this happens, each computer in the network must decide for itself which branch is the "correct" one that should be accepted and extended further.

The rule in this case is to accept the "longest" valid branch. Choose from the branches of blocks that you have received, the path, the total "difficulty" of which is the highest. This is the sequence of blocks that is assumed to have required the most work (CPU time) to generate. For Bitcoin, this will be the "true" order of events, and this is what it will take into account when calculating the balance to show to the user. "Valid" means that Bitcoin will reject branches which don't contain a strong enough [[proof of work]] or contain invalid transactions (i.e. calculating a wrong balance, giving more money than you have, generating more bitcoins than is allowed at the time, etc).

It is still possible that, as new blocks are constantly being generated, at some later time, some other branch will become the longest branch. However, it takes significant effort to extend a branch, and nodes work to extend the branch that they have received and accepted (which is normally the longest one). So, the longer this branch becomes compared to the second-longest branch, the more effort it will take for the second-longest branch to catch up and overcome the first in length. Also, the more nodes in the network hear about the longest branch, the more unlikely it becomes for other branches to be extended the next time a block is generated, since the nodes will accept the longest chain.

Therefore, the more time a transaction has been part of the longest block chain, the more likely it is to remain part of the chain indefinitely. This is what makes transactions non-reversible and this is what prevents people from double-spending their coins. What the receiver of each transaction does, after money has been supposedly transferred to him/her is to check how long the block chain following the said transaction has become, because the more blocks are added to the longest branch after the transaction, the less likely is it that some other branch will overcome it.

When the block chain after the transaction has become long enough, it becomes near-impossible for another branch to overcome it, and so people can start accepting the transaction as true. This is why 'blocks' also serve as 'confirmations' for a transaction. Even if another branch does overcome the one with the transaction, most of the blocks will have been generated by people who have no affiliation with the sender of the coins, as a large number of people are working to generate blocks. Since transactions are broadcasted to all nodes in the network, these blocks are just as likely to contain the transaction as the blocks in the previously-accepted branch.

Bitcoin relies on the fact that no single entity can control most of the CPU power on the network for any significant length of time, since, if they could, they would be able to extend any branch of the tree they chose, and faster than any other branch can be extended, making it the longest branch, and then permanently controlling which transactions appear in it.

==See also==

* [[Introduction]]
* [[Getting started]]
* [[Using Bitcoin]]
* Bitcoin [[FAQ]]

==External Links==

* http://www.bitcoin.org/smf/index.php?topic=2487.0 A forum thread with some good 'for-the-layperson' explanations of how bitcoin works.

[[Category:Introduction]]

Scalability

2011-09-06T15:28:41Z

Clark: Typo correction

The core BitCoin network can scale to very high [[transactions|transaction]] rates assuming a distributed version of the node software is built. This would not be very complicated.

==Note to readers==

If you're coming here because of Dan Kaminsky's criticisms related to this page, you can find a discussion of his points on the [[Talk:Scalability]] page.

==Scalability targets==

VISA handles on average around 2,000 transactions/sec, so call it a daily peak rate of 4,000/sec. They have burst capacity for over 10,000 transactions per second which they need to handle the busiest points of the holiday period (~8,500tps). [http://investor.visa.com/phoenix.zhtml?c=215693&p=irol-newsArticle_print&ID=1355716]

PayPal, in contrast, handles around 4 million transactions per day for an average of 46tps or a probably peak rate of 100tps.

Let's take 4,000 tps as starting goal. Obviously if we want BitCoin to scale to all economic transactions worldwide, including cash, it'd be a lot higher than that, perhaps more in the region of a few hundred thousand transactions/sec. And the need to be able to withstand DoS attacks (which VISA does not have to deal with) implies we would want to scale far beyond the standard peak rates. Still, picking a target let us do some basic calculations even if it's a little arbitrary.

==Current bottlenecks==

Today the BitCoin network is restricted to a sustained rate of 7 tps by some artificial limits. These were put in place to stop people from ballooning the size of the block chain before the network and community was ready for it. Once those limits are lifted, the maximum transaction rate will go up significantly.

==CPU==

The protocol has two parts. Nodes send "inv" messages to other nodes telling them they have a new transaction. If the receiving node doesn't have that transaction it requests it with a getdata.

The big cost is the crypto and block chain lookups involved with verifying the transaction. An ECDSA verification of a transaction input takes around 3msec on a modern Intel core. RIPEMD-160 runs at 106 megabytes/sec (call it 100 for simplicity) and SHA256 is about the same. So hashing 1 megabyte should take around 10 milliseconds and hashing 1 kilobyte would take 0.01 milliseconds, ie it's dwarfed by the cost of the ECDSA and thus can be ignored.

So the slowest part of verifying a transaction is verifying its inputs, which is ~3 msec per input on todays hardware. It seems like in the current blockchain most transactions have only one input, and a few have more like 5/6 inputs. Let's call it an average of 2 inputs overall. However each transaction input is verified twice: once when first received, and a second time when a block containing that transaction is received, so call it 12msec in total per transaction.

This means a single core today can probably, with tuning and the block chain held in RAM but no special hardware beyond that, verify and accept about 80 transactions/sec. This means a network node capable of keeping up with VISA would need roughly 50 cores + whatever is used for mining (done by separate machines/GPUs). Whilst building a single machine with 50 cores would be kind of a pain load balancing inbound "tx" messages over multiple machines would be very easy. Certainly a single machine could easily load balance all of VISAs transactions to a small group of verification machines which would then send the verified tx hash to the miners for incorporation into the merkle tree.

For receiving and handling all the "tx" messages, you therefore could build a rack of 12 4-core machines that would keep up.

That leaves the inbound inv messages. The cost of handling an inv is basically reading a small message from the network and then doing a RAM lookup to see if we already have the transaction. This is really, really fast. A single core could easily handle several thousand inv messages per second before breaking a sweat, even assuming it needs to read from a sharded in-memory block chain index.

==Network==

Let's assume an average rate of 2000tps, so just VISA. Transactions vary in size from about 0.2 kilobytes to over 1 kilobyte, but from looking at the block explorer it's probably averaging half a kilobyte today. So let's assume the way people use BitCoin gets more complicated and call it 1kb per transaction.

A solved block will then be around (1024 bytes * 2000tps * 60 seconds in a minute * 10minutes) / 1024 bytes in a kilobyte / 1024 kilobytes in a megabyte / 1024 megabytes in a gigabyte = 1.14 gigabytes per block.

But you only have to transmit a solved block to your connected peers. If we assume these big futuristic supernodes have something like 40 or 50 peered connections, that means in the worst case scenario where you solve a block OR you receive a block but none of your peers have it yet (unlikely), you have to send ~57 gigabytes of data (call it 60).

Shifting 60 gigabytes of data in, say, 60 seconds means an average rate of 1 gigabyte per second, or 8 gigabits per second.

The real question you want to know is how much does that sort of bandwidth cost? Well, bandwidth prices are a very tricky thing as some of the largest consumers pay the least due to how peering agreements work. The Googles and Akamais of this world will pay way less for a 10G wave than a small operator would. And, you wouldn't be hitting the 8Gbps very frequently .... only when you solve a block, really, as when relaying a block the peers you connect to will likely have already received it from some other peer anyway so only a subset would need to receive it from you.

Luckily, a node would very likely not have to transfer this much data this quickly. Assuming all nodes are equally well connected to other nodes with the same number of connections, each node would only have to send one copy of each block received, on average. Even if you are the first node to become aware of a block, once you send the block to 3 or 4 others, it would propagate among the others in exponentially growing numbers, similar to the bit-torrent protocol.

Take a look at [http://icecolo.com/colocation-packages] to get a feel for data transfer costs.

==Storage==

At very high transaction rates each block can be over a gigabyte in size. These blocks must be stored somewhere. Whilst for speed it'd be ideal to store the block chain entirely in RAM, for cheapness storing only the hot parts in RAM and the rest on disk is the way to go. A 3 terabyte hard disk costs less than $200 today and will be cheaper still in future, so you'd need one such disk for every 21 days of operation (at 1gb per block).

==Network structure==

Today BitCoin is a flat peer to peer network in which all nodes are equal. However the intention is to evolve it towards a more typical two-tier structure in which low powered client nodes connect to long-lived, high powered supernodes. The protocol already has some support for this (see the services flags in the version/address messages). However client mode is only partially implemented and no code exists to decide if and when to switch between supernode/client node status.

As the network scales up, the costs of running a supernode that stores the full block chain and verifies every transaction will get progressively higher, but the two tier structure ensures everyone can still get started quickly. Client nodes only need to download a small number of headers the first time they connect (from their last checkpoint until the chain head). It's quite possible to run such nodes on a modern smartphone. The security model for lightweight clients is slightly different to a full node: whilst they don't need to talk to a trusted node (ie any network node will do), in that configuration it's important that the network be very difficult to attack as the block contents are not verified.

==Optimizations==

The description above applies to the current software. However several optimizations exist that can dramatically cheapen the cost of running a node and these are fairly easy to implement.

===CPU===

The CPU cost of a transaction is doubled by the fact that the current software verifies each input twice. There's no need for this. Once a transaction is received the fact that it passed verification can be stored, and when it re-appears in a block the second verification can be skipped. This would roughly double per-core capacity, ie you would need only 25 cores to verify VISA-level traffic loads. This can actually fit into a single high-end server.

===Storage===

The storage costs of the block chain calculated above assume transactions are never deleted. Satoshi's paper explains how transactions with fully spent outputs can be pruned from long term storage due to how they are arranged in a Merkle tree. Nodes try to avoid accumulating lots of small unspent outputs as that means to send a reasonable quantity of coins would require transactions with lots of inputs and thus, be large and perhaps requiring a fee. Because nodes fight fragmentation, as time goes by it's likely that many blocks can be completely pruned of all or nearly all transactions, reducing their storage costs in the best case down to 80 bytes. As of May, 2011, the software does not implement pruning, and the potential savings are [http://forum.bitcoin.org/index.php?topic=9461.msg137059#msg137059 calculated] at 71% of transactions or 73% of raw block bytes.

===Bandwidth===

The network costs of distributing blocks can be minimized by changing the protocol to send blocks as a header plus a list of hashes. Because nodes are very likely to have already seen a transaction when it was first broadcast, this means the size of a block to download would be trivial (80 bytes + 32 bytes per transaction). If a node didn't see a transaction broadcast, it can ask the connected node to provide it.

===Network structure===

The peer-finding mechanism today relies on IRC. Switching to DNS would give dramatically faster startup times that do not scale with the size of the network. NOTE: This is done in 0.3.24

===Simplified payment verification===

It's possible to build a Bitcoin implementation that does not verify everything, but instead relies on either connecting to a trusted node, or puts its faith in high difficulty as a proxy for proof of validity. [[BitCoinJ]] is an implementation of this mode.

In SPV mode, named after the section of Satoshis paper that describes it, clients connect to an arbitrary full node and download only the block headers. They verify the chain headers connect together correctly and that the difficulty is high enough. They then request transactions matching particular patterns from the remote node (ie, payments to your addresses), which provides copies of those transactions along with a Merkle branch linking them to the block in which they appeared. This exploits the Merkle tree structure to allow proof of inclusion without needing the full contents of the block. The pattern matching protocol message isn't implemented yet, [http://forum.bitcoin.org/index.php?topic=7972.msg116285#msg116285 a proposal] was discussed in May 2011.

As a further optimization, block headers that are buried sufficiently deep can be thrown away after some time (eg, you only really need to store say 1000 blocks).

The level of difficulty required to obtain confidence the remote node is not feeding you fictional transactions depends on your threat model. If you are connecting to a node that is known to be reliable, the difficulty doesn't matter. If you want to pick a random node, the cost for an attacker to mine a block sequence containing a bogus transaction should be higher than the value to be obtained by defrauding you. By changing how deeply buried the block must be, you can trade off confirmation time vs cost of an attack.

Programs implementing this approach can have fixed storage/network overhead in the null case of no usage, and resource usage proportional to received/sent transactions.

[[Category:Technical]]

User:Clark

2011-07-23T16:02:42Z

Clark: Created page with "I am the creator of the Real Time Bitcoin Market Data services."

I am the creator of the [[Real Time Bitcoin Market Data]] services.