Bitcoin Wiki - User contributions [en]

P2Pool

2012-01-25T15:23:15Z

Brec: /* Stales */ link PPLNS to page containing explanation

[[Image:P2pool_chain.png‎|thumb|350px|right|Visualization of the P2Pool share chain]]
P2Pool is a decentralized [[Bitcoin]] [[Bitcoin Pool|mining pool]] that works by creating a peer-to-peer network of miner nodes.

Decentralized payout pooling solves the problem of centralized mining pools degrading the decentralization of Bitcoin, avoids the risk of hard to detect theft by pool operators, and has better fundamental resistance to DoS attacks than centralized pools.

Miners are configured to connect to a P2Pool node that can be run locally, alongside the miner. P2Pool users must run a full Bitcoin node which serves the purpose of independently validating transactions and the Bitcoin blockchain. P2Pool also supports merged mining and several alternative blockchains.

P2Pool nodes work on a chain of shares similar to Bitcoin's blockchain. Each node works on a block that includes payouts to the previous shares' owners and the node itself, which can also result in a share if it meets P2Pool's difficulty.

Because of the importance of strengthening Bitcoin's decentralization some Bitcoin supporters donate to P2Pool miners, resulting in returns above 100% of the expected reward.

== Overview ==

P2Pool shares form a "sharechain" with each share referencing the previous share's hash. Each share contains a standard Bitcoin block header, some P2Pool-specific data that is used to compute the generation transaction (total subsidy, payout script of this share, a nonce, the previous share's hash, and the current target for shares), and a Merkle branch linking that generation transaction to the block header's Merkle hash.

The chain continuously regulates its target to keep generation around one share every ten seconds, just as Bitcoin regulates it to generate one block every ten minutes.

Unlike Bitcoin, nodes do not know the entire chain - instead they only hold the last 8640 shares (the last day's worth). In order to prevent an attacker from working on a chain in secret and then releasing it, overriding the existing chain, chains are judged by how much work they have since a point in the past. To ascertain that the work has been done since that point, nodes look at the Bitcoin blocks that the shares reference, establishing a provable timestamp. (If a share points to a block, it was definitely made after that block was made.)

=== Payout logic ===

Each share contains a generation transaction that pays to the previous ''n'' shares, where ''n'' is the number of shares whose total work is equal to 3 times the average work required to solve a block, or 8640, whichever is smaller. Payouts are weighted based on the amount of work each share took to solve, which is proportional to the p2pool difficulty at that time.

The block reward (currently 50BTC) and the transaction fees are combined and apportioned according to these rules:

A subsidy of 0.5% is sent to the node that solved the block in order to discourage not sharing solutions that qualify as a block. (A miner with the aim to harm others could withhold the block, thereby preventing anybody from getting paid. He can NOT redirect the payout to himself.) The remaining 99.5% is distributed evenly to miners based on work done recently.

In the event that a share qualifies as a block, this generation transaction is exposed to the Bitcoin network and takes effect, transferring each node its payout.

=== Stales ===

P2Pool stales don't work the same way as stales on centralized pools. On a centralized pool a stale is work which is too old to be accepted by the pool's Bitcoin node; this kind of stale is very rare in P2Pool because each user runs their own local bitcoind.

On P2Pool stales refer to shares which can't make it into the sharechain. Because the sharechain is 60 times faster than the Bitcoin chain many stales are common and expected. However, because the payout is [[Comparison_of_mining_pools|PPLNS]] only your stale rate relative to other nodes is relevant; the absolute rate is not.

There are two reported kinds of stales in P2Pool: "DEAD ON ARRIVAL" shares and orphan shares. Dead shares were too old by the time they arrived at your local P2Pool. Very high dead rates can indicate miner misconfiguration. Orphan shares are shares which were not extended by the rest of the P2Pool network, because some other miner's share was accepted first. Very high orphan rates may indicate network connectivity problems.

The P2Pool console output shows your relative stale rate compared to other P2Pool miners in the 'Own efficiency' column:
<pre>
2012-01-07 20:57:51.797420 Pool stales: 13% Own: 13±2% Own efficiency: 100±2%
</pre>

When you first start P2Pool claimed efficiency will be low and the error bounds on this estimate will be large, but as it runs the numbers will converge to their correct values.

If your efficiency is unusually low, make sure your network connection isn't overloaded, that your miners support long polling and are not set to work for excessive amounts of time, and that your bitcoind has multiple connections.

== Joining the pool ==

Follow these steps to join the pool:

* Run Bitcoin with the RPC interface enabled: put rpcuser=USER, rpcpassword=PASS, and server=1 in bitcoin.conf
** Bitcoin 0.5 or later is required
** It's important that your Bitcoin client be fully synchronized before starting. It's also better if you have the Bitcoin port forwarded
* Download p2pool:
** Windows binary: See http://forum.bitcoin.org/index.php?topic=18313.0
** Source download: https://github.com/forrestv/p2pool/tags
** git: git clone git://github.com/forrestv/p2pool.git
* Run p2pool: (See below for additional options.)
** Windows py2exe: run_p2pool.exe USER PASS
** Source: python run_p2pool.py USER PASS
* Run a miner daemon with long polling connecting to 127.0.0.1 (or the IP of the host running p2pool if you're mining remotely) on port 9332 with any username and password
** cgminer -O u:p -o http://127.0.0.1:9332/

Dependencies if running from source:
* Python 2.6 or higher
* python-argparse for Python 2.6 and lower
* Twisted (Ubuntu package python-twisted)

=== Miners ===

This is all for the latest p2pool version, as it includes several new workarounds. With all miners, using a high FPS target (100?) or a low aggression, and waiting for p2pool to completely start (line shows > 17000 shares) helps a lot with reducing stales.

P2Pool uses higher difficulty shares than most centralized pools, so you'll see fewer shares reported. This is normal and doesn't reduce your payments. It's also normal to see longpoll messages once per every ten seconds on average.

==== Works as-is ====

===== cgminer =====
Works very well as is.

===== ufasoft =====
Works as is.

===== DiabloMiner =====
Works fine after commit 3b731b9b54.

==== Needs patch to reduce stales ====

===== Poclbm =====
Waits a full second between long polls.

GitHub fork: https://github.com/forrestv/poclbm
Pull request: https://github.com/m0mchil/poclbm/pull/41
<pre>git clone git://github.com/forrestv/poclbm.git
cd poclbm
git checkout fast_long_polling</pre>

Windows binary: http://u.forre.st/u/wodukkea/p2pool-poclbm_win32_5590e7c.zip

===== Phoenix =====
(Works fine after commit 8263f65!)

Has a similar bug (waiting a full second).

GitHub fork: https://github.com/forrestv/phoenix-miner

Windows binary: http://u.forre.st/u/ycvzejfm/phoenix-miner-fba48d2-5.zip

==== Not-compatible ====

===== puddinpop's RPC Miners =====
Does not have long polling so will not work at all.

=== Option Reference ===
<pre>
usage: run_p2pool.py [-h] [--version] [--net {bitcoin, litecoin, namecoin}]
[--testnet] [--debug] [-a ADDRESS] [--logfile LOGFILE]
[--merged-url MERGED_URL]
[--merged-userpass MERGED_USERPASS]
[--give-author DONATION_PERCENTAGE] [--p2pool-port PORT]
[-n ADDR[:PORT]] [--disable-upnp] [-w PORT]
[-f FEE_PERCENTAGE] [--bitcoind-address BITCOIND_ADDRESS]
[--bitcoind-rpc-port BITCOIND_RPC_PORT]
[--bitcoind-p2p-port BITCOIND_P2P_PORT]
[BITCOIND_RPCUSER] BITCOIND_RPCPASSWORD

p2pool (version 31cbeea)

optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--net {bitcoin, litecoin, namecoin}
use specified network (default: bitcoin)
--testnet use the network's testnet
--debug enable debugging mode
-a ADDRESS, --address ADDRESS
generate payouts to this address (default: <address
requested from bitcoind>)
--logfile LOGFILE log to this file (default: data/<NET>/log)
--merged-url MERGED_URL
call getauxblock on this url to get work for merged
mining (example: http://127.0.0.1:10332/)
--merged-userpass MERGED_USERPASS
use this user and password when requesting merged
mining work (example: ncuser:ncpass)
--give-author DONATION_PERCENTAGE
donate this percentage of work to author of p2pool
(default: 0.5)
--disable-upnp don't attempt to use UPnP to forward p2pool's P2P port
from the Internet to this computer

p2pool interface:
--p2pool-port PORT use port PORT to listen for connections (forward this
port from your router!) (default: bitcoin:9333,
litecoin:9338, namecoin:9334)
-n ADDR[:PORT], --p2pool-node ADDR[:PORT]
connect to existing p2pool node at ADDR listening on
port PORT (defaults to default p2pool P2P port) in
addition to builtin addresses

worker interface:
-w PORT, --worker-port PORT
listen on PORT for RPC connections from miners
(default: bitcoin:9332, litecoin:9327, namecoin:9331)
-f FEE_PERCENTAGE, --fee FEE_PERCENTAGE
charge workers mining to their own bitcoin address (by
setting their miner's username to a bitcoin address)
this percentage fee to mine on your p2pool instance.
Amount displayed at http://127.0.0.1:WORKER_PORT/fee
(default: 0)

bitcoind interface:
--bitcoind-address BITCOIND_ADDRESS
connect to this address (default: 127.0.0.1)
--bitcoind-rpc-port BITCOIND_RPC_PORT
connect to JSON-RPC interface at this port (default:
bitcoin:8332, litecoin:9332, namecoin:8332)
--bitcoind-p2p-port BITCOIND_P2P_PORT
connect to P2P interface at this port (default:
bitcoin:8333, litecoin:9333, namecoin:8334)
BITCOIND_RPCUSER bitcoind RPC interface username (default: <empty>)
BITCOIND_RPCPASSWORD bitcoind RPC interface password
</pre>

== Protocol description ==

P2Pool's protocol mirrors Bitcoin's P2P protocol in many ways. It uses the same framing (prefix, command, length, checksum, payload) and similar commands:

* '''version''' - sent to establish a connection - contains (''version'', ''services'', ''addr_to'', ''addr_from'', ''nonce'', ''sub_version'', ''mode'', ''best_share_hash'')
* '''setmode''' - sent to update the ''mode'' sent in the '''version''' message - contains (''mode'')
* '''ping''' - sent to keep connection alive - contains ()
* '''addrme''' - request that the receiving node send out an addr for the sending node - contains (''port'')
* '''addrs''' - broadcast list of nodes' addresses - contains (''addrs'')
* '''getaddrs''' - request that the receiving node send ''count'' addrs - contains (''count'')
* '''getshares''' - request that the receiving node send the shares referenced by ''hashes'' and ''parents'' of their parents, stopping at any share referenced by ''stops'' - contains (''hashes'', ''parents'', ''stops'')
* '''shares''' - broadcast message of the contents of shares - contains (''shares'')

==History==

This project was announced on June 17, 2011 by Forrest Voight<ref>[https://forum.bitcoin.org/index.php?topic=18313.0 p2pool: Decentralized, DoS-resistant, Hop-Proof - Now active on mainnet!]</ref>.

The began testing against mainnet in mid-July, 2011. The pool was reviewed on a [[Bitcoin Miner]] post on July 26, 2011<ref>[http://www.bitcoinminer.com/post/8101660461 P2Pool Decentralized Pool Nearly Ready For Prime-Time]</ref>.

The software author's address for donations can be found in the signature section of his [http://forum.bitcoin.org/index.php?action=profile;u=6447 forum profile].

==Donating to P2Pool miners==
In order to encourage people to mine to P2Pool you can donate to the recent miners in proportion using a sendmany:

E.g. a bash script to donate 10 btc is:
<pre>
~/src/bitcoin/src/bitcoind sendmany "" "$(GET http://forre.st:9332/patron_sendmany?total=10.0)"
</pre>

You can replace "" with "accountname" if you want to pay from some specific bitcoind account, and you can replace forre.st with 127.0.0.1 if you're running a P2Pool node locally, so you don't have to trust that the URL gives accurate figures.

If you decide to donate you should announce it on the forums so that your donations provide the most incentive possible.

==See Also==

* [[Comparison of mining pools]]
* [[Pooled Mining]]

==External Links==

* [http://forum.bitcoin.org/index.php?topic=18313.0 P2Pool forum]
* [https://github.com/forrestv/p2pool p2pool] project on GitHub
* {{Freenode IRC|p2pool}} discussion and support

==References==
<references />

[[Category:Pool Operators]]

P2Pool

2012-01-25T15:15:46Z

Brec: /* Stales */

[[Image:P2pool_chain.png‎|thumb|350px|right|Visualization of the P2Pool share chain]]
P2Pool is a decentralized [[Bitcoin]] [[Bitcoin Pool|mining pool]] that works by creating a peer-to-peer network of miner nodes.

Decentralized payout pooling solves the problem of centralized mining pools degrading the decentralization of Bitcoin, avoids the risk of hard to detect theft by pool operators, and has better fundamental resistance to DoS attacks than centralized pools.

Miners are configured to connect to a P2Pool node that can be run locally, alongside the miner. P2Pool users must run a full Bitcoin node which serves the purpose of independently validating transactions and the Bitcoin blockchain. P2Pool also supports merged mining and several alternative blockchains.

P2Pool nodes work on a chain of shares similar to Bitcoin's blockchain. Each node works on a block that includes payouts to the previous shares' owners and the node itself, which can also result in a share if it meets P2Pool's difficulty.

Because of the importance of strengthening Bitcoin's decentralization some Bitcoin supporters donate to P2Pool miners, resulting in returns above 100% of the expected reward.

== Overview ==

P2Pool shares form a "sharechain" with each share referencing the previous share's hash. Each share contains a standard Bitcoin block header, some P2Pool-specific data that is used to compute the generation transaction (total subsidy, payout script of this share, a nonce, the previous share's hash, and the current target for shares), and a Merkle branch linking that generation transaction to the block header's Merkle hash.

The chain continuously regulates its target to keep generation around one share every ten seconds, just as Bitcoin regulates it to generate one block every ten minutes.

Unlike Bitcoin, nodes do not know the entire chain - instead they only hold the last 8640 shares (the last day's worth). In order to prevent an attacker from working on a chain in secret and then releasing it, overriding the existing chain, chains are judged by how much work they have since a point in the past. To ascertain that the work has been done since that point, nodes look at the Bitcoin blocks that the shares reference, establishing a provable timestamp. (If a share points to a block, it was definitely made after that block was made.)

=== Payout logic ===

Each share contains a generation transaction that pays to the previous ''n'' shares, where ''n'' is the number of shares whose total work is equal to 3 times the average work required to solve a block, or 8640, whichever is smaller. Payouts are weighted based on the amount of work each share took to solve, which is proportional to the p2pool difficulty at that time.

The block reward (currently 50BTC) and the transaction fees are combined and apportioned according to these rules:

A subsidy of 0.5% is sent to the node that solved the block in order to discourage not sharing solutions that qualify as a block. (A miner with the aim to harm others could withhold the block, thereby preventing anybody from getting paid. He can NOT redirect the payout to himself.) The remaining 99.5% is distributed evenly to miners based on work done recently.

In the event that a share qualifies as a block, this generation transaction is exposed to the Bitcoin network and takes effect, transferring each node its payout.

=== Stales ===

P2Pool stales don't work the same way as stales on centralized pools. On a centralized pool a stale is work which is too old to be accepted by the pool's Bitcoin node; this kind of stale is very rare in P2Pool because each user runs their own local bitcoind.

On P2Pool stales refer to shares which can't make it into the sharechain. Because the sharechain is 60 times faster than the Bitcoin chain many stales are common and expected. However, because the payout is PPLNS only your stale rate relative to other nodes is relevant; the absolute rate is not.

There are two reported kinds of stales in P2Pool: "DEAD ON ARRIVAL" shares and orphan shares. Dead shares were too old by the time they arrived at your local P2Pool. Very high dead rates can indicate miner misconfiguration. Orphan shares are shares which were not extended by the rest of the P2Pool network, because some other miner's share was accepted first. Very high orphan rates may indicate network connectivity problems.

The P2Pool console output shows your relative stale rate compared to other P2Pool miners in the 'Own efficiency' column:
<pre>
2012-01-07 20:57:51.797420 Pool stales: 13% Own: 13±2% Own efficiency: 100±2%
</pre>

When you first start P2Pool claimed efficiency will be low and the error bounds on this estimate will be large, but as it runs the numbers will converge to their correct values.

If your efficiency is unusually low, make sure your network connection isn't overloaded, that your miners support long polling and are not set to work for excessive amounts of time, and that your bitcoind has multiple connections.

== Joining the pool ==

Follow these steps to join the pool:

* Run Bitcoin with the RPC interface enabled: put rpcuser=USER, rpcpassword=PASS, and server=1 in bitcoin.conf
** Bitcoin 0.5 or later is required
** It's important that your Bitcoin client be fully synchronized before starting. It's also better if you have the Bitcoin port forwarded
* Download p2pool:
** Windows binary: See http://forum.bitcoin.org/index.php?topic=18313.0
** Source download: https://github.com/forrestv/p2pool/tags
** git: git clone git://github.com/forrestv/p2pool.git
* Run p2pool: (See below for additional options.)
** Windows py2exe: run_p2pool.exe USER PASS
** Source: python run_p2pool.py USER PASS
* Run a miner daemon with long polling connecting to 127.0.0.1 (or the IP of the host running p2pool if you're mining remotely) on port 9332 with any username and password
** cgminer -O u:p -o http://127.0.0.1:9332/

Dependencies if running from source:
* Python 2.6 or higher
* python-argparse for Python 2.6 and lower
* Twisted (Ubuntu package python-twisted)

=== Miners ===

This is all for the latest p2pool version, as it includes several new workarounds. With all miners, using a high FPS target (100?) or a low aggression, and waiting for p2pool to completely start (line shows > 17000 shares) helps a lot with reducing stales.

P2Pool uses higher difficulty shares than most centralized pools, so you'll see fewer shares reported. This is normal and doesn't reduce your payments. It's also normal to see longpoll messages once per every ten seconds on average.

==== Works as-is ====

===== cgminer =====
Works very well as is.

===== ufasoft =====
Works as is.

===== DiabloMiner =====
Works fine after commit 3b731b9b54.

==== Needs patch to reduce stales ====

===== Poclbm =====
Waits a full second between long polls.

GitHub fork: https://github.com/forrestv/poclbm
Pull request: https://github.com/m0mchil/poclbm/pull/41
<pre>git clone git://github.com/forrestv/poclbm.git
cd poclbm
git checkout fast_long_polling</pre>

Windows binary: http://u.forre.st/u/wodukkea/p2pool-poclbm_win32_5590e7c.zip

===== Phoenix =====
(Works fine after commit 8263f65!)

Has a similar bug (waiting a full second).

GitHub fork: https://github.com/forrestv/phoenix-miner

Windows binary: http://u.forre.st/u/ycvzejfm/phoenix-miner-fba48d2-5.zip

==== Not-compatible ====

===== puddinpop's RPC Miners =====
Does not have long polling so will not work at all.

=== Option Reference ===
<pre>
usage: run_p2pool.py [-h] [--version] [--net {bitcoin, litecoin, namecoin}]
[--testnet] [--debug] [-a ADDRESS] [--logfile LOGFILE]
[--merged-url MERGED_URL]
[--merged-userpass MERGED_USERPASS]
[--give-author DONATION_PERCENTAGE] [--p2pool-port PORT]
[-n ADDR[:PORT]] [--disable-upnp] [-w PORT]
[-f FEE_PERCENTAGE] [--bitcoind-address BITCOIND_ADDRESS]
[--bitcoind-rpc-port BITCOIND_RPC_PORT]
[--bitcoind-p2p-port BITCOIND_P2P_PORT]
[BITCOIND_RPCUSER] BITCOIND_RPCPASSWORD

p2pool (version 31cbeea)

optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--net {bitcoin, litecoin, namecoin}
use specified network (default: bitcoin)
--testnet use the network's testnet
--debug enable debugging mode
-a ADDRESS, --address ADDRESS
generate payouts to this address (default: <address
requested from bitcoind>)
--logfile LOGFILE log to this file (default: data/<NET>/log)
--merged-url MERGED_URL
call getauxblock on this url to get work for merged
mining (example: http://127.0.0.1:10332/)
--merged-userpass MERGED_USERPASS
use this user and password when requesting merged
mining work (example: ncuser:ncpass)
--give-author DONATION_PERCENTAGE
donate this percentage of work to author of p2pool
(default: 0.5)
--disable-upnp don't attempt to use UPnP to forward p2pool's P2P port
from the Internet to this computer

p2pool interface:
--p2pool-port PORT use port PORT to listen for connections (forward this
port from your router!) (default: bitcoin:9333,
litecoin:9338, namecoin:9334)
-n ADDR[:PORT], --p2pool-node ADDR[:PORT]
connect to existing p2pool node at ADDR listening on
port PORT (defaults to default p2pool P2P port) in
addition to builtin addresses

worker interface:
-w PORT, --worker-port PORT
listen on PORT for RPC connections from miners
(default: bitcoin:9332, litecoin:9327, namecoin:9331)
-f FEE_PERCENTAGE, --fee FEE_PERCENTAGE
charge workers mining to their own bitcoin address (by
setting their miner's username to a bitcoin address)
this percentage fee to mine on your p2pool instance.
Amount displayed at http://127.0.0.1:WORKER_PORT/fee
(default: 0)

bitcoind interface:
--bitcoind-address BITCOIND_ADDRESS
connect to this address (default: 127.0.0.1)
--bitcoind-rpc-port BITCOIND_RPC_PORT
connect to JSON-RPC interface at this port (default:
bitcoin:8332, litecoin:9332, namecoin:8332)
--bitcoind-p2p-port BITCOIND_P2P_PORT
connect to P2P interface at this port (default:
bitcoin:8333, litecoin:9333, namecoin:8334)
BITCOIND_RPCUSER bitcoind RPC interface username (default: <empty>)
BITCOIND_RPCPASSWORD bitcoind RPC interface password
</pre>

== Protocol description ==

P2Pool's protocol mirrors Bitcoin's P2P protocol in many ways. It uses the same framing (prefix, command, length, checksum, payload) and similar commands:

* '''version''' - sent to establish a connection - contains (''version'', ''services'', ''addr_to'', ''addr_from'', ''nonce'', ''sub_version'', ''mode'', ''best_share_hash'')
* '''setmode''' - sent to update the ''mode'' sent in the '''version''' message - contains (''mode'')
* '''ping''' - sent to keep connection alive - contains ()
* '''addrme''' - request that the receiving node send out an addr for the sending node - contains (''port'')
* '''addrs''' - broadcast list of nodes' addresses - contains (''addrs'')
* '''getaddrs''' - request that the receiving node send ''count'' addrs - contains (''count'')
* '''getshares''' - request that the receiving node send the shares referenced by ''hashes'' and ''parents'' of their parents, stopping at any share referenced by ''stops'' - contains (''hashes'', ''parents'', ''stops'')
* '''shares''' - broadcast message of the contents of shares - contains (''shares'')

==History==

This project was announced on June 17, 2011 by Forrest Voight<ref>[https://forum.bitcoin.org/index.php?topic=18313.0 p2pool: Decentralized, DoS-resistant, Hop-Proof - Now active on mainnet!]</ref>.

The began testing against mainnet in mid-July, 2011. The pool was reviewed on a [[Bitcoin Miner]] post on July 26, 2011<ref>[http://www.bitcoinminer.com/post/8101660461 P2Pool Decentralized Pool Nearly Ready For Prime-Time]</ref>.

The software author's address for donations can be found in the signature section of his [http://forum.bitcoin.org/index.php?action=profile;u=6447 forum profile].

==Donating to P2Pool miners==
In order to encourage people to mine to P2Pool you can donate to the recent miners in proportion using a sendmany:

E.g. a bash script to donate 10 btc is:
<pre>
~/src/bitcoin/src/bitcoind sendmany "" "$(GET http://forre.st:9332/patron_sendmany?total=10.0)"
</pre>

You can replace "" with "accountname" if you want to pay from some specific bitcoind account, and you can replace forre.st with 127.0.0.1 if you're running a P2Pool node locally, so you don't have to trust that the URL gives accurate figures.

If you decide to donate you should announce it on the forums so that your donations provide the most incentive possible.

==See Also==

* [[Comparison of mining pools]]
* [[Pooled Mining]]

==External Links==

* [http://forum.bitcoin.org/index.php?topic=18313.0 P2Pool forum]
* [https://github.com/forrestv/p2pool p2pool] project on GitHub
* {{Freenode IRC|p2pool}} discussion and support

==References==
<references />

[[Category:Pool Operators]]

P2Pool

2012-01-25T15:13:54Z

Brec:

[[Image:P2pool_chain.png‎|thumb|350px|right|Visualization of the P2Pool share chain]]
P2Pool is a decentralized [[Bitcoin]] [[Bitcoin Pool|mining pool]] that works by creating a peer-to-peer network of miner nodes.

Decentralized payout pooling solves the problem of centralized mining pools degrading the decentralization of Bitcoin, avoids the risk of hard to detect theft by pool operators, and has better fundamental resistance to DoS attacks than centralized pools.

Miners are configured to connect to a P2Pool node that can be run locally, alongside the miner. P2Pool users must run a full Bitcoin node which serves the purpose of independently validating transactions and the Bitcoin blockchain. P2Pool also supports merged mining and several alternative blockchains.

P2Pool nodes work on a chain of shares similar to Bitcoin's blockchain. Each node works on a block that includes payouts to the previous shares' owners and the node itself, which can also result in a share if it meets P2Pool's difficulty.

Because of the importance of strengthening Bitcoin's decentralization some Bitcoin supporters donate to P2Pool miners, resulting in returns above 100% of the expected reward.

== Overview ==

P2Pool shares form a "sharechain" with each share referencing the previous share's hash. Each share contains a standard Bitcoin block header, some P2Pool-specific data that is used to compute the generation transaction (total subsidy, payout script of this share, a nonce, the previous share's hash, and the current target for shares), and a Merkle branch linking that generation transaction to the block header's Merkle hash.

The chain continuously regulates its target to keep generation around one share every ten seconds, just as Bitcoin regulates it to generate one block every ten minutes.

Unlike Bitcoin, nodes do not know the entire chain - instead they only hold the last 8640 shares (the last day's worth). In order to prevent an attacker from working on a chain in secret and then releasing it, overriding the existing chain, chains are judged by how much work they have since a point in the past. To ascertain that the work has been done since that point, nodes look at the Bitcoin blocks that the shares reference, establishing a provable timestamp. (If a share points to a block, it was definitely made after that block was made.)

=== Payout logic ===

Each share contains a generation transaction that pays to the previous ''n'' shares, where ''n'' is the number of shares whose total work is equal to 3 times the average work required to solve a block, or 8640, whichever is smaller. Payouts are weighted based on the amount of work each share took to solve, which is proportional to the p2pool difficulty at that time.

The block reward (currently 50BTC) and the transaction fees are combined and apportioned according to these rules:

A subsidy of 0.5% is sent to the node that solved the block in order to discourage not sharing solutions that qualify as a block. (A miner with the aim to harm others could withhold the block, thereby preventing anybody from getting paid. He can NOT redirect the payout to himself.) The remaining 99.5% is distributed evenly to miners based on work done recently.

In the event that a share qualifies as a block, this generation transaction is exposed to the Bitcoin network and takes effect, transferring each node its payout.

=== Stales ===

P2Pool stales don't work the same way as stales on centralized pools. On a centralized pool a stale is work which is too old to be accepted by the pool's Bitcoin node; this kind of stale is very rare in P2Pool because each user runs their own local bitcoind.

On P2Pool stales refer to shares which can't make it into the sharechain. Because the sharechain is 60 times faster than the Bitcoin chain many stales are common and expected. However, because the payout is PPLNS the absolute amount of of stales is irrelevant, only your stale rate relative to other nodes.

There are two reported kinds of stales in P2Pool: "DEAD ON ARRIVAL" shares and orphan shares. Dead shares were too old by the time they arrived at your local P2Pool. Very high dead rates can indicate miner misconfiguration. Orphan shares are shares which were not extended by the rest of the P2Pool network, because some other miner's share was accepted first. Very high orphan rates may indicate network connectivity problems.

The P2Pool console output shows your relative stale rate compared to other P2Pool miners in the 'Own efficiency' column:
<pre>
2012-01-07 20:57:51.797420 Pool stales: 13% Own: 13±2% Own efficiency: 100±2%
</pre>

When you first start P2Pool claimed efficiency will be low and the error bounds on this estimate will be large, but as it runs the numbers will converge to their correct values.

If your efficiency is unusually low, make sure your network connection isn't overloaded, that your miners support long polling and are not set to work for excessive amounts of time, and that your bitcoind has multiple connections.

== Joining the pool ==

Follow these steps to join the pool:

* Run Bitcoin with the RPC interface enabled: put rpcuser=USER, rpcpassword=PASS, and server=1 in bitcoin.conf
** Bitcoin 0.5 or later is required
** It's important that your Bitcoin client be fully synchronized before starting. It's also better if you have the Bitcoin port forwarded
* Download p2pool:
** Windows binary: See http://forum.bitcoin.org/index.php?topic=18313.0
** Source download: https://github.com/forrestv/p2pool/tags
** git: git clone git://github.com/forrestv/p2pool.git
* Run p2pool: (See below for additional options.)
** Windows py2exe: run_p2pool.exe USER PASS
** Source: python run_p2pool.py USER PASS
* Run a miner daemon with long polling connecting to 127.0.0.1 (or the IP of the host running p2pool if you're mining remotely) on port 9332 with any username and password
** cgminer -O u:p -o http://127.0.0.1:9332/

Dependencies if running from source:
* Python 2.6 or higher
* python-argparse for Python 2.6 and lower
* Twisted (Ubuntu package python-twisted)

=== Miners ===

This is all for the latest p2pool version, as it includes several new workarounds. With all miners, using a high FPS target (100?) or a low aggression, and waiting for p2pool to completely start (line shows > 17000 shares) helps a lot with reducing stales.

P2Pool uses higher difficulty shares than most centralized pools, so you'll see fewer shares reported. This is normal and doesn't reduce your payments. It's also normal to see longpoll messages once per every ten seconds on average.

==== Works as-is ====

===== cgminer =====
Works very well as is.

===== ufasoft =====
Works as is.

===== DiabloMiner =====
Works fine after commit 3b731b9b54.

==== Needs patch to reduce stales ====

===== Poclbm =====
Waits a full second between long polls.

GitHub fork: https://github.com/forrestv/poclbm
Pull request: https://github.com/m0mchil/poclbm/pull/41
<pre>git clone git://github.com/forrestv/poclbm.git
cd poclbm
git checkout fast_long_polling</pre>

Windows binary: http://u.forre.st/u/wodukkea/p2pool-poclbm_win32_5590e7c.zip

===== Phoenix =====
(Works fine after commit 8263f65!)

Has a similar bug (waiting a full second).

GitHub fork: https://github.com/forrestv/phoenix-miner

Windows binary: http://u.forre.st/u/ycvzejfm/phoenix-miner-fba48d2-5.zip

==== Not-compatible ====

===== puddinpop's RPC Miners =====
Does not have long polling so will not work at all.

=== Option Reference ===
<pre>
usage: run_p2pool.py [-h] [--version] [--net {bitcoin, litecoin, namecoin}]
[--testnet] [--debug] [-a ADDRESS] [--logfile LOGFILE]
[--merged-url MERGED_URL]
[--merged-userpass MERGED_USERPASS]
[--give-author DONATION_PERCENTAGE] [--p2pool-port PORT]
[-n ADDR[:PORT]] [--disable-upnp] [-w PORT]
[-f FEE_PERCENTAGE] [--bitcoind-address BITCOIND_ADDRESS]
[--bitcoind-rpc-port BITCOIND_RPC_PORT]
[--bitcoind-p2p-port BITCOIND_P2P_PORT]
[BITCOIND_RPCUSER] BITCOIND_RPCPASSWORD

p2pool (version 31cbeea)

optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--net {bitcoin, litecoin, namecoin}
use specified network (default: bitcoin)
--testnet use the network's testnet
--debug enable debugging mode
-a ADDRESS, --address ADDRESS
generate payouts to this address (default: <address
requested from bitcoind>)
--logfile LOGFILE log to this file (default: data/<NET>/log)
--merged-url MERGED_URL
call getauxblock on this url to get work for merged
mining (example: http://127.0.0.1:10332/)
--merged-userpass MERGED_USERPASS
use this user and password when requesting merged
mining work (example: ncuser:ncpass)
--give-author DONATION_PERCENTAGE
donate this percentage of work to author of p2pool
(default: 0.5)
--disable-upnp don't attempt to use UPnP to forward p2pool's P2P port
from the Internet to this computer

p2pool interface:
--p2pool-port PORT use port PORT to listen for connections (forward this
port from your router!) (default: bitcoin:9333,
litecoin:9338, namecoin:9334)
-n ADDR[:PORT], --p2pool-node ADDR[:PORT]
connect to existing p2pool node at ADDR listening on
port PORT (defaults to default p2pool P2P port) in
addition to builtin addresses

worker interface:
-w PORT, --worker-port PORT
listen on PORT for RPC connections from miners
(default: bitcoin:9332, litecoin:9327, namecoin:9331)
-f FEE_PERCENTAGE, --fee FEE_PERCENTAGE
charge workers mining to their own bitcoin address (by
setting their miner's username to a bitcoin address)
this percentage fee to mine on your p2pool instance.
Amount displayed at http://127.0.0.1:WORKER_PORT/fee
(default: 0)

bitcoind interface:
--bitcoind-address BITCOIND_ADDRESS
connect to this address (default: 127.0.0.1)
--bitcoind-rpc-port BITCOIND_RPC_PORT
connect to JSON-RPC interface at this port (default:
bitcoin:8332, litecoin:9332, namecoin:8332)
--bitcoind-p2p-port BITCOIND_P2P_PORT
connect to P2P interface at this port (default:
bitcoin:8333, litecoin:9333, namecoin:8334)
BITCOIND_RPCUSER bitcoind RPC interface username (default: <empty>)
BITCOIND_RPCPASSWORD bitcoind RPC interface password
</pre>

== Protocol description ==

P2Pool's protocol mirrors Bitcoin's P2P protocol in many ways. It uses the same framing (prefix, command, length, checksum, payload) and similar commands:

* '''version''' - sent to establish a connection - contains (''version'', ''services'', ''addr_to'', ''addr_from'', ''nonce'', ''sub_version'', ''mode'', ''best_share_hash'')
* '''setmode''' - sent to update the ''mode'' sent in the '''version''' message - contains (''mode'')
* '''ping''' - sent to keep connection alive - contains ()
* '''addrme''' - request that the receiving node send out an addr for the sending node - contains (''port'')
* '''addrs''' - broadcast list of nodes' addresses - contains (''addrs'')
* '''getaddrs''' - request that the receiving node send ''count'' addrs - contains (''count'')
* '''getshares''' - request that the receiving node send the shares referenced by ''hashes'' and ''parents'' of their parents, stopping at any share referenced by ''stops'' - contains (''hashes'', ''parents'', ''stops'')
* '''shares''' - broadcast message of the contents of shares - contains (''shares'')

==History==

This project was announced on June 17, 2011 by Forrest Voight<ref>[https://forum.bitcoin.org/index.php?topic=18313.0 p2pool: Decentralized, DoS-resistant, Hop-Proof - Now active on mainnet!]</ref>.

The began testing against mainnet in mid-July, 2011. The pool was reviewed on a [[Bitcoin Miner]] post on July 26, 2011<ref>[http://www.bitcoinminer.com/post/8101660461 P2Pool Decentralized Pool Nearly Ready For Prime-Time]</ref>.

The software author's address for donations can be found in the signature section of his [http://forum.bitcoin.org/index.php?action=profile;u=6447 forum profile].

==Donating to P2Pool miners==
In order to encourage people to mine to P2Pool you can donate to the recent miners in proportion using a sendmany:

E.g. a bash script to donate 10 btc is:
<pre>
~/src/bitcoin/src/bitcoind sendmany "" "$(GET http://forre.st:9332/patron_sendmany?total=10.0)"
</pre>

You can replace "" with "accountname" if you want to pay from some specific bitcoind account, and you can replace forre.st with 127.0.0.1 if you're running a P2Pool node locally, so you don't have to trust that the URL gives accurate figures.

If you decide to donate you should announce it on the forums so that your donations provide the most incentive possible.

==See Also==

* [[Comparison of mining pools]]
* [[Pooled Mining]]

==External Links==

* [http://forum.bitcoin.org/index.php?topic=18313.0 P2Pool forum]
* [https://github.com/forrestv/p2pool p2pool] project on GitHub
* {{Freenode IRC|p2pool}} discussion and support

==References==
<references />

[[Category:Pool Operators]]

Miner fees

2011-12-24T03:45:29Z

Brec:

[[File:fee.png|thumb|Receiving a transaction fee of 0.44 BC]]
Transaction fees may be included with any transfer of bitcoins from one address to another. At the moment, many [[transactions]] are typically processed in a way where no fee is expected at all, but for transactions which draw coins from many bitcoin addresses and therefore have a large data size, a small transaction fee is usually expected.

The transaction fee is processed by and received by the bitcoin miner. When a new bitcoin block is generated with a successful hash, the information for all of the transactions is included with the block and all transaction fees are collected by that user creating the block, who is free to assign those fees to himself.

Transaction fees are voluntary on the part of the person making the bitcoin transaction, as the person attempting to make a transaction can include any fee or none at all in the transaction. On the other hand, nobody mining new bitcoins necessarily needs to accept the transactions and include them in the new block being created. The transaction fee is therefore an incentive on the part of the bitcoin user to make sure that a particular transaction will get included into the next block which is generated.

It is envisioned that over time the cumulative effect of collecting transaction fees will allow somebody creating new blocks to "earn" more bitcoins than will be mined from new bitcoins created by the new block itself. This is also an incentive to keep trying to create new blocks even if the value of the newly created block from the mining activity is zero in the far future.

It works like this:
* Whoever sends the transaction is often able to guess an appropriate fee based on their own fee rules. The [[Original Bitcoin client|original client]] will always assess the transaction, and if a fee will typically be expected, it will not allow you to send the transaction without the calculated fee.
* The user is prompted to confirm the fee before the transaction is sent.
* The sender makes a transaction with more coins in the ''In'' portion than the ''Out'' portion so that there are “leftovers” not assigned to any address.
* Whoever ends up publishing the [[block]] which contains this transaction will take these (and any other) leftover coins. They are included with their normal generated coins and is an extra bonus for creating the block.
* If a mining node receives a transaction that should include a transaction fee but doesn't, they may refuse to include it in their blocks. It might be included in a later block if someone is willing to accept it. Generators can't force a certain fee on transactions -- they can only accept or reject the transaction's “fee offer”.
[[File:lfm_fee.png|thumb|This balance is made entirely of 0.01 BTC cents. Since sending them requires a lot of data, a very large fee is required.]]

Different bitcoin clients and different versions have different rules for determining which transactions to accept and how large a fee to send.

Current default rules for the original Bitcoin client (Bitcoin 0.3.23):
* minimum TX fee for new transactions reduced to 0.0005 BTC.

Original Bitcoin client version 0.3.20:
* 0.01 BTC fee if sending any transaction less than 0.01 BTC. This is to help prevent DoS attacks against the network. Remember: fees are not network-enforced, so it's still ''possible'' to send these small transactions without the fee -- you just have to generate the blocks that contain them yourself (after modifying Bitcoin).
* 0.01 BTC fee per kilobyte of transaction, but:
** If the blocksize (size of all transactions currently waiting to be included in a block) is less than 27 kB, transactions are free.
** If the blocksize is more than 250 kB, transactions get increasingly more expensive as the blocksize approaches the limit of 500 kB. Sending a transaction when the blocksize is 400 kB will cost 5 times the normal amount; sending when it's 499 kB will cost 500x, etc.
* Transactions within each fee tier are prioritized based on several factors. Most importantly, a transaction has more priority if the coins it is using have a lot of confirmations. Someone spamming the network will almost certainly be re-using the same coins, which will lower the priority of their transactions. Priority is also increased for transactions with more BTC, and reduced for transactions with more data.
* If the blocksize is over 4kB, free transactions in the above rules are only allowed if the transaction's priority is above a certain level.

Note that if you want to send a transaction with less than the default rules, or if you are a miner and want to include them in your blocks, you may need to peer with the [[Free transaction relay policy|Free transaction relay network]].

An advantage for bitcoin users to include a transaction fee is that the likelihood of getting a transaction included into the next block is going to be higher than if a transaction fee is not included. This is a trade off of time vs. money put forward on the transaction fees, as you can be patient with a low or non-existent fee included in a transaction, or you can make sure that the transaction is processed immediately by including a higher fee than is typical.

The rules are far from set in stone, and the network can support many different rules simultaneously. If there are mining nodes that never require a transaction fee and your client is modified to never send any transaction fee, then your transactions will eventually be picked up by one of those free nodes when they generate a block, though it will probably take a very long time. In the far future, different rules about transaction fees among mining nodes will probably create a clear choice between fees and transaction speed. For example, you might choose to spend 2% for a guaranteed spot in the next block or 0.01% for the transaction to be sent in a few hours.

If you notice that your sent transactions take a very long time to confirm, this is possibly because no fee was included. Using a more recent release of the client will help lessen the chance of sending a transaction without an adequate fee.
[[File:feesend.png|thumb|Sending a transaction when the sender doesn't have enough money to actually pay the fee]]

==Technical info==

Transaction priority is calculated as a value-weighted sum of input age, divided by transaction size in bytes:
priority = sum(input_value_in_base_units * input_age)/size_in_bytes
Transactions need to have a priority above 57,600,000 to avoid the enforced limit (as of client version 0.3.21). This threshold is written in the code as COIN * 144 / 250, suggesting that the threshold represents a one day old, 1 btc coin (144 is the expected number of blocks per day) and a transaction size of 250 bytes.

So, for example, a transaction that has 2 inputs, one of 5 btc with 10 confirmations, and one of 2 btc with 3 confirmations, and has a size of 500bytes, will have a priority of
(500000000 * 10 + 200000000 * 3) / 500 = 11,800,000

==See Also==

* [[Free transaction relay policy]]

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

Pooled mining

2011-12-23T20:08:49Z

Brec:

'''Pooled mining''' is a [[Mining|mining]] approach where multiple generating clients contribute to the generation of a block, and then split the block reward according the contributed processing power. Pooled mining effectively reduces the granularity of the block generation reward, spreading it out more smoothly over time.

==Introduction==

With increasing generation difficulty, mining with lower-performance devices can take a very long time before block generation, on average. For example, with a mining speed of 1000 Khps, at a difficulty of 14484 (which was in effect at the end of December, 2010), the average time to generate a block is almost 2 years.

To provide a more smooth incentive to lower-performance miners, several pooled miners, using different approaches, have been created. With a mining pool, a lot of different people contribute to generating a block, and the reward is then split among them according to their processing contribution. This way, instead of waiting for years to generate 50btc in a block, a smaller miner may get a fraction of a bitcoin on a more regular basis.

A '''share''' is awarded by the mining pool to the clients who present a valid [[proof of work]] of the same type as the proof of work that is used for creating [[block|blocks]], but of lesser difficulty, so that it requires less time on average to generate.

==Pooled mining approaches==

The problem with pooled mining is that steps must be taken to prevent cheating by the clients and the server. Currently there are several different approaches used.

===The slush approach===

[[Bitcoin Pooled Mining]] (BPM), sometimes referred to as "slush's pool", follows a score-based method. Older shares (from beginning of the round) have lower weight than more recent shares, which reduces the motivation to cheat by switching between pools within a round.

===The puddinpop approach===

(As of February, 2011, there are no puddinpop pools running.)

Another approach is the 'metahash' technique, used by puddinpop's [[remote miner]]. Clients generate hashes, and also submit 'metahashes', which are hashes of a large chunk of generated hashes. The server checks that the metahashes are correct (in a round-robin fashion, picking up a metahash from a client that hasn't been checked on the longest), thus preventing clients from simply claiming that they have done work without actually doing it. The withholding of good blocks by the clients is prevented by the server's possession of the private key, just as in the previous approach. Rewards are distributed based on the number of metahashes submitted by the clients.

The generated blocks contain multiple keys in the generation transaction, giving fractional bitcoin amounts to each key in proportion to their hashing contribution for that block.

===The Pay-per-Share approach===

The Pay-per-Share (PPS) approach, first described by [[BitPenny]], is to offer an instant flat payout for each share that is solved. The payout is offered from the pool's existing balance and can therefore be withdrawn immediately, without waiting for a block to be solved or confirmed. The possibility of cheating the miners by the pool operator and by timing attacks is thus completely eliminated.

This method results in the least possible variance for miners while transferring all risk to the pool operator. The resulting possibility of loss for the server is offset by setting a payout lower than the full expected value.

===Luke-Jr's approach ("[[Eligius]]")===
[[User:Luke-Jr|Luke]] came up with a third approach borrowing strengths from the earlier two.
Like slush's approach, miners submit proofs-of-work to earn shares.
Like puddinpop's approach, the pool pays out immediately via block generation.
When distributing block rewards, it is divided equally among all shares since the last valid block.
Unlike any preexisting pool approach, this means that the shares contributed toward orphaned blocks are recycled into the next block's shares.
In order to spare participating miners from transaction fees, rewards are only paid out if a miner has earned at least 1 BTC. If the amount owed is less, it will be added to the earnings of a later block (which may then total over 1 BTC).
If a miner does not submit a share for over a week, the pool sends any balance remaining, regardless of its size.

===The Triplemining approach===
The [[Triplemining]] approach is to bring together a medium-sized pool with no fees and clever redistribution of 1% of every found block to allow your share to grow more rapidly than on any other bitcoin mining pool.

For every found block, Triplemining redistributes 1% of the profits to all minipool owners (people with 1 or more friends mining with them). The redistribution is connected to the shares found by the members of the minipool. So if the hash rate of the minipool members equals or is bigger than yours, the part in the redistribution will be equally bigger.

===P2Pool approach===

[[P2Pool]] mining nodes work on a chain of shares similar to Bitcoin’s blockchain. There is no central point of failure and thus P2Pool becomes DoS resistant.

P2Pool works different from existing mining pool technologies — each node works on a block that includes payouts to the previous shares’ owners and the node itself. 99% of the block reward (the 50BTC reward plus any included transaction fees) is distributed evenly to miners based on work done recently. An additional 0.5% is awarded to the node which solves the block.

===Comparison===

The cooperative mining approach (slush and Luke-Jr) uses a lot less resources on the pool server, since rather than continuously checking metahashes, all that has to be checked is the validity of submitted shares. The number of shares sent can be adjusted by adjusting the artificial difficulty level.

Further, the cooperative mining approach allows the clients to use existing miners without any modification, while the puddinpop approach requires the custom pool miner, which are as of now not as efficient on GPU mining as the existing GPU miners.
[[File:Smallgeneration.png|thumb|Puddinpop miners receive coins directly.]]

Additionally, the puddinpop and Luke-Jr approaches of distributing the earnings by way of including precise sub-cent amounts in the generation transaction for the participants, results in the presence of sub-cent bitcoin amounts in your wallet, which are liable to disappear (as unnecessary fees) later due to a bug in old (before 0.3.21) bitcoin nodes. (E.g., if you have a transaction with 0.052 in your wallet, and you later send .05 to someone, your .002 will disappear.).

Puddinpop and Luke-Jr miners receive coins directly, which eliminates the delay in receiving earnings that is required on slush-based mining servers. However, using some [[eWallet]] services like MyBitcoin for generated coin will cause those coins to be lost.

==See Also==

* [[:Category:Miners|Miners]]
* [[Comparison of mining pools]]
* [[:Category:Pool Operators|Pool Operators]]
* [[Why a GPU mines faster than a CPU]]
* [[Why pooled mining]]
* [[Mining pool reward FAQ]]

==External links==
* [http://btcserv.net BTCSERV.net - Bitcoin Pool]
* [http://21bitcoin.com/pool/ 21bitcoin mining pool, Chinese Interface]
* [http://mining.bitcoin.cz slush's mining pool]
* [http://www.bitcash.cz bitcash.cz - czech mining pool]
* [http://www.bitcoin.org/smf/index.php?topic=1458.0 puddinpop's mining pool thread]
* [http://blockexplorer.com/block/00000000000233334b157d901714baf59e5b9236227b2878844e52244da4195e example puddinpop block]
* [http://bitclockers.com bitclockers mining pool]
* [http://forum.bitcoin.org/index.php?topic=18313 P2Pool forum]

==References==
<references />

[[Category:Mining]]

Pooled mining

2011-12-23T20:04:21Z

Brec: a share proof-of-work is not of less *complexity*, but less *difficulty* (less expected computation) as compared with block generation

'''Pooled mining''' is a [[Mining|mining]] approach where multiple generating clients contribute to the generation of a block, and then split the block reward according the contributed processing power. Pooled mining effectively reduces the granularity of the block generation reward, spreading it out more smoothly over time.

==Introduction==

With increasing generation difficulty, mining with lower-performance devices can take a very long time before block generation, on average. For example, with a mining speed of 1000 Khps, at a difficulty of 14484 (which was in effect at the end of December, 2010), the average time to generate a block is almost 2 years.

To provide a more smooth incentive to lower-performance miners, several pooled miners, using different approaches, have been created. With a mining pool, a lot of different people contribute to generating a block, and the reward is then split among them according to their processing contribution. This way, instead of waiting for years to generate 50btc in a block, a smaller miner may get a fraction of a bitcoin on a more regular basis.

A '''share''' is awarded by the mining pool to the clients who present a valid [[proof of work]] of the same type as the proof of work that is used for creating [[block|blocks]], but of lesser difficulty, so that it requires less time on average to generate.

==Pooled mining approaches==

The problem with pooled mining is that steps must be taken to prevent cheating by the clients and the server. Currently there are several different approaches used.

===The slush approach===

[[Bitcoin Pooled Mining]] (BPM), sometimes referred to as "slush's pool", follows a score-based method. Older shares (from beginning of the round) has lower weight than newer shares, which demotivate cheater from switching between pools inside one round.

===The puddinpop approach===

(As of February, 2011, there are no puddinpop pools running.)

Another approach is the 'metahash' technique, used by puddinpop's [[remote miner]]. Clients generate hashes, and also submit 'metahashes', which are hashes of a large chunk of generated hashes. The server checks that the metahashes are correct (in a round-robin fashion, picking up a metahash from a client that hasn't been checked on the longest), thus preventing clients from simply claiming that they have done work without actually doing the work. The withholding of good blocks by the clients is prevented via the server being in possession of the private key, just as in the previous approach. Rewards are distributed based on the number of metahashes submitted by the clients.

The generated blocks contain multiple keys in the generation transaction, giving fractional bitcoin amounts to each key, in proportion to their hashing contribution for that block.

===The Pay-per-Share approach===

The Pay-per-Share (PPS) approach, first described by [[BitPenny]], is to offer an instant flat payout for each share that is solved. The payout is offered from the pool's existing balance and can therefore be withdrawn immediately, without waiting for a block to be solved or confirmed. The possibility of cheating the miners by the pool operator and by timing attacks is thus completely eliminated.

This method results in the least possible variance for miners while transferring all risk to the pool operator. The resulting possibility of loss for the server is offset by setting the payout lower than the full expected value.

===Luke-Jr's approach ("[[Eligius]]")===
[[User:Luke-Jr|Luke]] came up with a third approach borrowing strengths from the earlier two.
Like slush's approach, miners submit proofs-of-work to earn shares.
Like puddinpop's approach, the pool pays out immediately via block generation.
When distributing block rewards, it is divided equally among all shares since the last valid block.
Unlike any preexisting pool approach, this means that the shares contributed toward orphaned blocks are recycled into the next block's shares.
In order to spare participating miners from transaction fees, rewards are only paid out if a miner has earned at least 1 BTC. If the amount owed is less, it will be added to the earnings of a later block (which may then total over 1 BTC).
If a miner does not submit a share for over a week, the pool sends any balance remaining, regardless of its size.

===The Triplemining approach===
The [[Triplemining]] approach is to bring together a medium-sized pool with no fees and clever redistribution of 1% of every found block to allow your share to grow more rapidly than on any other bitcoin mining pool.

For every found block, Triplemining redistributes 1% of the profits to all minipool owners (people with 1 or more friends mining with them). The redistribution is connected to the shares found by the members of the minipool. So if the hash rate of the minipool members equals or is bigger than yours, the part in the redistribution will be equally bigger.

===P2Pool approach===

[[P2Pool]] mining nodes work on a chain of shares similar to Bitcoin’s blockchain. There is no central point of failure and thus P2Pool becomes DoS resistant.

P2Pool works different from existing mining pool technologies — each node works on a block that includes payouts to the previous shares’ owners and the node itself. 99% of the block reward (the 50BTC reward plus any included transaction fees) is distributed evenly to miners based on work done recently. An additional 0.5% is awarded to the node which solves the block.

===Comparison===

The cooperative mining approach (slush and Luke-Jr) uses a lot less resources on the pool server, since rather than continuously checking metahashes, all that has to be checked is the validity of submitted shares. The number of shares sent can be adjusted by adjusting the artificial difficulty level.

Further, the cooperative mining approach allows the clients to use existing miners without any modification, while the puddinpop approach requires the custom pool miner, which are as of now not as efficient on GPU mining as the existing GPU miners.
[[File:Smallgeneration.png|thumb|Puddinpop miners receive coins directly.]]

Additionally, the puddinpop and Luke-Jr approaches of distributing the earnings by way of including precise sub-cent amounts in the generation transaction for the participants, results in the presence of sub-cent bitcoin amounts in your wallet, which are liable to disappear (as unnecessary fees) later due to a bug in old (before 0.3.21) bitcoin nodes. (E.g., if you have a transaction with 0.052 in your wallet, and you later send .05 to someone, your .002 will disappear.).

Puddinpop and Luke-Jr miners receive coins directly, which eliminates the delay in receiving earnings that is required on slush-based mining servers. However, using some [[eWallet]] services like MyBitcoin for generated coin will cause those coins to be lost.

==See Also==

* [[:Category:Miners|Miners]]
* [[Comparison of mining pools]]
* [[:Category:Pool Operators|Pool Operators]]
* [[Why a GPU mines faster than a CPU]]
* [[Why pooled mining]]
* [[Mining pool reward FAQ]]

==External links==
* [http://btcserv.net BTCSERV.net - Bitcoin Pool]
* [http://21bitcoin.com/pool/ 21bitcoin mining pool, Chinese Interface]
* [http://mining.bitcoin.cz slush's mining pool]
* [http://www.bitcash.cz bitcash.cz - czech mining pool]
* [http://www.bitcoin.org/smf/index.php?topic=1458.0 puddinpop's mining pool thread]
* [http://blockexplorer.com/block/00000000000233334b157d901714baf59e5b9236227b2878844e52244da4195e example puddinpop block]
* [http://bitclockers.com bitclockers mining pool]
* [http://forum.bitcoin.org/index.php?topic=18313 P2Pool forum]

==References==
<references />

[[Category:Mining]]

Satoshi Client Initialization and Startup

2011-12-12T04:16:28Z

Brec: fix typo: already in user -> already in use

==Startup Process==

The client uses a fixed number of threads that are created on startup. All of the reading and writing on active network sockets are handled by one thread.

The main() entry point to the program is in init.cpp. Do not go looking in main.cpp for main() - you will not find it.

The first thing main() does is call AppInit, which calls AppInit2 which performs a bunch of initialization busy work mostly related to how the application handles errors. At some point AppInit2 calls ParseParameters, and then some argument handling code processes some basic arguments.

Now it checks to see if an existing GUI window is already present and if so, brings it to the foreground.

Next it creates a lock file in the bitcoin directory and if bitcoin is already running, displays a message and exits.

Next it attemps to listen on the bitcoin port, and if the port is already in use or other error, displays a message and exits.

Next it loads IP addresses from a database, then it loads the block index, and then it loads the wallet.

Next it gets the top block number from the wallet, or zero if -rescan is used. Then It scans the block chain from the block number above.

Side Note: printf has been redefined in util.h. So printf is really OutputDebugStringF which directs to a file if appropriate (see util.h and util.cpp). Also "loop" is defined in util.h as for ( ; ; ).

Then it does a bit more initialization and parameter processing and then it finally opens the GUI main window.

Next it creates two threads:

# StartNode()
# And if acting as server: ThreadRPCServer()

This is the only place where these threads are created.

StartNode() is in net.cpp and ThreadRPCServer() is in rpc.cpp.

Last, if not compiled for the GUI it sleeps for 5 seonds in an infinite loop.

== fClient Mode ==

It is worth noting that there is code in the client to allow it to operate in a mode where it only downloads block headers. The implementation is intended to be used as a lightweight client mode which can operate without verifying and storing all blocks and transactions. This is controlled by the fClient variable in the code which is currently hard coded to false. This is currently not considered to be finished code. This mode is known as fClient mode and the phrase Simplified Payment Verification (or SPV) mode has also been used to describe a lightweight client approach.

==Thread StartNode() in net.cpp==

StartNode is sort of a master networking thread.

First it creates a CNode for the localhost 127.0.0.1 internal addresss to
handle communication.

Next, it gets the local IP address. On windows, its a lookup using the
local host name. On Linux, it is the first IP address it finds on an
interface that is up and is not the loopback interface.

Next it creates a thread (ThreadGetMyExternalIP) to confirm the local IP
address using 3rd party verification. If using a proxy, it does not
bother, because it will not take incoming connections.

Next, if Universal Plug and Play is used, then a thread (ThreadMapPort)
to deal with port mapping is created.

Next it creates a thread (ThreadIRCSeed) to exchange IP addresses.

Next it creates a thread (ThreadSocketHandler) to "Send and receive from
sockets, accept connections".

Next it creates a thread (ThreadOpenConnections) to initiate outbound
connections.

Next it creates a thread (ThreadMessageHandler) to process messages.

Finally, if you have specified so, it will start a bitcoin mining thread.

==Thread IRCSeed in net.cpp==

Connects to 92.243.23.21 port 6667, JOINs the channel, and then
reads lines one at a time looking for other users.

==Thread ThreadSocketHandler in net.cpp==

Goes into an endless loop servicing sockets that need servicing.
Handles disconnected nodes.
Prepares "select" descriptor list and then calls select, waiting for
I/O on all the relevant sockets with a 50ms timeout.
Process new incoming connection on listening socket. Create a CNode for them.
Handle receiving and sending.
Set sockets that have not done anything to disconnected state.

==Thread ThreadOpenConnecions in net.cpp==

Figures out nodes from parameters, seeds, irc, etc, and then goes into a
loop, connecting to each one by one.

==Thread ThreadMessageHandler in net.cpp==

This thread goes through all the nodes and calls ProcessMessages(pnode) in
main.cpp which looks for valid messages on the node receive
queue (pFrom->vRecv) and if it finds one, it calls
ProcessMessage(CNode* pfrom, string strCommand, CDataStream& vRecv), which
is also in main.cpp.

Then the thread calls SendMessages for each node (which is in main.cpp)
which handles creating and sending any messages appropriate for that node.

==Thread ThreadRPCServer in rpc.cpp==

This thread will be rather complicated in that it implements an
HTTP(S)+JSONRPC server using boost classes that are probably going
to be unfamiliar to most developers.

You will see lines like this:
acceptor.set_option(boost::asio::ip::tcp::acceptor::reuse_address(true));

and this:
boost::thread api_caller(ReadHTTP, boost::ref(stream), boost::ref(mapHeaders), boost::ref(strRequest));
if (!api_caller.timed_join(boost::posix_time::seconds(GetArg("-rpctimeout", 30))))

It appears the code above is creating a thread in order to apply 30
second timeout to reading an HTTPrequest. When HTTP requests are
read, they are parsed, and then a routine corresponding to the
request command name is called to handle the request. This happens
in a loop until shutdown.

[[Category:Developer]]
[[Category:Technical]]

Block chain

2011-12-12T04:13:06Z

Brec: Avoid run-on sentence

[[File:blockchain.png|thumb|Blocks in the main chain (black) are the longest series of blocks that go from the genesis block (green) to the current block. Orphan blocks (purple) are blocks that are not in the longest chain.]]

A '''block chain''' is a transaction database shared by all [[Node|nodes]] participating in a [[crypto-currency]] such as Bitcoin. A full copy of a currency's block chain contains every [[transaction]] ever executed in the currency. With this information, one can find out how much value belonged to each [[address]] at any point in history.

Every [[block]] contains a [[hash]] of the previous block. This has the effect of creating a chain of blocks from the [[genesis block]] to the current block. Each block is guaranteed to come after the previous block chronologically because the previous block's hash would otherwise not be known. Each block is also computationally impractical to modify once it has been in the chain for a while because every block after it would also have to be regenerated. These properties are what make double-spending of bitcoins very difficult. The block chain is the main innovation of Bitcoin.

Honest generators only build onto a block (by referencing it in blocks they create) if it is the latest block in the longest valid chain. "Length" is calculated as total combined difficulty of that chain, not number of blocks, though this distinction is only important in the context of a few potential attacks. A chain is valid if all of the blocks and transactions within it are valid, and only if it starts with the genesis block.

For any block on the chain, there is only one path to the genesis block. Coming from the genesis block, however, there can be forks. One-block forks are created from time to time when two blocks are created just a few seconds apart. When that happens, generating nodes build onto whichever one of the blocks they received first. Whichever block ends up being included in the next block becomes part of the main chain because that chain is longer. More serious forks have occurred after fixing bugs that required backward-incompatible changes.

Blocks in shorter chains (or invalid chains) are called "orphan blocks", and while they are stored, they are not used for anything. When a block becomes an orphan block, all of its valid transactions are re-added to the pool of queued transactions and will be included in another block. The 50 BTC reward for the orphan block will be lost, which is why a network-enforced 100-block maturation time for generations exists.

Because a block can only reference one previous block, it is impossible for two forked chains to merge.

It's possible to use the block chain algorithm for non-financial purposes: see [[Alternative Chains]].

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

MtGox/API

2011-11-29T05:21:40Z

Brec: /* Incoming Data */

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

Two APIs are currently available: the HTTP API (available by posting to mtgox.com/code/*) and the websocket API.

==Number Formats==

In the "old API", currency- and amount-values (price, volume,...) were given as '''float'''. These values are likely being deprecated and replaced by fields of the same name with "_int" as suffix. These are '''fixed-decimal''', so you have to move the decimal point yourself (divide). The exponent differs based on the kind of the value.

In order to convert the '''int''' to a '''decimal''' you can...

{| class="wikitable"
|-
! kind of field !! ...divide by !! ...multiply by
|-
| BTC (volume, amount) || 1E8 (10,000,000) || 0.00000001
|-
| USD (price) || 1E5 (100,000) || 0.00001
|-
| JPY (price) || 1E3 (1,000) || 0.001
|}

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

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

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

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

=== Authentication ===

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

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

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

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

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

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

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

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

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

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

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

=== Cache ===

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

=== Methods API version 0===

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

Parameters:
* since: Passing a tid in "since" allows retrieving all trades since that trade. The passed id is may not exist. Ie. to get all trades from the very beginning one would just call https://mtgox.com/code/data/getTrades.php?since=0 . since returns only 100 trades, and you can call the method again by passing the latest trade you have imported in since.

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

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

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

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

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

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

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

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

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

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

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

returns a list of your open orders

you can omit the price to do a market order

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

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

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

returns a list of your open orders

you can omit the price to do a market order

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

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

oid: Order ID

type: 1 for sell order or 2 for buy order

status: 1 for active, 2 for not enough funds

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

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

POST data: oid=#&type=#

oid: Order ID

type: 1 for sell order or 2 for buy order

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

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

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

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

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

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

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

* pass btca parameter to withdraw to a btc adress

* pass group1 for a coupon : BTC2CODE or USD2CODE

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

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

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

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

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

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

* returns a bitcoin deposit address

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

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

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

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

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

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

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

==== 0/ticker ====

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

returns the current ticker :

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

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

what is vwap ?

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

=== API version 0 examples ===

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

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

perl : http://pastebin.com/vEpgw5nW

==== other ====

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

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

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

==== gather data ====

https://github.com/Lexiks/MyBitBoard

==== gettrade ====

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

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

==== ticker ====

http://pastebin.com/pd0ZR4WY

=== Methods API version 1===

==== Multi Currency Ticker ====

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

returns the current ticker for the selected currency :

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

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

==== Multi Currency depth ====

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

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

==== Multi currency trades ====

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

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

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

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

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

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

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

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

==== Cancelled Trades ====

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

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

==== Full Depth ====

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

returns full depth

==== Private info ====

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

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

==== Your open orders ====

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

returns information about your current open orders

==== Currency information ====

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

pass parameter ?currency=<currency_symbol>

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

==== HOTP key ====

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

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

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

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

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

:{| class="wikitable"
|-
! MESSAGE_TYPE !! Description
|-
| ticker || Ticker messages
|-
| trade || Trades, as they occur
|-
| depth || Orders placed or removed
|}

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

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

'''trade''' contains the following:

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

====Depth====

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

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

'''depth''' contains the following:

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

|}

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

=== examples ===

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

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

http://github.com/hookio

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

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

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

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

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

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

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

MtGox/API

2011-11-29T05:17:55Z

Brec:

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

Two APIs are currently available: the HTTP API (available by posting to mtgox.com/code/*) and the websocket API.

==Number Formats==

In the "old API", currency- and amount-values (price, volume,...) were given as '''float'''. These values are likely being deprecated and replaced by fields of the same name with "_int" as suffix. These are '''fixed-decimal''', so you have to move the decimal point yourself (divide). The exponent differs based on the kind of the value.

In order to convert the '''int''' to a '''decimal''' you can...

{| class="wikitable"
|-
! kind of field !! ...divide by !! ...multiply by
|-
| BTC (volume, amount) || 1E8 (10,000,000) || 0.00000001
|-
| USD (price) || 1E5 (100,000) || 0.00001
|-
| JPY (price) || 1E3 (1,000) || 0.001
|}

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

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

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

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

=== Authentication ===

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

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

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

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

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

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

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

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

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

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

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

=== Cache ===

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

=== Methods API version 0===

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

Parameters:
* since: Passing a tid in "since" allows retrieving all trades since that trade. The passed id is may not exist. Ie. to get all trades from the very beginning one would just call https://mtgox.com/code/data/getTrades.php?since=0 . since returns only 100 trades, and you can call the method again by passing the latest trade you have imported in since.

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

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

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

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

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

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

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

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

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

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

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

returns a list of your open orders

you can omit the price to do a market order

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

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

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

returns a list of your open orders

you can omit the price to do a market order

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

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

oid: Order ID

type: 1 for sell order or 2 for buy order

status: 1 for active, 2 for not enough funds

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

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

POST data: oid=#&type=#

oid: Order ID

type: 1 for sell order or 2 for buy order

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

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

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

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

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

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

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

* pass btca parameter to withdraw to a btc adress

* pass group1 for a coupon : BTC2CODE or USD2CODE

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

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

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

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

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

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

* returns a bitcoin deposit address

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

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

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

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

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

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

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

==== 0/ticker ====

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

returns the current ticker :

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

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

what is vwap ?

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

=== API version 0 examples ===

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

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

perl : http://pastebin.com/vEpgw5nW

==== other ====

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

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

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

==== gather data ====

https://github.com/Lexiks/MyBitBoard

==== gettrade ====

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

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

==== ticker ====

http://pastebin.com/pd0ZR4WY

=== Methods API version 1===

==== Multi Currency Ticker ====

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

returns the current ticker for the selected currency :

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

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

==== Multi Currency depth ====

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

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

==== Multi currency trades ====

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

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

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

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

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

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

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

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

==== Cancelled Trades ====

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

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

==== Full Depth ====

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

returns full depth

==== Private info ====

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

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

==== Your open orders ====

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

returns information about your current open orders

==== Currency information ====

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

pass parameter ?currency=<currency_symbol>

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

==== HOTP key ====

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

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

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

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

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

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

The <tt>OPERATION_TYPE</tt> field may take a few values:

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

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

Some of the channels are:

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

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

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

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

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

:{| class="wikitable"
|-
! MESSAGE_TYPE !! Description
|-
| ticker || Ticker messages
|-
| trade || Trades, as they occur
|-
| depth || Orders placed or removed
|}

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

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

'''trade''' contains the following:

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

====Depth====

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

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

'''depth''' contains the following:

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

|}

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

=== examples ===

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

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

http://github.com/hookio

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

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

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

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

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

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

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

MtGox/API

2011-11-29T05:15:38Z

Brec:

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

Two APIs are available at this point: the HTTP api (available by posting to mtgox.com/code/*) and the websocket API.

==Number Formats==

In the "old API", currency- and amount-values (price, volume,...) were given as '''float'''. These values are likely being deprecated and replaced by fields of the same name with "_int" as suffix. These are '''fixed-decimal''', so you have to move the decimal point yourself (divide). The exponent differs based on the kind of the value.

In order to convert the '''int''' to a '''decimal''' you can...

{| class="wikitable"
|-
! kind of field !! ...divide by !! ...multiply by
|-
| BTC (volume, amount) || 1E8 (10,000,000) || 0.00000001
|-
| USD (price) || 1E5 (100,000) || 0.00001
|-
| JPY (price) || 1E3 (1,000) || 0.001
|}

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

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

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

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

=== Authentication ===

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

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

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

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

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

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

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

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

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

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

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

=== Cache ===

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

=== Methods API version 0===

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

Parameters:
* since: Passing a tid in "since" allows retrieving all trades since that trade. The passed id is may not exist. Ie. to get all trades from the very beginning one would just call https://mtgox.com/code/data/getTrades.php?since=0 . since returns only 100 trades, and you can call the method again by passing the latest trade you have imported in since.

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

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

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

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

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

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

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

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

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

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

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

returns a list of your open orders

you can omit the price to do a market order

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

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

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

returns a list of your open orders

you can omit the price to do a market order

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

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

oid: Order ID

type: 1 for sell order or 2 for buy order

status: 1 for active, 2 for not enough funds

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

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

POST data: oid=#&type=#

oid: Order ID

type: 1 for sell order or 2 for buy order

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

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

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

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

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

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

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

* pass btca parameter to withdraw to a btc adress

* pass group1 for a coupon : BTC2CODE or USD2CODE

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

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

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

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

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

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

* returns a bitcoin deposit address

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

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

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

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

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

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

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

==== 0/ticker ====

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

returns the current ticker :

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

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

what is vwap ?

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

=== API version 0 examples ===

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

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

perl : http://pastebin.com/vEpgw5nW

==== other ====

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

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

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

==== gather data ====

https://github.com/Lexiks/MyBitBoard

==== gettrade ====

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

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

==== ticker ====

http://pastebin.com/pd0ZR4WY

=== Methods API version 1===

==== Multi Currency Ticker ====

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

returns the current ticker for the selected currency :

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

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

==== Multi Currency depth ====

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

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

==== Multi currency trades ====

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

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

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

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

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

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

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

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

==== Cancelled Trades ====

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

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

==== Full Depth ====

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

returns full depth

==== Private info ====

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

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

==== Your open orders ====

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

returns information about your current open orders

==== Currency information ====

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

pass parameter ?currency=<currency_symbol>

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

==== HOTP key ====

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

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

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

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

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

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

The <tt>OPERATION_TYPE</tt> field may take a few values:

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

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

Some of the channels are:

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

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

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

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

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

:{| class="wikitable"
|-
! MESSAGE_TYPE !! Description
|-
| ticker || Ticker messages
|-
| trade || Trades, as they occur
|-
| depth || Orders placed or removed
|}

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

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

'''trade''' contains the following:

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

====Depth====

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

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

'''depth''' contains the following:

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

|}

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

=== examples ===

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

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

http://github.com/hookio

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

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

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

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

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

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

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

MtGox/API

2011-11-29T05:14:55Z

Brec:

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

Two APIs are available at this point: the HTTP api (available by posting to mtgox.com/code/*) and the websocket API.

==Number Formats==

In the "old API", currency- and amount-values (price, volume,...) were given as '''float'''. These values are likely being deprecated and replaced by fields of the same name with "_int" as suffix. These are '''fixed-decimal''', so you have to move the decimal point yourself (divide). The exponent differs based on the kind of the value.

In order to convert the '''int''' to a '''decimal''' you can...

{| class="wikitable"
|-
! kind of field !! ...divide by !! ...multiply by
|-
| BTC (volume, amount) || 1E8 (10,000,000) || 0.00000001
|-
| USD (price) || 1E5 (100,000) || 0.00001
|-
| JPY (price) || 1E3 (1,000) || 0.001
|}

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

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

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

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

=== Authentication ===

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

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

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

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

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

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

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

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

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

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

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

=== Cache ===

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

=== Methods API version 0===

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

Parameters:
* since: Passing a tid in "since" allows retrieving all trades since that trade. The passed id is may not exist. Ie. to get all trades from the very beginning one would just call https://mtgox.com/code/data/getTrades.php?since=0 . since returns only 100 trades, and you can call the method again by passing the latest trade you have imported in since.

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

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

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

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

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

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

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

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

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

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

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

returns a list of your open orders

you can omit the price to do a market order

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

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

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

returns a list of your open orders

you can omit the price to do a market order

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

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

oid: Order ID

type: 1 for sell order or 2 for buy order

status: 1 for active, 2 for not enough funds

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

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

POST data: oid=#&type=#

oid: Order ID

type: 1 for sell order or 2 for buy order

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

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

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

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

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

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

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

* pass btca parameter to withdraw to a btc adress

* pass group1 for a coupon : BTC2CODE or USD2CODE

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

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

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

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

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

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

* returns a bitcoin deposit address

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

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

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

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

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

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

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

==== 0/ticker ====

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

returns the current ticker :

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

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

what is vwap ?

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

=== API version 0 examples ===

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

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

perl : http://pastebin.com/vEpgw5nW

==== other ====

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

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

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

==== gather data ====

https://github.com/Lexiks/MyBitBoard

==== gettrade ====

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

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

==== ticker ====

http://pastebin.com/pd0ZR4WY

=== Methods API version 1===

==== Multi Currency Ticker ====

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

returns the current ticker for the selected currency :

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

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

==== Multi Currency depth ====

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

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

==== Multi currency trades ====

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

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

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

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

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

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

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

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

==== Cancelled Trades ====

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

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

==== Full Depth ====

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

returns full depth

==== Private info ====

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

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

==== Your open orders ====

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

returns information about your current open orders

==== Currency information ====

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

pass parameter ?currency=<currency_symbol>

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

==== HOTP key ====

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

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

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

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

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

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

The <tt>OPERATION_TYPE</tt> field may take a few values:

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

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

Some of the channels are:

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

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

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

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

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

:{| class="wikitable"
|-
! MESSAGE_TYPE !! Description
|-
| ticker || Ticker messages
|-
| trade || Trades, as they occur
|-
| depth || Orders placed or removed
|}

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

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

'''trade''' contains the following:

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

====Depth====

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

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

'''depth''' contains the following:

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

|}

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

=== examples ===

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

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

http://github.com/hookio

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

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

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

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

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

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

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

MtGox/API

2011-11-29T05:14:10Z

Brec:

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

Two APIs are available at this point: the HTTP api (available by posting to mtgox.com/code/*) and the websocket API.

==Number Formats==

In the "old API", currency- and amount-values (price, volume,...) were given as '''float'''. These values are likely being deprecated and replaced by fields of the same name with "_int" as suffix. These are '''fixed-decimal''', so you have to move the decimal point yourself (divide). The exponent differs based on the kind of the value.

In order to convert the '''int''' to a '''decimal''' you can...

{| class="wikitable"
|-
! kind of field !! ...divide by !! ...multiply by
|-
| BTC (volume, amount) || 1E8 (10,000,000) || 0.00000001
|-
| USD (price) || 1E5 (100,000) || 0.00001
|-
| JPY (price) || 1E3 (1,000) || 0.001
|}

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

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

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

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

=== Authentication ===

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

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

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

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

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

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

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

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

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

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

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

=== Cache ===

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

=== Methods API version 0===

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

Parameters:
* since: Passing a tid in "since" allows retrieving all trades since that trade. The passed id is may not exist. Ie. to get all trades from the very beginning one would just call https://mtgox.com/code/data/getTrades.php?since=0 . since returns only 100 trades, and you can call the method again by passing the latest trade you have imported in since.

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

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

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

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

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

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

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

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

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

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

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

returns a list of your open orders

you can omit the price to do a market order

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

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

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

returns a list of your open orders

you can omit the price to do a market order

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

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

oid: Order ID

type: 1 for sell order or 2 for buy order

status: 1 for active, 2 for not enough funds

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

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

POST data: oid=#&type=#

oid: Order ID

type: 1 for sell order or 2 for buy order

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

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

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

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

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

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

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

* pass btca parameter to withdraw to a btc adress

* pass group1 for a coupon : BTC2CODE or USD2CODE

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

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

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

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

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

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

* returns a bitcoin deposit address

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

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

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

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

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

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

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

==== 0/ticker ====

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

returns the current ticker :

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

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

what is vwap ?

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

=== API version 0 examples ===

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

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

perl : http://pastebin.com/vEpgw5nW

==== other ====

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

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

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

==== gather data ====

https://github.com/Lexiks/MyBitBoard

==== gettrade ====

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

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

==== ticker ====

http://pastebin.com/pd0ZR4WY

=== Methods API version 1===

==== Multi Currency Ticker ====

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

returns the current ticker for the selected currency :

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

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

==== Multi Currency depth ====

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

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

==== Multi currency trades ====

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

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

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

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

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

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

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

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

==== Cancelled Trades ====

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

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

==== Full Depth ====

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

returns full depth

==== Private info ====

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

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

==== Your open orders ====

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

returns information about your current open orders

==== Currency information ====

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

pass parameter ?currency=<currency_symbol>

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

==== HOTP key ====

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

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

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

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

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

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

The <tt>OPERATION_TYPE</tt> field may take a few values:

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

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

Some of the channels are:

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

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

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

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

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

:{| class="wikitable"
|-
! MESSAGE_TYPE !! Description
|-
| ticker || Ticker messages
|-
| trade || Trades, as they occur
|-
| depth || Orders placed or removed
|}

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

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

'''trade''' contains the following:

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

====Depth====

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

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

'''depth''' contains the following:

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

|}

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

=== examples ===

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

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

http://github.com/hookio

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

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

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

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

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

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

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

Help:Introduction

2011-11-26T17:56:16Z

Brec: fixed homonymic misspelling: fourth -> forth

The purpose of this page is to provide a general overview of the Bitcoin system and economy.

==Basic Concepts==

===Currency===

Alice is far away from Bob and wants to buy his [http://www.grasshillalpacas.com/alpacaproductsforbitcoinoffer.html Alpaca socks]. In return, she wants to send him a dollar. A dollar bill is a piece of paper which is very easy to create (by those who can), but which is accepted by people in exchange for valuable products and services in the real world, such as the socks Alice wants to buy. One simple thing Alice can do is put a dollar bill in an envelope, mail it to Bob, and then wait for Bob to send the socks to her.

===Banks===

Another thing Alice can do is to "wire" the money to Bob. She can do that by first giving her dollar bills to an institution called a bank, the job of which is to safe-keep Alice's dollar bills and, in return, to give Alice a written promise (called a "bank statement") that, whenever she wishes, she can come to the bank to take back the same number of dollar bills that she deposited. Since the money is still Alice's, she is entitled to do with it whatever she pleases, and the bank (like most banks), for a small fee, will do Alice the service of "giving" the dollar bills to Bob instead of her. This could be done by sending a person to Bob's door, with Alice's dollar bills in hand (or, better, fresh new dollar bills, if Alice's dollar bills are in bad condition), but usually it is done by Alice's bank by giving the dollar bills to Bob's bank and informing them that the money is for Bob, who will then see the amount in his next statement, or, if he is in a hurry, the next time he contacts his bank asking about how much money they have for him.

Since banks have many customers, and bank employees require money for doing the job of talking to people and signing documents, banks in recent times have been using machines such as ATMs and web servers, that do the job of interacting with customers instead of paid bank employees. The job of these machines is to learn what each customer wants to do with his/her money and, to the extent that it's possible, act on what the customer wants (for example, ATMs can hand cash). In the end, there is very little human involvement in this process, most of the time. The people can always know how much money out of the money that the bank is safe-keeping is theirs, and they are confident that the numbers they see in their bank statements and on their computer screens stand for the number of dollar bills that they can get from the bank at any time they wish. They can be so sure of that, that they can accept those numbers in the same way they accept paper dollars (this is similar to the way people started accepting paper dollars as they accepted gold or silver).

However, the fact that machines are used does not change the structure of this system, which is, as it was, based on a central authority (the bank) which is responsible for keeping records about how much money belongs to whom. Everybody has to rely on this central authority to be honest (i.e. to say the truth about how much money they are safe-keeping in total, or at least to make the paper money available upon demand from the owners). Also, every person has to identify him/herself to this authority, by giving his/her real name, in order to be allowed to get their paper bills back or to send money to another person.

Bitcoin is a system of owning and voluntarily transferring amounts of so-called bitcoins, in a manner similar to an on-line banking interface, but anonymously and without reliance on a central authority to maintain account balances. These bitcoins are valuable because they are useful and because they are limited in supply.

==Bitcoin Basics==

===Creation of coins===
The creation of coins must be limited for the currency to have any value.

New coins are slowly "mined" into existence by following a mutually agreed-upon set of rules. A user "mining" bitcoins is running a program that searches tirelessly for a solution to a very difficult math problem whose difficulty is precisely known. The difficulty is automatically adjusted regularly so that the number of solutions found globally, by everyone, is constant: an average of 6 per hour. When a solution is found, the user may tell everyone of the existence of this new found solution, along with other information, packaged together in what is called a "block".

Blocks contain 50 bitcoins at present. This amount is an incentive for people to perform the computation work required for block generation. Roughly every 4 years, the number of bitcoins that can be "mined" in a block reduces by 50%. Any blocks that are created by a malicious user that do not follow this rule (or any other rules) will be rejected by everyone else. The result is that no more than 21 million bitcoins will ever exist.

Because the "mining" incentive to put forth the computational power to create blocks will eventually diminish, miners will some day pay for their hardware and electricity costs by collecting [[Transaction_fee|transaction fees]]. The sender of money may voluntarily pay a small transaction fee which will be kept by whoever finds the next block. Paying this fee will encourage the miner to include the transaction in a block more quickly.

===Transferring a coin===
To guarantee that an eavesdropper, Eve, cannot access other people's bitcoins by creating transactions in their names we use a [[Wikipedia:Public-key_cryptography|public key system]] to make digital signatures. In this system, each person, such as Alice and Bob, has a pair of public and private keys which he/she stores in a safe [[Wallet|wallet]]. Only the user with his secret private key can sign a document, such as the transaction to give some of his bitcoins to somebody else, but any one can validate the signature using the user’s public key.

Suppose Alice wants to send a bitcoin to Bob.
* Bob sends his public key to Alice.
* Alice adds Bob’s public key along with the amount she wants to transfer to a message: a 'transaction' message.
* Alice signs the transaction with her secret private key.
* Alice broadcasts the transaction out over the bitcoin network for all to see.

(Only the first step is actually completed by a human. The rest is done by the bitcoin client software.)

As a result, anyone who knows the public keys of both Alice and Bob can now see that Alice agreed to transfer the amount to Bob, because nobody other than Alice has Alice's private key. Alice would be foolish to give her private key to other people, as this would allow them to sign transactions in her name, removing funds from her control.

Later on, when Bob wishes to transfer the same bitcoin to Charley, he will do the same thing:
* Charlie sends Bob his public key.
* Bob adds Charlie's public key along with the amount he wants to transfer to a message: a 'transaction' message.
* Bob signs the transaction with his private key.
* Bob broadcasts the transaction out over the bitcoin network for all to see.

Only Bob can do this because only Bob has the private key that corresponds to the public key Alice included in the previous transaction.

Eve cannot change who the coins belong to by replacing Bob’s public key with her public key, because Alice signed the transfer to Bob using her private key, declaring that the coins which belonged to her now belong to Bob, and Alice's private key is kept secret from Eve. So if Charley accepts that the original coin was in the hands of Alice he will also accept the fact that this coin was later passed to Bob and now Bob is passing this same coin to him.

===Preventing double-spending===
The process described above does not prevent Alice from using a coin in more than one transaction. The following process does. This is the primary innovation behind Bitcoin.

* Details about the [[Transactions|transaction]] are [[Network|sent and forwarded]] to all or as many other computers as possible.
* A constantly growing chain of [[Blocks|blocks]] that contains a record of all transactions is collectively maintained by all computers (each has a full copy).
* To be accepted in the chain, transaction blocks must be valid and must include [[proof of work]] (one block generated by the network every 10 minutes).
* Blocks are chained in a way so that, if any one is modified, all following blocks will have to be recomputed.
* When multiple valid continuations to this chain appear, only the longest such branch is accepted and it is then extended further.

When Bob sees that his transaction has been included in a block, which has been made part of the single longest and fastest-growing block chain (extended with significant computational effort), he can be confident that the transaction by Alice has been accepted by the computers in the network and is permanently recorded, preventing Alice from creating a second transaction with the same coin. In order for Alice to thwart this system and double-spend her coins, she would need to muster more computing power than all other bitcoin users combined.

===Anonymity===
There are no bitcoin "accounts" to set up, no e-mail addresses and no user-names and passwords to give, just for owning bitcoins. Each balance is simply associated with a randomly generated public-private key pair and the money "belongs" to whoever has the private key and can sign transactions with it. Moreover, those keys do not have to be registered anywhere in advance, as they are only actually used if and when there is a transaction involving them. Transacting parties do not need to know each other's identity in the same way that a store owner does not know Bob's name is Bob when Bob goes and buys groceries with cash.

A [[Address|Bitcoin address]] mathematically corresponds to a public key and looks like this:

:15VjRaDX9zpbA8LVnbrCAFzrVzN7ixHNsC

Each person can have many such addresses, each with its own balance, which makes it very difficult to know which person owns what amount. In order to protect his [[Anonymity|privacy]], Bob can even generate a new public-private key pair for each individual transaction. The Bitcoin software encourages this behavior by default. Continuing the example from above, when Charlie receives the bitcoin from Bob, Charlie will not be able to identify who owned the coin before Bob (not without asking Bob).

You have completed reading our Bitcoin introduction!

==Where to see and explore==
You can directly explore the system in action by visiting the [http://blockexplorer.com/ Bitcoin Block Explorer].
The site shows you the latest blocks in the block chain. The [[Block_chain|block chain]] contains the agreed history of all transactions that took place in the system.
Note how many blocks were generated in the last hour which on average will be 6. Also notice the number of transactions and the total amount transferred in the last hour (last time I checked it was about 64 and 15K).
This should give you an indication of how active the system is.

Next, drill into one of these blocks.
Start by noticing that the block's [[hash|hash]] begins with a run of zeros. This what made making it so difficult; a hash that begins with many zeros is much more difficult to find than a hash with few or no zeros. The computer that generated this block had to try many ''Nonce'' values (also listed on the block's page) until it found one that generated this run of zeros.
Next notice the line titled ''Previous block'', each block contains the hash of the block that came before it, this is what forms the chain of blocks.
Now notice all the transactions the block contains. The first transaction is the income earned by the computer that generated this block. It includes a fixed amount of coins created out of thin air and possibly fee collected from other transactions in the same block.

Drill into any of the transactions and you will see how it is made from one or more amounts coming in and out.
The fact that there can be more than one incoming and outgoing amounts, allow the system to join and break amounts in any possible way allowing for any fractional amount needed. Each incoming amount is a transaction from the past (which you can also drill to) coming from an address of someone and each outgoing amount is addressed to someone and will be part of a future transaction (which you can also drill too if it also had already taken place.)

Finally you can drill into any of the [[Address|addresses]] and see what public information is available.

To get an impression of the amount of activity on the Bitcoin network, you might like to visit the monitoring websites [[Bitcoin Monitor]] and [[Bitcoin Watch]]. The first shows a real-time visualization of events on the Bitcoin network and the second lists general statistics on the amount and size of recent transactions.

===How many people use Bitcoin?===

This is quite a difficult question to answer accurately. The best estimation is to count how many bitcoin clients connected to the network in the last 24 hours. We can do this as the client transmits its address to the other members of the network periodically. The estimate as of Sept 2011 is about 60,000 users. To get a more current estimate see [http://bitcoinstatus.rowit.co.uk/ Bitcoin Network Status Charts]

==See Also==

* [http://www.youtube.com/watch?v=Um63OQz3bjo What is Bitcoin?] video introduction
* Installing Bitcoin [[getting started]]
* [[How bitcoin works]]
* [[Using Bitcoin]]
* A gentle introduction to Bitcoin - [[BitcoinMe]]
* Another introduction, ''The Rebooting Of Money'' podcast is found at [[Bitcoin Money]]
* A beginner's step-by-step guide to using Bitcoin, use of alternative wallets, and generally keeping your money and computer secure - [http://BitcoinIntro.com BitcoinIntro.com]

[[zh-cn:简介]]

[[de:Einführung]]