Bitcoin Wiki - User contributions [en]

MtGox/API/HTTP/v1

2012-06-06T08:46:59Z

Crobin: /* Merchant System */

Ď'''Note: All API methods require a valid User-Agent header.'''
== HTTP API version 1 methods ==

=== Multi Currency Ticker ===

https://mtgox.com/api/1/BTCUSD/ticker
https://mtgox.com/api/1/BTCEUR/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_all":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"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 about prices:'''

* last_local include only the last trade in the selected currency
* last_all is the last trade in ANY currency, converted to your currency
* last_orig include data of the original last trade ( currency,price in currency . . . ),
* last is always the same as last_all

=== Multi Currency depth ===

https://mtgox.com/api/1/BTCPLN/depth?raw

https://mtgox.com/api/1/BTCAUD/depth?raw

=== Multi currency trades ===

https://mtgox.com/api/1/BTCUSD/trades?raw

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

https://mtgox.com/api/1/BTCAUD/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/trades?since=0

https://mtgox.com/api/1/BTCEUR/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:
<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>

The meaning of each field is as follows:
:{| 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?
|-
|}

=== Cancelled Trades ===

https://mtgox.com/api/1/BTCUSD/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/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 . . .

=== redeem a private key ===

https://mtgox.com/api/1/generic/private/bitcoin/addpriv

allows you to add a private key to your account

* parameters :
"key":code
"keytype":"auto"
"description":description

* returns the btc adress and the total number of btcs in this private key

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

=== Order result ===

https://mtgox.com/api/1/generic/private/order/result

parameters : type ( bid or ask ) and order (the order id)

returns a json array like this :

<source lang="javascript">
order_id: '1234234-e9ef-4b75-aa1c-90cd109d24ea',
trades:
[ { trade_id: '1336611143363429',
primary: 'N',
currency: 'USD',
type: 'ask',
properties: 'market,mixed_currency',
item: 'BTC',
amount: [Object],
price: [Object],
date: '2012-05-10 00:52:23' } ],
total_amount:
{ value: '0.01000000',
value_int: '1000000',
display: '0.01000000 BTC',
display_short: '0.01 BTC',
currency: 'BTC' } }</source>

=== Your wallet history ===

https://mtgox.com/api/1/generic/private/wallet/history

parameters : currency, type, date_start, date_end, trade_id, page

only the currency parameter is mandatory

returns a json array with your wallet history

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

pass parameter ?currency=<currency_symbol>

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

=== HOTP key ===

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

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

=== App activation ===

https://mtgox.com/api/1/generic/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
* '''email''': ''int'' Set to 1 to receive an email for each successful payment
* '''autosell''': ''int'' Set to 1 to automatically sell received bitcoins at market price
* '''multipay''': ''int'' Set to 1 to allow multiple payments on the same transaction ID
* '''instant_only''': ''int'' Set to 1 to only allow MtGox users to pay on this transaction

===== 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 ======
<source lang="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);
}
</source>

==== Dynamic Button ====

While you can create buttons through the MtGox website, those are generated with the normal API. To display a button with your API transaction, first add the following markup to your page:

<source lang="html5">
<span class="mtgox" data-id="<txid>" data-amount="<amount>" data-currency="<currency>">
<a href="https://payment.mtgox.com/<txid>">
<img src="https://payment.mtgox.com/img/mtgox-checkout.png" border="0" />
</a>
</span>

<![if !IE]><script type="text/javascript" src="https://payment.mtgox.com/js/button.min.js"></script><![endif]>
</source>

Make sure to change '''<txid>''', '''<amount>''' and '''<currency>''' to whatever value apply to that transaction.

== Examples ==

=== bitcoin_dealer (trading script) ===

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

=== magento mtgox ===

magento ( php ) module : https://github.com/MtGox/magento

==See Also==

* [[MtGox/API/Streaming]]

MtGox/API/HTTP/v1

2012-06-06T08:37:11Z

Crobin:

Ď'''Note: All API methods require a valid User-Agent header.'''
== HTTP API version 1 methods ==

=== Multi Currency Ticker ===

https://mtgox.com/api/1/BTCUSD/ticker
https://mtgox.com/api/1/BTCEUR/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_all":{"value":"5.5594","value_int":"555940","display":"$5.55940","currency":"USD"},
"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 about prices:'''

* last_local include only the last trade in the selected currency
* last_all is the last trade in ANY currency, converted to your currency
* last_orig include data of the original last trade ( currency,price in currency . . . ),
* last is always the same as last_all

=== Multi Currency depth ===

https://mtgox.com/api/1/BTCPLN/depth?raw

https://mtgox.com/api/1/BTCAUD/depth?raw

=== Multi currency trades ===

https://mtgox.com/api/1/BTCUSD/trades?raw

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

https://mtgox.com/api/1/BTCAUD/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/trades?since=0

https://mtgox.com/api/1/BTCEUR/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:
<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>

The meaning of each field is as follows:
:{| 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?
|-
|}

=== Cancelled Trades ===

https://mtgox.com/api/1/BTCUSD/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/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 . . .

=== redeem a private key ===

https://mtgox.com/api/1/generic/private/bitcoin/addpriv

allows you to add a private key to your account

* parameters :
"key":code
"keytype":"auto"
"description":description

* returns the btc adress and the total number of btcs in this private key

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

=== Order result ===

https://mtgox.com/api/1/generic/private/order/result

parameters : type ( bid or ask ) and order (the order id)

returns a json array like this :

<source lang="javascript">
order_id: '1234234-e9ef-4b75-aa1c-90cd109d24ea',
trades:
[ { trade_id: '1336611143363429',
primary: 'N',
currency: 'USD',
type: 'ask',
properties: 'market,mixed_currency',
item: 'BTC',
amount: [Object],
price: [Object],
date: '2012-05-10 00:52:23' } ],
total_amount:
{ value: '0.01000000',
value_int: '1000000',
display: '0.01000000 BTC',
display_short: '0.01 BTC',
currency: 'BTC' } }</source>

=== Your wallet history ===

https://mtgox.com/api/1/generic/private/wallet/history

parameters : currency, type, date_start, date_end, trade_id, page

only the currency parameter is mandatory

returns a json array with your wallet history

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

pass parameter ?currency=<currency_symbol>

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

=== HOTP key ===

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

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

=== App activation ===

https://mtgox.com/api/1/generic/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
* '''email''': ''int'' Set to 1 to receive an email for each successful payment
* '''autosell''': ''int'' Set to 1 to automatically sell received bitcoins at market price
* '''multipay''': ''int'' Set to 1 to allow multiple payments on the same transaction ID
* '''instant_only''': ''int'' Set to 1 to only allow MtGox users to pay on this transaction

===== 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 ====
<source lang="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);
}
</source>

== Examples ==

=== bitcoin_dealer (trading script) ===

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

=== magento mtgox ===

magento ( php ) module : https://github.com/MtGox/magento

==See Also==

* [[MtGox/API/Streaming]]

MtGox/API/HTTP/v1

2012-03-09T03:24:21Z

Crobin:

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

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

=== 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: '''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 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. 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 ====
<source lang="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);
}
</source>

== Examples ==

=== bitcoin_dealer (trading script) ===

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

Main Page

2012-03-06T12:29:15Z

Crobin:

{| id="mp-topbanner" style="width:100%; background:#f6f6f6; margin-top:1.2em; border:1px solid #ddd;"
| style="width:61%; color:#000;" |

{| style="width:100%; border:none; background:none;"
| style="text-align:center; white-space:nowrap; color:#000;" |
<div style="font-size:162%; border:none; margin:0; padding:.1em; color:#000;">Welcome to the [[Bitcoin]] wiki,</div>
<div style="top:+0.2em; font-size:95%;">For all your bitcoin information needs.</div>
<div id="articlecount" style="width:100%; text-align:center; font-size:85%;">[[Special:Statistics|{{NUMBEROFARTICLES}}]] articles.</div>
'''Improve [[:Category:Stubs|this wiki]] and [[Bitcoin:Contributors Award|earn bitcoins]].'''
|}

| style="width:13%; font-size:120%;" |
* <span class="plainlinks">[http://bitcoin.org Frontpage]</span>
| style="width:13%; font-size:120%;" |
* <span class="plainlinks">[[Forums]]</span>
| style="width:13%; font-size:120%; padding-right: 40px;" |
* <span class="plainlinks">[[IRC channels|Chatrooms]]</span>
|}


{| id="mp-upper" style="width: 100%; margin:6px 0 0 0; background:none; border-spacing: 0px;"
| class="MainPageBG" style="width:55%; border:1px solid #cef2e0; background:#f6e5f1; vertical-align:top; color:#000;" |
{| id="mp-left" style="vertical-align:top; background:#f6e5f1;"
! style="padding:2px;" | <h2 id="mp-tfa-h2" style="margin:3px; background:#e9caef; font-size:120%; font-weight:bold; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em;">Bitcoin</h2>
|-
| style="color:#000;" | <div id="mp-tfa" style="padding:2px 5px">{{MainPage_Intro}}</div>
|-
! style="padding:2px" | <h2 id="mp-dyk-h2" style="margin:3px; background:#e9caef; font-size:120%; font-weight:bold; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em;">Why</h2>
|-
| style="color:#000;padding:2px 5px 5px" | <div id="mp-dyk">{{MainPage_Reasons}}</div>
|}
| style="border:1px solid transparent;" |

| class="MainPageBG" style="width:45%; border:1px solid #cedff2; background:#f6e5f1; vertical-align:top;"|
{| id="mp-right" style="width:100%; vertical-align:top; background:#f6e5f1;"
! style="padding:2px" | <h2 id="mp-otd-h2" style="margin:3px; background:#efc1e2; font-size:120%; font-weight:bold; border:1px solid #a3b0bf; text-align:left; color:#000; padding:0.2em 0.4em;">Topic central</h2>
|-
| style="color:#000;padding:2px 5px 5px" | <div id="mp-otd">{{MainPage_Topics}}</div>
|-
! style="padding:2px" | <h2 id="mp-otd-h2" style="margin:3px; background:#efc1e2; font-size:120%; font-weight:bold; border:1px solid #a3b0bf; text-align:left; color:#000; padding:0.2em 0.4em;">FAQ</h2>
|-
| style="color:#000;padding:2px 5px 5px" | <div id="mp-otd">{{MainPage_FAQ}}</div>
|}
|}

== Other pages ==

* '''[[mw:Help:Formatting|Help]]''' - Documentation on wiki editing.
* '''[[Bitcoin.it Wiki|About]]''' - Information on this site.
[[de:Hauptseite]]
[[es:Página Principal]]
[[fr:Accueil]]
[[it:Pagina principale]]
[[pl:Strona główna]]
[[ru:Заглавная страница]]
[[zh-cn:首页]]

__NOTOC____NOEDITSECTION__

MtGox/API/HTTP

2012-03-06T09:58:28Z

Crobin:

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] 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.

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

=== 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 ===
<source lang="javascript">
var querystring = require('querystring'),
https = require('https'),
crypto = require('crypto');

function MtGoxClient(key, secret) {
this.key = key;
this.secret = secret;
}

MtGoxClient.prototype.query = function(path, args, callback) {
var client = this;

// if no args or invalid args provided, just reset the arg object
if (typeof args != "object") args = {};

// generate a nonce
args['nonce'] = (new Date()).getTime() * 1000;
// compute the post data
var post = querystring.stringify(args);
// compute the sha512 signature of the post data
var hmac = crypto.createHmac('sha512', new Buffer(client.secret, 'base64'));
hmac.update(post);

// this is our query
var options = {
host: 'mtgox.com',
port: 443,
path: '/api/' + path,
method: 'POST',
agent: false,
headers: {
'Rest-Key': client.key,
'Rest-Sign': hmac.digest('base64'),
'User-Agent': 'Mozilla/4.0 (compatible; MtGox node.js client)',
'Content-type': 'application/x-www-form-urlencoded'
}
};

// run the query, buffer the data and call the callback
var req = https.request(options, function(res) {
res.setEncoding('utf8');
var buffer = '';
res.on('data', function(data) { buffer += data; });
res.on('end', function() { if (typeof callback == "function") { callback(JSON.parse(buffer)); } });
});

// basic error management
req.on('error', function(e) {
console.log('warning: problem with request: ' + e.message);
});

// post the data
req.write(post);
req.end();
};

var client = new MtGoxClient('mykey', 'mysecret');
client.query('1/BTCUSD/public/ticker', {}, function(json) {
// do something
console.log(json);
});
</source>

MtGox/API/HTTP/v1

2012-03-06T09:41:05Z

Crobin:

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

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

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

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