Bitcoin Wiki - User contributions [en]

MtGox/API/HTTP

2013-04-27T10:53:36Z

Advanced:

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

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

== Summary ==

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

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

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

== Cache ==

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

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

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

== Authentication ==

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

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

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

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

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

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

=== perl ===

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

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

<source lang="perl">

#!/usr/bin/perl

use strict;
use warnings;

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

use JSON;
use LWP::UserAgent;

use Data::Dumper;

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

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

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

## user code

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

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

exit 0;

## sub routines and helpers

sub genReq {
my ($uri) = shift;

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

return $req;
};

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Python ===
<source lang="python">
from urllib import urlencode
import urllib2
import time
from hashlib import sha512
from hmac import HMAC
import base64
import json
def get_nonce():
return int(time.time()*100000)

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

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

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

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

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

=== Java ===

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

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

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

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

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

==See Also==

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

MtGox/API/HTTP

2013-04-26T14:09:08Z

Advanced: /* Java */

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

* [[MtGox/API/HTTP/v0|Version 0]]
* [[MtGox/API/HTTP/v1|Version 1]]
* [[MtGox/API/HTTP/v2|Version 2]]
Version 2 Exists. Its very similar to API 1 although the method of which you hash your signature now includes the URL for better security. The PDF file is here: https://github.com/MtGox/mtgox-doc/blob/master/api/money.pdf?raw=true

== Summary ==

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

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

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

== Cache ==

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

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

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

== Authentication ==

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

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

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

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

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

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

=== perl ===

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

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

<source lang="perl">

#!/usr/bin/perl

use strict;
use warnings;

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

use JSON;
use LWP::UserAgent;

use Data::Dumper;

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

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

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

## user code

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

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

exit 0;

## sub routines and helpers

sub genReq {
my ($uri) = shift;

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

return $req;
};

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Python ===
<source lang="python">
from urllib import urlencode
import urllib2
import time
from hashlib import sha512
from hmac import HMAC
import base64
import json
def get_nonce():
return int(time.time()*100000)

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

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

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

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

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

=== Java ===

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

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

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

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

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

==See Also==

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

MtGox/API/HTTP/v2

2013-04-26T14:07:22Z

Advanced:

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

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

=== Documentation ===
'''unofficial''' documentation (So far the best we have) is provided at :

'''https://bitbucket.org/nitrous/mtgox-api/overview''' 
(The bitcointalk forum link is: '''https://bitcointalk.org/index.php?topic=164404.0'''
 

'''official''' docs are on :

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

===== Technical Use Explanation: =====

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

This is how it was done for version 1:

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

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

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

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

'''The URL is now ''' something along the lines of BTCUSD/money/order/add instead of BTCUSD/private/order/add in api1. 
So in my python code below which is very readable you can see everything remains the same as API v1 except now we are using api2postdatatohash = path + chr(0) + post_data #new way to hash for API 2, includes path + NUL.

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

=== Code Examples: ===

====Java:====

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

====C# :====

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

====Python v 2.7.3====

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

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