Bitcoin Wiki - User contributions [en]

User:Neofutur

2017-11-30T03:11:21Z

Neofutur:

see

* '''my services :''' http://ww7.pe

* '''my otc reputation :''' http://bitcoin-otc.com/viewratingdetail.php?nick=ne0futur

* '''my gpg key :''' http://pgp.cs.uu.nl/stats/690B4E07.html and http://webware.lysator.liu.se/jc/wotsap/wots/latest/keystatistics/0x690B4E07.txt

* '''my linkedin :''' https://www.linkedin.com/in/neofutur/

Genesis block

2017-11-30T03:09:31Z

Neofutur: /* Coinbase */ topic "second bailout for banks"

A '''genesis block''' is the first block of a [[block chain]]. Modern versions of Bitcoin number it as '''block 0''', though very early versions counted it as block 1. The genesis block is almost always hardcoded into the software of the applications that utilize its block chain. It is a special case in that it does not reference a previous block, and for [[Bitcoin]] and almost all of its derivatives, it produces an unspendable subsidy.

== Main network genesis block ==
Here is a representation of the genesis block<ref name="block">{{cite block|hash=000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f|0|year=2009|month=01|day=03}}</ref> as it appeared in a comment in an old version of Bitcoin ([http://sourceforge.net/p/bitcoin/code/133/tree/trunk/main.cpp#l1613 line 1613]). The first section defines exactly all of the variables necessary to recreate the block. The second section is the block in standard printblock format, which contains shortened versions of the data in the first section.

GetHash() = 0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f
hashMerkleRoot = 0x4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b
txNew.vin[0].scriptSig = 486604799 4 0x736B6E616220726F662074756F6C69616220646E6F63657320666F206B6E697262206E6F20726F6C6C65636E61684320393030322F6E614A2F33302073656D695420656854
txNew.vout[0].nValue = 5000000000
txNew.vout[0].scriptPubKey = 0x5F1DF16B2B704C8A578D0BBAF74D385CDE12C11EE50455F3C438EF4C3FBCF649B6DE611FEAE06279A60939E028A8D65C10B73071A6F16719274855FEB0FD8A6704 OP_CHECKSIG
block.nVersion = 1
block.nTime = 1231006505
block.nBits = 0x1d00ffff
block.nNonce = 2083236893

CBlock(hash=000000000019d6, ver=1, hashPrevBlock=00000000000000, hashMerkleRoot=4a5e1e, nTime=1231006505, nBits=1d00ffff, nNonce=2083236893, vtx=1)
CTransaction(hash=4a5e1e, ver=1, vin.size=1, vout.size=1, nLockTime=0)
CTxIn(COutPoint(000000, -1), coinbase 04ffff001d0104455468652054696d65732030332f4a616e2f32303039204368616e63656c6c6f72206f6e206272696e6b206f66207365636f6e64206261696c6f757420666f722062616e6b73)
CTxOut(nValue=50.00000000, scriptPubKey=0x5F1DF16B2B704C8A578D0B)
vMerkleTree: 4a5e1e
===Hash===
The hash of the genesis block, '''000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f''',<ref name="block"/> has two more leading hex zeroes than were required for an early block.

===Coinbase===
[[File:jonny1000thetimes.png|thumb|256px|The Times 03/Jan/2009]]
The [[coinbase]] parameter (seen above in hex) contains, along with the normal data, the following text:<ref>[http://web.archive.org/web/20140309004338/http://uk.reuters.com/article/2009/01/03/idUKPTIP32510920090103 Reuters' reference on The Financial Times article (archive.org cached copy)]</ref>

<blockquote>The Times 03/Jan/2009 Chancellor on brink of second bailout for banks<ref name="block"/></blockquote>

This was probably intended as proof that the block was created on or after January 3, 2009, as well as a comment on the instability caused by fractional-reserve banking. Additionally, it suggests that [[Satoshi Nakamoto]] may have lived in the United Kingdom.<ref>{{cite web|author=Davis, J.|year=2011|title=The Crypto-Currency|publisher=''The New Yorker''|url=http://www.newyorker.com/magazine/2011/10/10/the-crypto-currency}}</ref>

This detail, "second bailout for banks" could also suggest that the fact a supposedly liberal and capitalist system, rescuing banks like that, was a problem for satoshi . . . the choosen topic could have a meaning about bitcoin s purpose . . .

===Block reward===
The first 50 BTC block reward went to [[address]] ''1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa'',<ref name="block"/> though this reward can't be spent due to a quirk in the way that the genesis block is expressed in the code. It is not known if this was done intentionally or accidentally.<ref>http://bitcoin.stackexchange.com/questions/10009/why-can-t-the-genesis-block-coinbase-be-spent</ref><ref>https://www.reddit.com/r/Bitcoin/comments/1nc13r/the_first_50btc_block_reward_cant_be_spend_why/</ref><ref>https://github.com/bitcoin/bitcoin/blob/9546a977d354b2ec6cd8455538e68fe4ba343a44/src/main.cpp#L1668 - Genesis block transaction treated as a special case in the reference code</ref> It is believed that other outputs sent to this address are spendable, but it is unknown if Satoshi Nakamoto has the private key for this particular address, if one existed at all.

===Timestamp===
Although the average time between Bitcoin blocks is 10 minutes, the timestamp of the next block is a full 6 days after the genesis block. One interpretation is that Satoshi was working on bitcoin for some time beforehand and the ''The Times'' front page prompted him to release it to the public. He then mined the genesis block with a timestamp in the past to match the headline. It is also possible that, since the block's hash is so low, he may have spent 6 days mining it with the same timestamp before proceeding to block 1. The [[prenet hypothesis]] suggests that the genesis block was solved on January 3, but the software was tested by Satoshi Nakamoto using that genesis block until January 9, when all the test blocks were deleted and the genesis block was reused for the main network.

===Raw block data===

The [https://bitcointalk.org/index.php?topic=52706 raw hex version] of the Genesis block looks like:
00000000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000020 00 00 00 00 3B A3 ED FD 7A 7B 12 B2 7A C7 2C 3E ....;£íýz{.²zÇ,>
00000030 67 76 8F 61 7F C8 1B C3 88 8A 51 32 3A 9F B8 AA gv.a.È.ÃˆŠQ2:Ÿ¸ª
00000040 4B 1E 5E 4A 29 AB 5F 49 FF FF 00 1D 1D AC 2B 7C K.^J)«_Iÿÿ...¬+|
00000050 01 01 00 00 00 01 00 00 00 00 00 00 00 00 00 00 ................
00000060 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000070 00 00 00 00 00 00 FF FF FF FF 4D 04 FF FF 00 1D ......ÿÿÿÿM.ÿÿ..
00000080 01 04 45 54 68 65 20 54 69 6D 65 73 20 30 33 2F ..EThe Times 03/
00000090 4A 61 6E 2F 32 30 30 39 20 43 68 61 6E 63 65 6C Jan/2009 Chancel
000000A0 6C 6F 72 20 6F 6E 20 62 72 69 6E 6B 20 6F 66 20 lor on brink of
000000B0 73 65 63 6F 6E 64 20 62 61 69 6C 6F 75 74 20 66 second bailout f
000000C0 6F 72 20 62 61 6E 6B 73 FF FF FF FF 01 00 F2 05 or banksÿÿÿÿ..ò.
000000D0 2A 01 00 00 00 43 41 04 67 8A FD B0 FE 55 48 27 *....CA.gŠý°þUH'
000000E0 19 67 F1 A6 71 30 B7 10 5C D6 A8 28 E0 39 09 A6 .gñ¦q0·.\Ö¨(à9.¦
000000F0 79 62 E0 EA 1F 61 DE B6 49 F6 BC 3F 4C EF 38 C4 ybàê.aÞ¶Iö¼?Lï8Ä
00000100 F3 55 04 E5 1E C1 12 DE 5C 38 4D F7 BA 0B 8D 57 óU.å.Á.Þ\8M÷º..W
00000110 8A 4C 70 2B 6B F1 1D 5F AC 00 00 00 00 ŠLp+kñ._¬....

Broken down it looks like this:

01000000 - version
0000000000000000000000000000000000000000000000000000000000000000 - prev block
3BA3EDFD7A7B12B27AC72C3E67768F617FC81BC3888A51323A9FB8AA4B1E5E4A - merkle root
29AB5F49 - timestamp
FFFF001D - bits
1DAC2B7C - nonce
01 - number of transactions
01000000 - version
01 - input
0000000000000000000000000000000000000000000000000000000000000000FFFFFFFF - prev output
4D - script length
04FFFF001D0104455468652054696D65732030332F4A616E2F32303039204368616E63656C6C6F72206F6E206272696E6B206F66207365636F6E64206261696C6F757420666F722062616E6B73 - scriptsig
FFFFFFFF - sequence
01 - outputs
00F2052A01000000 - 50 BTC
43 - pk_script length
4104678AFDB0FE5548271967F1A67130B7105CD6A828E03909A67962E0EA1F61DEB649F6BC3F4CEF38C4F35504E51EC112DE5C384DF7BA0B8D578A4C702B6BF11D5FAC - pk_script
00000000 - lock time
==References==
<references/>

[[zh-cn:创世block]]
[[es:Bloque Génesis]]
__NOTOC__

[[Category:Technical]]

Template:MainPage Topics

2013-06-12T14:20:57Z

Neofutur:

{|cellpadding="2" style="background-color: inherit;"
|-
| scope="col" style="width: 200px;" |
* [[Introduction]]
* [http://www.weusecoins.com/getting-started.php Getting started]
* [[Myths]]
* [http://bitcoin.gw.gd/-Bitcoin-News- News]

* [[Securing your wallet]]
| scope="col" style="width: 200px;" |
* [[PHP developer intro]]
* [[API reference (JSON-RPC)]]
* [[Protocol specification]]
* [[Secure Trading|Best practices for traders]]
* [[Bitcoin Improvement Proposals]]
|}

{|cellpadding="2" style="background-color: inherit;"
|-
! scope="col" style="width: 200px;" |
! scope="col" style="width: 200px;" |
|-
|
* [[Software]]
* [[Mining]]
* [[:Category:Exchanges|Exchanges]]
* [[:Category:Directories|Local Directories]]
* [[:Category:Marketing|Marketing resources]]
* [[People]]
|
* [[:Category:Technical|Technical articles]]
* [[:Category:Clients|Clients]] / [[:Category:Frontends|Frontends]]
* [[:Category:Economics|Economics]]
* [[Trade|Businesses (Trade)]]
* [[:Category:Games|Games]]
* [[Real world shops|Real world merchants map]]
* [[Donation-accepting_organizations_and_projects|Donation-accepting sites]]
* [[Meetups]]
|}

<div style="text-align: right;" class="noprint"><span class="plainlinks">[{{fullurl:Template:MainPage_Topics|action=edit}} '''Edit''']</span> – '''[[Special:Categories|See More]]'''</div>

Main Page

2013-06-12T12:05:55Z

Neofutur:

{| id="mp-topbanner" style="width:100%; background:#f6f6f6; margin-top:1.2em; border:1px solid #ddd;"
| style="width:61%; color:#000;" |

{| style="width:100%; border:none; background:none;"
| style="text-align:center; white-space:nowrap; color:#000;" |
<div style="font-size:162%; border:none; margin:0; padding:.1em; color:#000;">Welcome to the [[Bitcoin]] wiki,</div>
<div style="top:+0.2em; font-size:95%;">For all your Bitcoin information needs.</div>
<div id="articlecount" style="width:100%; text-align:center; font-size:85%;">[[Special:Statistics|{{NUMBEROFARTICLES}}]] articles. Anti-spam protection from [[BitcoinPayment]]</div>
'''[[:Category:Stubs|This wiki]] is maintained by the Bitcoin community.'''
|}

| style="width:13%; font-size:120%;" |
* <span class="plainlinks">[http://bitcoin.org Frontpage]</span>
| style="width:13%; font-size:120%;" |
* <span class="plainlinks">[[Forums]]</span>
| style="width:13%; font-size:120%; padding-right: 40px;" |
* <span class="plainlinks">[[IRC channels|Chatrooms]]</span>
|}


{| id="mp-upper" style="width: 100%; margin:6px 0 0 0; background:none; border-spacing: 0px;"
| class="MainPageBG" style="width:55%; border:1px solid #cef2e0; background:#f6e5f1; vertical-align:top; color:#000;" |
{| id="mp-left" style="vertical-align:top; background:#f6e5f1;"
! style="padding:2px;" | <h2 id="mp-tfa-h2" style="margin:3px; background:#e9caef; font-size:120%; font-weight:bold; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em;">Bitcoin</h2>
|-
| style="color:#000;" | <div id="mp-tfa" style="padding:2px 5px">{{MainPage_Intro}}</div>
|-
! style="padding:2px" | <h2 id="mp-dyk-h2" style="margin:3px; background:#e9caef; font-size:120%; font-weight:bold; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em;">Why</h2>
|-
| style="color:#000;padding:2px 5px 5px" | <div id="mp-dyk">{{MainPage_Reasons}}</div>
|}
| style="border:1px solid transparent;" |

| class="MainPageBG" style="width:45%; border:1px solid #cedff2; background:#f6e5f1; vertical-align:top;"|
{| id="mp-right" style="width:100%; vertical-align:top; background:#f6e5f1;"
! style="padding:2px" | <h2 id="mp-otd-h2" style="margin:3px; background:#efc1e2; font-size:120%; font-weight:bold; border:1px solid #a3b0bf; text-align:left; color:#000; padding:0.2em 0.4em;">Topic central</h2>
|-
| style="color:#000;padding:2px 5px 5px" | <div id="mp-otd">{{MainPage_Topics}}</div>
|-
! style="padding:2px" | <h2 id="mp-otd-h2" style="margin:3px; background:#efc1e2; font-size:120%; font-weight:bold; border:1px solid #a3b0bf; text-align:left; color:#000; padding:0.2em 0.4em;">FAQ</h2>
|-
| style="color:#000;padding:2px 5px 5px" | <div id="mp-otd">{{MainPage_FAQ}}</div>
|}
|}

== Other pages ==

* '''[[mw:Help:Formatting|Help]]''' - Documentation on wiki editing.
* '''[[Bitcoin.it Wiki|About]]''' - Information on this site.
* '''[http://dump.bitcoin.it/ Dumps]''' Backup this wiki.
[[de:Hauptseite]]
[[es:Página Principal]]
[[fr:Accueil]]
[[it:Pagina principale]]
[[pl:Strona główna]]
[[ru:Заглавная страница]]
[[zh-cn:首页]]
[[ro:Pagina principală]]

__NOTOC____NOEDITSECTION__

User:Neofutur

2013-06-07T14:50:26Z

Neofutur:

see

* '''my services :''' http://gw.gd/bcservices

* '''my otc reputation :''' http://bitcoin-otc.com/viewratingdetail.php?nick=ne0futur

* '''my gpg key :''' http://pgp.cs.uu.nl/stats/690B4E07.html and http://webware.lysator.liu.se/jc/wotsap/wots/latest/keystatistics/0x690B4E07.txt

* '''my news services :''' http://bitcoin.gw.gd/

User:Neofutur

2013-06-07T14:49:07Z

Neofutur:

see

my services : http://gw.gd/bcservices

my otc reputation : http://bitcoin-otc.com/viewratingdetail.php?nick=ne0futur

my gpg key : http://pgp.cs.uu.nl/stats/690B4E07.html and http://webware.lysator.liu.se/jc/wotsap/wots/latest/keystatistics/0x690B4E07.txt

my news services : http://bitcoin.gw.gd/

User:Neofutur

2013-06-07T14:48:24Z

Neofutur:

see

my services : http://gw.gd/bcservices
my otc reputation : http://bitcoin-otc.com/viewratingdetail.php?nick=ne0futur
my gpg key : http://pgp.cs.uu.nl/stats/690B4E07.html and http://webware.lysator.liu.se/jc/wotsap/wots/latest/keystatistics/0x690B4E07.txt
my news services : http://bitcoin.gw.gd/

MtGox/API/HTTP/v1

2013-05-30T20:32:17Z

Neofutur: /* App activation */

MtGox/API/HTTP/v1

2013-05-26T00:20:53Z

Neofutur:

MtGox/API/HTTP/v2

2013-05-26T00:18:19Z

Neofutur: /* Differences between v1 and v2: */

== API Version 2: ==
The V2 API URL is:

'''https://data.mtgox.com/api/2/'''

=== Documentation ===
'''Unofficial''' documentation (So far the best we have) is provided at : https://bitbucket.org/nitrous/mtgox-api/overview (The bitcointalk forum link is: https://bitcointalk.org/index.php?topic=164404.0 )

'''Official''' docs are on: https://github.com/MtGox/mtgox-doc

===== Differences between v1 and v2: =====

* The '''URL''' is now something along the lines of BTCUSD/money/order/add instead of BTCUSD/private/order/add in api1. All current known methods are found in the money category.
* The ''requested path'' must now be included when you compute your '''hashed signature (Rest-Sign)''' for added security.<br><br> In version 1, Rest-Sign is created through base64-encoding the 256-digest HMAC hashing of your post data (which of course must include your nonce) with your API secret, previously base64 decoded. Now in version 2, you must simply add ''before'' your post data the relative path you are requesting (anything after the /api/2/ base, ie: BTCUSD/money/ticker), concatenated with a NUL character (ASCII code 0). So the signature is now made starting from your relative path + NUL character + post data (which must include your nonce!).

* fast ticker
http://data.mtgox.com/api/2/BTCUSD/money/ticker_fast

and

http://data.mtgox.com/api/2/BTCUSD/money/ticker_fast?pretty

=== Explanation of Methods ===
'''BTCUSD/money/order/quote''' <br>
<@MagicalTux> it estimate the result of running an order at a given price based on market depth<br>
'''BTCUSD/money/ticker_fast'''<br>
Solves the problem of ticker lag. (supposedly)<br>

=== Code Examples: ===

====Java:====

https://github.com/adv0r/mtgox-api-v2-java Java lib for API V2, under development

====C# :====

https://bitbucket.org/pipe2grep/cryptocoinxchange C# lib for V2 API and socketIO

====Python v 2.7.3====

http://pastebin.com/aXQfULyq - Remove any proprietary unlock_api_key stuff. You'll need [https://github.com/genbtc/trader.python/blob/master/lib/json_ascii.py json_ascii] also. Works on API 0/1/2. Link to git-repo: [https://github.com/genbtc/trader.python/ genbtc's trader.python] <br>

====Perl====
https://en.bitcoin.it/wiki/MtGox/API/HTTP#PHP The Perl example on the main page is compatible with v2

MtGox/API

2013-05-20T21:03:15Z

Neofutur: /* Number Formats */

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

Two APIs are currently available:

* [[MtGox/API/HTTP|HTTP API]]
* [[MtGox/API/Streaming|Streaming websocket API]]

__TOC__

==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 (100,000,000) || 0.00000001
|-
| USD, AUD, CAD, CHF, CNY, DKK, EUR, GBP, HKD, NZD, PLN, RUB, SGD, THB, NOK, CZK (price) || 1E5 (100,000) || 0.00001
|-
| JPY, SEK (price) || 1E3 (1,000) || 0.001
|}

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

== Currency Symbols ==
List of the currency symbols available with the API:

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

==Date and time==

Most dates you will find in mtgox API are UNIX time

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

Most programming languages should have tools for managing those timestamps

==See Also==

* [http://bitcointalk.org/index.php?topic=164404.0 MtGox API version 2: Unofficial Documentation]

MtGox/API

2013-05-20T20:34:15Z

Neofutur: /* Number Formats */

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

Two APIs are currently available:

* [[MtGox/API/HTTP|HTTP API]]
* [[MtGox/API/Streaming|Streaming websocket API]]

__TOC__

==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 (100,000,000) || 0.00000001
|-
| USD, AUD, CAD, CHF, CNY, DKK, EUR, GBP, HKD, NZD, PLN, RUB, SEK, SGD, THB, NOK, CZK (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, NOK, CZK

==Date and time==

Most dates you will find in mtgox API are UNIX time

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

Most programming languages should have tools for managing those timestamps

==See Also==

* [http://bitcointalk.org/index.php?topic=164404.0 MtGox API version 2: Unofficial Documentation]

Block

2013-05-19T13:46:56Z

Neofutur:

Data is permanently recorded in the Bitcoin network through files called '''blocks'''. A block is a record of some or all of the most recent Bitcoin transactions that have not yet been recorded in any prior blocks. They could be thought of like the individual pages of a city recorder's recordbook (where changes to title to real estate are recorded) or a stock transaction ledger. In all but a few exceptional cases, new blocks are added to the end of the record (known in Bitcoin as the [[block chain]]), and once written, are never changed or removed. Each block memorializes what took place immediately before it was created.
===Block structure===
{| class="wikitable"
|-
! Field
! Description
! Size
|-
|Magic no
|value always 0xD9B4BEF9
|4 bytes
|-
|Blocksize
|number of bytes following up to end of block
|4 bytes
|-
|Blockheader
|[[Block hashing algorithm| consists of 6 items]]
|80 bytes
|-
|Transaction counter
| positive integer [[ Protocol_specification#Variable_length_integer|VI = VarInt]]
| 1 - 9 bytes
|-
|[[transactions]]
|the (non empty) list of transactions
|<Transaction counter>-many transactions
|}
==Description==
Each block contains, among other things, in its block header a record of some or all recent [[transactions]], and a reference to the block that came immediately before it. It also contains an answer to a difficult-to-solve mathematical puzzle - the answer to which is unique to each block. New blocks can't be submitted to the network without the correct answer - the process of "[[Mining]]" is essentially the process of competing to be the next to find the answer that "solves" the current block. The mathematical problem in each block is difficult to solve, but once a valid solution is found, it is very easy for the rest of the network to confirm that the solution is correct. There are multiple valid solutions for any given block - only one of the solutions needs to be found for the block to be solved.

Because there is a reward of brand new Bitcoins for solving each block, every block also contains a record of which [[Bitcoin address]] is entitled to receive the reward. This record is known as a generation transaction, or a [[coinbase]] transaction, and is always the first transaction appearing in every block. The number of [[Bitcoins]] generated per block starts at 50 and is halved every 210,000 blocks (about four years).

Bitcoin transactions are [[transaction broadcasting|broadcast]] to the [[network]] by the sender, and all peers trying to solve blocks collect the transaction records and add them to the block they're working to solve.

The difficulty of the mathematical problem is automatically adjusted by the network, such that it targets a goal of solving an average of 6 blocks per hour. Every 2016 blocks (about two weeks), all Bitcoin clients compare the actual number created with this goal and modify the target by the percentage that it varied. This increases (or decreases) the difficulty of generating blocks.

Because each block contains a reference to the prior block, the collection of all blocks in existence can be said to form a chain. However, it's possible for the chain to have temporary splits - for example, if two miners arrive at two different valid solutions for the same block at the same time, unbeknownst to one another. The peer-to-peer network is designed to resolve these splits within a short period of time, so that only one branch of the chain survives.

The client accepts the 'longest' chain of blocks as valid. The 'length' of the entire [[block chain]] refers to the chain with the most combined difficulty, not the one with the most blocks. This prevents someone from forking the chain and creating a large number of low-difficulty blocks, and having it accepted by the network as 'longest'.

== Common Questions about Blocks ==

=== How many blocks are there? ===
[http://blockexplorer.com/q/getblockcount Current block count]

=== What is the maximum number of blocks? ===
There is no maximum number, blocks just keep getting added to the end of the chain at an average rate of one every 10 minutes.

==== Even when all 21 million coins have been generated? ====
Yes. The blocks are for proving that transactions existed at a particular time. Transactions will still occur once all the coins have been generated, so blocks will still be created as long as people are trading Bitcoins.

=== How long will it take me to generate a block? ===
No-one can say exactly. There is a [[Generation Calculator|generation calculator]] that will tell you how long it '''might''' take.

=== What if I'm 1% towards calculating a block and...? ===
There's no such thing as being 1% towards solving a block. You don't make progress towards solving it. After working on it for 24 hours, your chances of solving it are equal to what your chances were at the start or at any moment. Believing otherwise is what's known as the Gambler's fallacy [http://en.wikipedia.org/wiki/Gambler's_fallacy].

It's like trying to flip 53 coins at once and have them all come up heads. Each time you try, your chances of success are the same.

=== Where can I find more technical detail? ===
There is more technical detail on the [[block hashing algorithm]] page.

==See Also==

[https://bitcointalk.org/index.php?topic=101514.0 Format of the BDB-style block files]
* [http://en.bitcoin.it/wiki/File:Total_bitcoins_over_time_graph.png Total Bitcoins Over Time]

[[Category:Technical]]
[[Category:Vocabulary]]

[[fr:Blocs]][[pl:Bloki]][[zh-cn:Block]]
[[de:Block]]

Transaction

2013-05-19T13:45:04Z

Neofutur:

[[File:TxBinaryMap.png|thumb|right|Byte-map of Transaction with each type of TxIn and TxOut]]
A transaction is a signed section of data that is broadcast to the [[network]] and collected into [[block|blocks]]. It typically references previous transaction(s) and dedicates a certain number of bitcoins from it to one or more new public key(s) (Bitcoin address). It is not encrypted (nothing in Bitcoin is encrypted).

A [[block chain browser]] is a site where every transaction included within the block chain can be viewed. This is useful for seeing the technical details of transaction in action, and for payment verification purposes.

=== general format of a Bitcoin transaction (inside a block) ===
{| class="wikitable"
|-
! Field
! Description
! Size
|-
|Version no
|currently 1
|4 bytes
|-
|In-counter
| positive integer [[ Protocol_specification#Variable_length_integer|VI = VarInt]]
| 1 - 9 bytes
|-
|list of inputs
|[[Transactions#general_format_.28inside_a_block.29_of_each_input_of_a_transaction_-_Txin|the first input of the first transaction is also called "coinbase" (its content was ignored in earlier versions)]]
|<in-counter>-many inputs
|-
|Out-counter
| positive integer [[ Protocol_specification#Variable_length_integer|VI = VarInt]]
| 1 - 9 bytes
|-
|list of outputs
|[[Transactions#general_format_.28inside_a_block.29_of_each_output_of_a_transaction_-_Txout|the outputs of the first transaction spend the mined bitcoins for the block]]
|<out-counter>-many outputs
|-
|lock_time
|if non-zero and sequence numbers are < 0xFFFFFFFF: block height or timestamp when transaction is final
|4 bytes
|}

=== Principle example of a Bitcoin transaction with 1 input and 1 output only ===

==== Data ====

<pre>Input:
Previous tx: f5d8ee39a430901c91a5917b9f2dc19d6d1a0e9cea205b009ca73dd04470b9a6
Index: 0
scriptSig: 304502206e21798a42fae0e854281abd38bacd1aeed3ee3738d9e1446618c4571d10
90db022100e2ac980643b0b82c0e88ffdfec6b64e3e6ba35e7ba5fdd7d5d6cc8d25c6b241501

Output:
Value: 5000000000
scriptPubKey: OP_DUP OP_HASH160 404371705fa9bd789a2fcd52d2c580b65d35549d
OP_EQUALVERIFY OP_CHECKSIG</pre>

==== Explanation ====

The input in this transaction imports 50 BTC from output #0 in transaction f5d8... Then the output sends 50 BTC to a Bitcoin address (expressed here in hexadecimal 4043... instead of the normal base58). When the recipient wants to spend this money, he will reference output #0 of this transaction in an input of his own transaction.

===== Input =====

An '''input''' is a reference to an output in a different transaction. Multiple inputs are often listed in a transaction. The values of the referenced outputs are added up, and the total is usable in the outputs of this transaction. '''Previous tx''' is a [[hash]] of a previous transaction. '''Index''' is the specific output in the referenced transaction. '''ScriptSig''' is the first half of a [[script]] (discussed in more detail later).

The script contains two components, a signature and a public key. The public key belongs to the redeemer of the output transaction and proves the creator is allowed to redeem the outputs value. The other component is an ECDSA signature over a hash of a simplified version of the transaction. It, combined with the public key, proves the transaction was created by the real owner of the address in question. Various flags define how the transaction is simplified and can be used to create different types of payment.

===== Output =====

An '''output''' contains instructions for sending bitcoins. '''Value''' is the number of Satoshi (1 BTC = 100,000,000 Satoshi) that this output will be worth when claimed. '''ScriptPubKey''' is the second half of a script (discussed later). There can be more than one output, and they share the combined value of the inputs. Because an output can only ever be referenced by a single input, the entire combined input value needs to be sent in an output if you don't want to lose it. If the input is worth 50 BTC but you only want to send 25 BTC, Bitcoin will create two outputs worth 25 BTC: one to the destination, and one back to you (known as "[[change]]", though you send it to yourself). Any input bitcoins not redeemed in an output is considered a [[transaction fee]]; whoever generates the block will get it.
[[File:transaction.png|thumb|A sends 100 BTC to C and C generates 50 BTC. C sends 101 BTC to D, and he needs to send himself some change. D sends the 101 BTC to someone else, but they haven't redeemed it yet. Only D's output and C's change are capable of being spent in the current state.]]

===== Verification =====

To verify that inputs are authorized to collect the values of referenced outputs, Bitcoin uses a custom Forth-like [[script|scripting]] system. The input's scriptSig and the ''referenced'' output's scriptPubKey are evaluated (in that order), with scriptPubKey using the values left on the stack by scriptSig. The input is authorized if scriptPubKey returns true. Through the scripting system, the sender can create very complex conditions that people have to meet in order to claim the output's value. For example, it's possible to create an output that can be claimed by anyone without any authorization. It's also possible to require that an input be signed by ten different keys, or be redeemable with a password instead of a key.

=== Types of Transaction ===
Bitcoin currently only creates three different scriptSig/scriptPubKey pairs. These are described below.

It is possible to design more complex types of transactions, and link them together into cryptographically enforced agreements. These are known as [[Contracts]].

==== Transfer to IP address ====

scriptPubKey: <pubKey> OP_CHECKSIG
scriptSig: <sig>
The sender gets the public key when talking to the recipient over IP. When redeeming coins that have been sent to an IP address, the recipient provides only a signature. The signature is checked against the public key in scriptPubKey.

Checking process:
{| class="wikitable"
|-
! Stack
! Script
! Description
|-
|Empty.
|<sig> <pubKey> OP_CHECKSIG
|scriptSig and scriptPubKey are combined.
|-
|<sig> <pubKey>
| OP_CHECKSIG
|Constants are added to the stack.
|-
|true
|Empty.
|Signature is checked for top two stack items.
|}

==== Transfer to Bitcoin address ====

scriptPubKey: OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
scriptSig: <sig> <pubKey>
A Bitcoin [[address]] is only a hash, so the sender can't provide a full public key in scriptPubKey. When redeeming coins that have been sent to a Bitcoin address, the recipient provides both the signature and the public key. The script verifies that the provided public key does hash to the hash in scriptPubKey, and then it also checks the signature against the public key.

Checking process:
{| class="wikitable"
|-
! Stack
! Script
! Description
|-
|Empty.
| <sig> <pubKey> OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| scriptSig and scriptPubKey are combined.
|-
|<sig> <pubKey>
| OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| Constants are added to the stack.
|-
|<sig> <pubKey> <pubKey>
| OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| Top stack item is duplicated.
|-
|<sig> <pubKey> <pubHashA>
|<pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| Top stack item is hashed.
|-
|<sig> <pubKey> <pubHashA> <pubKeyHash>
|OP_EQUALVERIFY OP_CHECKSIG
| Constant added.
|-
|<sig> <pubKey>
|OP_CHECKSIG
| Equality is checked between the top two stack items.
|-
|true
|Empty.
|Signature is checked for top two stack items.
|}

==== Generation ====

Generations have a single input, and this input has a "coinbase" parameter instead of a scriptSig. The data in "coinbase" can be anything; it isn't used. Bitcoin puts the current compact-format [[target]] and the arbitrary-precision "extraNonce" number there, which increments every time the Nonce field in the [[block_hashing_algorithm|block header]] overflows. Outputs can be anything, but Bitcoin creates one exactly like an IP address transaction.
The extranonce contributes to enlarge the domain for the proof of work function. Miners can easily modify nonce (4byte), timestamp and extranonce (2 to 100bytes).

=== general format (inside a block) of each input of a transaction - Txin ===
{| class="wikitable"
|-
! Field
! Description
! Size
|-
|Previous Transaction hash
| doubled [[Wikipedia:SHA-256|SHA256]]-[[hash|hashed]] of a (previous) to-be-used transaction
|32 bytes
|-
|Previous Txout-index
| non negative integer indexing an output of the to-be-used transaction
|4 bytes
|-
|Txin-script length
|non negative integer [[ Protocol_specification#Variable_length_integer|VI = VarInt]]
|1 - 9 bytes
|-
|Txin-script / scriptSig
|[[Script]]
|<in-script length>-many bytes
|-
|sequence_no
|normally 0xFFFFFFFF; irrelevant unless transaction's lock_time is > 0
|4 bytes
|}

The input sufficiently describes where and how to get the bitcoin amout to be redeemed.
If it is the (only) input of the first transaction of a block, it is called the generation transaction input and its content completely ignored. (Historically the Previous Transaction hash is 0 and the Previous Txout-index is -1.)

=== general format (inside a block) of each output of a transaction - Txout ===
{| class="wikitable"
|-
! Field
! Description
! Size
|-
|value
|non negative integer giving the number of [[FAQ#What_do_I_call_the_various_denominations_of_bitcoins.3F|Satoshis(BTC/10^8)]] to be transfered
|8 bytes
|-
|Txout-script length
|non negative integer
|1 - 9 bytes [[ Protocol_specification#Variable_length_integer|VI = VarInt]]
|-
|Txout-script / scriptPubKey
|[[Script]]
|<out-script length>-many bytes
|}
The output sets the conditions to release this bitcoin amount later. The sum of the output values of the first transaction is the value of the mined bitcoins for the block plus possible transactions fees of the other transactions in the block.

==See Also==

* [[Script]]
* [[BTC Sender]] Transmit raw, hand-crafted transactions
* [[Raw Transactions]]
* [[Transaction Malleability]]

[[Category:Technical]]
[[Category:Vocabulary]]
[[de:Transaktion]]
[[es:Transacción]]
[[pl:Transakcje]]

Transaction

2013-05-19T13:43:33Z

Neofutur:

[[File:TxBinaryMap.png|thumb|right|Byte-map of Transaction with each type of TxIn and TxOut]]
A transaction is a signed section of data that is broadcast to the [[network]] and collected into [[block|blocks]]. It typically references previous transaction(s) and dedicates a certain number of bitcoins from it to one or more new public key(s) (Bitcoin address). It is not encrypted (nothing in Bitcoin is encrypted).

A [[block chain browser]] is a site where every transaction included within the block chain can be viewed. This is useful for seeing the technical details of transaction in action, and for payment verification purposes.

=== general format of a Bitcoin transaction (inside a block) ===
{| class="wikitable"
|-
! Field
! Description
! Size
|-
|Version no
|currently 1
|4 bytes
|-
|In-counter
| positive integer [[ Protocol_specification#Variable_length_integer|VI = VarInt]]
| 1 - 9 bytes
|-
|list of inputs
|[[Transactions#general_format_.28inside_a_block.29_of_each_input_of_a_transaction_-_Txin|the first input of the first transaction is also called "coinbase" (its content was ignored in earlier versions)]]
|<in-counter>-many inputs
|-
|Out-counter
| positive integer
| 1 - 9 bytes
|-
|list of outputs
|[[Transactions#general_format_.28inside_a_block.29_of_each_output_of_a_transaction_-_Txout|the outputs of the first transaction spend the mined bitcoins for the block]]
|<out-counter>-many outputs
|-
|lock_time
|if non-zero and sequence numbers are < 0xFFFFFFFF: block height or timestamp when transaction is final
|4 bytes
|}

=== Principle example of a Bitcoin transaction with 1 input and 1 output only ===

==== Data ====

<pre>Input:
Previous tx: f5d8ee39a430901c91a5917b9f2dc19d6d1a0e9cea205b009ca73dd04470b9a6
Index: 0
scriptSig: 304502206e21798a42fae0e854281abd38bacd1aeed3ee3738d9e1446618c4571d10
90db022100e2ac980643b0b82c0e88ffdfec6b64e3e6ba35e7ba5fdd7d5d6cc8d25c6b241501

Output:
Value: 5000000000
scriptPubKey: OP_DUP OP_HASH160 404371705fa9bd789a2fcd52d2c580b65d35549d
OP_EQUALVERIFY OP_CHECKSIG</pre>

==== Explanation ====

The input in this transaction imports 50 BTC from output #0 in transaction f5d8... Then the output sends 50 BTC to a Bitcoin address (expressed here in hexadecimal 4043... instead of the normal base58). When the recipient wants to spend this money, he will reference output #0 of this transaction in an input of his own transaction.

===== Input =====

An '''input''' is a reference to an output in a different transaction. Multiple inputs are often listed in a transaction. The values of the referenced outputs are added up, and the total is usable in the outputs of this transaction. '''Previous tx''' is a [[hash]] of a previous transaction. '''Index''' is the specific output in the referenced transaction. '''ScriptSig''' is the first half of a [[script]] (discussed in more detail later).

The script contains two components, a signature and a public key. The public key belongs to the redeemer of the output transaction and proves the creator is allowed to redeem the outputs value. The other component is an ECDSA signature over a hash of a simplified version of the transaction. It, combined with the public key, proves the transaction was created by the real owner of the address in question. Various flags define how the transaction is simplified and can be used to create different types of payment.

===== Output =====

An '''output''' contains instructions for sending bitcoins. '''Value''' is the number of Satoshi (1 BTC = 100,000,000 Satoshi) that this output will be worth when claimed. '''ScriptPubKey''' is the second half of a script (discussed later). There can be more than one output, and they share the combined value of the inputs. Because an output can only ever be referenced by a single input, the entire combined input value needs to be sent in an output if you don't want to lose it. If the input is worth 50 BTC but you only want to send 25 BTC, Bitcoin will create two outputs worth 25 BTC: one to the destination, and one back to you (known as "[[change]]", though you send it to yourself). Any input bitcoins not redeemed in an output is considered a [[transaction fee]]; whoever generates the block will get it.
[[File:transaction.png|thumb|A sends 100 BTC to C and C generates 50 BTC. C sends 101 BTC to D, and he needs to send himself some change. D sends the 101 BTC to someone else, but they haven't redeemed it yet. Only D's output and C's change are capable of being spent in the current state.]]

===== Verification =====

To verify that inputs are authorized to collect the values of referenced outputs, Bitcoin uses a custom Forth-like [[script|scripting]] system. The input's scriptSig and the ''referenced'' output's scriptPubKey are evaluated (in that order), with scriptPubKey using the values left on the stack by scriptSig. The input is authorized if scriptPubKey returns true. Through the scripting system, the sender can create very complex conditions that people have to meet in order to claim the output's value. For example, it's possible to create an output that can be claimed by anyone without any authorization. It's also possible to require that an input be signed by ten different keys, or be redeemable with a password instead of a key.

=== Types of Transaction ===
Bitcoin currently only creates three different scriptSig/scriptPubKey pairs. These are described below.

It is possible to design more complex types of transactions, and link them together into cryptographically enforced agreements. These are known as [[Contracts]].

==== Transfer to IP address ====

scriptPubKey: <pubKey> OP_CHECKSIG
scriptSig: <sig>
The sender gets the public key when talking to the recipient over IP. When redeeming coins that have been sent to an IP address, the recipient provides only a signature. The signature is checked against the public key in scriptPubKey.

Checking process:
{| class="wikitable"
|-
! Stack
! Script
! Description
|-
|Empty.
|<sig> <pubKey> OP_CHECKSIG
|scriptSig and scriptPubKey are combined.
|-
|<sig> <pubKey>
| OP_CHECKSIG
|Constants are added to the stack.
|-
|true
|Empty.
|Signature is checked for top two stack items.
|}

==== Transfer to Bitcoin address ====

scriptPubKey: OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
scriptSig: <sig> <pubKey>
A Bitcoin [[address]] is only a hash, so the sender can't provide a full public key in scriptPubKey. When redeeming coins that have been sent to a Bitcoin address, the recipient provides both the signature and the public key. The script verifies that the provided public key does hash to the hash in scriptPubKey, and then it also checks the signature against the public key.

Checking process:
{| class="wikitable"
|-
! Stack
! Script
! Description
|-
|Empty.
| <sig> <pubKey> OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| scriptSig and scriptPubKey are combined.
|-
|<sig> <pubKey>
| OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| Constants are added to the stack.
|-
|<sig> <pubKey> <pubKey>
| OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| Top stack item is duplicated.
|-
|<sig> <pubKey> <pubHashA>
|<pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| Top stack item is hashed.
|-
|<sig> <pubKey> <pubHashA> <pubKeyHash>
|OP_EQUALVERIFY OP_CHECKSIG
| Constant added.
|-
|<sig> <pubKey>
|OP_CHECKSIG
| Equality is checked between the top two stack items.
|-
|true
|Empty.
|Signature is checked for top two stack items.
|}

==== Generation ====

Generations have a single input, and this input has a "coinbase" parameter instead of a scriptSig. The data in "coinbase" can be anything; it isn't used. Bitcoin puts the current compact-format [[target]] and the arbitrary-precision "extraNonce" number there, which increments every time the Nonce field in the [[block_hashing_algorithm|block header]] overflows. Outputs can be anything, but Bitcoin creates one exactly like an IP address transaction.
The extranonce contributes to enlarge the domain for the proof of work function. Miners can easily modify nonce (4byte), timestamp and extranonce (2 to 100bytes).

=== general format (inside a block) of each input of a transaction - Txin ===
{| class="wikitable"
|-
! Field
! Description
! Size
|-
|Previous Transaction hash
| doubled [[Wikipedia:SHA-256|SHA256]]-[[hash|hashed]] of a (previous) to-be-used transaction
|32 bytes
|-
|Previous Txout-index
| non negative integer indexing an output of the to-be-used transaction
|4 bytes
|-
|Txin-script length
|non negative integer
|1 - 9 bytes
|-
|Txin-script / scriptSig
|[[Script]]
|<in-script length>-many bytes
|-
|sequence_no
|normally 0xFFFFFFFF; irrelevant unless transaction's lock_time is > 0
|4 bytes
|}

The input sufficiently describes where and how to get the bitcoin amout to be redeemed.
If it is the (only) input of the first transaction of a block, it is called the generation transaction input and its content completely ignored. (Historically the Previous Transaction hash is 0 and the Previous Txout-index is -1.)

=== general format (inside a block) of each output of a transaction - Txout ===
{| class="wikitable"
|-
! Field
! Description
! Size
|-
|value
|non negative integer giving the number of [[FAQ#What_do_I_call_the_various_denominations_of_bitcoins.3F|Satoshis(BTC/10^8)]] to be transfered
|8 bytes
|-
|Txout-script length
|non negative integer
|1 - 9 bytes
|-
|Txout-script / scriptPubKey
|[[Script]]
|<out-script length>-many bytes
|}
The output sets the conditions to release this bitcoin amount later. The sum of the output values of the first transaction is the value of the mined bitcoins for the block plus possible transactions fees of the other transactions in the block.

==See Also==

* [[Script]]
* [[BTC Sender]] Transmit raw, hand-crafted transactions
* [[Raw Transactions]]
* [[Transaction Malleability]]

[[Category:Technical]]
[[Category:Vocabulary]]
[[de:Transaktion]]
[[es:Transacción]]
[[pl:Transakcje]]

Deflationary spiral

2013-05-18T16:19:05Z

Neofutur: /* See Also */

'''Deflationary spiral''' is an economic argument that proposes that runaway deflation can eventually lead to the collapse of the currency given certain conditions and constraints. It is a common criticism made against the viability of [[Bitcoin]].
The ‘deflationary spiral’ is a real condition that affects the popular fractional reserve backing system. Bitcoin is not affected by this because it is fundamentally different from popular currency.

Deflation is a decline in the general price level. Deflation occurs when the price of goods and services, relative to a specific measure, decline. It is not necessarily that the value of the goods and services themselves declined, but can be because the value of the currency itself increased.

For example, let us consider an economy comprised entirely of beef and oranges where the medium of exchange is gold. Both beef and oranges can decay and are not consistent, and therefore cannot be used as a currency. In order to trade, people exchange gold for either beef or oranges. They see gold as a store of value that they can use to purchase beef or oranges in the future. What happens when the economy grows and we can produce more beef and more oranges? The price of both beef and oranges will decline. To the extent our productive capacity for both beef and oranges increased at the same pace, the exchange value between the two (the amount of beef for a given number of oranges) will likely stay the same; however, those who held gold as a store of value would now be able to purchase more beef and more oranges for a given amount of gold.

A deflationary spiral occurs when the value of a currency, relative to the goods in an economy, increases continually as a result of hoarding. As the value of the currency relative to the goods in the economy increase, people have the incentive to hoard the currency, because by merely holding it, they hope to be able to purchase more goods for less money in the future. A lack of currency available in the market causes the price of goods to further decrease, resulting in more hoarding.

In our economy of beef and oranges it is easy to see how this could occur. First, people see a significant gain in productivity on the horizon; we will be able to produce more beef and oranges for the same effort in the future. The supply of gold, however, is fixed. As a result, people desire to hold gold, because they will be able to purchase more beef and oranges with their gold in the future than they can now. This will lead to a decline in the price of beef and oranges as measured by gold (an increase in the value of gold). Limiting the amount of currency in the market available for exchange can also make transactions more difficult. In a complex system where we do not only have beef, oranges and gold, this can result in a deflationary spiral where no one wishes to spend their currency and the economy itself slows as a result of the limited number of transactions. Limited demand with fixed output results in a decline in prices, which further exacerbates the problem.

Alternative explanation:
A deflationary spiral occurs when the price of a traded article increases at some given rate, which causes people to hoard it. As people hoard the commodity, less and less of it is available thus causing the price to go up even more. In turn, even more people hoard the commodity. Thus a feedback loop or spiral of deflation occurs.<br />

In practice, there is only a limited amount of 'value' that can be placed upon a good before it becomes too attractive to trade for other goods (thus ending the spiral). The only time that the 'Deflationary Spiral' can happen (to it's conclusion) is when people can foresee a time where they are forced to use that particular traded article. See below for a dissenting argument on this topic.

==In The Popular Fractional Reserve Banking System==
The popular money that we trade consists of the principal of the loans of other people. All this money must be someday 'repaid.' When people save (pay back their loans), the total monetary supply contracts. When people spend (take out loans), the total monetary supply is increasing.

If you have people who are hoarding money, the principal still needs to be repaid. Hoarding will make it harder for other people in the economy to pay back their loans.

Because people foresee a time where they need to pay back their loans (a future fixed expense), when the value of the money starts to increase (deflation), those with loans will endeavor to pay back the loans quicker. This causes the monetary supply to reduce, reducing the total amount of money available for repayment of loans, again making it harder for people to pay back what they owe.

This Deflationary spiral diverts funds away from the legitimate economy, to the repayment of debt. Causing the economy to stagnate and stop.

==Bitcoin==
The key difference is that people don't foresee a fixed cost (unit amount) that they must pay with Bitcoin. If the value of the Bitcoins that they own increases, then any future cost will take a proportionally smaller amount of Bitcoins. There isn't any fixed incentive to holding Bitcoin other than speculation.

If the economy that uses Bitcoin grows, the per-unit value of Bitcoin proportionally increases also.

Everything is the opposite of the popular fractional reserve banking system (because Bitcoin isn't a debt but an asset). Bitcoins '''only''' deflate in value when the Bitcoin Economy is '''growing'''.

Because the Deflationary spiral is a real problem in the traditional monetary system, doesn't necessarily mean that it will also be a problem in the Bitcoin economy.

<blockquote>
"Elaborate controls to make sure that currency is not produced in greater numbers is not something any other currency, like the dollar or the euro, has," says Russ Roberts, professor of economics at George Mason University. The consequence will likely be slow and steady deflation, as the growth in circulating bitcoins declines and their value rises.

"That is considered very destructive in today's economies, mostly because when it occurs, it is unexpected," says Roberts. But he thinks that won't apply in an economy where deflation is expected. "In a Bitcoin world, everyone would anticipate that, and they know what they got paid would buy more then than it would now."
</blockquote>
--MIT Technology Review: [http://www.technologyreview.com/computing/37619/page2/ What Bitcoin Is, and Why It Matters], May 25, 2011

==Alternative Argument==
A deflationary spiral occurs when there is an incentive to hoard because of declining prices, which results in even less available currency on the market, further perpetuating declining prices.

How could this occur in the Bitcoin market?

1. Limited price stability has a negative impact on the acceptance of a currency. Vendors do not wish to speculate on the price of currency when selling goods or services.

2. Once prices do stabilize in the future, there will always be the knowledge that the number of Bitcoins in the market is limited. As a result, to the extent the GDP of the Bitcoin economy increases (the total value of all Bitcoin transactions completed increases in "real" terms), there will continue to be price deflation. The expectation of future deflation means that there will be a discrepancy in perceived values between parties valuing bitcoin on longer or shorter time horizons.
The apparent over-pricing of bitcoin from the perspective of people engaging in short term transactions will encourage the creation and adoption of competing systems.

While this is not a traditional deflationary spiral, the constraint on the actual money supply can produce the same result, which is a limit on the value of goods and services transacted using Bitcoins.

==See Also==

* [[Controlled inflation]]
* [[Bitcoin Days Destroyed]]
* [http://bitcoin.stackexchange.com/questions/408/does-hoarding-really-hurt-bitcoin Does hoarding really hurt bitcoin?] on stackexchange.com
* [http://www.jjgames.com/page/bitcoin-spending-during-deflation BitCoin Consumption Increases During Deflation ]

[[Category:Economics]]

MtGox/API/Streaming

2013-05-18T16:08:39Z

Neofutur: /* Authenticated commands */

Real time streaming data may be obtained over the streaming API, using [http://socket.io/ Socket.io] or the vanilla websocket

==websocket channel list ==

List of the public streaming channels :

https://mtgox.com/api/2/stream/list_public

==Connecting==

* Host: '''websocket.mtgox.com''' or '''socketio.mtgox.com'''
* Port: '''80''' or '''443''' ( ssl )
* Namespace: '''/mtgox''' (Including beginning slash)

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

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

and the websocket will give you updates in EUR currency

if you need need more than one currency, you can add currency symbols like that :

websocket.mtgox.com:80/mtgox?Currency=EUR,USD

websocket.mtgox.com:80/mtgox?Currency=EUR,USD,CHF

find the list of currency symbols on https://en.bitcoin.it/wiki/MtGox/API#Currency_Symbols

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

====Ticker====
Ticker messages contain the current inside Bid and Ask as well as daily highs, lows, and volume. The fields contained in the ticker match those defined in the version 1.0 API above. All fields contain <tt>currency</tt>, <tt>display</tt>, <tt>value</tt>, and <tt>value_int</tt> entries.
<source lang="javascript">
{
"channel":"d5f06780-30a8-4a48-a2f8-7ed181b4a13f",
"op":"private",
"origin":"broadcast",
"private":"ticker",
"ticker":{
"avg":{
"currency":"USD",
"display":"$2.26847",
"value":"2.26847",
"value_int":"226847"
},
"buy":{...},
"high":{...},
"last":{..},
"last_local":{...},
"last_orig":{...},
"low":{...},
"sell":{...},
"vol":{
"currency":"BTC",
"display":"118,696.02104208",
"value":"118696.02104208",
"value_int":"11869602104208"
},
"vwap":{...}
}
}
</source>

====Trade====
<source lang="javascript">{
"channel":"dbf1dee9-4f2e-4a08-8cb7-748919a71b21",
"op":"private",
"origin":"broadcast",
"private":"trade",
"trade":{
"amount":2.71,
"amount_int":"271000000",
"date":1310279340,
"item":"BTC",
"price":14.43,
"price_currency":"USD",
"price_int":"1443000",
"primary":"Y",
"properties":"limit, mixed_currency",
"tid":"1310279340877902",
"trade_type":"bid",
"type":"trade"
}
}
</source>

'''trade''' contains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| amount || the traded amount in item (BTC), float, deprecated
|-
| amount_int || the traded amount * 1E8
|-
| date || unix timestamp of trade
|-
| item || What was this trade about
|-
| price || price per unit, float, deprecated
|-
| price_int || price in smallest unit as integer (5 decimals of USD, 3 in case of JPY)
|-
| price_currency || currency in which trade was completed
|-
| properties || "market": the trade ate the whole order, "limit": the trade ate the order partially - some of the original order still exists
|-
| tid || Trade id (big integer, which is in fact trade timestamp in microseconds)
|-
| trade_type || Did this trade result from the execution of a bid or a ask?
|-
|}

====Depth====

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

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

'''depth''' contains the following:

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

|}

=== op:result ===

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

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

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

=== Private per-account messages ===

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

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

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

==== user_order ====

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

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

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

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

==== wallet ====

Updates to the user's wallet balance.

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

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

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

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

==== trade ====

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

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

Commands that can be sent without authentication

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

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

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

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

=== Authenticated commands ===

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

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

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

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

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

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

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

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

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

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

== Examples ==

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

=== Websockets ===
* https://github.com/cronopio/hook.io-ws (Node.js)
* https://github.com/progrium/wssh (Python)
* https://github.com/sta/websocket-sharp (C#)

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

=== Arbitrage ===
* https://github.com/goteppo/ArBit
* https://github.com/vbmithr/breakbot

==See Also==

* [[MtGox/API/HTTP/v1]]
* [http://bitcointalk.org/index.php?topic=164404.0 MtGox API version 2: Unofficial Documentation]

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

MtGox/API/HTTP

2013-05-18T16:06:54Z

Neofutur: /* tonce and nonce */

Two versions of the HTTP API are currently available, see the following pages for details on the methods available for each:

* [[MtGox/API/HTTP/v0|Version 0]]
* [[MtGox/API/HTTP/v1|Version 1]]
* [[MtGox/API/HTTP/v2|Version 2]]

== Summary ==

'''The URL mtgox.com was changed to data.mtgox.com on March 19th 2013. https://bitcointalk.org/index.php?topic=150786.0'''

All HTTP API requests are sent to URLs beginning with <nowiki>https://data.mtgox.com/api/*</nowiki>. It allows placing orders, performing withdrawls, deposits, and other things. All responses are in [http://json.org/ JSON] format.

There is a [https://rubygems.org/gems/mtgox Ruby gem], [https://rubygems.org/gems/guten-mtgox guten-mtgox] and a [[Finance::MtGox|Perl module]] available for interacting with the HTTP API.

== Cache ==

All API methods are cached for 10 seconds. Do not request results more often than that, you might be blocked by the anti-DDoS filters.

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

== tonce and nonce ==

Each request to the private http API ( v0, v1 , or v2 ) needs to have a nonce or a tonce

Please have a look at http://en.wikipedia.org/wiki/Cryptographic_nonce for explanations of what is a nonce .

See also http://en.wikipedia.org/wiki/System_time and http://en.wikipedia.org/wiki/Unix_time

The tonce is a variant of the nonce.

A few facts about nonce and tonce :

* The value of the nonce must always increase, if you use a very high value during your tests, you could have to generate new api keys to be allowed to get back to lower values

* The value of the tonce is based on the current timestamp in microseconds ( example : 1368892862123456 ) . It needs to be current microtime with +/- 10secs, and needs to be unique

* Your computer's time needs to be exact if you want to use the tonce parameter

* For the tonce you will use the time in microseconds , besed on http://en.wikipedia.org/wiki/Unix_time

* As long as your tonce value is unique and is within +/-10secs of now, it doesn't need to be incremental

* depending of which you want to use, you will add the "tonce=" or "nonce=" parameter to your api request

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

'''basically the base64 string should contain:'''
* the binary representation of the api key id
* binary hmac-sha512 signature
* json data

api key looks like that: 12345678-abcd-1234-abcd-50286e649d5c

it's actually hexadecimal, it should be converted to binary

hash should then be appended (binary too) and then encode everything in base64

'''Warning : the API is no more accepting authentication by login/pass ( since 2012 march 1 ) , you _need_ to use an API key.'''

=== perl ===

'''IMPORTANT! This is a simplified perl module simply returning user info not a full API, it is shown simply for illustrative purposes for those wishing to developing there own modules from scratch.. or bots.. or other'''

'''IMPORTANT! This requires you compiled perl libwww with https support'''

<source lang="perl">

#!/usr/bin/perl

use strict;
use warnings;

use Time::HiRes qw(gettimeofday);
use MIME::Base64;
use Digest::SHA qw(hmac_sha512);

use JSON;
use LWP::UserAgent;

use Data::Dumper;

my $lwp = LWP::UserAgent->new;
$lwp->agent("perl $]");

my $json = JSON->new->allow_nonref;

my $secret = '_MTGOX API SECRET GET YOURS AT https://classic.mtgox.com/support/tradeAPI';
my $key = '_MTGOX API KEY GET YOURS AT https://classic.mtgox.com/support/tradeAPI';

## user code

my $request = genReq('/1/generic/private/info');
my $res = $lwp->request($request);

# Check the outcome of the response
if ($res->is_success) {
print Dumper($json->decode( $res->content ))."\n";
}
else { print $res->status_line, "\n"; }

exit 0;

## sub routines and helpers

sub genReq {
my ($uri) = shift;

my $req = HTTP::Request->new(POST => 'https://mtgox.com/api/'.$uri);
$req->content_type('application/x-www-form-urlencoded');
$req->content("nonce=".microtime());
$req->header('Rest-Key' => $key);
$req->header('Rest-Sign' => signReq($req->content(),$secret));

return $req;
};

sub signReq {
my ($content,$secret) = @_;
return encode_base64(hmac_sha512($content,decode_base64($secret)));
}

sub microtime { return sprintf "%d%06d", gettimeofday; }

</source>
=== PHP ===
<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, '', '&');

$prefix = '';
if (substr($path, 0, 2) == '2/') {
$prefix = substr($path, 2)."\0";
}

// generate the extra headers
$headers = array(
'Rest-Key: '.$key,
'Rest-Sign: '.base64_encode(hash_hmac('sha512', $prefix.$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);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

// 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 ===
<source lang="python">
from urllib import urlencode
import urllib2
import time
from hashlib import sha512
from hmac import HMAC
import base64
import json
def get_nonce():
return int(time.time()*100000)

def sign_data(secret, data):
return base64.b64encode(str(HMAC(secret, data, sha512).digest()))

class requester:
def __init__(self, auth_key, auth_secret):
self.auth_key = auth_key
self.auth_secret = base64.b64decode(auth_secret)

def build_query(self, req={}):
req["nonce"] = get_nonce()
post_data = urlencode(req)
headers = {}
headers["User-Agent"] = "GoxApi"
headers["Rest-Key"] = self.auth_key
headers["Rest-Sign"] = sign_data(self.auth_secret, post_data)
return (post_data, headers)

def perform(self, path, args):
data, headers = self.build_query(args)
req = urllib2.Request("https://mtgox.com/api/0/"+path, data, headers)
res = urllib2.urlopen(req, data)
return json.load(res)
</source>

=== Node.js ===
Generic [[Node.js Example]] trading library (supports MtGox and Bitfloor): https://github.com/bitfloor/trader.nodejs

=== Java ===

basic [[Java Example]] on https://gist.github.com/2396722 hoping for many java forks and pull requests on github

XChange API : https://github.com/timmolter/XChange

mtgox-java: A Java API (based on Spring & Maven) for the MtGox bitcoin exchange WebSocket & HTTP services.
http://grantsparks.github.com/mtgox-java/

mtgox-api-v2-java: A Java lib for the v2 of the API https://github.com/adv0r/mtgox-api-v2-java
====Java:====

=== Javascript Firefox addon ===
* [https://github.com/joric/mtgox-ticker] firefox ticker addon

==See Also==

* [[MtGox|Mt. Gox]]
* [http://bitcointalk.org/index.php?topic=164404.0 MtGox API version 2: Unofficial Documentation]

MtGox/API/HTTP

2013-05-18T15:54:55Z

Neofutur:

Two versions of the HTTP API are currently available, see the following pages for details on the methods available for each:

* [[MtGox/API/HTTP/v0|Version 0]]
* [[MtGox/API/HTTP/v1|Version 1]]
* [[MtGox/API/HTTP/v2|Version 2]]

== Summary ==

'''The URL mtgox.com was changed to data.mtgox.com on March 19th 2013. https://bitcointalk.org/index.php?topic=150786.0'''

All HTTP API requests are sent to URLs beginning with <nowiki>https://data.mtgox.com/api/*</nowiki>. It allows placing orders, performing withdrawls, deposits, and other things. All responses are in [http://json.org/ JSON] format.

There is a [https://rubygems.org/gems/mtgox Ruby gem], [https://rubygems.org/gems/guten-mtgox guten-mtgox] and a [[Finance::MtGox|Perl module]] available for interacting with the HTTP API.

== Cache ==

All API methods are cached for 10 seconds. Do not request results more often than that, you might be blocked by the anti-DDoS filters.

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

== tonce and nonce ==

Each request to the private http API ( v0, v1 , or v2 ) needs to have a nonce or a tonce

Please have a look at http://en.wikipedia.org/wiki/Cryptographic_nonce for explanations of what is a nonce .

See also http://en.wikipedia.org/wiki/System_time and http://en.wikipedia.org/wiki/Unix_time

The tonce is a variant of the nonce.

A few facts about nonce and tonce :

* The value of the nonce must always increase, if you use a very high value during your tests, you could have to generate new api keys to be allowed to get back to lower values

* The value of the tonce is based on the current timestamp in microseconds. It needs to be current microtime with +/- 10secs, and needs to be unique

* Your computer's time needs to be exact if you want to use the tonce parameter

* For the tonce you will use the time in microseconds , besed on http://en.wikipedia.org/wiki/Unix_time

* As long as your tonce value is unique and is within +/-10secs of now, it doesn't need to be incremental

* depending of which you want to use, you will add the "tonce=" or "nonce=" parameter to your api request

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

'''basically the base64 string should contain:'''
* the binary representation of the api key id
* binary hmac-sha512 signature
* json data

api key looks like that: 12345678-abcd-1234-abcd-50286e649d5c

it's actually hexadecimal, it should be converted to binary

hash should then be appended (binary too) and then encode everything in base64

'''Warning : the API is no more accepting authentication by login/pass ( since 2012 march 1 ) , you _need_ to use an API key.'''

=== perl ===

'''IMPORTANT! This is a simplified perl module simply returning user info not a full API, it is shown simply for illustrative purposes for those wishing to developing there own modules from scratch.. or bots.. or other'''

'''IMPORTANT! This requires you compiled perl libwww with https support'''

<source lang="perl">

#!/usr/bin/perl

use strict;
use warnings;

use Time::HiRes qw(gettimeofday);
use MIME::Base64;
use Digest::SHA qw(hmac_sha512);

use JSON;
use LWP::UserAgent;

use Data::Dumper;

my $lwp = LWP::UserAgent->new;
$lwp->agent("perl $]");

my $json = JSON->new->allow_nonref;

my $secret = '_MTGOX API SECRET GET YOURS AT https://classic.mtgox.com/support/tradeAPI';
my $key = '_MTGOX API KEY GET YOURS AT https://classic.mtgox.com/support/tradeAPI';

## user code

my $request = genReq('/1/generic/private/info');
my $res = $lwp->request($request);

# Check the outcome of the response
if ($res->is_success) {
print Dumper($json->decode( $res->content ))."\n";
}
else { print $res->status_line, "\n"; }

exit 0;

## sub routines and helpers

sub genReq {
my ($uri) = shift;

my $req = HTTP::Request->new(POST => 'https://mtgox.com/api/'.$uri);
$req->content_type('application/x-www-form-urlencoded');
$req->content("nonce=".microtime());
$req->header('Rest-Key' => $key);
$req->header('Rest-Sign' => signReq($req->content(),$secret));

return $req;
};

sub signReq {
my ($content,$secret) = @_;
return encode_base64(hmac_sha512($content,decode_base64($secret)));
}

sub microtime { return sprintf "%d%06d", gettimeofday; }

</source>
=== PHP ===
<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, '', '&');

$prefix = '';
if (substr($path, 0, 2) == '2/') {
$prefix = substr($path, 2)."\0";
}

// generate the extra headers
$headers = array(
'Rest-Key: '.$key,
'Rest-Sign: '.base64_encode(hash_hmac('sha512', $prefix.$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);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

// 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 ===
<source lang="python">
from urllib import urlencode
import urllib2
import time
from hashlib import sha512
from hmac import HMAC
import base64
import json
def get_nonce():
return int(time.time()*100000)

def sign_data(secret, data):
return base64.b64encode(str(HMAC(secret, data, sha512).digest()))

class requester:
def __init__(self, auth_key, auth_secret):
self.auth_key = auth_key
self.auth_secret = base64.b64decode(auth_secret)

def build_query(self, req={}):
req["nonce"] = get_nonce()
post_data = urlencode(req)
headers = {}
headers["User-Agent"] = "GoxApi"
headers["Rest-Key"] = self.auth_key
headers["Rest-Sign"] = sign_data(self.auth_secret, post_data)
return (post_data, headers)

def perform(self, path, args):
data, headers = self.build_query(args)
req = urllib2.Request("https://mtgox.com/api/0/"+path, data, headers)
res = urllib2.urlopen(req, data)
return json.load(res)
</source>

=== Node.js ===
Generic [[Node.js Example]] trading library (supports MtGox and Bitfloor): https://github.com/bitfloor/trader.nodejs

=== Java ===

basic [[Java Example]] on https://gist.github.com/2396722 hoping for many java forks and pull requests on github

XChange API : https://github.com/timmolter/XChange

mtgox-java: A Java API (based on Spring & Maven) for the MtGox bitcoin exchange WebSocket & HTTP services.
http://grantsparks.github.com/mtgox-java/

mtgox-api-v2-java: A Java lib for the v2 of the API https://github.com/adv0r/mtgox-api-v2-java
====Java:====

=== Javascript Firefox addon ===
* [https://github.com/joric/mtgox-ticker] firefox ticker addon

==See Also==

* [[MtGox|Mt. Gox]]
* [http://bitcointalk.org/index.php?topic=164404.0 MtGox API version 2: Unofficial Documentation]

MtGox/API/HTTP

2013-05-18T15:53:58Z

Neofutur:

Two versions of the HTTP API are currently available, see the following pages for details on the methods available for each:

* [[MtGox/API/HTTP/v0|Version 0]]
* [[MtGox/API/HTTP/v1|Version 1]]
* [[MtGox/API/HTTP/v2|Version 2]]

== Summary ==

'''The URL mtgox.com was changed to data.mtgox.com on March 19th 2013. https://bitcointalk.org/index.php?topic=150786.0'''

All HTTP API requests are sent to URLs beginning with <nowiki>https://data.mtgox.com/api/*</nowiki>. It allows placing orders, performing withdrawls, deposits, and other things. All responses are in [http://json.org/ JSON] format.

There is a [https://rubygems.org/gems/mtgox Ruby gem], [https://rubygems.org/gems/guten-mtgox guten-mtgox] and a [[Finance::MtGox|Perl module]] available for interacting with the HTTP API.

== Cache ==

All API methods are cached for 10 seconds. Do not request results more often than that, you might be blocked by the anti-DDoS filters.

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

== tonce and nonce ==

Each request to the private http API ( v0, v1 , or v2 ) needs to have a nonce or a tonce

Please have a look at http://en.wikipedia.org/wiki/Cryptographic_nonce for explanations of what is a nonce .

See also http://en.wikipedia.org/wiki/System_time and http://en.wikipedia.org/wiki/Unix_time

The tonce is a variant of the nonce.

A few facts about nonce and tonce :

* The value of the nonce must always increase, if you use a very high value during your tests, you could have to generate new api keys to be allowed to get back to lower values

* The value of the tonce is based on the current timestamp, needs to be current microtime with +/- 10secs, and needs to be unique

* Your computer's time needs to be exact if you want to use the tonce parameter

* For the tonce you will use the time in microseconds , besed on http://en.wikipedia.org/wiki/Unix_time

* As long as your tonce value is unique and is within +/-10secs of now, it doesn't need to be incremental

* depending of which you want to use, you will add the "tonce=" or "nonce=" parameter to your api request

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

'''basically the base64 string should contain:'''
* the binary representation of the api key id
* binary hmac-sha512 signature
* json data

api key looks like that: 12345678-abcd-1234-abcd-50286e649d5c

it's actually hexadecimal, it should be converted to binary

hash should then be appended (binary too) and then encode everything in base64

'''Warning : the API is no more accepting authentication by login/pass ( since 2012 march 1 ) , you _need_ to use an API key.'''

=== perl ===

'''IMPORTANT! This is a simplified perl module simply returning user info not a full API, it is shown simply for illustrative purposes for those wishing to developing there own modules from scratch.. or bots.. or other'''

'''IMPORTANT! This requires you compiled perl libwww with https support'''

<source lang="perl">

#!/usr/bin/perl

use strict;
use warnings;

use Time::HiRes qw(gettimeofday);
use MIME::Base64;
use Digest::SHA qw(hmac_sha512);

use JSON;
use LWP::UserAgent;

use Data::Dumper;

my $lwp = LWP::UserAgent->new;
$lwp->agent("perl $]");

my $json = JSON->new->allow_nonref;

my $secret = '_MTGOX API SECRET GET YOURS AT https://classic.mtgox.com/support/tradeAPI';
my $key = '_MTGOX API KEY GET YOURS AT https://classic.mtgox.com/support/tradeAPI';

## user code

my $request = genReq('/1/generic/private/info');
my $res = $lwp->request($request);

# Check the outcome of the response
if ($res->is_success) {
print Dumper($json->decode( $res->content ))."\n";
}
else { print $res->status_line, "\n"; }

exit 0;

## sub routines and helpers

sub genReq {
my ($uri) = shift;

my $req = HTTP::Request->new(POST => 'https://mtgox.com/api/'.$uri);
$req->content_type('application/x-www-form-urlencoded');
$req->content("nonce=".microtime());
$req->header('Rest-Key' => $key);
$req->header('Rest-Sign' => signReq($req->content(),$secret));

return $req;
};

sub signReq {
my ($content,$secret) = @_;
return encode_base64(hmac_sha512($content,decode_base64($secret)));
}

sub microtime { return sprintf "%d%06d", gettimeofday; }

</source>
=== PHP ===
<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, '', '&');

$prefix = '';
if (substr($path, 0, 2) == '2/') {
$prefix = substr($path, 2)."\0";
}

// generate the extra headers
$headers = array(
'Rest-Key: '.$key,
'Rest-Sign: '.base64_encode(hash_hmac('sha512', $prefix.$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);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

// 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 ===
<source lang="python">
from urllib import urlencode
import urllib2
import time
from hashlib import sha512
from hmac import HMAC
import base64
import json
def get_nonce():
return int(time.time()*100000)

def sign_data(secret, data):
return base64.b64encode(str(HMAC(secret, data, sha512).digest()))

class requester:
def __init__(self, auth_key, auth_secret):
self.auth_key = auth_key
self.auth_secret = base64.b64decode(auth_secret)

def build_query(self, req={}):
req["nonce"] = get_nonce()
post_data = urlencode(req)
headers = {}
headers["User-Agent"] = "GoxApi"
headers["Rest-Key"] = self.auth_key
headers["Rest-Sign"] = sign_data(self.auth_secret, post_data)
return (post_data, headers)

def perform(self, path, args):
data, headers = self.build_query(args)
req = urllib2.Request("https://mtgox.com/api/0/"+path, data, headers)
res = urllib2.urlopen(req, data)
return json.load(res)
</source>

=== Node.js ===
Generic [[Node.js Example]] trading library (supports MtGox and Bitfloor): https://github.com/bitfloor/trader.nodejs

=== Java ===

basic [[Java Example]] on https://gist.github.com/2396722 hoping for many java forks and pull requests on github

XChange API : https://github.com/timmolter/XChange

mtgox-java: A Java API (based on Spring & Maven) for the MtGox bitcoin exchange WebSocket & HTTP services.
http://grantsparks.github.com/mtgox-java/

mtgox-api-v2-java: A Java lib for the v2 of the API https://github.com/adv0r/mtgox-api-v2-java
====Java:====

=== Javascript Firefox addon ===
* [https://github.com/joric/mtgox-ticker] firefox ticker addon

==See Also==

* [[MtGox|Mt. Gox]]
* [http://bitcointalk.org/index.php?topic=164404.0 MtGox API version 2: Unofficial Documentation]

MtGox/API/HTTP

2013-05-18T15:51:21Z

Neofutur: /* tonce et nonce */

Two versions of the HTTP API are currently available, see the following pages for details on the methods available for each:

* [[MtGox/API/HTTP/v0|Version 0]]
* [[MtGox/API/HTTP/v1|Version 1]]
* [[MtGox/API/HTTP/v2|Version 2]]

== Summary ==

'''The URL mtgox.com was changed to data.mtgox.com on March 19th 2013. https://bitcointalk.org/index.php?topic=150786.0'''

All HTTP API requests are sent to URLs beginning with <nowiki>https://data.mtgox.com/api/*</nowiki>. It allows placing orders, performing withdrawls, deposits, and other things. All responses are in [http://json.org/ JSON] format.

There is a [https://rubygems.org/gems/mtgox Ruby gem], [https://rubygems.org/gems/guten-mtgox guten-mtgox] and a [[Finance::MtGox|Perl module]] available for interacting with the HTTP API.

== Cache ==

All API methods are cached for 10 seconds. Do not request results more often than that, you might be blocked by the anti-DDoS filters.

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

== tonce et nonce ==

Each request to the private http API ( v0, v1 , or v2 ) needs to have a nonce or a tonce

Please have a look at http://en.wikipedia.org/wiki/Cryptographic_nonce for explanations of what is a nonce .

See also http://en.wikipedia.org/wiki/System_time and http://en.wikipedia.org/wiki/Unix_time

The tonce is a variant of the nonce.

A few facts about nonce and tonce :

* The value of the nonce must always increase, if you use a very high value during your tests, you could have to generate new api keys to be allowed to get back to lower values

* The value of the tonce is based on the current timestamp, needs to be current microtime with +/- 10secs, and needs to be unique

* Your computer's time needs to be exact if you want to use the tonce parameter

* For the tonce you will use the time in microseconds , besed on http://en.wikipedia.org/wiki/Unix_time

* As long as your tonce value is unique and is within +/-10secs of now, it doesn't need to be incremental

* depending of which you want to use, you will add the "tonce=" or "nonce=" parameter to your api request

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

'''basically the base64 string should contain:'''
* the binary representation of the api key id
* binary hmac-sha512 signature
* json data

api key looks like that: 12345678-abcd-1234-abcd-50286e649d5c

it's actually hexadecimal, it should be converted to binary

hash should then be appended (binary too) and then encode everything in base64

'''Warning : the API is no more accepting authentication by login/pass ( since 2012 march 1 ) , you _need_ to use an API key.'''

=== perl ===

'''IMPORTANT! This is a simplified perl module simply returning user info not a full API, it is shown simply for illustrative purposes for those wishing to developing there own modules from scratch.. or bots.. or other'''

'''IMPORTANT! This requires you compiled perl libwww with https support'''

<source lang="perl">

#!/usr/bin/perl

use strict;
use warnings;

use Time::HiRes qw(gettimeofday);
use MIME::Base64;
use Digest::SHA qw(hmac_sha512);

use JSON;
use LWP::UserAgent;

use Data::Dumper;

my $lwp = LWP::UserAgent->new;
$lwp->agent("perl $]");

my $json = JSON->new->allow_nonref;

my $secret = '_MTGOX API SECRET GET YOURS AT https://classic.mtgox.com/support/tradeAPI';
my $key = '_MTGOX API KEY GET YOURS AT https://classic.mtgox.com/support/tradeAPI';

## user code

my $request = genReq('/1/generic/private/info');
my $res = $lwp->request($request);

# Check the outcome of the response
if ($res->is_success) {
print Dumper($json->decode( $res->content ))."\n";
}
else { print $res->status_line, "\n"; }

exit 0;

## sub routines and helpers

sub genReq {
my ($uri) = shift;

my $req = HTTP::Request->new(POST => 'https://mtgox.com/api/'.$uri);
$req->content_type('application/x-www-form-urlencoded');
$req->content("nonce=".microtime());
$req->header('Rest-Key' => $key);
$req->header('Rest-Sign' => signReq($req->content(),$secret));

return $req;
};

sub signReq {
my ($content,$secret) = @_;
return encode_base64(hmac_sha512($content,decode_base64($secret)));
}

sub microtime { return sprintf "%d%06d", gettimeofday; }

</source>
=== PHP ===
<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, '', '&');

$prefix = '';
if (substr($path, 0, 2) == '2/') {
$prefix = substr($path, 2)."\0";
}

// generate the extra headers
$headers = array(
'Rest-Key: '.$key,
'Rest-Sign: '.base64_encode(hash_hmac('sha512', $prefix.$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);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

// 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 ===
<source lang="python">
from urllib import urlencode
import urllib2
import time
from hashlib import sha512
from hmac import HMAC
import base64
import json
def get_nonce():
return int(time.time()*100000)

def sign_data(secret, data):
return base64.b64encode(str(HMAC(secret, data, sha512).digest()))

class requester:
def __init__(self, auth_key, auth_secret):
self.auth_key = auth_key
self.auth_secret = base64.b64decode(auth_secret)

def build_query(self, req={}):
req["nonce"] = get_nonce()
post_data = urlencode(req)
headers = {}
headers["User-Agent"] = "GoxApi"
headers["Rest-Key"] = self.auth_key
headers["Rest-Sign"] = sign_data(self.auth_secret, post_data)
return (post_data, headers)

def perform(self, path, args):
data, headers = self.build_query(args)
req = urllib2.Request("https://mtgox.com/api/0/"+path, data, headers)
res = urllib2.urlopen(req, data)
return json.load(res)
</source>

=== Node.js ===
Generic [[Node.js Example]] trading library (supports MtGox and Bitfloor): https://github.com/bitfloor/trader.nodejs

=== Java ===

basic [[Java Example]] on https://gist.github.com/2396722 hoping for many java forks and pull requests on github

XChange API : https://github.com/timmolter/XChange

mtgox-java: A Java API (based on Spring & Maven) for the MtGox bitcoin exchange WebSocket & HTTP services.
http://grantsparks.github.com/mtgox-java/

mtgox-api-v2-java: A Java lib for the v2 of the API https://github.com/adv0r/mtgox-api-v2-java
====Java:====

=== Javascript Firefox addon ===
* [https://github.com/joric/mtgox-ticker] firefox ticker addon

==See Also==

* [[MtGox|Mt. Gox]]
* [http://bitcointalk.org/index.php?topic=164404.0 MtGox API version 2: Unofficial Documentation]

MtGox/API/HTTP

2013-05-18T15:48:10Z

Neofutur:

Two versions of the HTTP API are currently available, see the following pages for details on the methods available for each:

* [[MtGox/API/HTTP/v0|Version 0]]
* [[MtGox/API/HTTP/v1|Version 1]]
* [[MtGox/API/HTTP/v2|Version 2]]

== Summary ==

'''The URL mtgox.com was changed to data.mtgox.com on March 19th 2013. https://bitcointalk.org/index.php?topic=150786.0'''

All HTTP API requests are sent to URLs beginning with <nowiki>https://data.mtgox.com/api/*</nowiki>. It allows placing orders, performing withdrawls, deposits, and other things. All responses are in [http://json.org/ JSON] format.

There is a [https://rubygems.org/gems/mtgox Ruby gem], [https://rubygems.org/gems/guten-mtgox guten-mtgox] and a [[Finance::MtGox|Perl module]] available for interacting with the HTTP API.

== Cache ==

All API methods are cached for 10 seconds. Do not request results more often than that, you might be blocked by the anti-DDoS filters.

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

== tonce et nonce ==

Each request to the private http PI need to have a nonce or a tonce

Please have a look at http://en.wikipedia.org/wiki/Cryptographic_nonce for explanations of what is a nonce .

See also http://en.wikipedia.org/wiki/System_time and http://en.wikipedia.org/wiki/Unix_time

The tonce is a variant of the nonce.

A few facts about nonce and tonce :

* The value of the nonce must always increase, if you use a very high value during your tests, you could have to generate new api keys to be allowed to get back to lower values

* The value of the tonce is based on the current timestamp, needs to be current microtime with +/- 10secs, and needs to be unique

* Your computer's time needs to be exact if you want to use the tonce parameter

* For the tonce you will use the time in microseconds , besed on http://en.wikipedia.org/wiki/Unix_time

* As long as your tonce value is unique and is within +/-10secs of now, it doesn't need to be incremental

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

'''basically the base64 string should contain:'''
* the binary representation of the api key id
* binary hmac-sha512 signature
* json data

api key looks like that: 12345678-abcd-1234-abcd-50286e649d5c

it's actually hexadecimal, it should be converted to binary

hash should then be appended (binary too) and then encode everything in base64

'''Warning : the API is no more accepting authentication by login/pass ( since 2012 march 1 ) , you _need_ to use an API key.'''

=== perl ===

'''IMPORTANT! This is a simplified perl module simply returning user info not a full API, it is shown simply for illustrative purposes for those wishing to developing there own modules from scratch.. or bots.. or other'''

'''IMPORTANT! This requires you compiled perl libwww with https support'''

<source lang="perl">

#!/usr/bin/perl

use strict;
use warnings;

use Time::HiRes qw(gettimeofday);
use MIME::Base64;
use Digest::SHA qw(hmac_sha512);

use JSON;
use LWP::UserAgent;

use Data::Dumper;

my $lwp = LWP::UserAgent->new;
$lwp->agent("perl $]");

my $json = JSON->new->allow_nonref;

my $secret = '_MTGOX API SECRET GET YOURS AT https://classic.mtgox.com/support/tradeAPI';
my $key = '_MTGOX API KEY GET YOURS AT https://classic.mtgox.com/support/tradeAPI';

## user code

my $request = genReq('/1/generic/private/info');
my $res = $lwp->request($request);

# Check the outcome of the response
if ($res->is_success) {
print Dumper($json->decode( $res->content ))."\n";
}
else { print $res->status_line, "\n"; }

exit 0;

## sub routines and helpers

sub genReq {
my ($uri) = shift;

my $req = HTTP::Request->new(POST => 'https://mtgox.com/api/'.$uri);
$req->content_type('application/x-www-form-urlencoded');
$req->content("nonce=".microtime());
$req->header('Rest-Key' => $key);
$req->header('Rest-Sign' => signReq($req->content(),$secret));

return $req;
};

sub signReq {
my ($content,$secret) = @_;
return encode_base64(hmac_sha512($content,decode_base64($secret)));
}

sub microtime { return sprintf "%d%06d", gettimeofday; }

</source>
=== PHP ===
<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, '', '&');

$prefix = '';
if (substr($path, 0, 2) == '2/') {
$prefix = substr($path, 2)."\0";
}

// generate the extra headers
$headers = array(
'Rest-Key: '.$key,
'Rest-Sign: '.base64_encode(hash_hmac('sha512', $prefix.$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);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

// 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 ===
<source lang="python">
from urllib import urlencode
import urllib2
import time
from hashlib import sha512
from hmac import HMAC
import base64
import json
def get_nonce():
return int(time.time()*100000)

def sign_data(secret, data):
return base64.b64encode(str(HMAC(secret, data, sha512).digest()))

class requester:
def __init__(self, auth_key, auth_secret):
self.auth_key = auth_key
self.auth_secret = base64.b64decode(auth_secret)

def build_query(self, req={}):
req["nonce"] = get_nonce()
post_data = urlencode(req)
headers = {}
headers["User-Agent"] = "GoxApi"
headers["Rest-Key"] = self.auth_key
headers["Rest-Sign"] = sign_data(self.auth_secret, post_data)
return (post_data, headers)

def perform(self, path, args):
data, headers = self.build_query(args)
req = urllib2.Request("https://mtgox.com/api/0/"+path, data, headers)
res = urllib2.urlopen(req, data)
return json.load(res)
</source>

=== Node.js ===
Generic [[Node.js Example]] trading library (supports MtGox and Bitfloor): https://github.com/bitfloor/trader.nodejs

=== Java ===

basic [[Java Example]] on https://gist.github.com/2396722 hoping for many java forks and pull requests on github

XChange API : https://github.com/timmolter/XChange

mtgox-java: A Java API (based on Spring & Maven) for the MtGox bitcoin exchange WebSocket & HTTP services.
http://grantsparks.github.com/mtgox-java/

mtgox-api-v2-java: A Java lib for the v2 of the API https://github.com/adv0r/mtgox-api-v2-java
====Java:====

=== Javascript Firefox addon ===
* [https://github.com/joric/mtgox-ticker] firefox ticker addon

==See Also==

* [[MtGox|Mt. Gox]]
* [http://bitcointalk.org/index.php?topic=164404.0 MtGox API version 2: Unofficial Documentation]

MtGox/API/HTTP/v1

2013-05-16T14:32:21Z

Neofutur: /* Your open orders */

MtGox/API/HTTP/v1

2013-05-16T14:32:01Z

Neofutur: /* Your open orders */

MtGox/API

2013-05-02T21:43:19Z

Neofutur:

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

Two APIs are currently available:

* [[MtGox/API/HTTP|HTTP API]]
* [[MtGox/API/Streaming|Streaming websocket API]]

__TOC__

==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 (100,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, NOK, CZK

==Date and time==

Most dates you will find in mtgox API are UNIX time

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

Most programming languages should have tools for managing those timestamps

==See Also==

* [http://bitcointalk.org/index.php?topic=164404.0 MtGox API version 2: Unofficial Documentation]

Category:History

2013-05-01T12:32:34Z

Neofutur:

== Important milestones of the Bitcoin project ==
=== 2008 ===
{| style="text-align: left"
|-
! width="8em" | August 18
|| Domain name "bitcoin.org" registered<ref>[https://bitcointalk.org/index.php?topic=103369.msg1135218#msg1135218 According to theymos], Satoshi registered bitcoin.org via https://www.anonymousspeech.com/ which allows to anonymously register domains.</ref>.
|-
! October 31
|| [http://article.gmane.org/gmane.comp.encryption.general/12588/ Bitcoin design paper] published
|-
! November 09
|| Bitcoin project registered at SourceForge.net
|}

=== 2009 ===
{| style="text-align: left"
|-
! width="8em" | January 3
|| [http://www.BlockExplorer.com/b/0 Genesis block] established at 18:15:05 GMT
|-
! January 11
|| Bitcoin v0.1 released and announced on the [http://www.mail-archive.com/cryptography@metzdowd.com/msg10152.html cryptography mailing list]
|-
! January 12
|| First Bitcoin transaction, [http://www.BlockExplorer.com/b/170 in block 170] - from [[Satoshi]] to Hal Finney<ref>[http://bitcointalk.org/index.php?topic=91806.msg1012234#msg1012234 Earliest Block With A Spend]</ref>.
|-
! October 5
|| Exchange rates [http://newlibertystandard.wetpaint.com/page/2009+Exchange+Rate published] by New Liberty Standard. $1 = 1,309.03 BTC (and [[User:theymos|theymos]] thought NLS was overcharging<ref>[http://bitcointalk.org/index.php?topic=104287.msg1143955#msg1143955 Historical Price Data for 2009]</ref>)
|-
! October 9
|| #bitcoin-dev channel registered on freenode IRC.
|-
! December 16
|| Bitcoin v0.2 released
|-
! December 30
|| First difficulty increase at 06:11:04 GMT
|}

=== 2010 ===
{| style="text-align: left"
|-
! width="8em" | February 6
|| [[Bitcoin Market]] established
|-
! May 21
|| laszlo first to buy pizza with Bitcoins agreeing upon paying 10,000 BTC for ~$25 worth of pizza courtesy of jercos<ref>[https://bitcointalk.org/index.php?topic=137.msg1195#msg1195 bitcointalk post] where laszlo confirmed having bought pizza</ref>
|-
! July 7
|| Bitcoin v0.3 released
|-
! July 11
|| Bitcoin v0.3 release mentioned on slashdot<ref>[http://news.slashdot.org/story/10/07/11/1747245/Bitcoin-Releases-Version-03 slashdot] metiones Bitcoin</ref>, bringing a large influx of new bitcoin users.
|-
! July 12
|| Beginning of a 10x increase in exchange value over a 5 day period, from about $0.008/BTC to $0.08/BTC
|-
! July 17
|| [[MtGox]] established
|-
! July 18
|| ArtForz generated his first block after establishing his personal OpenCL GPU hash farm
|-
! August 15
|| Bug in the bitcoin code allows a bad transaction into block 74638. Users quickly adopt fixed code and the "good" block chain overtook the bad one at a block height of 74691, 53 blocks later ([[Incidents#Value_overflow]]).
|-
! September 14
|| jgarzik [https://bitcointalk.org/index.php?topic=133.msg12921#msg12921 offered] 10,000 BTC (valued at ~$600-650) to puddinpop to open source their windows-based CUDA client
|-
! September 14
|| Block [http://blockexplorer.com/b/79764 79,764] is first to be mined using split allocation of the generation reward.
|-
! September 18
|| puddinpop [https://bitcointalk.org/index.php?topic=133.msg13135#msg13135 released] source to their windows-based CUDA client under MIT license
|-
! September 29
|| kermit [https://bitcointalk.org/index.php?topic=1306.0 discovered] a microtransactions exploit which precipitated the Bitcoin v0.3.13 release
|-
! October 01
|| First public OpenCL miner released
|-
! October 04
|| Original Bitcoin History wiki page (this page) established (ooh so meta) on Bitcoin.org's wiki.
|-
! October 07
|| Exchange rate started climbing up from $0.06/BTC after several flat months.
|-
! October 16
|| First recorded escrowed bitcoin trade conducted, between nanotube and Diablo-D3, escrowed by theymos.
|-
! October 17
|| [[Bitcoin_OTC|#bitcoin-otc]] trading channel established on freenode IRC.
|-
! October 28
|| First bitcoin short sale transaction initiated, with a loan of 100 BTC by nanotube to [[User:Kiba|kiba]], facilitated by the [[Bitcoin-otc|#bitcoin-otc]] market.
|-
! November 6
|| The [https://bitcointalk.org/index.php?topic=1672 Bitcoin economy passed US $1 million]. The MtGox price touched USD $0.50/BTC.
|-
! December 7
|| Bitcoind was compiled for the Nokia N900 mobile computer by doublec. The following day, ribuck sent him 0.42 BTC in the first portable-to-portable Bitcoin transaction.
|-
! December 9
|| The generation difficulty passed 10,000.
|-
|
|| First bitcoin call option contract sold, from nanotube to [[User:Sgornick|sgornick]], via the [[Bitcoin-otc|#bitcoin-otc]] market.
|-
! December 16
|| [http://mining.bitcoin.cz/ Bitcoin Pooled Mining], operated by slush, found its first block
|}

=== 2011 ===
{| style="text-align: left"
|-
! width="8em" | January 2
|| [[Tonal Bitcoin]] units standardized.
|-
! January 8
|| [[History of Bitcoin]] page (this page) created after replicating from original Bitcoin History page on Bitcoin.org.
|-
|
|| Bitcoin Pooled Mining reached a total of 10,000 Mhash/s
|-
! January 27
|| Largest numeric value ever traded for bitcoins thus far occurred on this date. Three currency bills from Zimbabwe, known as Zimdollars, were traded on [[Bitcoin-otc|#bitcoin-otc]] at the rate of 4 BTC for each of the one-hundred trillion dollar ($100,000,000,000,000) Zimbabwe notes<ref>Serial numbers for Zimdollars sold: AA1669317, AA1669318 and AA1669319</ref>
|-
! January 28
|| Block 105000 was generated. This means that 5.25 million bitcoins have been generated, which is just over one-quarter of the eventual total of nearly 21 million.
|-
! February 9
|| Bitcoin reached parity with the US dollar, touching $1 per BTC at [[MtGox]].
|-
! February 10
|| Bitcoin.org website struggles to handle [https://bitcointalk.org/index.php?topic=3444.0 traffic] resulting from mentions on Slashdot<ref>[http://news.slashdot.org/story/11/02/10/189246/Online-Only-Currency-BitCoin-Reaches-Dollar-Parity Online-Only Currency BitCoin Reaches Dollar Parity]</ref>, Hacker News and Twitter following the news that parity had been reached.
|-
! February 14
|| A vehicle was, for the first time, offered in exchange for a certain number of bitcoins<ref>[https://bitcointalk.org/index.php?topic=3485.0 Car for Sale - Australia]</ref>.
|-
! March 1
|| MagicalTux buy mtgox.com to historical owner Jed
|-
! March 6
|| Total Bitcoin network computation speed for a short time reached a new high of almost 900Ghash/sec, dropping to 500Ghash/sec soon after. Some speculate that this was due to some supercomputer or bot-net that joined the network ([http://bitcoin.atspace.com/mysteryminer.html mystery miner]).
|-
! March 18
|| BTC/USD exchange rate reaches a 6-week low point at almost $0.70/BTC, after what appeared to be a short burst of, possibly automated, BTC sales at progressively lower prices. BTC price had been declining since the February 9 high.
|-
! March 25
|| Difficulty decreased nearly 10%. A decrease has only occurred once before, and this decrease of nearly 10% was the largest.
|-
! March 27
|| The first market for exchanging bitcoins to and from the British Pound Sterling BTC/GBP, [[Britcoin]], opens.
|-
! March 31
|| The first market for exchanging bitcoins to and from Brazilian Reals, [[Bitcoin Brazil]], opens.
|-
! April 5
|| The first market for exchanging bitcoins to and from the Polish złoty, [[BitMarket.eu]], opens.
|-
! April 12
|| First bitcoin put option contract sold via the [[Bitcoin-otc|#bitcoin-otc]] market.
|-
! April 16
|| TIME does [http://techland.time.com/2011/04/16/online-cash-bitcoin-could-challenge-governments/ an article on Bitcoin].
|-
! April 23
|| BTC/USD exchange rate reaches and passes parity with the Euro (EUR) on [[MtGox]] exchange.
|-
|
|| BTC/USD exchange rate reaches and passes parity with the British Sterling Pound (GBP) on [[MtGox]] exchange.
|-
|
|| Value of the Bitcoin money stock at current exchange rate passes $10 million USD threshold.
|-
! April 27
|| [[VirWoX]] opens first market to trade bitcoins against a virtual currency on BTC/SL (Second Life Lindens) exchange.
|-
! April 30
|| The generation difficulty passed 100,000.
|-
! June 2
|| The exchange rate at [[MtGox]] touched 10 USD per BTC.
|-
! June 3
|| [[Tonal Bitcoin]] reached parity with the US cent, touching 1¢ per TBC at [[Bitcoin Market]].
|-
! June 8
|| The [[MtGox]] exchange rate peaked at 31.91 USD, at a "market capitalization" of about $206 M [http://bitcoin.stackexchange.com/questions/2047/market-capitalization-over-time].
|-
! June 12
|| The [[MtGox]] exchange rate briefly dropped to near 10 USD four days after the peak, in its largest percentage price retreat to date.
|-
! June 13
|| Forum user allinvain claimed to have had [http://forum.bitcoin.org/index.php?topic=16457.0 25,000 BTC stolen] from his Bitcoin wallet (approx. USD equivalent $375,000).
|-
! June 19
|| The MtGox database was compromised and the user table was leaked, containing details of 60,000 usernames, email addresses and password hashes, some of which were overly simple to brute force passwords.
|-
! June 19
|| Someone was able to access an admin account at MtGox and issue sell orders for hundreds of thousands of fake bitcoins, forcing the MtGox price down from $17.51 per bitcoin to $0.01. MtGox announced that these trades would be reversed. Trading was halted at MtGox for 7 days (and also briefly at TradeHill and Britcoin while their security was reviewed).
|-
! June 19
|| Some of the users on the leaked MtGox database had used the same username at MyBitcoin and had their passwords hacked. About 600 of them had their balance [http://forum.bitcoin.org/index.php?topic=22221.msg279396#msg279396 stolen from their MyBitcoin accounts]. One user lost over 2000 BTC.
|-
! June 20
|| The EFF announced that it was no longer accepting Bitcoin donations due to legal uncertainties.
|-
! June 24
|| The generation difficulty passed 1,000,000 with Block [http://blockexplorer.com/b/133056 133056].
|-
! July 19
|| "Let it go on record that at 4:05pm CET [19 July 2011], my manager Tadek was the first person in the world to receive [testnet] Bitcoins via NFC ;)" - Mike Hearn
|-
! July 22
|| [[BitCoins Mobile]], the first Bitcoin application for iPad was released by [http://www.intervex.net Intervex Digital].
|-
! July 30
|| [http://pastebin.com/raw.php?i=BUB3dygQ Tribute to Len Sassaman] included in the blockchain<ref>[http://bitcointalk.org/index.php?topic=33618.msg420597#msg420597 A Tribute to Len "rabbi" Sassama]</ref>.
|-
! August 20
|| First Bitcoin Conference and World Expo held, in NYC.<ref>[http://bitcoinme.com/index.php/conference/ New York Conference 2011]</ref>
|-
! August 23
|| [[P2Pool]], the first P2P decentralized pool, mines its first Bitcoin mainnet block (Block [http://blockexplorer.com/b/142312 142,312]).
|-
! August 30
|| Difficulty adjustment at block [http://blockexplorer.com/b/143136 143,136] marks the first back-to-back drop.
|-
! November 15
|| First CVE (CVE-2011-4447) assigned to a Bitcoin client exploit.
|-
! November 25
|| First European Bitcoin Conference in Prague, Czech Rep.<ref>[http://bitgroups.org/ Prague Conference 2011]</ref>
|-
! December 12
|| Largest amount of fees, to-date, in a single transaction, and most fees in a single block. A [http://blockexplorer.com/tx/1d7749c65c90c32f5e2c036217a2574f3f4403da39174626b246eefa620b58d9 transaction] paid 171 BTC in fees in [http://blockexplorer.com/b/157235 block 157235]<ref>[http://bitcointalk.org/index.php?topic=88423.msg973509#msg973509 Largest fee ever?]</ref>.
|}

=== 2012 ===
{| style="text-align: left"
|-
! width="8em" | March 1
|| Largest theft of bitcoins to-date occurred (near 50K BTC) after security breach at web host Linode.
|-
! width="8em" | April 1
|| Pay-to-script-hash ([[P2SH]]) as defined through [[BIP 0016]] goes live.
|-
! May 08
|| A single service, [[SatoshiDICE]] becomes responsible for over half the transaction volume on the Bitcoin blockchain.
|-
! June 3
|| Largest block (most transactions), to-date (June 3), is [http://BlockExplorer.com/b/181919 block 181919] with 1322 transactions<ref>[http://bitcointalk.org/index.php?topic=85353.msg939859#msg939859 Largest block to date]</ref>.
|-
! July 22
|| One millionth topic reply was posted on the unofficial [[Bitcoin Forum]] <ref>[https://bitcointalk.org/index.php?topic=94608.0 Topic about one millionth forum post]</ref>.
|-
! September 15-16
|| Bitcoin Conference in London <ref>[http://bitcoin2012.com/ London Conference 2012]</ref>.
|-
! September 27
|| Formation of the [[Bitcoin Foundation]].
|-
! November 28
|| Halving day. [http://blockexplorer.com/b/210000 Block 210,000] is the first with a block reward subsidy of only 25 BTC.
|-
! December 6
|| First Bitcoin exchange [https://bitcointalk.org/index.php?topic=129461.0 licensed "as a bank" in europe] (actually a PSP which is like a bank, without debt-money issuing).
|}

=== 2013 ===
{| style="text-align: left"
|-
! width="8em" | February 19
|| Bitcoin Client v0.8 released featuring improved download speed and [https://en.wikipedia.org/wiki/Bloom_filter Bloom Filtering]
|-
! February 28
|| The [[MtGox]] exchange rate broke the June 8 2011 peak of 31.91 USD. The first all time high since 601 days
|-
! March 12
|| A previously undiscovered protocol rule results in a [http://bitcoin.org/chainfork.html hard fork of the 0.8.0 reference client].
|-
! March 18
|| The United States federal agency charged with enforcing laws against money laundering (FinCEN) declares that Bitcoin users are subject to regulation only at the point of USD-BTC exchange.<ref>[http://arstechnica.com/tech-policy/2013/03/us-regulator-bitcoin-exchanges-must-comply-with-money-laundering-laws/ US regulator: Bitcoin exchanges must comply with money-laundering laws]</ref>
|-
! March 28
|| Total Bitcoin market cap passes $1 billion. <ref>http://spectrum.ieee.org/computing/networks/bitcoin-hits-1billion</ref>
|-
! April 1
|| Bitcoin price breaks 100 USD on [[MtGox]] and other major exchanges.
|-
|}

==See Also==

* [[Bitcoin Firsts]]
* [[Press]]

==References==
<references />

Category:History

2013-05-01T12:06:09Z

Neofutur:

== Important milestones of the Bitcoin project ==
=== 2008 ===
{| style="text-align: left"
|-
! width="8em" | August 18
|| Domain name "bitcoin.org" registered<ref>[https://bitcointalk.org/index.php?topic=103369.msg1135218#msg1135218 According to theymos], Satoshi registered bitcoin.org via https://www.anonymousspeech.com/ which allows to anonymously register domains.</ref>.
|-
! October 31
|| [http://article.gmane.org/gmane.comp.encryption.general/12588/ Bitcoin design paper] published
|-
! November 09
|| Bitcoin project registered at SourceForge.net
|}

=== 2009 ===
{| style="text-align: left"
|-
! width="8em" | January 3
|| [http://www.BlockExplorer.com/b/0 Genesis block] established at 18:15:05 GMT
|-
! January 11
|| Bitcoin v0.1 released and announced on the [http://www.mail-archive.com/cryptography@metzdowd.com/msg10152.html cryptography mailing list]
|-
! January 12
|| First Bitcoin transaction, [http://www.BlockExplorer.com/b/170 in block 170] - from [[Satoshi]] to Hal Finney<ref>[http://bitcointalk.org/index.php?topic=91806.msg1012234#msg1012234 Earliest Block With A Spend]</ref>.
|-
! October 5
|| Exchange rates [http://newlibertystandard.wetpaint.com/page/2009+Exchange+Rate published] by New Liberty Standard. $1 = 1,309.03 BTC (and [[User:theymos|theymos]] thought NLS was overcharging<ref>[http://bitcointalk.org/index.php?topic=104287.msg1143955#msg1143955 Historical Price Data for 2009]</ref>)
|-
! October 9
|| #bitcoin-dev channel registered on freenode IRC.
|-
! December 16
|| Bitcoin v0.2 released
|-
! December 30
|| First difficulty increase at 06:11:04 GMT
|}

=== 2010 ===
{| style="text-align: left"
|-
! width="8em" | February 6
|| [[Bitcoin Market]] established
|-
! May 21
|| laszlo first to buy pizza with Bitcoins agreeing upon paying 10,000 BTC for ~$25 worth of pizza courtesy of jercos<ref>[https://bitcointalk.org/index.php?topic=137.msg1195#msg1195 bitcointalk post] where laszlo confirmed having bought pizza</ref>
|-
! July 7
|| Bitcoin v0.3 released
|-
! July 11
|| Bitcoin v0.3 release mentioned on slashdot<ref>[http://news.slashdot.org/story/10/07/11/1747245/Bitcoin-Releases-Version-03 slashdot] metiones Bitcoin</ref>, bringing a large influx of new bitcoin users.
|-
! July 12
|| Beginning of a 10x increase in exchange value over a 5 day period, from about $0.008/BTC to $0.08/BTC
|-
! July 17
|| [[MtGox]] established
|-
! July 18
|| ArtForz generated his first block after establishing his personal OpenCL GPU hash farm
|-
! August 15
|| Bug in the bitcoin code allows a bad transaction into block 74638. Users quickly adopt fixed code and the "good" block chain overtook the bad one at a block height of 74691, 53 blocks later ([[Incidents#Value_overflow]]).
|-
! September 14
|| jgarzik [https://bitcointalk.org/index.php?topic=133.msg12921#msg12921 offered] 10,000 BTC (valued at ~$600-650) to puddinpop to open source their windows-based CUDA client
|-
! September 14
|| Block [http://blockexplorer.com/b/79764 79,764] is first to be mined using split allocation of the generation reward.
|-
! September 18
|| puddinpop [https://bitcointalk.org/index.php?topic=133.msg13135#msg13135 released] source to their windows-based CUDA client under MIT license
|-
! September 29
|| kermit [https://bitcointalk.org/index.php?topic=1306.0 discovered] a microtransactions exploit which precipitated the Bitcoin v0.3.13 release
|-
! October 01
|| First public OpenCL miner released
|-
! October 04
|| Original Bitcoin History wiki page (this page) established (ooh so meta) on Bitcoin.org's wiki.
|-
! October 07
|| Exchange rate started climbing up from $0.06/BTC after several flat months.
|-
! October 16
|| First recorded escrowed bitcoin trade conducted, between nanotube and Diablo-D3, escrowed by theymos.
|-
! October 17
|| [[Bitcoin_OTC|#bitcoin-otc]] trading channel established on freenode IRC.
|-
! October 28
|| First bitcoin short sale transaction initiated, with a loan of 100 BTC by nanotube to [[User:Kiba|kiba]], facilitated by the [[Bitcoin-otc|#bitcoin-otc]] market.
|-
! November 6
|| The [https://bitcointalk.org/index.php?topic=1672 Bitcoin economy passed US $1 million]. The MtGox price touched USD $0.50/BTC.
|-
! December 7
|| Bitcoind was compiled for the Nokia N900 mobile computer by doublec. The following day, ribuck sent him 0.42 BTC in the first portable-to-portable Bitcoin transaction.
|-
! December 9
|| The generation difficulty passed 10,000.
|-
|
|| First bitcoin call option contract sold, from nanotube to [[User:Sgornick|sgornick]], via the [[Bitcoin-otc|#bitcoin-otc]] market.
|-
! December 16
|| [http://mining.bitcoin.cz/ Bitcoin Pooled Mining], operated by slush, found its first block
|}

=== 2011 ===
{| style="text-align: left"
|-
! width="8em" | January 2
|| [[Tonal Bitcoin]] units standardized.
|-
! January 8
|| [[History of Bitcoin]] page (this page) created after replicating from original Bitcoin History page on Bitcoin.org.
|-
|
|| Bitcoin Pooled Mining reached a total of 10,000 Mhash/s
|-
! January 27
|| Largest numeric value ever traded for bitcoins thus far occurred on this date. Three currency bills from Zimbabwe, known as Zimdollars, were traded on [[Bitcoin-otc|#bitcoin-otc]] at the rate of 4 BTC for each of the one-hundred trillion dollar ($100,000,000,000,000) Zimbabwe notes<ref>Serial numbers for Zimdollars sold: AA1669317, AA1669318 and AA1669319</ref>
|-
! January 28
|| Block 105000 was generated. This means that 5.25 million bitcoins have been generated, which is just over one-quarter of the eventual total of nearly 21 million.
|-
! February 9
|| Bitcoin reached parity with the US dollar, touching $1 per BTC at [[MtGox]].
|-
! February 10
|| Bitcoin.org website struggles to handle [https://bitcointalk.org/index.php?topic=3444.0 traffic] resulting from mentions on Slashdot<ref>[http://news.slashdot.org/story/11/02/10/189246/Online-Only-Currency-BitCoin-Reaches-Dollar-Parity Online-Only Currency BitCoin Reaches Dollar Parity]</ref>, Hacker News and Twitter following the news that parity had been reached.
|-
! February 14
|| A vehicle was, for the first time, offered in exchange for a certain number of bitcoins<ref>[https://bitcointalk.org/index.php?topic=3485.0 Car for Sale - Australia]</ref>.
|-
! March 1
|| MagicalTux buy mtgox.com to historical owner Jed
|-
! March 6
|| Total Bitcoin network computation speed for a short time reached a new high of almost 900Ghash/sec, dropping to 500Ghash/sec soon after. Some speculate that this was due to some supercomputer or bot-net that joined the network ([http://bitcoin.atspace.com/mysteryminer.html mystery miner]).
|-
! March 18
|| BTC/USD exchange rate reaches a 6-week low point at almost $0.70/BTC, after what appeared to be a short burst of, possibly automated, BTC sales at progressively lower prices. BTC price had been declining since the February 9 high.
|-
! March 25
|| Difficulty decreased nearly 10%. A decrease has only occurred once before, and this decrease of nearly 10% was the largest.
|-
! March 27
|| The first market for exchanging bitcoins to and from the British Pound Sterling BTC/GBP, [[Britcoin]], opens.
|-
! March 31
|| The first market for exchanging bitcoins to and from Brazilian Reals, [[Bitcoin Brazil]], opens.
|-
! April 5
|| The first market for exchanging bitcoins to and from the Polish złoty, [[BitMarket.eu]], opens.
|-
! April 12
|| First bitcoin put option contract sold via the [[Bitcoin-otc|#bitcoin-otc]] market.
|-
! April 16
|| TIME does [http://techland.time.com/2011/04/16/online-cash-bitcoin-could-challenge-governments/ an article on Bitcoin].
|-
! April 23
|| BTC/USD exchange rate reaches and passes parity with the Euro (EUR) on [[MtGox]] exchange.
|-
|
|| BTC/USD exchange rate reaches and passes parity with the British Sterling Pound (GBP) on [[MtGox]] exchange.
|-
|
|| Value of the Bitcoin money stock at current exchange rate passes $10 million USD threshold.
|-
! April 27
|| [[VirWoX]] opens first market to trade bitcoins against a virtual currency on BTC/SL (Second Life Lindens) exchange.
|-
! April 30
|| The generation difficulty passed 100,000.
|-
! June 2
|| The exchange rate at [[MtGox]] touched 10 USD per BTC.
|-
! June 3
|| [[Tonal Bitcoin]] reached parity with the US cent, touching 1¢ per TBC at [[Bitcoin Market]].
|-
! June 8
|| The [[MtGox]] exchange rate peaked at 31.91 USD, at a "market capitalization" of about $206 M [http://bitcoin.stackexchange.com/questions/2047/market-capitalization-over-time].
|-
! June 12
|| The [[MtGox]] exchange rate briefly dropped to near 10 USD four days after the peak, in its largest percentage price retreat to date.
|-
! June 13
|| Forum user allinvain claimed to have had [http://forum.bitcoin.org/index.php?topic=16457.0 25,000 BTC stolen] from his Bitcoin wallet (approx. USD equivalent $375,000).
|-
! June 19
|| The MtGox database was compromised and the user table was leaked, containing details of 60,000 usernames, email addresses and password hashes, some of which were based on a highly vulnerable hashing algorithm.
|-
! June 19
|| Someone was able to access an admin account at MtGox and issue sell orders for hundreds of thousands of fake bitcoins, forcing the MtGox price down from $17.51 per bitcoin to $0.01. MtGox announced that these trades would be reversed. Trading was halted at MtGox for 7 days (and also briefly at TradeHill and Britcoin while their security was reviewed).
|-
! June 19
|| Some of the users on the leaked MtGox database had used the same username at MyBitcoin and had their passwords hacked. About 600 of them had their balance [http://forum.bitcoin.org/index.php?topic=22221.msg279396#msg279396 stolen from their MyBitcoin accounts]. One user lost over 2000 BTC.
|-
! June 20
|| The EFF announced that it was no longer accepting Bitcoin donations due to legal uncertainties.
|-
! June 24
|| The generation difficulty passed 1,000,000 with Block [http://blockexplorer.com/b/133056 133056].
|-
! July 19
|| "Let it go on record that at 4:05pm CET [19 July 2011], my manager Tadek was the first person in the world to receive [testnet] Bitcoins via NFC ;)" - Mike Hearn
|-
! July 22
|| [[BitCoins Mobile]], the first Bitcoin application for iPad was released by [http://www.intervex.net Intervex Digital].
|-
! July 30
|| [http://pastebin.com/raw.php?i=BUB3dygQ Tribute to Len Sassaman] included in the blockchain<ref>[http://bitcointalk.org/index.php?topic=33618.msg420597#msg420597 A Tribute to Len "rabbi" Sassama]</ref>.
|-
! August 20
|| First Bitcoin Conference and World Expo held, in NYC.<ref>[http://bitcoinme.com/index.php/conference/ New York Conference 2011]</ref>
|-
! August 23
|| [[P2Pool]], the first P2P decentralized pool, mines its first Bitcoin mainnet block (Block [http://blockexplorer.com/b/142312 142,312]).
|-
! August 30
|| Difficulty adjustment at block [http://blockexplorer.com/b/143136 143,136] marks the first back-to-back drop.
|-
! November 15
|| First CVE (CVE-2011-4447) assigned to a Bitcoin client exploit.
|-
! November 25
|| First European Bitcoin Conference in Prague, Czech Rep.<ref>[http://bitgroups.org/ Prague Conference 2011]</ref>
|-
! December 12
|| Largest amount of fees, to-date, in a single transaction, and most fees in a single block. A [http://blockexplorer.com/tx/1d7749c65c90c32f5e2c036217a2574f3f4403da39174626b246eefa620b58d9 transaction] paid 171 BTC in fees in [http://blockexplorer.com/b/157235 block 157235]<ref>[http://bitcointalk.org/index.php?topic=88423.msg973509#msg973509 Largest fee ever?]</ref>.
|}

=== 2012 ===
{| style="text-align: left"
|-
! width="8em" | March 1
|| Largest theft of bitcoins to-date occurred (near 50K BTC) after security breach at web host Linode.
|-
! width="8em" | April 1
|| Pay-to-script-hash ([[P2SH]]) as defined through [[BIP 0016]] goes live.
|-
! May 08
|| A single service, [[SatoshiDICE]] becomes responsible for over half the transaction volume on the Bitcoin blockchain.
|-
! June 3
|| Largest block (most transactions), to-date (June 3), is [http://BlockExplorer.com/b/181919 block 181919] with 1322 transactions<ref>[http://bitcointalk.org/index.php?topic=85353.msg939859#msg939859 Largest block to date]</ref>.
|-
! July 22
|| One millionth topic reply was posted on the unofficial [[Bitcoin Forum]] <ref>[https://bitcointalk.org/index.php?topic=94608.0 Topic about one millionth forum post]</ref>.
|-
! September 15-16
|| Bitcoin Conference in London <ref>[http://bitcoin2012.com/ London Conference 2012]</ref>.
|-
! September 27
|| Formation of the [[Bitcoin Foundation]].
|-
! November 28
|| Halving day. [http://blockexplorer.com/b/210000 Block 210,000] is the first with a block reward subsidy of only 25 BTC.
|-
! December 6
|| First Bitcoin exchange [https://bitcointalk.org/index.php?topic=129461.0 licensed "as a bank" in europe] (actually a PSP which is like a bank, without debt-money issuing).
|}

=== 2013 ===
{| style="text-align: left"
|-
! width="8em" | February 19
|| Bitcoin Client v0.8 released featuring improved download speed and [https://en.wikipedia.org/wiki/Bloom_filter Bloom Filtering]
|-
! February 28
|| The [[MtGox]] exchange rate broke the June 8 2011 peak of 31.91 USD. The first all time high since 601 days
|-
! March 12
|| A previously undiscovered protocol rule results in a [http://bitcoin.org/chainfork.html hard fork of the 0.8.0 reference client].
|-
! March 18
|| The United States federal agency charged with enforcing laws against money laundering (FinCEN) declares that Bitcoin users are subject to regulation only at the point of USD-BTC exchange.<ref>[http://arstechnica.com/tech-policy/2013/03/us-regulator-bitcoin-exchanges-must-comply-with-money-laundering-laws/ US regulator: Bitcoin exchanges must comply with money-laundering laws]</ref>
|-
! March 28
|| Total Bitcoin market cap passes $1 billion. <ref>http://spectrum.ieee.org/computing/networks/bitcoin-hits-1billion</ref>
|-
! April 1
|| Bitcoin price breaks 100 USD on [[MtGox]] and other major exchanges.
|-
|}

==See Also==

* [[Bitcoin Firsts]]
* [[Press]]

==References==
<references />

MtGox/API/HTTP/v1

2013-04-13T05:41:05Z

Neofutur: /* Multi Currency Ticker */

MtGox/API/HTTP/v0

2013-04-12T11:34:35Z

Neofutur: /* 0/bitcoin_tx */

Version 0 of the HTTP API is available at https://data.mtgox.com/api/0/.<br />
This API is becoming deprecated. You will see warning messages in the responses when you use this API.<br />
The URLs used as titles below already include the 0 as part of the url shown above. There is no need to repeat this.

== HTTP API version 0 methods ==

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

http://data.mtgox.com/api/0/data/getTrades.php?Currency=USD
http://data.mtgox.com/api/0/data/getTrades.php?Currency=USD&since=1

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://data.mtgox.com/api/0/data/getDepth.php?Currency=PLN
https://data.mtgox.com/api/0/data/getDepth.php?Currency=AUD
https://data.mtgox.com/api/0/data/getDepth.php?Currency=USD

<source lang="php">
{"asks":[[11.37998,22.89],[11.38,42.44592124],[11.3844,165],[11.599,1000]],"bids":[[10.7078,0.3],[10.70964,0.02024837],[10.70978,0.55822],[11.2903,2.8]]}
</source>

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

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

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

<source lang="php">
{
["usds"]=> "18.74737"
["btcs"]=> "0.01733"
}
</source>

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

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

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

returns a list of your open orders

you can omit the price to do a market order

This will return THE ENTIRE list of all open orders (after the cancel). <br>
Consider switching to V1/V2 if you do not need the complete list returned after every call to buyBTC.php <br>

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

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

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

returns a list of your open orders

you can omit the price to do a market order

This will return THE ENTIRE list of all open orders (after the cancel). <br>
Consider switching to V1/V2 if you do not need the complete list returned after every call to sellBTC.php <br>

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

https://data.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

This will return THE ENTIRE list of all open orders (after the cancel). <br>
Consider switching to V1/V2 if you do not need the complete list returned after every call to getOrders.php <br>
This will break apart "Not enough funds" Orders into two parts, the first part will be the order ID with the amount of the valid portion. The second part will have an "X" in front of the Order_ID (so it will be 1 char longer) with the amount of the INVALID portion. (that you can't afford)

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

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

POST data: oid=#&type=#

oid: Order ID

type: 1 for sell order or 2 for buy order

This will return THE ENTIRE list of all open orders (after the cancel).<br>
Consider switching to V1/V2 if you do not need the complete list returned after every call to cancelOrder.php

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

Most likely requires deposit privileges on the API Key.

https://data.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/redeemBtcPrivkey.php ===
used to redeem a private key via the API

Most likely requires deposit privileges on the API Key.

https://data.mtgox.com/api/0/redeemBtcPrivkey.php

* parameters :
"key":code
"keytype":"auto"
"description":description

* returns the btc adress and the total number of btcs in this private key

=== 0/withdraw.php ===
withdraw / Send BTC
You NEED Withdraw privileges set up to enabled on the API key.

https://data.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]] )
* pass no_instant=1 to use the bitcoin blockchain, even if the receiving address (btca) is on MtGox

* return code and status if successful
;Example response:
{u'status': u'Funds are on their way (bitcoin transaction: 2426f19cda3332b25d02daf2479bc558b243a0631584d75dd2bb8ee45f50a118)',
<br/> u'reference': u'58a9e537-e64a-4e66-bc45-31c1bdc3a91b'}
;Example error:
{u'error': u'Please enter a valid amount'}

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

You NEED Deposit privileges set up to enabled on the API key.

https://data.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

*pass POST data "ipn" to add an url that mtgox will ping whenever this new address receive funds
description ( see above ) is also required for ipn to work

* returns a bitcoin deposit address

;Example response:
{u'return': {u'addr': u'17A1vbzQ39o8cGNnpqx8UvXNrhqwAEP8wY'}, u'result': u'success'}

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

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

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

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

encoding is utf-8

=== 0/info.php ===

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

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

<source lang="php">
{
["Login"]=> "some_user"
["Index"]=> "111111"
["Rights"]=> {
[0]=> "get_info"
[1]=> "trade"
}
["Language"]=> "en_US"
["Created"]=> "2012-03-12 17:58:53"
["Last_Login"]=> "2012-07-10 09:19:56"
["Wallets"]=>
{
["BTC"]=>
{
["Balance"]=>
{
["value"]=> "0.01733000"
["value_int"]=> "1733000"
["display"]=> "0.01733000| BTC"
["display_short"]=> "0.02| BTC"
["currency"]=> "BTC"
}
["Operations"]=> ''
["Daily_Withdraw_Limit"]=>
{
["value"]=> "200.00000000"
["value_int"]=> "20000000000"
["display"]=> "200.00000000| BTC"
["display_short"]=> "200.00| BTC"
["currency"]=> "BTC"
}
["Monthly_Withdraw_Limit"]=> ''
["Max_Withdraw"]=>
{
["value"]=> "200.00000000"
["value_int"]=> "20000000000"
["display"]=> "200.00000000| BTC"
["display_short"]=> "200.00| BTC"
["currency"]=> "BTC"
}
}
["EUR"]=>
{
...
}
}
["Trade_Fee"]=> float(0.6)
}
</source>

=== 0/ticker ===

http://data.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

=== 0/bitcoin_tx ===

https://data.mtgox.com/api/0/bitcoin_tx.php

will show the list of all unconfirmed pending txs tracked by mtgox

when you place a tx on mtgox, we try to broadcast it, but if after 2 hours it hasn't appeared in the blockchain, it'll appear in this API

containing the raw signed tx number in base64

=== pending transactions ===

https://data.mtgox.com/api/0/bitcoin_tx.php

gives a list of the transaction numbers for transactions broadcasted by mtgox to the bitcoin network, but not yet included in a block

== Examples & Tools ==

=== Shell-type CLI ===

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

=== Perl module ===

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/

=== PHP Dashboard ===

https://github.com/Lexiks/MyBitBoard

=== PHP ticker and pricing tools ===

https://github.com/neofutur/bitcoin_simple_php_tools

=== Bash trade history ===

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

=== PHP Ticker & BTCGuild mining estimator ===

http://pastebin.com/pd0ZR4WY

MtGox/API/Streaming

2013-04-04T23:00:38Z

Neofutur:

Real time streaming data may be obtained over the streaming API, using [http://socket.io/ Socket.io] or the vanilla websocket

==websocket channel list ==

List of the public streaming channels :

https://mtgox.com/api/2/stream/list_public

==Connecting==

* Host: '''websocket.mtgox.com''' or '''socketio.mtgox.com'''
* Port: '''80''' or '''443''' ( ssl )
* Namespace: '''/mtgox''' (Including beginning slash)

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

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

and the websocket will give you updates in EUR currency

if you need need more than one currency, you can add currency symbols like that :

websocket.mtgox.com:80/mtgox?Currency=EUR,USD

websocket.mtgox.com:80/mtgox?Currency=EUR,USD,CHF

find the list of currency symbols on https://en.bitcoin.it/wiki/MtGox/API#Currency_Symbols

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

====Ticker====
Ticker messages contain the current inside Bid and Ask as well as daily highs, lows, and volume. The fields contained in the ticker match those defined in the version 1.0 API above. All fields contain <tt>currency</tt>, <tt>display</tt>, <tt>value</tt>, and <tt>value_int</tt> entries.
<source lang="javascript">
{
"channel":"d5f06780-30a8-4a48-a2f8-7ed181b4a13f",
"op":"private",
"origin":"broadcast",
"private":"ticker",
"ticker":{
"avg":{
"currency":"USD",
"display":"$2.26847",
"value":"2.26847",
"value_int":"226847"
},
"buy":{...},
"high":{...},
"last":{..},
"last_local":{...},
"last_orig":{...},
"low":{...},
"sell":{...},
"vol":{
"currency":"BTC",
"display":"118,696.02104208",
"value":"118696.02104208",
"value_int":"11869602104208"
},
"vwap":{...}
}
}
</source>

====Trade====
<source lang="javascript">{
"channel":"dbf1dee9-4f2e-4a08-8cb7-748919a71b21",
"op":"private",
"origin":"broadcast",
"private":"trade",
"trade":{
"amount":2.71,
"amount_int":"271000000",
"date":1310279340,
"item":"BTC",
"price":14.43,
"price_currency":"USD",
"price_int":"1443000",
"primary":"Y",
"properties":"limit, mixed_currency",
"tid":"1310279340877902",
"trade_type":"bid",
"type":"trade"
}
}
</source>

'''trade''' contains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| amount || the traded amount in item (BTC), float, deprecated
|-
| amount_int || the traded amount * 1E8
|-
| date || unix timestamp of trade
|-
| item || What was this trade about
|-
| price || price per unit, float, deprecated
|-
| price_int || price in smallest unit as integer (5 decimals of USD, 3 in case of JPY)
|-
| price_currency || currency in which trade was completed
|-
| properties || "market": the trade ate the whole order, "limit": the trade ate the order partially - some of the original order still exists
|-
| tid || Trade id (big integer, which is in fact trade timestamp in microseconds)
|-
| trade_type || Did this trade result from the execution of a bid or a ask?
|-
|}

====Depth====

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

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

'''depth''' contains the following:

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

|}

=== op:result ===

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

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

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

=== Private per-account messages ===

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

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

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

==== user_order ====

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

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

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

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

==== wallet ====

Updates to the user's wallet balance.

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

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

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

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

==== trade ====

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

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

Commands that can be sent without authentication

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

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

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

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

=== Authenticated commands ===

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

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

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

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

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

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

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

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

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

== examples ==

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

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

http://github.com/hookio

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

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

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

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

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

=== arbitrage ===
* https://github.com/goteppo/ArBit
* https://github.com/vbmithr/breakbot

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

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

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

https://github.com/sta/websocket-sharp

https://github.com/pipe2grep/GoxSharp

==See Also==

* [[MtGox/API/HTTP/v1]]
* [http://bitcointalk.org/index.php?topic=164404.0 MtGox API version 2: Unofficial Documentation]

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

MtGox/API/HTTP/v2

2013-03-30T05:47:36Z

Neofutur:

== API Version 2: ==
v2 api is found at :

'''https://data.mtgox.com/api/2/'''

official docs are on :

'''https://github.com/MtGox/mtgox-doc'''

The requested path (anything after the /2/) must now be included when you compute your hashed signature (Rest-Sign) for added security.

===== Explanation: =====

This is how it was done for version 1:

You have your params(post_data) = the word nonce, followed by the actual ''nonce'' integer (params = [(u'nonce',nonce)])

You have your header made up of ''Rest-Key'' (your API-KEY) and ''Rest-Sign'' (a hashed signature)

Rest-Sign is created by doing : base64encode( HMAC hash( base64decoded(API-secret), the nonce, with SHA512 digest))

'''What differs in version 2 is now''' : BEFORE the nonce, you are adding the '''relative path you are requesting'''(ie: BTCUSD/money/ticker) '''+ a NUL char (ascii code 0)'''.

So in my python code below which is very readable you can see everything remains the same as API v1 except now we are using api2postdatatohash = path + chr(0) + post_data #new way to hash for API 2, includes path + NUL.

=== Code Examples: ===

====C# :====

https://github.com/pipe2grep/GoxSharp C# lib for V2 API and socketIO

====Python====

http://pastebin.com/aXQfULyq<br />

====Perl====
https://en.bitcoin.it/wiki/MtGox/API/HTTP#PHP The Perl example on the main page is compatible with v2

MtGox/API/Streaming

2013-03-29T03:26:17Z

Neofutur: /* websocket tools */

Real time streaming data may be obtained over the streaming API, using [http://socket.io/ Socket.io] or the vanilla websocket

==Connecting==

* Host: '''websocket.mtgox.com''' or '''socketio.mtgox.com'''
* Port: '''80''' or '''443''' ( ssl )
* Namespace: '''/mtgox''' (Including beginning slash)

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

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

and the websocket will give you updates in EUR currency

if you need need more than one currency, you can add currency symbols like that :

websocket.mtgox.com:80/mtgox?Currency=EUR,USD

websocket.mtgox.com:80/mtgox?Currency=EUR,USD,CHF

find the list of currency symbols on https://en.bitcoin.it/wiki/MtGox/API#Currency_Symbols

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

====Ticker====
Ticker messages contain the current inside Bid and Ask as well as daily highs, lows, and volume. The fields contained in the ticker match those defined in the version 1.0 API above. All fields contain <tt>currency</tt>, <tt>display</tt>, <tt>value</tt>, and <tt>value_int</tt> entries.
<source lang="javascript">
{
"channel":"d5f06780-30a8-4a48-a2f8-7ed181b4a13f",
"op":"private",
"origin":"broadcast",
"private":"ticker",
"ticker":{
"avg":{
"currency":"USD",
"display":"$2.26847",
"value":"2.26847",
"value_int":"226847"
},
"buy":{...},
"high":{...},
"last":{..},
"last_local":{...},
"last_orig":{...},
"low":{...},
"sell":{...},
"vol":{
"currency":"BTC",
"display":"118,696.02104208",
"value":"118696.02104208",
"value_int":"11869602104208"
},
"vwap":{...}
}
}
</source>

====Trade====
<source lang="javascript">{
"channel":"dbf1dee9-4f2e-4a08-8cb7-748919a71b21",
"op":"private",
"origin":"broadcast",
"private":"trade",
"trade":{
"amount":2.71,
"amount_int":"271000000",
"date":1310279340,
"item":"BTC",
"price":14.43,
"price_currency":"USD",
"price_int":"1443000",
"primary":"Y",
"properties":"limit, mixed_currency",
"tid":"1310279340877902",
"trade_type":"bid",
"type":"trade"
}
}
</source>

'''trade''' contains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| amount || the traded amount in item (BTC), float, deprecated
|-
| amount_int || the traded amount * 1E8
|-
| date || unix timestamp of trade
|-
| item || What was this trade about
|-
| price || price per unit, float, deprecated
|-
| price_int || price in smallest unit as integer (5 decimals of USD, 3 in case of JPY)
|-
| price_currency || currency in which trade was completed
|-
| properties || "market": the trade ate the whole order, "limit": the trade ate the order partially - some of the original order still exists
|-
| tid || Trade id (big integer, which is in fact trade timestamp in microseconds)
|-
| trade_type || Did this trade result from the execution of a bid or a ask?
|-
|}

====Depth====

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

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

'''depth''' contains the following:

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

|}

=== op:result ===

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

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

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

=== Private per-account messages ===

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

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

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

==== user_order ====

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

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

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

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

==== wallet ====

Updates to the user's wallet balance.

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

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

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

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

==== trade ====

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

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

Commands that can be sent without authentication

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

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

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

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

=== Authenticated commands ===

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

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

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

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

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

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

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

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

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

== examples ==

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

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

http://github.com/hookio

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

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

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

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

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

=== arbitrage ===
* https://github.com/goteppo/ArBit
* https://github.com/vbmithr/breakbot

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

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

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

https://github.com/sta/websocket-sharp

https://github.com/pipe2grep/GoxSharp

==See Also==

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

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

MtGox/API/HTTP/v2

2013-03-29T03:24:49Z

Neofutur: /* C# : */

== API Version 2: ==
'''https://data.mtgox.com/api/2/'''<br />

The requested path (anything after the /2/) must now be included when you compute your hashed signature (Rest-Sign) for added security.<br />

===== Explanation: =====

This is how it was done for version 1: <br />

You have your params(post_data) = the word nonce, followed by the actual ''nonce'' integer (params = [(u'nonce',nonce)]) <br />

You have your header made up of ''Rest-Key'' (your API-KEY) and ''Rest-Sign'' (a hashed signature)<br />

Rest-Sign is created by doing : base64encode( HMAC hash( base64decoded(API-secret), the nonce, with SHA512 digest))<br />

'''What differs in version 2 is now''' : BEFORE the nonce, you are adding the '''relative path you are requesting'''(ie: BTCUSD/money/ticker) '''+ a NUL char (ascii code 0)'''.<br />

So in my python code below which is very readable you can see everything remains the same as API v1 except now we are using api2postdatatohash = path + chr(0) + post_data #new way to hash for API 2, includes path + NUL. <br />

=== Code Examples: ===

====C# :====

https://github.com/pipe2grep/GoxSharp C# lib for V2 API and socketIO

====Python====

http://pastebin.com/aXQfULyq<br />

====Perl====
https://en.bitcoin.it/wiki/MtGox/API/HTTP#PHP The Perl example on the main page is compatible with v2

MtGox/API/HTTP/v2

2013-03-29T03:22:43Z

Neofutur: /* Code Examples: */

== API Version 2: ==
'''https://data.mtgox.com/api/2/'''<br />

The requested path (anything after the /2/) must now be included when you compute your hashed signature (Rest-Sign) for added security.<br />

===== Explanation: =====

This is how it was done for version 1: <br />

You have your params(post_data) = the word nonce, followed by the actual ''nonce'' integer (params = [(u'nonce',nonce)]) <br />

You have your header made up of ''Rest-Key'' (your API-KEY) and ''Rest-Sign'' (a hashed signature)<br />

Rest-Sign is created by doing : base64encode( HMAC hash( base64decoded(API-secret), the nonce, with SHA512 digest))<br />

'''What differs in version 2 is now''' : BEFORE the nonce, you are adding the '''relative path you are requesting'''(ie: BTCUSD/money/ticker) '''+ a NUL char (ascii code 0)'''.<br />

So in my python code below which is very readable you can see everything remains the same as API v1 except now we are using api2postdatatohash = path + chr(0) + post_data #new way to hash for API 2, includes path + NUL. <br />

=== Code Examples: ===

====C# :====

https://github.com/pipe2grep/GoxSharp C# lib for V2 API and socketIO

http://pastebin.com/ZdfCszQr

====Python====

http://pastebin.com/aXQfULyq<br />

====Perl====
https://en.bitcoin.it/wiki/MtGox/API/HTTP#PHP The Perl example on the main page is compatible with v2

MtGox/API/HTTP/

2013-03-29T03:19:23Z

Neofutur: Created page with "see MtGox/API/HTTP"

see [[MtGox/API/HTTP]]

MtGox/API

2013-03-13T06:52:24Z

Neofutur: /* Date and time */

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

Two APIs are currently available:

* [[MtGox/API/HTTP|HTTP API]]
* [[MtGox/API/Streaming|Streaming websocket API]]

__TOC__

==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 (100,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

==Date and time==

Most dates you will find in mtgox API are UNIX time

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

Most programming languages should have tools for managing those timestamps

MtGox/API

2013-03-13T06:51:43Z

Neofutur:

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

Two APIs are currently available:

* [[MtGox/API/HTTP|HTTP API]]
* [[MtGox/API/Streaming|Streaming websocket API]]

__TOC__

==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 (100,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

==Date and time==

Most dates you will find in mtgox API are UNIX time
See http://en.wikipedia.org/wiki/Unix_time
Most programming languages should have tools for managing those timestamps

MtGox/API/HTTP/v0

2013-03-10T00:42:39Z

Neofutur: /* pending transactions */

Version 0 of the HTTP API is available at https://mtgox.com/api/0.

== HTTP API version 0 methods ==

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

http://data.mtgox.com/api/0/data/getTrades.php?Currency=USD
http://data.mtgox.com/api/0/data/getTrades.php?Currency=USD&since=1

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://data.mtgox.com/api/0/data/getDepth.php?Currency=PLN
https://data.mtgox.com/api/0/data/getDepth.php?Currency=AUD
https://data.mtgox.com/api/0/data/getDepth.php?Currency=USD

<source lang="php">
{"asks":[[11.37998,22.89],[11.38,42.44592124],[11.3844,165],[11.599,1000]],"bids":[[10.7078,0.3],[10.70964,0.02024837],[10.70978,0.55822],[11.2903,2.8]]}
</source>

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

<source lang="php">
{
["usds"]=> "18.74737"
["btcs"]=> "0.01733"
}
</source>

=== 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/redeemBtcPrivkey.php ===

used to redeem a private key via the API

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

* parameters :
"key":code
"keytype":"auto"
"description":description

* returns the btc adress and the total number of btcs in this private key

=== 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]] )
* pass no_instant=1 to use the bitcoin blockchain, even if the receiving address (btca) is on MtGox

* return code and status if successful
;Example response:
{u'status': u'Funds are on their way (bitcoin transaction: 2426f19cda3332b25d02daf2479bc558b243a0631584d75dd2bb8ee45f50a118)',
<br/> u'reference': u'58a9e537-e64a-4e66-bc45-31c1bdc3a91b'}

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

*pass POST data "ipn" to add an url that mtgox will ping whenever this new address receive funds
description ( see above ) is also required for ipn to work

* 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

encoding is utf-8

=== 0/info.php ===

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

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

<source lang="php">
{
["Login"]=> "some_user"
["Index"]=> "111111"
["Rights"]=> {
[0]=> "get_info"
[1]=> "trade"
}
["Language"]=> "en_US"
["Created"]=> "2012-03-12 17:58:53"
["Last_Login"]=> "2012-07-10 09:19:56"
["Wallets"]=>
{
["BTC"]=>
{
["Balance"]=>
{
["value"]=> "0.01733000"
["value_int"]=> "1733000"
["display"]=> "0.01733000| BTC"
["display_short"]=> "0.02| BTC"
["currency"]=> "BTC"
}
["Operations"]=> ''
["Daily_Withdraw_Limit"]=>
{
["value"]=> "200.00000000"
["value_int"]=> "20000000000"
["display"]=> "200.00000000| BTC"
["display_short"]=> "200.00| BTC"
["currency"]=> "BTC"
}
["Monthly_Withdraw_Limit"]=> ''
["Max_Withdraw"]=>
{
["value"]=> "200.00000000"
["value_int"]=> "20000000000"
["display"]=> "200.00000000| BTC"
["display_short"]=> "200.00| BTC"
["currency"]=> "BTC"
}
}
["EUR"]=>
{
...
}
}
["Trade_Fee"]=> float(0.6)
}
</source>

=== 0/ticker ===

http://data.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

=== 0/bitcoin_tx ===

https://data.mtgox.com/api/0/bitcoin_tx.php

will show the list of all unconfirmed pending txs tracked by mtgox

=== pending transactions ===

https://data.mtgox.com/api/0/bitcoin_tx.php

gives a list of the transaction numbers for transactions broadcasted by mtgox to the bitcoin network, but not yet included in a block

== Examples & Tools ==

=== Shell-type CLI ===

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

=== Perl module ===

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/

=== PHP Dashboard ===

https://github.com/Lexiks/MyBitBoard

=== PHP ticker and pricing tools ===

https://github.com/neofutur/bitcoin_simple_php_tools

=== Bash trade history ===

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

=== PHP Ticker & BTCGuild mining estimator ===

http://pastebin.com/pd0ZR4WY

MtGox/API/HTTP/v0

2013-03-10T00:42:03Z

Neofutur: /* 0/bitcoin_tx */

Version 0 of the HTTP API is available at https://mtgox.com/api/0.

== HTTP API version 0 methods ==

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

http://data.mtgox.com/api/0/data/getTrades.php?Currency=USD
http://data.mtgox.com/api/0/data/getTrades.php?Currency=USD&since=1

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://data.mtgox.com/api/0/data/getDepth.php?Currency=PLN
https://data.mtgox.com/api/0/data/getDepth.php?Currency=AUD
https://data.mtgox.com/api/0/data/getDepth.php?Currency=USD

<source lang="php">
{"asks":[[11.37998,22.89],[11.38,42.44592124],[11.3844,165],[11.599,1000]],"bids":[[10.7078,0.3],[10.70964,0.02024837],[10.70978,0.55822],[11.2903,2.8]]}
</source>

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

<source lang="php">
{
["usds"]=> "18.74737"
["btcs"]=> "0.01733"
}
</source>

=== 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/redeemBtcPrivkey.php ===

used to redeem a private key via the API

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

* parameters :
"key":code
"keytype":"auto"
"description":description

* returns the btc adress and the total number of btcs in this private key

=== 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]] )
* pass no_instant=1 to use the bitcoin blockchain, even if the receiving address (btca) is on MtGox

* return code and status if successful
;Example response:
{u'status': u'Funds are on their way (bitcoin transaction: 2426f19cda3332b25d02daf2479bc558b243a0631584d75dd2bb8ee45f50a118)',
<br/> u'reference': u'58a9e537-e64a-4e66-bc45-31c1bdc3a91b'}

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

*pass POST data "ipn" to add an url that mtgox will ping whenever this new address receive funds
description ( see above ) is also required for ipn to work

* 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

encoding is utf-8

=== 0/info.php ===

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

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

<source lang="php">
{
["Login"]=> "some_user"
["Index"]=> "111111"
["Rights"]=> {
[0]=> "get_info"
[1]=> "trade"
}
["Language"]=> "en_US"
["Created"]=> "2012-03-12 17:58:53"
["Last_Login"]=> "2012-07-10 09:19:56"
["Wallets"]=>
{
["BTC"]=>
{
["Balance"]=>
{
["value"]=> "0.01733000"
["value_int"]=> "1733000"
["display"]=> "0.01733000| BTC"
["display_short"]=> "0.02| BTC"
["currency"]=> "BTC"
}
["Operations"]=> ''
["Daily_Withdraw_Limit"]=>
{
["value"]=> "200.00000000"
["value_int"]=> "20000000000"
["display"]=> "200.00000000| BTC"
["display_short"]=> "200.00| BTC"
["currency"]=> "BTC"
}
["Monthly_Withdraw_Limit"]=> ''
["Max_Withdraw"]=>
{
["value"]=> "200.00000000"
["value_int"]=> "20000000000"
["display"]=> "200.00000000| BTC"
["display_short"]=> "200.00| BTC"
["currency"]=> "BTC"
}
}
["EUR"]=>
{
...
}
}
["Trade_Fee"]=> float(0.6)
}
</source>

=== 0/ticker ===

http://data.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

=== 0/bitcoin_tx ===

https://data.mtgox.com/api/0/bitcoin_tx.php

will show the list of all unconfirmed pending txs tracked by mtgox

=== pending transactions ===

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

gives a list of the transaction numbers for transactions broadcasted by mtgox to the bitcoin network, but not yet included in a block

== Examples & Tools ==

=== Shell-type CLI ===

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

=== Perl module ===

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/

=== PHP Dashboard ===

https://github.com/Lexiks/MyBitBoard

=== PHP ticker and pricing tools ===

https://github.com/neofutur/bitcoin_simple_php_tools

=== Bash trade history ===

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

=== PHP Ticker & BTCGuild mining estimator ===

http://pastebin.com/pd0ZR4WY

MtGox/API/HTTP/v0

2013-03-10T00:41:28Z

Neofutur: /* 0/ticker */

Version 0 of the HTTP API is available at https://mtgox.com/api/0.

== HTTP API version 0 methods ==

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

http://data.mtgox.com/api/0/data/getTrades.php?Currency=USD
http://data.mtgox.com/api/0/data/getTrades.php?Currency=USD&since=1

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://data.mtgox.com/api/0/data/getDepth.php?Currency=PLN
https://data.mtgox.com/api/0/data/getDepth.php?Currency=AUD
https://data.mtgox.com/api/0/data/getDepth.php?Currency=USD

<source lang="php">
{"asks":[[11.37998,22.89],[11.38,42.44592124],[11.3844,165],[11.599,1000]],"bids":[[10.7078,0.3],[10.70964,0.02024837],[10.70978,0.55822],[11.2903,2.8]]}
</source>

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

<source lang="php">
{
["usds"]=> "18.74737"
["btcs"]=> "0.01733"
}
</source>

=== 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/redeemBtcPrivkey.php ===

used to redeem a private key via the API

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

* parameters :
"key":code
"keytype":"auto"
"description":description

* returns the btc adress and the total number of btcs in this private key

=== 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]] )
* pass no_instant=1 to use the bitcoin blockchain, even if the receiving address (btca) is on MtGox

* return code and status if successful
;Example response:
{u'status': u'Funds are on their way (bitcoin transaction: 2426f19cda3332b25d02daf2479bc558b243a0631584d75dd2bb8ee45f50a118)',
<br/> u'reference': u'58a9e537-e64a-4e66-bc45-31c1bdc3a91b'}

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

*pass POST data "ipn" to add an url that mtgox will ping whenever this new address receive funds
description ( see above ) is also required for ipn to work

* 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

encoding is utf-8

=== 0/info.php ===

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

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

<source lang="php">
{
["Login"]=> "some_user"
["Index"]=> "111111"
["Rights"]=> {
[0]=> "get_info"
[1]=> "trade"
}
["Language"]=> "en_US"
["Created"]=> "2012-03-12 17:58:53"
["Last_Login"]=> "2012-07-10 09:19:56"
["Wallets"]=>
{
["BTC"]=>
{
["Balance"]=>
{
["value"]=> "0.01733000"
["value_int"]=> "1733000"
["display"]=> "0.01733000| BTC"
["display_short"]=> "0.02| BTC"
["currency"]=> "BTC"
}
["Operations"]=> ''
["Daily_Withdraw_Limit"]=>
{
["value"]=> "200.00000000"
["value_int"]=> "20000000000"
["display"]=> "200.00000000| BTC"
["display_short"]=> "200.00| BTC"
["currency"]=> "BTC"
}
["Monthly_Withdraw_Limit"]=> ''
["Max_Withdraw"]=>
{
["value"]=> "200.00000000"
["value_int"]=> "20000000000"
["display"]=> "200.00000000| BTC"
["display_short"]=> "200.00| BTC"
["currency"]=> "BTC"
}
}
["EUR"]=>
{
...
}
}
["Trade_Fee"]=> float(0.6)
}
</source>

=== 0/ticker ===

http://data.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

=== 0/bitcoin_tx ===

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

will show the list of all unconfirmed pending txs tracked by mtgox

=== pending transactions ===

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

gives a list of the transaction numbers for transactions broadcasted by mtgox to the bitcoin network, but not yet included in a block

== Examples & Tools ==

=== Shell-type CLI ===

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

=== Perl module ===

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/

=== PHP Dashboard ===

https://github.com/Lexiks/MyBitBoard

=== PHP ticker and pricing tools ===

https://github.com/neofutur/bitcoin_simple_php_tools

=== Bash trade history ===

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

=== PHP Ticker & BTCGuild mining estimator ===

http://pastebin.com/pd0ZR4WY

MtGox/API/HTTP/v0

2013-03-10T00:40:50Z

Neofutur:

Version 0 of the HTTP API is available at https://mtgox.com/api/0.

== HTTP API version 0 methods ==

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

http://data.mtgox.com/api/0/data/getTrades.php?Currency=USD
http://data.mtgox.com/api/0/data/getTrades.php?Currency=USD&since=1

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://data.mtgox.com/api/0/data/getDepth.php?Currency=PLN
https://data.mtgox.com/api/0/data/getDepth.php?Currency=AUD
https://data.mtgox.com/api/0/data/getDepth.php?Currency=USD

<source lang="php">
{"asks":[[11.37998,22.89],[11.38,42.44592124],[11.3844,165],[11.599,1000]],"bids":[[10.7078,0.3],[10.70964,0.02024837],[10.70978,0.55822],[11.2903,2.8]]}
</source>

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

<source lang="php">
{
["usds"]=> "18.74737"
["btcs"]=> "0.01733"
}
</source>

=== 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/redeemBtcPrivkey.php ===

used to redeem a private key via the API

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

* parameters :
"key":code
"keytype":"auto"
"description":description

* returns the btc adress and the total number of btcs in this private key

=== 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]] )
* pass no_instant=1 to use the bitcoin blockchain, even if the receiving address (btca) is on MtGox

* return code and status if successful
;Example response:
{u'status': u'Funds are on their way (bitcoin transaction: 2426f19cda3332b25d02daf2479bc558b243a0631584d75dd2bb8ee45f50a118)',
<br/> u'reference': u'58a9e537-e64a-4e66-bc45-31c1bdc3a91b'}

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

*pass POST data "ipn" to add an url that mtgox will ping whenever this new address receive funds
description ( see above ) is also required for ipn to work

* 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

encoding is utf-8

=== 0/info.php ===

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

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

<source lang="php">
{
["Login"]=> "some_user"
["Index"]=> "111111"
["Rights"]=> {
[0]=> "get_info"
[1]=> "trade"
}
["Language"]=> "en_US"
["Created"]=> "2012-03-12 17:58:53"
["Last_Login"]=> "2012-07-10 09:19:56"
["Wallets"]=>
{
["BTC"]=>
{
["Balance"]=>
{
["value"]=> "0.01733000"
["value_int"]=> "1733000"
["display"]=> "0.01733000| BTC"
["display_short"]=> "0.02| BTC"
["currency"]=> "BTC"
}
["Operations"]=> ''
["Daily_Withdraw_Limit"]=>
{
["value"]=> "200.00000000"
["value_int"]=> "20000000000"
["display"]=> "200.00000000| BTC"
["display_short"]=> "200.00| BTC"
["currency"]=> "BTC"
}
["Monthly_Withdraw_Limit"]=> ''
["Max_Withdraw"]=>
{
["value"]=> "200.00000000"
["value_int"]=> "20000000000"
["display"]=> "200.00000000| BTC"
["display_short"]=> "200.00| BTC"
["currency"]=> "BTC"
}
}
["EUR"]=>
{
...
}
}
["Trade_Fee"]=> float(0.6)
}
</source>

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

=== 0/bitcoin_tx ===

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

will show the list of all unconfirmed pending txs tracked by mtgox

=== pending transactions ===

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

gives a list of the transaction numbers for transactions broadcasted by mtgox to the bitcoin network, but not yet included in a block

== Examples & Tools ==

=== Shell-type CLI ===

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

=== Perl module ===

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/

=== PHP Dashboard ===

https://github.com/Lexiks/MyBitBoard

=== PHP ticker and pricing tools ===

https://github.com/neofutur/bitcoin_simple_php_tools

=== Bash trade history ===

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

=== PHP Ticker & BTCGuild mining estimator ===

http://pastebin.com/pd0ZR4WY

MtGox/API/HTTP/v1

2013-03-10T00:28:46Z

Neofutur: /* Multi Currency Ticker */

MtGox/API/HTTP/v1

2013-03-10T00:28:11Z

Neofutur:

MtGox/API/Streaming

2013-02-08T18:28:43Z

Neofutur:

Real time streaming data may be obtained over the streaming API, using [http://socket.io/ Socket.io] or the vanilla websocket

==Connecting==

* Host: '''websocket.mtgox.com''' or '''socketio.mtgox.com'''
* Port: '''80''' or '''443''' ( ssl )
* Namespace: '''/mtgox''' (Including beginning slash)

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

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

and the websocket will give you updates in EUR currency

if you need need more than one currency, you can add currency symbols like that :

websocket.mtgox.com:80/mtgox?Currency=EUR,USD

websocket.mtgox.com:80/mtgox?Currency=EUR,USD,CHF

find the list of currency symbols on https://en.bitcoin.it/wiki/MtGox/API#Currency_Symbols

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

====Ticker====
Ticker messages contain the current inside Bid and Ask as well as daily highs, lows, and volume. The fields contained in the ticker match those defined in the version 1.0 API above. All fields contain <tt>currency</tt>, <tt>display</tt>, <tt>value</tt>, and <tt>value_int</tt> entries.
<source lang="javascript">
{
"channel":"d5f06780-30a8-4a48-a2f8-7ed181b4a13f",
"op":"private",
"origin":"broadcast",
"private":"ticker",
"ticker":{
"avg":{
"currency":"USD",
"display":"$2.26847",
"value":"2.26847",
"value_int":"226847"
},
"buy":{...},
"high":{...},
"last":{..},
"last_local":{...},
"last_orig":{...},
"low":{...},
"sell":{...},
"vol":{
"currency":"BTC",
"display":"118,696.02104208",
"value":"118696.02104208",
"value_int":"11869602104208"
},
"vwap":{...}
}
}
</source>

====Trade====
<source lang="javascript">{
"channel":"dbf1dee9-4f2e-4a08-8cb7-748919a71b21",
"op":"private",
"origin":"broadcast",
"private":"trade",
"trade":{
"amount":2.71,
"amount_int":"271000000",
"date":1310279340,
"item":"BTC",
"price":14.43,
"price_currency":"USD",
"price_int":"1443000",
"primary":"Y",
"properties":"limit, mixed_currency",
"tid":"1310279340877902",
"trade_type":"bid",
"type":"trade"
}
}
</source>

'''trade''' contains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| amount || the traded amount in item (BTC), float, deprecated
|-
| amount_int || the traded amount * 1E8
|-
| date || unix timestamp of trade
|-
| item || What was this trade about
|-
| price || price per unit, float, deprecated
|-
| price_int || price in smallest unit as integer (5 decimals of USD, 3 in case of JPY)
|-
| price_currency || currency in which trade was completed
|-
| properties || "market": the trade ate the whole order, "limit": the trade ate the order partially - some of the original order still exists
|-
| tid || Trade id (big integer, which is in fact trade timestamp in microseconds)
|-
| trade_type || Did this trade result from the execution of a bid or a ask?
|-
|}

====Depth====

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

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

'''depth''' contains the following:

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

|}

=== op:result ===

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

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

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

=== Private per-account messages ===

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

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

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

==== user_order ====

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

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

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

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

==== wallet ====

Updates to the user's wallet balance.

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

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

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

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

==== trade ====

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

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

Commands that can be sent without authentication

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

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

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

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

=== Authenticated commands ===

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

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

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

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

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

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

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

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

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

== examples ==

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

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

http://github.com/hookio

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

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

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

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

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

=== arbitrage ===
* https://github.com/goteppo/ArBit
* https://github.com/vbmithr/breakbot

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

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

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

https://github.com/sta/websocket-sharp

==See Also==

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

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

MtGox/API/Streaming

2013-02-06T14:12:52Z

Neofutur: /* Connecting */

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

* Host: '''websocket.mtgox.com''' or '''socketio.mtgox.com'''
* Port: '''80''' or '''443''' ( ssl )
* Namespace: '''/mtgox''' (Including beginning slash)

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

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

and the websocket will give you updates in EUR currency

if you need need more than one currency, you can add currency symbols like that :

websocket.mtgox.com:80/mtgox?Currency=EUR,USD

websocket.mtgox.com:80/mtgox?Currency=EUR,USD,CHF

find the list of currency symbols on https://en.bitcoin.it/wiki/MtGox/API#Currency_Symbols

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

====Ticker====
Ticker messages contain the current inside Bid and Ask as well as daily highs, lows, and volume. The fields contained in the ticker match those defined in the version 1.0 API above. All fields contain <tt>currency</tt>, <tt>display</tt>, <tt>value</tt>, and <tt>value_int</tt> entries.
<source lang="javascript">
{
"channel":"d5f06780-30a8-4a48-a2f8-7ed181b4a13f",
"op":"private",
"origin":"broadcast",
"private":"ticker",
"ticker":{
"avg":{
"currency":"USD",
"display":"$2.26847",
"value":"2.26847",
"value_int":"226847"
},
"buy":{...},
"high":{...},
"last":{..},
"last_local":{...},
"last_orig":{...},
"low":{...},
"sell":{...},
"vol":{
"currency":"BTC",
"display":"118,696.02104208",
"value":"118696.02104208",
"value_int":"11869602104208"
},
"vwap":{...}
}
}
</source>

====Trade====
<source lang="javascript">{
"channel":"dbf1dee9-4f2e-4a08-8cb7-748919a71b21",
"op":"private",
"origin":"broadcast",
"private":"trade",
"trade":{
"amount":2.71,
"amount_int":"271000000",
"date":1310279340,
"item":"BTC",
"price":14.43,
"price_currency":"USD",
"price_int":"1443000",
"primary":"Y",
"properties":"limit, mixed_currency",
"tid":"1310279340877902",
"trade_type":"bid",
"type":"trade"
}
}
</source>

'''trade''' contains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| amount || the traded amount in item (BTC), float, deprecated
|-
| amount_int || the traded amount * 1E8
|-
| date || unix timestamp of trade
|-
| item || What was this trade about
|-
| price || price per unit, float, deprecated
|-
| price_int || price in smallest unit as integer (5 decimals of USD, 3 in case of JPY)
|-
| price_currency || currency in which trade was completed
|-
| properties || "market": the trade ate the whole order, "limit": the trade ate the order partially - some of the original order still exists
|-
| tid || Trade id (big integer, which is in fact trade timestamp in microseconds)
|-
| trade_type || Did this trade result from the execution of a bid or a ask?
|-
|}

====Depth====

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

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

'''depth''' contains the following:

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

|}

=== op:result ===

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

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

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

=== Private per-account messages ===

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

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

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

==== user_order ====

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

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

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

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

==== wallet ====

Updates to the user's wallet balance.

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

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

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

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

==== trade ====

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

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

Commands that can be sent without authentication

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

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

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

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

=== Authenticated commands ===

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

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

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

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

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

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

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

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

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

== examples ==

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

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

http://github.com/hookio

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

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

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

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

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

=== arbitrage ===
* https://github.com/goteppo/ArBit
* https://github.com/vbmithr/breakbot

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

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

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

https://github.com/sta/websocket-sharp

==See Also==

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

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

MtGox/API/Streaming

2013-02-06T13:38:03Z

Neofutur: /* websocket tools */

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

* Host: '''websocket.mtgox.com''' or '''socketio.mtgox.com'''
* Port: '''443''' or '''443''' ( ssl )
* Namespace: '''/mtgox''' (Including beginning slash)

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

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

and the websocket will give you updates in EUR currency

if you need need more than one currency, you can add currency symbols like that :

websocket.mtgox.com:80/mtgox?Currency=EUR,USD

websocket.mtgox.com:80/mtgox?Currency=EUR,USD,CHF

find the list of currency symbols on https://en.bitcoin.it/wiki/MtGox/API#Currency_Symbols

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

====Ticker====
Ticker messages contain the current inside Bid and Ask as well as daily highs, lows, and volume. The fields contained in the ticker match those defined in the version 1.0 API above. All fields contain <tt>currency</tt>, <tt>display</tt>, <tt>value</tt>, and <tt>value_int</tt> entries.
<source lang="javascript">
{
"channel":"d5f06780-30a8-4a48-a2f8-7ed181b4a13f",
"op":"private",
"origin":"broadcast",
"private":"ticker",
"ticker":{
"avg":{
"currency":"USD",
"display":"$2.26847",
"value":"2.26847",
"value_int":"226847"
},
"buy":{...},
"high":{...},
"last":{..},
"last_local":{...},
"last_orig":{...},
"low":{...},
"sell":{...},
"vol":{
"currency":"BTC",
"display":"118,696.02104208",
"value":"118696.02104208",
"value_int":"11869602104208"
},
"vwap":{...}
}
}
</source>

====Trade====
<source lang="javascript">{
"channel":"dbf1dee9-4f2e-4a08-8cb7-748919a71b21",
"op":"private",
"origin":"broadcast",
"private":"trade",
"trade":{
"amount":2.71,
"amount_int":"271000000",
"date":1310279340,
"item":"BTC",
"price":14.43,
"price_currency":"USD",
"price_int":"1443000",
"primary":"Y",
"properties":"limit, mixed_currency",
"tid":"1310279340877902",
"trade_type":"bid",
"type":"trade"
}
}
</source>

'''trade''' contains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| amount || the traded amount in item (BTC), float, deprecated
|-
| amount_int || the traded amount * 1E8
|-
| date || unix timestamp of trade
|-
| item || What was this trade about
|-
| price || price per unit, float, deprecated
|-
| price_int || price in smallest unit as integer (5 decimals of USD, 3 in case of JPY)
|-
| price_currency || currency in which trade was completed
|-
| properties || "market": the trade ate the whole order, "limit": the trade ate the order partially - some of the original order still exists
|-
| tid || Trade id (big integer, which is in fact trade timestamp in microseconds)
|-
| trade_type || Did this trade result from the execution of a bid or a ask?
|-
|}

====Depth====

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

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

'''depth''' contains the following:

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

|}

=== op:result ===

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

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

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

=== Private per-account messages ===

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

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

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

==== user_order ====

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

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

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

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

==== wallet ====

Updates to the user's wallet balance.

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

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

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

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

==== trade ====

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

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

Commands that can be sent without authentication

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

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

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

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

=== Authenticated commands ===

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

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

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

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

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

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

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

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

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

== examples ==

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

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

http://github.com/hookio

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

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

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

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

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

=== arbitrage ===
* https://github.com/goteppo/ArBit
* https://github.com/vbmithr/breakbot

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

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

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

https://github.com/sta/websocket-sharp

==See Also==

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

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

MtGox/API/Streaming

2013-02-06T13:34:21Z

Neofutur: /* Connecting */

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

* Host: '''websocket.mtgox.com''' or '''socketio.mtgox.com'''
* Port: '''443''' or '''443''' ( ssl )
* Namespace: '''/mtgox''' (Including beginning slash)

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

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

and the websocket will give you updates in EUR currency

if you need need more than one currency, you can add currency symbols like that :

websocket.mtgox.com:80/mtgox?Currency=EUR,USD

websocket.mtgox.com:80/mtgox?Currency=EUR,USD,CHF

find the list of currency symbols on https://en.bitcoin.it/wiki/MtGox/API#Currency_Symbols

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

====Ticker====
Ticker messages contain the current inside Bid and Ask as well as daily highs, lows, and volume. The fields contained in the ticker match those defined in the version 1.0 API above. All fields contain <tt>currency</tt>, <tt>display</tt>, <tt>value</tt>, and <tt>value_int</tt> entries.
<source lang="javascript">
{
"channel":"d5f06780-30a8-4a48-a2f8-7ed181b4a13f",
"op":"private",
"origin":"broadcast",
"private":"ticker",
"ticker":{
"avg":{
"currency":"USD",
"display":"$2.26847",
"value":"2.26847",
"value_int":"226847"
},
"buy":{...},
"high":{...},
"last":{..},
"last_local":{...},
"last_orig":{...},
"low":{...},
"sell":{...},
"vol":{
"currency":"BTC",
"display":"118,696.02104208",
"value":"118696.02104208",
"value_int":"11869602104208"
},
"vwap":{...}
}
}
</source>

====Trade====
<source lang="javascript">{
"channel":"dbf1dee9-4f2e-4a08-8cb7-748919a71b21",
"op":"private",
"origin":"broadcast",
"private":"trade",
"trade":{
"amount":2.71,
"amount_int":"271000000",
"date":1310279340,
"item":"BTC",
"price":14.43,
"price_currency":"USD",
"price_int":"1443000",
"primary":"Y",
"properties":"limit, mixed_currency",
"tid":"1310279340877902",
"trade_type":"bid",
"type":"trade"
}
}
</source>

'''trade''' contains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| amount || the traded amount in item (BTC), float, deprecated
|-
| amount_int || the traded amount * 1E8
|-
| date || unix timestamp of trade
|-
| item || What was this trade about
|-
| price || price per unit, float, deprecated
|-
| price_int || price in smallest unit as integer (5 decimals of USD, 3 in case of JPY)
|-
| price_currency || currency in which trade was completed
|-
| properties || "market": the trade ate the whole order, "limit": the trade ate the order partially - some of the original order still exists
|-
| tid || Trade id (big integer, which is in fact trade timestamp in microseconds)
|-
| trade_type || Did this trade result from the execution of a bid or a ask?
|-
|}

====Depth====

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

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

'''depth''' contains the following:

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

|}

=== op:result ===

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

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

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

=== Private per-account messages ===

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

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

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

==== user_order ====

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

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

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

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

==== wallet ====

Updates to the user's wallet balance.

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

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

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

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

==== trade ====

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

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

Commands that can be sent without authentication

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

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

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

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

=== Authenticated commands ===

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

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

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

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

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

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

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

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

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

== examples ==

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

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

http://github.com/hookio

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

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

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

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

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

=== arbitrage ===
* https://github.com/goteppo/ArBit
* https://github.com/vbmithr/breakbot

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

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

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

==See Also==

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

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

MtGox/API/Streaming

2013-02-06T13:05:04Z

Neofutur: /* the Currency parameter */

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

* Host: '''socketio.mtgox.com'''
* Port: '''443'''
* Namespace: '''/mtgox''' (Including beginning slash)

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

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

and the websocket will give you updates in EUR currency

if you need need more than one currency, you can add currency symbols like that :

websocket.mtgox.com:80/mtgox?Currency=EUR,USD

websocket.mtgox.com:80/mtgox?Currency=EUR,USD,CHF

find the list of currency symbols on https://en.bitcoin.it/wiki/MtGox/API#Currency_Symbols

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

====Ticker====
Ticker messages contain the current inside Bid and Ask as well as daily highs, lows, and volume. The fields contained in the ticker match those defined in the version 1.0 API above. All fields contain <tt>currency</tt>, <tt>display</tt>, <tt>value</tt>, and <tt>value_int</tt> entries.
<source lang="javascript">
{
"channel":"d5f06780-30a8-4a48-a2f8-7ed181b4a13f",
"op":"private",
"origin":"broadcast",
"private":"ticker",
"ticker":{
"avg":{
"currency":"USD",
"display":"$2.26847",
"value":"2.26847",
"value_int":"226847"
},
"buy":{...},
"high":{...},
"last":{..},
"last_local":{...},
"last_orig":{...},
"low":{...},
"sell":{...},
"vol":{
"currency":"BTC",
"display":"118,696.02104208",
"value":"118696.02104208",
"value_int":"11869602104208"
},
"vwap":{...}
}
}
</source>

====Trade====
<source lang="javascript">{
"channel":"dbf1dee9-4f2e-4a08-8cb7-748919a71b21",
"op":"private",
"origin":"broadcast",
"private":"trade",
"trade":{
"amount":2.71,
"amount_int":"271000000",
"date":1310279340,
"item":"BTC",
"price":14.43,
"price_currency":"USD",
"price_int":"1443000",
"primary":"Y",
"properties":"limit, mixed_currency",
"tid":"1310279340877902",
"trade_type":"bid",
"type":"trade"
}
}
</source>

'''trade''' contains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| amount || the traded amount in item (BTC), float, deprecated
|-
| amount_int || the traded amount * 1E8
|-
| date || unix timestamp of trade
|-
| item || What was this trade about
|-
| price || price per unit, float, deprecated
|-
| price_int || price in smallest unit as integer (5 decimals of USD, 3 in case of JPY)
|-
| price_currency || currency in which trade was completed
|-
| properties || "market": the trade ate the whole order, "limit": the trade ate the order partially - some of the original order still exists
|-
| tid || Trade id (big integer, which is in fact trade timestamp in microseconds)
|-
| trade_type || Did this trade result from the execution of a bid or a ask?
|-
|}

====Depth====

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

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

'''depth''' contains the following:

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

|}

=== op:result ===

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

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

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

=== Private per-account messages ===

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

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

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

==== user_order ====

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

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

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

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

==== wallet ====

Updates to the user's wallet balance.

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

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

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

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

==== trade ====

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

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

Commands that can be sent without authentication

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

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

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

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

=== Authenticated commands ===

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

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

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

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

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

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

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

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

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

== examples ==

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

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

http://github.com/hookio

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

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

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

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

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

=== arbitrage ===
* https://github.com/goteppo/ArBit
* https://github.com/vbmithr/breakbot

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

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

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

==See Also==

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

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

MtGox/API/Streaming

2013-02-06T13:04:46Z

Neofutur: /* the Currency parameter */

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

* Host: '''socketio.mtgox.com'''
* Port: '''443'''
* Namespace: '''/mtgox''' (Including beginning slash)

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

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

and the websocket will give you updates in EUR currency

if you need need more than one currency, you can add currency symbols like that :

websocket.mtgox.com:80/mtgox?Currency=EUR,USD
websocket.mtgox.com:80/mtgox?Currency=EUR,USD,CHF

find the list of currency symbols on https://en.bitcoin.it/wiki/MtGox/API#Currency_Symbols

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

====Ticker====
Ticker messages contain the current inside Bid and Ask as well as daily highs, lows, and volume. The fields contained in the ticker match those defined in the version 1.0 API above. All fields contain <tt>currency</tt>, <tt>display</tt>, <tt>value</tt>, and <tt>value_int</tt> entries.
<source lang="javascript">
{
"channel":"d5f06780-30a8-4a48-a2f8-7ed181b4a13f",
"op":"private",
"origin":"broadcast",
"private":"ticker",
"ticker":{
"avg":{
"currency":"USD",
"display":"$2.26847",
"value":"2.26847",
"value_int":"226847"
},
"buy":{...},
"high":{...},
"last":{..},
"last_local":{...},
"last_orig":{...},
"low":{...},
"sell":{...},
"vol":{
"currency":"BTC",
"display":"118,696.02104208",
"value":"118696.02104208",
"value_int":"11869602104208"
},
"vwap":{...}
}
}
</source>

====Trade====
<source lang="javascript">{
"channel":"dbf1dee9-4f2e-4a08-8cb7-748919a71b21",
"op":"private",
"origin":"broadcast",
"private":"trade",
"trade":{
"amount":2.71,
"amount_int":"271000000",
"date":1310279340,
"item":"BTC",
"price":14.43,
"price_currency":"USD",
"price_int":"1443000",
"primary":"Y",
"properties":"limit, mixed_currency",
"tid":"1310279340877902",
"trade_type":"bid",
"type":"trade"
}
}
</source>

'''trade''' contains the following:

:{| class="wikitable"
|-
! Name !! Value
|-
| amount || the traded amount in item (BTC), float, deprecated
|-
| amount_int || the traded amount * 1E8
|-
| date || unix timestamp of trade
|-
| item || What was this trade about
|-
| price || price per unit, float, deprecated
|-
| price_int || price in smallest unit as integer (5 decimals of USD, 3 in case of JPY)
|-
| price_currency || currency in which trade was completed
|-
| properties || "market": the trade ate the whole order, "limit": the trade ate the order partially - some of the original order still exists
|-
| tid || Trade id (big integer, which is in fact trade timestamp in microseconds)
|-
| trade_type || Did this trade result from the execution of a bid or a ask?
|-
|}

====Depth====

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

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

'''depth''' contains the following:

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

|}

=== op:result ===

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

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

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

=== Private per-account messages ===

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

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

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

==== user_order ====

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

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

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

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

==== wallet ====

Updates to the user's wallet balance.

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

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

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

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

==== trade ====

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

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

Commands that can be sent without authentication

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

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

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

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

=== Authenticated commands ===

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

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

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

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

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

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

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

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

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

== examples ==

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

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

http://github.com/hookio

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

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

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

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

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

=== arbitrage ===
* https://github.com/goteppo/ArBit
* https://github.com/vbmithr/breakbot

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

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

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

==See Also==

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

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

MtGox/API/HTTP/v1

2013-02-03T00:37:45Z

Neofutur: