MtGox/API/HTTP/v1
ĎNote: All API methods require a valid User-Agent header.
HTTP API version 1 methods
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 :
{
"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"}
}
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
Each trade is described by a JSON structure like the following:
{
"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"
}
The meaning of each field is as follows:
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?
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 . . .
idKey
https://mtgox.com/api/1/generic/private/idkey
Returns the idKey used to subscribe to a user's private updates channel in the websocket API. The key is valid for 24 hours.
Your open orders
https://mtgox.com/api/1/generic/private/orders
Returns information about your current open orders. Valid order statuses are: pending, executing, post-pending, open, stop, and invalid.
Your trade history
https://mtgox.com/api/1/generic/private/trades
Returns all of your trades. Does not include fees.
Submit an order
https://mtgox.com/api/1/BTCUSD/private/order/add
parameters:
- type (bid|ask) (easier to remember: bid == buy, 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 developers )
App activation
https://mtgox.com/api/1/generic/public/api/activate
parameters:
- key - Activation key
- name - Device name
- app - App ID
used in mobile apps to obtain an API key/secret pair. Contact MagicalTux on freenode to obtain an app ID. Activation key comes from the user's account, Settings > Access > Application Access.
Merchant System
Order Creation
https://mtgox.com/api/1/generic/private/merchant/order/create
Required Parameters:
- currency: <currency> (for now only BTC is supported)
- amount: <amount as float>
or
- amount_int: <amount as int>
- return_success: <string> Where to redirect the user on payment success
- return_failure: <string> Where to redirect the user on cancellation
Optional Parameters:
- description: <string> A small description that will appear on the payment page (defaults to "Payment to <user_login>")
- ipn: <string> URL that will be called by our services once the payment is complete (more below)
- data: <string> Custom data returned by the IPN
Returns
- transaction: <uuid> A unique transaction ID
- payment_url: <string> URL on which to redirect the user
IPN
The IPN (Instant payment notification) is a mechanism that POST data about a successful payment an a custom URL located on your website right after the payment as been validated. It is signed with your API key. Your website is supposed then to either acknowledge the IPN by returning "[OK]" as is. Anything else will be counted as an error and the system will try sending the IPN back every 30 minutes until it succeed.
Content
The IPN POST data will always contain the following:
- id: <uuid> The transaction ID generated by the initial call
- payment_id: <uuid> The payment ID
- status: <enum> Either paid, partial, cancelled or closed (4th one shouldn't happen)
If the status is partial, the user choose to pay without a MtGox account and bitcoins where detected on the network, we then send you an IPN telling you the amount of bitcoins pending and valid, pending bitcoins have less than 6 confirmations so it is up to you to accept or not the transaction based on that value. Your merchant account will be credited only after the 6 confirmations on our end.
Additional content of the partial IPN:
- amount_pending: <amount as int> The amount still pending confirmations
- amount_valid: <amount as int> The amount of bitcoins for which we had 6 confirmations
- amount_total: <amount as int> The total amount, pending and valid, on the payment address
If the status is paid:
- amount: <amount as int> The amount paid by the user
- currency: <currency> The currency used to pay (should always be BTC for now)
- method: <enum> The payment method, for now MTGOXBTC
- date: <date> The payment date
If data was provided in the initial call:
- data: <string> The data provided when creating the transaction
Signature
IPNs are now signed with the user secret like the original query to prevent fraudulents IPNs Two headers are added to the request:
- HTTP_REST_KEY: <uuid> The ReST key used for the query
- HTTP_REST_SIGN: <string> The IPN signature
HTTP_REST_SIGN is a base64 encoded sha512 HMAC of the post data using your ReST secret as a key.
See below for examples:
PHP
<?php
function mtgox_is_valid_ipn() {
$secret = '';
$raw_post_data = file_get_contents("php://input");
$good_sign = hash_hmac('sha512', $raw_post_data, base64_decode($secret), true);
$sign = base64_decode($_SERVER['HTTP_REST_SIGN']);
return ($sign == $good_sign);
}
Examples
bitcoin_dealer (trading script)
python (django) : https://github.com/rokj/bitcoin_dealer