MtGox/API/HTTP/v1

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

example of returned data :

{"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"
}

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 )

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. 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, cancelled or closed (3rd one shouldn't happen)

If the transaction was successfully 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

Examples

bitcoin_dealer (trading script)

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