Bitcoin Wiki - User contributions [en]

MtGox/API/Frameworks

2012-10-14T15:42:45Z

PaulGWebster: merged winproxy->safetynet

'''This section of the wiki is heavily under construction so antipate that some functions and frameworks may not have complete documented examples!'''

== Foreword ==
A list of some of the larger more commonly used FrameWorks used with the MtGox API

== Definition of Terms ==
* Safety caching - This process means the framework will actively cache 'save' information from queries so to reduce the amount of 'outbound' http calls required to mtgox, this is highly recommended as some features such as 'fullDepth' and 'Trades' are limted on MtGox its self.
* Protocol: V0/V1 - Support for the MtGox HTTP protocol version 0 or version 1.
* Protocol: WebSocket - Support for the streaming websocket protocol.
* Adaptive caching - Allow the frameworks cache for trades and depth to be updated adaptively via the WebSocket stream.
* Non-Blocking - The framework uses a non blocking method of communication with the MtGox API, that is its possible to execute many simultaneous tasks in parallel. This is beneficial to large applications that may have to manage multiple trades very quickly.
* Object Orientated - The framework uses an object based programming style.
* Blocking - The framework uses a blocking style of communication with the MtGox API, this menas that for instance when you place an order you have to wait for the information to come back to you before you can proceed. This is often easier to use for small bots and tickers.
* Maintained - If the framework is knowingly maintained.
* COMPAT_Linux - The framework is compatible with: linux.
* COMPAT_WIN32 - The framework is compatible with: windows (32bit).
* COMPAT_WIN32 - The framework is compatible with: windows (64bit).
* COMPAT_BSD - The framework is compatible with: BSD.
* Language - The language the framework is based in and the minimum version required. (Example: Python32, Perl 5.10)

== Frameworks ==

=== POE::Component::MtGox::Client ===
A perl based framework developed by Paul G Webster 'daemon' utilizing the non-blocking functions of POE, no large applications we know about yet use this, however it does implement some impressive features:

* Protocol: V1
* Protocol: WebSocket
* Safety caching
* Adaptive caching
* Non-Blocking
* Object Orientated
* Maintained
* COMPAT_Linux
* COMPAT_BSD
* Language: Perl 5.10+

=== POE::Component::MtGox::Server::SafetyNet ===
A pure adaptive cache for MtGox; that will automatically keep track of all the Trade Histories and Depth queries and serve them its self instead of querying MtGox, so if your client is a bit spam happy and keeps getting dropped by MtGox for spam protection; you can run your own safety net server to get around it. You may also want to run a SafetyNet server if you want to run PoCo-Client-MtGox on windows.

=== Finance::MtGox ===
The original perl based framework for MtGox, unrated.

=== Add more ===

MtGox/API/HTTP/v1

2012-10-13T12:55:45Z

PaulGWebster: small ntoe added to wallet history

MtGox/API/Frameworks

2012-10-13T10:59:01Z

PaulGWebster: Module names update

'''This section of the wiki is heavily under construction so antipate that some functions and frameworks may not have complete documented examples!'''

== Foreword ==
A list of some of the larger more commonly used FrameWorks used with the MtGox API

== Definition of Terms ==
* Safety caching - This process means the framework will actively cache 'save' information from queries so to reduce the amount of 'outbound' http calls required to mtgox, this is highly recommended as some features such as 'fullDepth' and 'Trades' are limted on MtGox its self.
* Protocol: V0/V1 - Support for the MtGox HTTP protocol version 0 or version 1.
* Protocol: WebSocket - Support for the streaming websocket protocol.
* Adaptive caching - Allow the frameworks cache for trades and depth to be updated adaptively via the WebSocket stream.
* Non-Blocking - The framework uses a non blocking method of communication with the MtGox API, that is its possible to execute many simultaneous tasks in parallel. This is beneficial to large applications that may have to manage multiple trades very quickly.
* Object Orientated - The framework uses an object based programming style.
* Blocking - The framework uses a blocking style of communication with the MtGox API, this menas that for instance when you place an order you have to wait for the information to come back to you before you can proceed. This is often easier to use for small bots and tickers.
* Maintained - If the framework is knowingly maintained.
* COMPAT_Linux - The framework is compatible with: linux.
* COMPAT_WIN32 - The framework is compatible with: windows (32bit).
* COMPAT_WIN32 - The framework is compatible with: windows (64bit).
* COMPAT_BSD - The framework is compatible with: BSD.
* Language - The language the framework is based in and the minimum version required. (Example: Python32, Perl 5.10)

== Frameworks ==

=== POE::Component::MtGox::Client ===
A perl based framework developed by Paul G Webster 'daemon' utilizing the non-blocking functions of POE, no large applications we know about yet use this, however it does implement some impressive features:

* Protocol: V1
* Protocol: WebSocket
* Safety caching
* Adaptive caching
* Non-Blocking
* Object Orientated
* Maintained
* COMPAT_Linux
* COMPAT_BSD
* Language: Perl 5.10+

=== POE::Component::MtGox::Server::SafetyNet ===
A pure adaptive cache for MtGox; that will automatically keep track of all the Trade Histories and Depth queries and serve them its self instead of querying MtGox, so if your client is a bit spam happy and keeps getting dropped by MtGox for spam protection; you can run your own safety net server to get around it. This would also be useful for multiple mtgox clients behind the same IP, if you simply need to contact MtGox through PoCo::MtGox::Client the best bit is using PoCo-MtGox-Winproxy.

=== POE::Component::MtGox::Server::WinProxy ===
A proposed extension to PoCo::MtGox that allows the same functionality, but will work on the windows architecture by offsetting processing to a linux or BSD mid-way server. There are security implications with doing this however; the BSD/Linux mid server will have to know your private key/secret, it would be advised that you run your own Mid-Level server on your own for all your windows machines unless you really trust the WinProxy provider.

=== Finance::MtGox ===
The original perl based framework for MtGox, unrated.

=== Add more ===

MtGox/API/Frameworks

2012-10-11T11:19:40Z

PaulGWebster: Phew.

'''This section of the wiki is heavily under construction so antipate that some functions and frameworks may not have complete documented examples!'''

== Foreword ==
A list of some of the larger more commonly used FrameWorks used with the MtGox API

== Definition of Terms ==
* Safety caching - This process means the framework will actively cache 'save' information from queries so to reduce the amount of 'outbound' http calls required to mtgox, this is highly recommended as some features such as 'fullDepth' and 'Trades' are limted on MtGox its self.
* Protocol: V0/V1 - Support for the MtGox HTTP protocol version 0 or version 1.
* Protocol: WebSocket - Support for the streaming websocket protocol.
* Adaptive caching - Allow the frameworks cache for trades and depth to be updated adaptively via the WebSocket stream.
* Non-Blocking - The framework uses a non blocking method of communication with the MtGox API, that is its possible to execute many simultaneous tasks in parallel. This is beneficial to large applications that may have to manage multiple trades very quickly.
* Object Orientated - The framework uses an object based programming style.
* Blocking - The framework uses a blocking style of communication with the MtGox API, this menas that for instance when you place an order you have to wait for the information to come back to you before you can proceed. This is often easier to use for small bots and tickers.
* Maintained - If the framework is knowingly maintained.
* COMPAT_Linux - The framework is compatible with: linux.
* COMPAT_WIN32 - The framework is compatible with: windows (32bit).
* COMPAT_WIN32 - The framework is compatible with: windows (64bit).
* COMPAT_BSD - The framework is compatible with: BSD.
* Language - The language the framework is based in and the minimum version required. (Example: Python32, Perl 5.10)

== Frameworks ==

=== POE::Component::MtGox::Client ===
A perl based framework developed by Paul G Webster 'daemon' utilizing the non-blocking functions of POE, no large applications we know about yet use this, however it does implement some impressive features:

* Protocol: V1
* Protocol: WebSocket
* Safety caching
* Adaptive caching
* Non-Blocking
* Object Orientated
* Maintained
* COMPAT_Linux
* COMPAT_BSD
* Language: Perl 5.10+

=== POE::Component::MtGox::Client::SafetyNet ===
A proposed extension to PoCo::MtGox that allows the same functionality, but will work on the windows architecture by offsetting processing to a linux or BSD mid-way server. There are security implications with doing this however; the BSD/Linux mid server will have to know your private key/secret, it would be advised that you run your own Mid-Level server on your own for all your windows machines unless you really trust the SafetyNet provider.

=== Finance::MtGox ===
The original perl based framework for MtGox, unrated.

=== Add more ===

MtGox/API/Frameworks

2012-10-11T11:15:03Z

PaulGWebster: Re Updated

'''This section of the wiki is heavily under construction so antipate that some functions and frameworks may not have complete documented examples!'''

== Foreword ==
A list of some of the larger more commonly used FrameWorks used with the MtGox API

== Definition of Terms ==
* Safety caching - This process means the framework will actively cache 'save' information from queries so to reduce the amount of 'outbound' http calls required to mtgox, this is highly recommended as some features such as 'fullDepth' and 'Trades' are limted on MtGox its self.
* Protocol: V0/V1 - Support for the MtGox HTTP protocol version 0 or version 1.
* Protocol: WebSocket - Support for the streaming websocket protocol.
* Adaptive caching - Allow the frameworks cache for trades and depth to be updated adaptively via the WebSocket stream.
* Non-Blocking - The framework uses a non blocking method of communication with the MtGox API, that is its possible to execute many simultaneous tasks in parallel. This is beneficial to large applications that may have to manage multiple trades very quickly.
* Object Orientated - The framework uses an object based programming style.
* Blocking - The framework uses a blocking style of communication with the MtGox API, this menas that for instance when you place an order you have to wait for the information to come back to you before you can proceed. This is often easier to use for small bots and tickers.
* Maintained - If the framework is knowingly maintained.
* COMPAT_Linux/COMPAT_WIN32/COMPAT_WIN32/COMPAT_BSD - The framework is compatible with: linux, windows (32bit), windows (64bit) or BSD.

== Frameworks ==

=== POE::Component::MtGox::Client ===
A perl based framework developed by Paul G Webster 'daemon' utilizing the non-blocking functions of POE, no large applications we know about yet use this, however it does implement some impressive features:

* Protocol: V1
* Protocol: WebSocket
* Safety caching
* Adaptive caching
* Non-Blocking
* Object Orientated
* Maintained
* COMPAT_Linux
* COMPAT_BSD

=== POE::Component::MtGox::Client::SafetyNet ===
A proposed extension to PoCo::MtGox that allows the same functionality, but will work on the windows architecture by offsetting processing to a linux or BSD mid-way server. There are security implications with doing this however; the BSD/Linux mid server will have to know your private key/secret, it would be advised that you run your own Mid-Level server on your own for all your windows machines unless you really trust the SafetyNet provider.

=== Finance::MtGox ===
The original perl based framework for MtGox, unrated.

=== Add more ===

MtGox/API/Frameworks

2012-10-11T11:10:47Z

PaulGWebster: blah

MtGox/API/Frameworks

2012-10-11T11:10:04Z

PaulGWebster: added coming up

MtGox/API/Frameworks

2012-10-11T10:58:47Z

PaulGWebster: moved warning up

MtGox/API/Frameworks

2012-10-11T10:58:03Z

PaulGWebster: minor update to layout

== Foreword ==
A list of some of the larger more commonly used FrameWorks used with the MtGox API
This section of the wiki is heavily under construction so antipate that some functions and frameworks may not have complete documented examples!

== Definition of Terms ==
* Safety caching - This process means the framework will actively cache 'save' information from queries so to reduce the amount of 'outbound' http calls required to mtgox, this is highly recommended as some features such as 'fullDepth' and 'Trades' are limted on MtGox its self.

== Frameworks ==

=== POE::Component::MtGox::Client ===
A perl based framework developed by Paul G Webster 'daemon' utilizing the non-blocking functions of POE, no large applications we know about yet use this, however it does implement some impressive features:

* Safety caching

=== Finance::MtGox ===
The original perl based framework for MtGox, unrated.

=== Add more ===

MtGox/API/Frameworks

2012-10-11T10:56:59Z

PaulGWebster: just added stub page for frameworks

== Foreword ==
A list of some of the larger more commonly used FrameWorks used with the MtGox API
This section of the wiki is heavily under construction so antipate that some functions and frameworks may not have complete documented examples!

=== Definition of Terms ===
* Safety caching - This process means the framework will actively cache 'save' information from queries so to reduce the amount of 'outbound' http calls required to mtgox, this is highly recommended as some features such as 'fullDepth' and 'Trades' are limted on MtGox its self.

=== POE::Component::MtGox::Client ===
A perl based framework developed by Paul G Webster 'daemon' utilizing the non-blocking functions of POE, no large applications we know about yet use this, however it does implement some impressive features:

* Safety caching

=== Finance::MtGox ===
The original perl based framework for MtGox, unrated.

=== Add more ===

MtGox/API/HTTP

2012-09-30T02:10:50Z

PaulGWebster: Updated to reflect API updated 0->1

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

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

== Summary ==

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

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

== Cache ==

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

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

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

== Authentication ==

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

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

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

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

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

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

=== perl ===

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

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

<source lang="perl">

#!/usr/bin/perl

use strict;
use warnings;

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

use JSON;
use LWP::UserAgent;

use Data::Dumper;

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

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

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

## user code

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

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

exit 0;

## sub routines and helpers

sub genReq {
my ($uri) = shift;

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

return $req;
};

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

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

</source>
=== PHP ===
<source lang="php">
<?php

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

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

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

// 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 ===
Python version here: https://bitcointalk.org/index.php?topic=49789.msg592388#msg592388

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

=== Java ===

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

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

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

==See Also==

* [[MtGox|Mt. Gox]]

MtGox/API/HTTP

2012-09-30T01:58:39Z

PaulGWebster: Added basic perl client

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

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

== Summary ==

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

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

== Cache ==

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

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

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

== Authentication ==

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

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

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

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

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

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

=== perl ===

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

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

<source lang="perl">

#!/usr/bin/perl

use strict;
use warnings;

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

use JSON;
use LWP::UserAgent;

use Data::Dumper;

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

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

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

## user code

my $request = genReq('0/info.php');
my $res = $lwp->request($request);

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

exit 0;

## sub routines and helpers

sub genReq {
my ($uri) = shift;

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

return $req;
};

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

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

</source>
=== PHP ===
<source lang="php">
<?php

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

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

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

// 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 ===
Python version here: https://bitcointalk.org/index.php?topic=49789.msg592388#msg592388

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

=== Java ===

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

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

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

==See Also==

* [[MtGox|Mt. Gox]]