Bitcoin Wiki - User contributions [en]

Donation-accepting organizations and projects

2012-07-10T11:41:14Z

Rokj:

Here is a list of organizations that accept bitcoin donations.
Only notable donation-accepting sites should be added here.

{| class="wikitable"
|-
! Organization
! Purpose
! Donation Page
|-
|-
|[http://www.osiris-sps.org Osiris-sps.org]
|Software for decentralized portal, managed and shared via P2P between members.
|[http://www.osiris-sps.org/donations/]
|-
|[http://www.bitcoinfunding.com BitcoinFunding.com]
|[Raise money with bitcoins] Kickstarter style website to raise funds for projects.
|[http://bitcoinfunding.com/]
|-
|-
|[http://www.AncientBeast.com AncientBeast.com]
|[Free Open Source] Turn Based Strategy Game Played Online Against Other People. Master your beasts!
|[http://http://ancientbeast.com/bitcoin]
|-
|[http://www.anonyops.com/index.php Anonyops.com]
|News about Anonymous actions and operations
|[http://anonyops.com/bitcoindonate.php]
|-
|'''[http://www.archive.org/ Archive.org]'''
|Digital archive of public domain media, original open/free media and historical website backups
|[http://www.archive.org/about/faqs.php#311]
|-
|[http://www.anonnews.org/ Anonnews.org]
|Open news platform for Anonymous
|[http://anonnews.org/bitcoin.html]
|-
|[http://awesome.naquadah.org/ awesome]
|Window manager for X11
|[http://awesome.naquadah.org/community/]
|-
|[https://iplayernotifier.appspot.com/ BBC iPlayer Notifier]
|Email and Google Talk notification of new content available on BBC iPlayer
|[https://iplayernotifier.appspot.com/]
|-
|[http://www.beatingdebt.org BeatingDebt.org]
|Teaching debt prevention by placing educational ads, supporting debt prevention groups, and providing online resources
|[http://www.beatingdebt.org/donate.php#BitCoinDonation]
|-
|[http://www.backbox.org/ Backbox]
|Ubuntu-based GNU/Linux distribution for perform penetration tests and security assessments for ethical hacking
|[http://www.backbox.org/services]
|-
|[http://www.kk-velikelasce.si/ Basketball club KK Velike Lašče]
|Basketball club KK Velike Lašče from Slovenia playing in the lower national league
|[http://www.kk-velikelasce.si/pokrovitelji/]
|-
|[http://www.bitcharity.org/ BitCharity]
|Hub for donating to charities using Bitcoin
|[http://www.bitcharity.org]
|-
|[https://bitcointalk.org/index.php?topic=52543.0 Bitcoin 100]
|Bitcoin 100: A Kickstarter for Charities (1BTC1oo)
|[https://bitcointalk.org/index.php?topic=52543.0]
|-
|[http://www.bitcoinspot.nl/ Bitcoinspot]
|Dutch website and forum about Bitcoins, how to acquire and how to use them.
|[http://www.bitcoinspot.nl/nieuws-algemeen/bitcoin-browser-integratie.html]
|-
|[http://www.bluetile.org Bluetile]
|Tiling window manager for GNOME
|[http://www.bluetile.org/#development]
|-
|[http://brmlab.cz/ Brmlab, hackerspace]
|The first hackerspace in the Czech Republic
|[http://brmlab.cz/project/bitcoin]
|-
|[http://c4ss.org/ Center for a Stateless Society]
|Builds public awareness of, and support for, market anarchism
|[http://c4ss.org/support-the-center]
|-
|[http://www.cheat-sheets.org/ Cheat-Sheets.org]
|Cheat/round-up/reference cards/guides/sheets for programming languages and software
|[http://www.cheat-sheets.org/]
|-
|[http://www.chambaproject.in/ Chamba Project]
|An effort to create a Swathanthra (Free/Libre/Open/Mukt) Animation Movie by pooling in contributions from people around the world and funding artists directly.
|[http://www.chambaproject.in/contribute/]
|-
|[http://www.bitcoinsreview.com Consumer - Merchant Trust Project]
|An initiative to increase trust between Consumer and Bitcoin Merchants. Proceedspay for hosting, ads, etc.
|[http://www.bitcoinsreview.com/donate/]
|-
|[http://convergence.io Convergence]
|Agile, distributed, and secure strategy for replacing certificate authorities.
|[http://convergence.io/involved.html]
|-
|[http://ccbib.org Creative Commons Bibliothek]
|Creative Commons and Public Domain library. Includes book source code for easy reprinting with custom layout. Local groups produce paper versions for lending.
|[http://ccbib.org/donate/]
|-
|[http://www.cryto.net/ Cryto Coding Collective]
|Host for IRC and web for free/libre software and cultural projects
|[http://www.cryto.net/donate/]
|-
|[http://www.DecryptedMatrix.com/ Decrypted Matrix ]
|Blog on science, society, nature, politics etc.
|[http://www.DecryptedMatrix.com]
|-
|[http://www.degenernet.com/ Degenernet Radio]
|Online radio station dedicated independent music from all genres
|[http://www.degenernet.com/donate.php]
|-
|[https://www.diasporafoundation.org/ Diaspora Foundation]
|Developers and hosts of a distributed "social network"
|[https://www.diasporafoundation.org/donate#bitcoin]
|-
|[http://www.digitalprecursor.org/ Digital Precursor]
|Website and Forum dedicated to scientific learning (particularly energetics)
|[http://www.digitalprecursor.org/content.php/93-Anonymous-Donations-Now-Available]
|-
|[http://opensource.doppelstern.com Doppelstern Antispam]
|Doppelstern Antispam signatures for ClamAV
|[http://opensource.doppelstern.com]
|-
|[http://www.dosbox.com/ DOSBox]
|An x86 emulator with DOS
|[http://www.dosbox.com/crew.php]
|-
|[http://www.downsizedc.org/link?uri=/&src=btc-wiki DownsizeDC.org]
|USA federal government downsizing movement
|[https://secure.downsizedc.org/contribute/]
|-
|[http://www.duplicati.com/ Duplicati]
|Free, open source backup client that securely stores encrypted, incremental, compressed backups on cloud storage services and remote file servers. It works with Amazon S3, Windows Live SkyDrive, Google Drive (Google Docs), Rackspace Cloud Files or WebDAV, SSH, FTP (and many more).
|[http://www.duplicati.com/]
|-
|[http://www.dyne.org Dyne.org]
|Since the year 2000 producing free and open source software for media activism: makers of the 100% Free Dyne:bolic GNU/Linux distribution and more software to record, edit and stream audio and video materials on-line, encrypt private communications and recycle existing hardware.
|[http://www.dyne.org]
|-
|[http://spices.org.my/ Early Intervention Program at SPICES]
|Non-profit organization providing services to children with learning disabilities since 1997
|[http://spices.org.my/be-involved/donations/]
|-
|[http://encyclopediadramatica.ch/Main_Page Encyclopedia Dramatica]
|4chan's Wikipedia
|[http://encyclopediadramatica.ch/donate.php]
|-
|[https://www.erowid.org/ Erowid]
|Portal on psychoactive plants and chemicals, meditation, lucid etc.
|[https://www.erowid.org/donations/donations_bitcoin.php]
|-
|[http://eudemocracia.org/english.html Eudemocracia] NGO
|Dedicated to the creation of a modern form of government that combines direct democracy and internet.
|[http://wiki.eudemocracia.org/en/donaciones]
|-
|[http://www.expanton.com Expanton]
|Occupy Wall Street Support
|[http://www.expanton.com/]
|-
|[http://www.ezyorg.com/ Ezyorg.com]
|Organizing & Planning Tool
|[http://ezyorg.com/]
|-
|[http://www.foo.be/forban/ Forban]
|Filesharing protocol for local area networks
|[http://www.foo.be/forban/]
|-
|[http://freedomboxfoundation.org FreedomBox Foundation]
|Non-profit turning small plug computers into personal servers that guard your privacy, anonymity and security.
|[https://freedomboxfoundation.org/donate]
|-
|[https://freenetproject.org/ Freenet Project]
|The Free Network
|[https://freenetproject.org/donate.html]
|-
|[http://www.fsf.org Free Software Foundation]
|Worldwide advocate for software freedom and host organization for the GNU Project.
|[https://my.fsf.org/donate/other]
|-
|[http://www.freetalklive.com/ Free Talk Live]
|Help spread the message of liberty by donating to a liberty leaning nationally syndicated radio show!
|[http://www.freetalklive.com/bitcoin]
|-
|[http://freedomainradio.com/ Freedomain Radio]
|Online philosophical conversation about freedom, religion, the state, and the family
|[http://board.freedomainradio.com/forums/t/30241.aspx]
|-
|[http://www.freehal.org/ FreeHAL]
|a self-learning artificial intelligence available as free software
|[http://www.freehal.net/funds/?p=do&l=en]
|-
|[http://www.FreezingMoon.org FreezingMoon.org]
|Free Open Source Game Development Organization
|[http://http://FreezingMoon.org/bitcoin]
|-
|[http://www.gentlelan.de/ GentleLAN]
|Since many years free private LANs in Bremen / Germany
|[http://www.gentlelan.de/?page_id=193]
|-
|[http://www.girlsgonebitcoin.info GirlsGoneBitcoin]
|Girls gone wild with bitcoin accepting donations!
|[http://www.girlsgonebitcoin.info/]
|-
|[http://http://www.groupbstrepinternational.org/ Group B Strep International]
|Promoting GBS Awareness Worldwide
|[http://www.groupbstrepinternational.org/donate.html]
|-
|[http://gzzt.org/ GZZT.org]
|Popular Useful Links Reference Site
|[http://gzzt.org]
|-
|[http://www.reddit.com/r/hackbloc HackBloc on Reddit]
|Hacktivism, Crypto-anarchy, Darknets.
|[http://www.reddit.com/r/hackbloc]
|-
|[http://www.heavensentgaming.com Heaven Sent Gaming]
|Heaven Sent Gaming is a new media entertainment group founded by Mario Lucero and Isabel Ruiz, in 2006, as a game development team.
|[http://heavensentgaming.com/support-and-donations/]
|-
|[http://www.helplinux.ru Help Linux]
|Russian language Linux support
|[http://helplinux.ourproject.org/wiki/about:start]
|-
|[http://thejuicemedia.com Juice Rap News]
|Juice Rap News - the news show for the Internet nation, delivering a bulletin to restore your faith in the fourth estate, make you nod your head to the beat even as you shake it in disbelief.
|[http://thejuicemedia.com/donate/]
|-
|[http://i2p2.de/ I2P Anonymous Network]
|Anonymising network similar to tor
|[http://www.i2p2.de/donate.html]
|-
|[http://www.intercom.gs/ Intercom - Emergency Communications Division]
|We Build Censorship Resistant Phone and Communications Networks
|[http://www.intercom.gs/support.html]
|-
|[http://www.partito-pirata.it/ Italian Pirate Party]
|Italian Pirate Party - Associazione Partito Pirata Italia
|[http://www.partito-pirata.it/magazzino/payBTC.html]
|-
|[http://lifeboat.com Lifeboat Foundation]
|Organization for scientific advancements and against harm from technological progress
|[https://lifeboat.com/ex/summer.growth]
|-
|[http://lorea.org/ Lorea]
|A distributed and federated organization working on pushing open source for social networking, social economy and autonomy of the people.
|[https://n-1.cc/pg/pages/view/14888/]
|-
|[http://biohackers.la/ Los Angeles Biohackers]
|Grass-roots biotechnology lab in downtown Los Angeles
|[http://www.socal-diybio.org/Main_Page#Donate]
|-
|[http://la.indymedia.org/ Los Angeles Indymedia]
|User-generated left-wing news.
|[http://la.indymedia.org/]
|-
|[http://love2d.org/ LÖVE]
|An open source 2D game engine that uses the Lua programming language.
|[http://love2d.org/]
|-
|[http://mars.radiome.me M.A.R.S. Radio]
|Commercial-free alternative rock online radio station
|[http://radiome.me/]
|-
|[http://joyridelabs.de/game Nikki and the Robots]
|Cute cross-platform open source platformer game by Joyride Labs
|[http://joyridelabs.de/blog]
|-
|[https://github.com/FellowTraveler/Open-Transactions/ Open Transactions]
|Easy-to-use, Financial Crypto and Digital Cash Library.
|[https://github.com/FellowTraveler/Moneychanger]
|-
|[http://opengameart.org/ OpenGameArt.org]
|Produces and hosts freely licensed art for use in open source games
|[http://opengameart.org/content/donate-bitcoins]
|-
|[http://www.openwall.com Openwall Project]
|Development of information security related free software, information security research, publications, and community activities aimed at making existing free software safer to use.
|[http://www.openwall.com/donations/]
|-
|[https://www.operationanonymous.org/ Operation Anonymous]
|Anonymous Political Group
|[http://www.operationanonymous.org/]
|-
|[http://www.organicdesign.co.nz OrganicDesign]
|A group developing methods and tools to support open-source bottom-up peer-to-peer governance for the people
|[http://www.organicdesign.co.nz]
|-
|[http://www.paniq.cc paniq.cc]
|Music from the other side of the universe
|[http://www.paniq.cc]
|-
|[http://www.liberallibertario.org Partido Liberal Libertario]
|Libertarian Party of Argentina
|[http://www.liberallibertario.org/aportes]
|-
|[http://http://www.p2pfoundation.net P2P Foundation]
|Researching, documenting and promoting peer to peer practices
|[http://blog.p2pfoundation.net/why-the-p2p-foundation-is-paying-its-salaries-in-bitcoin/2012/03/28]
|-
|[http://patch-tag.com/ Patch-Tag.com]
|Darcs and gitit wiki hosting for open source projects
|[http://patch-tag.com/h/pricing]
|-
|[http://pioneerone.tv/ Pioneer One]
|TV series funded purely through donations
|[https://twitter.com/pioneeronetv/status/36119594439544832]
|-
|[http://pirax.de/ PiraX]
|Hacker collective and web-tool pioneers.
|[http://pirax.de/donate/]
|-
|[http://plankhead.com/ Plankhead]
|Free/open source media and arts organization
|[http://plankhead.com/donate]
|-
|[http://plaztika.com/?lang=en Plaztika]
|Virtual art space. Non-profit/runs on donations. New artists are welcome to join.
|[http://plaztika.com/Who-are-we]
|-
|[https://privacybox.de/index.en.html PrivacyBox]
|System for anonymous and non-trackable contact forms
|[https://privacybox.de/donations.en.html]
|-
|[http://bitcoinintro.com/project-hidden-treasure/ Project Hidden Treasure]
|Promotes Bitcoin to new users by 'hiding' them in Geocaches. Also explains Bitcoin use and security.
|[http://bitcoinintro.com/project-hidden-treasure/]
|-
|[http://prometheusfusionperfection.com/ Prometheus Fusion Perfection]
|Open source nuclear fusion research
|[http://prometheusfusionperfection.com/2011/02/04/bitcoin-fundraiser/]
|-
|[http://protestbarrick.net/ Protest Barrick]
|A global campaign against the world's largest gold miner
|[http://protestbarrick.net/article.php?id=764]
|-
|[http://queeky.com/ Queeky]
|an online drawing community with special drawing tools and creative users from all around the world
|[http://www.queeky.com/content/support-queeky-and-donate]
|-
|[http://www.reactos.org/ ReactOS]
|Free open source Windows-compatible operating system
|[http://www.reactos.org/en/foundation_donate.html]
|-
|[http://www.recycles.org/ Recycles.Org]
|Nonprofit Recycling and ReUse Network - Nationwide (USA) technology exchange clearinghouse for nonprofits
|[http://www.recycles.org/computer/donation/support/]
|-
|[https://ripplepay.com/ Ripple]
|Payment system based on trust networks
|[https://ripplepay.com/donate/]
|-
| [https://riseup.net/ Riseup]
| Anti-capitalist collective
|[https://help.riseup.net/en/donate#bitcoin]
|-
|[http://rusinfo.cc/ RusInfo]
|Russian info agency
|[http://rusinfo.cc/help]
|-
|[http://seasteading.org The Seasteading Institute]
|To further the establishment and growth of permanent, autonomous ocean communities, enabling innovation with new political and social systems.
|[http://twitter.com/#!/patrissimo/status/76392851558244353]
|-
|[http://singinst.org Singularity Institute]
|Artificial Intelligence
|[http://singinst.org/donate]
|-
|[http://somefunnypranks.com/ SomeFunnyPranks.com]
|Audio recordings of phone pranks under Creative Commons
|[http://somefunnypranks.com/]
|-
|[http://sosmazunte.weeno.net/ ¡SOS Mazunte!]
|Support campaign after the Carlotta hurricane that hit the coast of Oaxaca (Mexico), particularly the community of Mazunte, on June 15th.
|[http://sosmazunte.weeno.net/]
|-
|[http://www.sparkleshare.org/ SparkleShare]
|A Free and Open Source host it yourself replacement for file syncing services like Dropbox. It uses the distributed version control system Git as a backend.
|[http://www.sparkleshare.org/support-us/]
|-
|[http://www.demokracjabezposrednia.pl Stowarzyszenie Więcej Demokracji]
|Association for direct democracy in Poland
|[http://www.demokracjabezposrednia.pl/donate]
|-
|[http://wiki.sugarlabs.org Sugar Labs]
|Free/open sourcee education/learning software
|[http://wiki.sugarlabs.org/go/Donate]
|-
|[http://gorod-solnca.org/ Sun City]
|Ukrainian centre for children in difficult circumstances
|[http://sms.gorod-solnca.org/]
|-
|[http://www.symphonyofscience.com/ Symphony of Science]
|A musical project headed by John Boswell, to deliver scientific knowledge in musical form.
|[http://www.symphonyofscience.com/]
|-
|[http://tahoe-lafs.org/ Tahoe-LAFS]
|A distributed filesystem with funky redundancy properties
|[http://tahoe-lafs.org/trac/tahoe-lafs/wiki/BitCoinPage]
|-
|[http://tangorin.com Tangorin Japanese Dictionary]
|Free online Japanese dictionary in development since October 2007 by a former Japanology student.
|[http://tangorin.com/bitcoin]
|-
|[http://tmac.technitium.com/ Technitium]
|Freeware MAC Address Changer
|[http://blog.technitium.com/2011/08/accepting-donations-again.html]
|-
|[http://the-alternative.co.uk/support-us/ The-alternative.co.uk]
|Alternative news and articles
|[http://the-alternative.co.uk/support-us/]
|-
|[http://theexperiments.com The Experiments]
|A rock / punk band who's music is free to download and licensed under the Creative Commons
|[http://theexperiments.com]
|-
|[http://theicarusproject.net The Icarus Project]
|A mutual aid/peer support organization dedicated to radical mental health
|[http://theicarusproject.net/about-us/donate-to-the-icarus-project]
|-
| [http://ThePythonGameBook.com ThePythonGameBook]
| Free CC/GPL licensed wikibook to learn open source game programming in Python
| [http://thepythongamebook.com/en:help?&#donating_money]
|-
|[http://Tn3t.com/ TN3T LLC TOR Project]
|TN3T LLC operates 2 TOR exit nodes.
| [http://tn3t.com/donate.txt]
|-
|[http://torchat.googlecode.com/ TorChat]
|A serverless encrypted anonymous instant messenger running on top of the Tor network
|[http://torchat.googlecode.com/]
|-
|[https://www.torservers.net/ Torservers.net]
|Runs [http://www.torproject.org/ Tor] relays and bridges
|[https://www.torservers.net/donate.html#anonymous]
|-
|[https://vaizard.org/ Vaizard institute]
| Backing people who want to make the world a better place by making their ideas real.
|[https://vaizard.org/en/about/contacts/]
|-
|[http://wikileaks.org Wikileaks]
|Whistleblower website
|[http://wikileaks.org/support.html]
|-
|[http://wlcentral.org/ WL Central]
|News, analysis and actions related to Wikileaks
|[http://wlcentral.org/q-a]
|-
|[http://www.wakingupmovie.com Waking Up Movie Project]
|Humanist collaborative film project
|[http://www.wakingupmovie.com/2011/12/bitcoin-donations/]
|-
|[https://wikispooks.com/wiki/Main_Page Wikispooks]
|An encyclopedia of deep political structures and events
|[https://wikispooks.com/wiki/WikiSpooks:Donate]
|-
|[http://yorba.org Yorba]
|Software group developing free desktop applications for GNOME
|[http://yorba.org/donate]
|-
|[http://420chan.org/ 420chan]
|Imageboard community
|[http://420chan.org/donate/]
|}

MtGox/API

2012-02-23T18:37:47Z

Rokj: /* API version 0 examples */

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 (100,000,000) || 0.00000001
|-
| USD (price) || 1E5 (100,000) || 0.00001
|-
| JPY (price) || 1E3 (1,000) || 0.001
|}

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

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

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

== 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);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

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

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

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

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

Python 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

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

* returns a bitcoin deposit address

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

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

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

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

encoding is utf-8

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

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

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

==== 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/BTCUSD/public/trades?raw

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

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

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

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

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

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

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

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

==== Cancelled Trades ====

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

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

==== Full Depth ====

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

returns full depth

==== Private info ====

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

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

==== Your open orders ====

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

returns information about your current open orders

==== Submit an order ====

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

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

submits an order and returns info about success or error

==== Currency information ====

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

pass parameter ?currency=<currency_symbol>

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

==== HOTP key ====

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

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

=== API version 1 examples ===

==== bitcoin_dealer (trading script) ====

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

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

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

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

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

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

'''trade''' contains the following:

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

====Depth====

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

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

'''depth''' contains the following:

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

|}

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

Commands that can be sent without authentication

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

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

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

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

==== Authenticated commands ====

These commands require an API key and secret pair to sign requests. Any of the "version 1" requests from the HTTP API can be called.

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

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

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

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

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

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

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

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

=== examples ===

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

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

http://github.com/hookio

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

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

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

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

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

2012-02-23T18:37:17Z

Rokj:

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 (100,000,000) || 0.00000001
|-
| USD (price) || 1E5 (100,000) || 0.00001
|-
| JPY (price) || 1E3 (1,000) || 0.001
|}

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

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

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

== 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);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

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

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

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

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

Python 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

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

* returns a bitcoin deposit address

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

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

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

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

encoding is utf-8

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

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

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

==== 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/BTCUSD/public/trades?raw

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

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

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

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

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

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

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

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

==== Cancelled Trades ====

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

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

==== Full Depth ====

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

returns full depth

==== Private info ====

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

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

==== Your open orders ====

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

returns information about your current open orders

==== Submit an order ====

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

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

submits an order and returns info about success or error

==== Currency information ====

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

pass parameter ?currency=<currency_symbol>

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

==== HOTP key ====

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

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

=== API version 0 examples ===

==== bitcoin_dealer (trading script) ====

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

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

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

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

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

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

'''trade''' contains the following:

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

====Depth====

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

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

'''depth''' contains the following:

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

|}

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

Commands that can be sent without authentication

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

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

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

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

==== Authenticated commands ====

These commands require an API key and secret pair to sign requests. Any of the "version 1" requests from the HTTP API can be called.

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

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

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

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

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

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

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

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

=== examples ===

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

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

http://github.com/hookio

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

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

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

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

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

2012-02-23T13:42:45Z

Rokj: /* Submit an order */

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 (100,000,000) || 0.00000001
|-
| USD (price) || 1E5 (100,000) || 0.00001
|-
| JPY (price) || 1E3 (1,000) || 0.001
|}

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

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

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

== 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);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

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

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

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

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

Python 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

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

* returns a bitcoin deposit address

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

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

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

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

encoding is utf-8

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

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

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

==== 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/BTCUSD/public/trades?raw

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

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

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

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

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

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

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

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

==== Cancelled Trades ====

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

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

==== Full Depth ====

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

returns full depth

==== Private info ====

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

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

==== Your open orders ====

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

returns information about your current open orders

==== Submit an order ====

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

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

submits an order and returns info about success or error

==== Currency information ====

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

pass parameter ?currency=<currency_symbol>

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

==== HOTP key ====

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

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

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

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

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

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

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

'''trade''' contains the following:

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

====Depth====

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

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

'''depth''' contains the following:

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

|}

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

Commands that can be sent without authentication

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

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

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

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

==== Authenticated commands ====

These commands require an API key and secret pair to sign requests. Any of the "version 1" requests from the HTTP API can be called.

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

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

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

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

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

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

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

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

=== examples ===

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

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

http://github.com/hookio

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

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

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

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

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

2012-02-23T13:42:21Z

Rokj: /* Submit an order */

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 (100,000,000) || 0.00000001
|-
| USD (price) || 1E5 (100,000) || 0.00001
|-
| JPY (price) || 1E3 (1,000) || 0.001
|}

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

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

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

== 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);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

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

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

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

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

Python 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

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

* returns a bitcoin deposit address

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

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

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

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

encoding is utf-8

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

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

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

==== 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/BTCUSD/public/trades?raw

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

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

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

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

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

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

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

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

==== Cancelled Trades ====

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

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

==== Full Depth ====

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

returns full depth

==== Private info ====

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

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

==== Your open orders ====

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

returns information about your current open orders

==== Submit an order ====

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

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

submits an order and returns info about success or error

==== Currency information ====

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

pass parameter ?currency=<currency_symbol>

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

==== HOTP key ====

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

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

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

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

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

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

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

'''trade''' contains the following:

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

====Depth====

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

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

'''depth''' contains the following:

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

|}

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

Commands that can be sent without authentication

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

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

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

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

==== Authenticated commands ====

These commands require an API key and secret pair to sign requests. Any of the "version 1" requests from the HTTP API can be called.

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

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

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

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

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

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

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

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

=== examples ===

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

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

http://github.com/hookio

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

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

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

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

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

2012-02-23T09:32:40Z

Rokj: One zero was missing.

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 (100,000,000) || 0.00000001
|-
| USD (price) || 1E5 (100,000) || 0.00001
|-
| JPY (price) || 1E3 (1,000) || 0.001
|}

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

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

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

== 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);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

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

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

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

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

Python 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

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

* returns a bitcoin deposit address

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

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

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

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

encoding is utf-8

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

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

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

==== 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/BTCUSD/public/trades?raw

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

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

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

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

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

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

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

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

==== Cancelled Trades ====

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

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

==== Full Depth ====

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

returns full depth

==== Private info ====

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

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

==== Your open orders ====

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

returns information about your current open orders

==== Submit an order ====

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

parameters:
* type (bid|ask)
* amount_int <amount as int>
* price_int <price as int> (can be omitted to place market order)

submits an order and returns info about success or error

==== Currency information ====

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

pass parameter ?currency=<currency_symbol>

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

==== HOTP key ====

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

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

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

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

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

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

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

'''trade''' contains the following:

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

====Depth====

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

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

'''depth''' contains the following:

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

|}

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

Commands that can be sent without authentication

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

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

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

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

==== Authenticated commands ====

These commands require an API key and secret pair to sign requests. Any of the "version 1" requests from the HTTP API can be called.

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

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

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

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

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

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

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

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

=== examples ===

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

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

http://github.com/hookio

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

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

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

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

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

2012-02-21T10:29:13Z

Rokj: This one.

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);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);

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

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

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

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

Python 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

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

* returns a bitcoin deposit address

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

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

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

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

encoding is utf-8

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

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

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

==== 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/BTCUSD/public/trades?raw

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

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

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

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

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

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

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

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

==== Cancelled Trades ====

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

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

==== Full Depth ====

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

returns full depth

==== Private info ====

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

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

==== Your open orders ====

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

returns information about your current open orders

==== Submit an order ====

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

parameters:
* type (bid|ask)
* amount_int <amount as int>
* price_int <price as int> (can be omitted to place market order)

submits an order and returns info about success or error

==== Currency information ====

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

pass parameter ?currency=<currency_symbol>

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

==== HOTP key ====

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

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

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

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

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

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

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

'''trade''' contains the following:

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

====Depth====

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

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

'''depth''' contains the following:

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

|}

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

Commands that can be sent without authentication

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

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

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

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

==== Authenticated commands ====

These commands require an API key and secret pair to sign requests. Any of the "version 1" requests from the HTTP API can be called.

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

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

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

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

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

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

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

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

=== examples ===

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

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

http://github.com/hookio

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

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

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

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

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

2012-02-21T10:28:37Z

Rokj: If we are verifiying peer, connection will not establish.

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);
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

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

* returns a bitcoin deposit address

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

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

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

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

encoding is utf-8

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

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

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

==== 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/BTCUSD/public/trades?raw

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

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

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

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

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

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

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

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

==== Cancelled Trades ====

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

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

==== Full Depth ====

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

returns full depth

==== Private info ====

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

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

==== Your open orders ====

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

returns information about your current open orders

==== Submit an order ====

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

parameters:
* type (bid|ask)
* amount_int <amount as int>
* price_int <price as int> (can be omitted to place market order)

submits an order and returns info about success or error

==== Currency information ====

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

pass parameter ?currency=<currency_symbol>

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

==== HOTP key ====

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

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

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

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

The session ID expires after 30 seconds

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

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

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

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

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

Some of the channels are:

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

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

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

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

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

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

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

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

'''trade''' contains the following:

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

====Depth====

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

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

'''depth''' contains the following:

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

|}

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

Commands that can be sent without authentication

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

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

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

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

==== Authenticated commands ====

These commands require an API key and secret pair to sign requests. Any of the "version 1" requests from the HTTP API can be called.

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

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

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

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

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

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

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

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

=== examples ===

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

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

http://github.com/hookio

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

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

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

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

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