MtGox/API/HTTP/v1: Difference between revisions

From Bitcoin Wiki
Jump to navigation Jump to search
← Older edit
Nederhoed (talk | contribs)
Editors
4 edits
Neofutur (talk | contribs)
Editors
228 edits
 
(19 intermediate revisions by 5 users not shown)
Line 7: Line 7:
==== Multi Currency Ticker ====
==== Multi Currency Ticker ====


  https://mtgox.com/api/1/BTCUSD/ticker
  http://data.mtgox.com/api/1/BTCUSD/ticker
https://mtgox.com/api/1/BTCEUR/ticker


returns the current ticker for the selected currency :
returns the current ticker for the selected currency :
 
caching and rate limit :30 seconds


<source lang="php">
<source lang="php">
Line 43: Line 44:
* last_orig  include data of the original last trade ( currency,price in currency . . . ),
* last_orig  include data of the original last trade ( currency,price in currency . . . ),
* last is always the same as last_all
* last is always the same as last_all
==== Fast Ticker ====
http://data.mtgox.com/api/1/BTCUSD/ticker_fast


==== Multi Currency depth ====
==== Multi Currency depth ====


https://mtgox.com/api/1/BTCPLN/depth?raw
http://data.mtgox.com/api/1/BTCUSD/depth/fetch
 
https://mtgox.com/api/1/BTCAUD/depth?raw


==== Multi currency trades ====
==== Multi currency trades ====


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


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


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


to get only the trades since a given trade id, you can add the parameter since=<trade_id>
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://data.mtgox.com/api/1/BTCUSD/trades?since=0


https://mtgox.com/api/1/BTCEUR/trades?since=1316312781670700
https://data.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
For multi currency,also returns the primary value,"Y" or "N", the primary currency is always the buyers currency
Line 113: Line 118:
==== Cancelled Trades ====
==== Cancelled Trades ====


https://mtgox.com/api/1/BTCUSD/cancelledtrades
https://data.mtgox.com/api/1/BTCUSD/cancelledtrades


returns a list of all the cancelled trades this last month, list of trade ids in json format .
returns a list of all the cancelled trades this last month, list of trade ids in json format .
Line 119: Line 124:
==== Full Depth ====
==== Full Depth ====


https://mtgox.com/api/1/BTCUSD/fulldepth
https://data.mtgox.com/api/1/BTCUSD/depth/full
 
returns full depth
returns full depth


Line 126: Line 130:


==== transaction information  ====
==== transaction information  ====
https://mtgox.com/api/1/generic/bitcoin/tx_details?hash=4462c88079cc51972f1bdcb8a4240ee8757b0bb69df828ade051c95ced540fa0
https://data.mtgox.com/api/1/generic/bitcoin/tx_details?hash=4462c88079cc51972f1bdcb8a4240ee8757b0bb69df828ade051c95ced540fa0


will return :
will return :
Line 174: Line 178:
block information can be accessed by depth ( the block number ) :
block information can be accessed by depth ( the block number ) :


https://mtgox.com/api/1/generic/bitcoin/block_list_tx?depth=188111
https://data.mtgox.com/api/1/generic/bitcoin/block_list_tx?depth=188111


or by hash :
or by hash :


https://mtgox.com/api/1/generic/bitcoin/block_list_tx?hash=000000000000076fa606a7b67c131afc87d24d34114be2863cf24ca3d48139e7
https://data.mtgox.com/api/1/generic/bitcoin/block_list_tx?hash=000000000000076fa606a7b67c131afc87d24d34114be2863cf24ca3d48139e7


both will return ( for block 188111 )  
both will return ( for block 188111 )  
Line 203: Line 207:


==== address information ====
==== address information ====
https://mtgox.com/api/1/generic/bitcoin/addr_details?hash=1f27d1fc284143729944ab89823111d2bb63dc46
https://data.mtgox.com/api/1/generic/bitcoin/addr_details?hash=1f27d1fc284143729944ab89823111d2bb63dc46




==== Order lag ====
==== Order lag ====


https://mtgox.com/api/1/generic/order/lag
https://data.mtgox.com/api/1/generic/order/lag


The "lag" value is the age in microseconds of the oldest order pending execution
The "lag" value is the age in microseconds of the oldest order pending execution
Line 215: Line 219:
==== Currency information ====
==== Currency information ====


https://mtgox.com/api/1/generic/currency
https://data.mtgox.com/api/1/generic/currency


pass parameter ?currency=<currency_symbol>
pass parameter ?currency=<currency_symbol>
https://data.mtgox.com/api/1/generic/currency?currency=EUR


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


=== Private API ===
=== Private API ===
 
3/25/2013 09:15AM<@MagicalTux> btw for api v1, the "private/" path element is not required anymore since ~5 months ago and is considered deprecated
So just remove private/ and should still work/return the same info.
==== Private info ====
==== Private info ====


https://mtgox.com/api/1/generic/private/info
https://data.mtgox.com/api/1/generic/private/info


returns information about your account, funds, fees, API privileges, withdraw limits . . .
returns information about your account, funds, fees, API privileges, withdraw limits . . .
Line 231: Line 238:
==== get a bitcoin deposit address ====
==== get a bitcoin deposit address ====


https://mtgox.com/api/1/generic/bitcoin/address
https://data.mtgox.com/api/1/generic/bitcoin/address


get a bitcoin address linked to your account.
get a bitcoin address linked to your account.
Line 254: Line 261:
==== redeem a private key ====
==== redeem a private key ====


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


  allows you to add a private key to your account
  allows you to add a private key to your account
Line 267: Line 274:
==== redeem a wallet.dat ====
==== redeem a wallet.dat ====


https://mtgox.com/api/1/generic/bitcoin/wallet_add
https://data.mtgox.com/api/1/generic/bitcoin/wallet_add


  allows you to add a wallet.dat file to your account
  allows you to add a wallet.dat file to your account
Line 278: Line 285:


==== Withdraw bitcoins ====
==== Withdraw bitcoins ====
https://mtgox.com/api/1/generic/bitcoin/send_simple
https://data.mtgox.com/api/1/generic/bitcoin/send_simple


Withdraw bitcoins from your account to a given bitcoin address.
Send bitcoins from your account to a bitcoin address.


Parameters:
Parameters:
:{| class="wikitable"
:{| class="wikitable"
|-
|-
! Name !! Value !! Example
! Name !! Value !! Required !! Example
|-
|-
| group1 || || ''"BTC"''
| address || string || Yes || N/A
|-
|-
| btca || Bitcoin address || <code>18ytF1DH13LYEmBGREr47bNXNe6oH9ygzj</code>
| amount_int || int || Yes || N/A
|-
|-
| amount_int || the traded amount * 1E8 || 123000000
| fee_int || int || No || N/A
|-
|-
| amount || amount of bitcoins as float, '''''deprecated'''''|| 1.23
| no_instant || bool || No || N/A
|-
| green ||  bool || No || N/A
|-
|-
|}
|}
Answer unknown at the time of writing
;Example Error:
{u'token': u'unknown_error', u'result': u'error', u'error': u'Parameter amount_int or amount is required'}


==== idKey ====
==== idKey ====


https://mtgox.com/api/1/generic/private/idkey
https://data.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.
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 trade history ====
https://mtgox.com/api/1/BTCUSD/private/trades
https://mtgox.com/api/1/BTCEUR/private/trades
Returns all of your trades in this currency (BTCUSD, BTCEUR . . . ) . Does not include fees.


==== Your wallet history ====
==== Your wallet history ====


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


'''README!''' if the above call does not work please use: https://mtgox.com/api/1/generic/wallet/history
'''README!''' if the above call does not work please use: https://mtgox.com/api/1/generic/wallet/history
Line 320: Line 327:


only the currency parameter is mandatory
only the currency parameter is mandatory
valid values for the "type" parameter are :
'in','out','spent','earned','fee','deposit','withdraw'
allowing you to filter on one type of transactions


returns a json array with your wallet history
returns a json array with your wallet history
Line 325: Line 336:
==== Submit an order ====
==== Submit an order ====


https://mtgox.com/api/1/BTCUSD/private/order/add
https://data.mtgox.com/api/1/BTCUSD/private/order/add


parameters:  
parameters:  
Line 341: Line 352:
     "result": "success"
     "result": "success"
}</source>
}</source>
==== Cancel an Order ====
API v2 URL: https://data.mtgox.com/api/2/BTCUSD/money/order/cancel <br>
API v1 URL: https://data.mtgox.com/api/1/BTCUSD/private/order/cancel <br>
Both are the format as shown below, but with API2, all "return" keys are changed to "data" <br>
<br>
;Parameters:
* oid <the order ID> <br>
;Example Response:
<source lang="javascript">
{
"return": {
          "qid": "09354767-455f-412e-9a0c-efb7bb98c958",
          "oid": "fda8917a-63d3-4415-b827-758408013690"
          },
"result": "success"
}
</source>
;Example Error:
<source lang="javascript">
{
"token": "unknown_error",
"result": "error",
"error": "Order not found"
}
</source>


==== Your open orders ====
==== Your open orders ====


https://mtgox.com/api/1/generic/private/orders
https://data.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.
Returns a list of all your currently existing orders with oid and status .
 
Valid order statuses are: pending, executing, post-pending, open, stop, and invalid.


The order can have 2 amounts, the valid amount and the invalid ( unfunded ) amount.
The order can have 2 amounts, the valid amount and the invalid ( unfunded ) amount.
Line 406: Line 449:
==== Order result ====
==== Order result ====


https://mtgox.com/api/1/generic/private/order/result
https://data.mtgox.com/api/1/generic/private/order/result     (the /private is not needed anymore)


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


returns a json array like this :
Returns JSON. trades is a list. everything is a string.


<source lang="javascript">
<source lang="javascript">
order_id: '1234234-e9ef-4b75-aa1c-90cd109d24ea',
{
  trades:
"return": {
  [ { trade_id: '1336611143363429',
      "order_id": "30f3311c-1d6d-4313-b22d-f45c048fd004",
      primary: 'N',
      "total_spent": {
      currency: 'USD',
              "value_int": "8484299",  
      type: 'ask',
              "currency": "USD",
      properties: 'market,mixed_currency',
              "display_short": "$84.84",
      item: 'BTC',
              "display": "$84.84299",
      amount: [Object],
              "value": "84.84299"
      price: [Object],
      },
      date: '2012-05-10 00:52:23' } ],
      "trades": [{
  total_amount:
              "item": "BTC",
  { value: '0.01000000',
              "price": {
    value_int: '1000000',
                    "value_int": "10384000",
    display: '0.01000000 BTC',
                    "currency": "USD",
    display_short: '0.01 BTC',
                    "display_short": "$103.84",
    currency: 'BTC' } }</source>
                    "display": "$103.84000",
                    "value": "103.84000"
              },
              "trade_id": "1364879059328495",  
              "spent": {
                    "value_int": "8484299",  
                    "currency": "USD",
                    "display_short": "$84.84",
                    "display": "$84.84299",  
                    "value": "84.84299"
              },
              "primary": "Y",  
              "currency": "USD",  
              "amount": {
                    "value_int": "81705496",  
                    "currency": "BTC",  
                    "display_short":
                    "0.82\u00a0BTC",
                    "display": "0.81705496\u00a0BTC",  
                    "value": "0.81705496"},  
                    "date": "2013-04-02 05:04:19",
                    "type": "ask",
                    "properties": "market"
              }],  
      "total_amount": {
              "value_int": "81705496",
              "currency": "BTC",
              "display_short": "0.82\u00a0BTC",
              "display": "0.81705496\u00a0BTC",
              "value": "0.81705496"
              },  
      "avg_cost": {
              "value_int": "10384000",  
              "currency": "USD",
              "display_short": "$103.84",
              "display": "$103.84000",  
              "value": "103.84000"}
      },  
"result": "success"
}
</source>


=== Application API ===
=== Application API ===
Line 435: Line 518:
==== HOTP key ====
==== HOTP key ====


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


used to generate a new HOTP key ( useful for developers )
used to generate a new HOTP key ( useful for developers )
Line 442: Line 525:


https://mtgox.com/api/1/generic/api/activate
https://mtgox.com/api/1/generic/api/activate
parameters:
parameters:
* '''key''' - Activation key
* '''key''' - Activation key
Line 454: Line 536:
==== Order Creation ====
==== Order Creation ====


https://mtgox.com/api/1/generic/private/merchant/order/create
https://data.mtgox.com/api/1/generic/private/merchant/order/create


===== Required Parameters: =====
===== Required Parameters: =====
Line 546: Line 628:


== Examples ==
== Examples ==
 
=== genBTC's trader ===
python: https://github.com/genbtc/trader.python/  also includes Windows binaries
(current project, please contact genBTC on freenode to contribute)
=== Goxcli ===
=== Goxcli ===
best example of all, using nearly all the API methods, works as an intereactive shell and as a shell API so you can build your own app on top of it :  
best example of all, using nearly all the API methods, works as an intereactive shell and as a shell API so you can build your own app on top of it :  
Line 563: Line 647:


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


==See Also==
==See Also==


* [[MtGox/API/Streaming]]
* [[MtGox/API/Streaming]]

Latest revision as of 20:32, 30 May 2013

Note: All API methods require a valid User-Agent header.

HTTP API version 1 methods

public information

Multi Currency Ticker

http://data.mtgox.com/api/1/BTCUSD/ticker

returns the current ticker for the selected currency :

caching and rate limit :30 seconds 

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

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

Fast Ticker

http://data.mtgox.com/api/1/BTCUSD/ticker_fast


Multi Currency depth

http://data.mtgox.com/api/1/BTCUSD/depth/fetch

Multi currency trades

http://data.mtgox.com/api/1/BTCUSD/trades/fetch

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

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

to get only the trades since a given trade id, you can add the parameter since=<trade_id>

https://data.mtgox.com/api/1/BTCUSD/trades?since=0

https://data.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: 

{
  "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://data.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://data.mtgox.com/api/1/BTCUSD/depth/full returns full depth

WARNING : since this is a big download, there is a rate limit on how often you can get it, limit your requests to 5 / hour or you could be dropped / banned.

transaction information

https://data.mtgox.com/api/1/generic/bitcoin/tx_details?hash=4462c88079cc51972f1bdcb8a4240ee8757b0bb69df828ade051c95ced540fa0

will return : 

{
"result":"success",
"return":
{
 "hash":"4462c88079cc51972f1bdcb8a4240ee8757b0bb69df828ade051c95ced540fa0",
 "blocks":["000000000000076fa606a7b67c131afc87d24d34114be2863cf24ca3d48139e7"],
 "version":"1",
 "size":"1158",
 "in":
 [{
  "n":"0",
  "prev_out_hash":"4578576f49418e69da6d7a1166168bb80a94682f21cca518b6c2451bc64bf858",
  "prev_out_n":"1",
  "coinbase":null,
  "scriptsig":"304402201d7eaf891bcda16ea2979694c02e590fea8fc43dc092ee60e5fb2dd756bcb19502205c5be31b772029700d0a43d499932e9c321af1cfbc8745fba6dbbe48fa79bbb501 043a264aac55e23f83b29ac7e7a914584d2aa6c2eb08ea05405f5efc38473183ca4fc075f8144bb78698df1a5be6f4057f1bccc9e1217a5658946bcc4d4f6972c3",
  "addr":"46f740cb9c737111ec91ec235f6877055be7175e"
 },
 {
  "n":"1",
  "prev_out_hash":"4feea511029896ff4c31132346a79594fcd0c4e60aab2fa4f527e1395d375488",
  "prev_out_n":"0",
  "coinbase":null,
  "scriptsig":"3046022100f3bc0445f629e4e896ced23013d89ba6e6488a6ec21c47df608aaf6d6d212fbb022100d321c4c7f5f33900b8c0efba8ff58a3541e621588f402e167f51968b6ee0bbf201 042157f97a8a78caf6315dbd6d9267b9edd9c1c37cdb211f2bc03703a28eeebaf274efdcff4ef3e3ef4a6b7ccb5d8c17acba941d1a5669c3299f22a0e78e702fdb","addr":"7b0a72820f6e92ccc384dbdecb5584d855ce9416"},
   
 {
"n":"2","prev_out_hash":"9adadb88c3075afdce1216b35d27fd5cac9736ce3977778999f9a85105d2ea8f","prev_out_n":"0","coinbase":null,"scriptsig":"3046022100d63237cca9bf2200c6aa255834e06f9dc5e4e20f1ea7e6678119bb0e4a5a109f022100db37ec795336509fb3a16d1acebfe08523d95e177284149614a6d3384286b27c01 04b16b41dab16cfbf59f1713559795440b98b384dc01656ebaceeec8f6d1463802cb474062b2b8c1de53ab1fe65be0f6213dd61519044e9c1f50291b915fc7fc6e","addr":"2ed7c49f080e9898737276ad802e2067a1d06ab7"},
  {
"n":"3","prev_out_hash":"0e2ed4e4db87ddc9cb54ab3cdcae59762293815d3093c238e42d33248b39e19d","prev_out_n":"1","coinbase":null,"scriptsig":"3045022100ab501414e7643cc1a78645f544cbcf6411e71e0c21953cd51f7f9933a50538a002201b4c9bac60aa19d659d0686d45bf06c4928c4446269692d88722f57624cdaf1401 048e1e4862c6fee7293f6c7be43a72a375e68395398e4d5da3db06199a35fc46cf51b87f3c6b87caeb81181d630706e23b5679ae8b96ca36701282ae5b49dd99c9","addr":"c74d2e95aeb037297c7b6a232d78c715fa1ab826"},
  {
"n":"4","prev_out_hash":"93c912462daa2a52e108e3424596d56fe2a136d6707a65b6423dee229e317ea1","prev_out_n":"1","coinbase":null,"scriptsig":"3045022100fe782441b8788ed9297c8fea735701ae0a77081fc748ceee8cde945107f64967022014d51d5bc8d8138b97a657eda6d03ba998810e3e941988da90b82f6d24d8471e01 045f53cf2dbdb3213084efa69ac1dfcd8d97be8073a8b8104feb000513aa048b653f400d23314fc090456078f46a0fc9daabdee57f1ef14c2111b9ddc35255189a","addr":"958bba83ac42ebf055c1724b25bfe5c698abbb51"},
  {
   "n":"5","prev_out_hash":"44a1b493ef6176cced4c02fb97a227b98e5bea0616d9cdd6005bcd6905d667f3","prev_out_n":"1","coinbase":null,"scriptsig":"30440220132484ad901567d2c52c0b4f3be5263d1d8ed6e76be1398d2bb7c2a1aec5f748022033b907afa05eb075dee9993b8a05c9e40c69e53d65a06cc8a975ff4c4407141e01 04bd5d7feb1884efdccbe8feb8fa9ff57d56272ac5f667bc59cb07a232fbbd9cbabdf54b6bb6ca4c77e0de22cb0f896fa6183e53381861641049f0edee2d64cfe5","addr":"3784c102bbfd34cc7fb6e12c51b5c6177592f267"}],
 "out":[{"n":"0",
 "value":
  {"value":"0.01000712","value_int":"1000712","display":"0.01000712\u00a0BTC","display_short":"0.01\u00a0BTC","currency":"BTC"},"script":"OP_DUP OP_HASH160 6427f36ed6e5a0cb526a0b0bef1335992326e9a9 OP_EQUALVERIFY OP_CHECKSIG","addr":"6427f36ed6e5a0cb526a0b0bef1335992326e9a9","claimed":"N"},{"n":"1","value":{"value":"3.31674208","value_int":"331674208","display":"3.31674208\u00a0BTC","display_short":"3.32\u00a0BTC","currency":"BTC"},"script":"OP_DUP OP_HASH160 1f27d1fc284143729944ab89823111d2bb63dc46 OP_EQUALVERIFY OP_CHECKSIG","addr":"1f27d1fc284143729944ab89823111d2bb63dc46","claimed":"N"}]
}

}


block information

block information can be accessed by depth ( the block number ) :

https://data.mtgox.com/api/1/generic/bitcoin/block_list_tx?depth=188111

or by hash :

https://data.mtgox.com/api/1/generic/bitcoin/block_list_tx?hash=000000000000076fa606a7b67c131afc87d24d34114be2863cf24ca3d48139e7

both will return ( for block 188111 )

{ "result":"success", "return": 

{
 "info":  
 {
  "hash":"000000000000076fa606a7b67c131afc87d24d34114be2863cf24ca3d48139e7",
  "parent":"00000000000005adbcc9846f9f3542f9349b19a3c8a8f8149a830e8d748b0c92",
  "depth":"188111",
  "mrkl_root":"772b7dcc99c98a9d77e40e2ea300ba492254dea5439599f666c77bd5be1f3b4b",
  "stamp":"2012-07-08 12:03:12",
  "size":"76898",
  "status":"confirmed"
 },
 "txs":["020d258be19e6b399301acca1857ceb13adf643edbc660942d7eacc3290bdf55","0575fb1c09f86de21bdb00bb1423053e5ee667158ad50aa0043e82bdb3d21a1e","07830422f821fcd63e316411c883486161f15154ba27b4fffbd934fe02423020","07a6cdf84e5b5aec5f3ec968a36a469e2923237254c31adf8cc895f4d47dbd0c","0af35c993e0094010a73d48bded49ea1c7f5d26a1d80fb1ddd2fada39f725656","0b5a4340a8daa28832c4ea7baa463b896fe954bca50bcfaa2671947725c103bb","0c5adc9fb24a3daa80fe0e2ed6c6b35ee0cb70e3aa6da42276e04fd2132ee4a3","0d28cea45a0a90ac105777d1d53318d23be489416aded7bcc1c92ed2f7426358","0f05493623804d9ad4501521c893fb186cbb03e41962bbd42a10bf6c89f60026","0f627402384a9c88ec878b6d7e3866f88d8c91295c7a3f595a50f32af3a962e9","100f488d2822b1e50ef6b7a885fc576a610b2aa5d36c660c6b000555f5edb182","12d1cdcd17cfbccfd5184543c9edc5a18c3add089c76afa33c0da72001fcd2ea","144516c54e56e3c9a049995fd402dd4749eb7bf4276c247c598f67ea126c1ef0","158be63da6a97dcb7ac2286ae148ba0bbee62d4eb3be9423e0de84337c67cef1","175a4c4708a6237bdde8cc355487c1b85f61915d1336fb9ec1216946ed949efe","180a9901550e68c552fab07b23788bf424636ef899a73313c9dde8e00757acd9","186d0632a342d20e97a612e2ef6c60b74af278678e2221a5c043bb8bac683f73","19cf092b8657d0da33ef97c628469bfa0e87f564327629311881e8ef4cbe203c","21a79eeaab53234b1017689fcf13894154d3a9083d10feeec9096b2bd5135649","222e59465dae7866897b9a750cddb3924e775637944d3ec6dd1cd0f81bd9f36b","23e28db3cb8dc658d010eb7b3ed9f4ac0ae3be4049bad0d557c2a7446954d185","2426cb2d1fd6958c1830f98aa54bd9ee86fd3325cb13b1e9aeeb2901f481b38f","2528e80141db0f5a09f6d8ded3ba06427476256a70442a7df51fe3c2686bef64","256e754aa2829469cf575b121eb4abb7f6a1f0aeee6f221bfd14a5e0b0ca9baf","25fd783b5cdcb1e1769092a007103556bc3d5d419b5d5ba9ef6e7400a5e0caa7","268fa8738fe708161071624d3143475a7a26f7ccf8dd031c91861a3dd59d3eee","2801207fb1b50f1d60324b7a790da36c244875de7b0329fe1be53439e74d9553","2826f91a4664031f5ed7239bddc11fe746b63e1c5d70bbe043ffb62e966a2c01","28d4fcec098886db460d300d9a62be49c31ddbd1cdaa203a5fbdf8021eba22b6","2ada3f324802d7ad3dfa7d5ff24e888c3919cb8e7ba1050f59cc814ccc6c7f41","2cdce29d3ef98062d36e63d150e203737f1374f43e8a1b36eea08286450e5e24","2ce5579a4c205761779668232c685eb0c0974f0328daa073bafec2119afba906","2d1928299d04653351d2358885e51a981f227d9ac8eaae34437b63eff8f4b28c","2e5686a497efdda63de8c5aa23fd349f3004a31ccebc6b3954de06669b3dfe9c","2ecc8f682cb7e65802072bf311cdb9f87e25cf34ab3f0f475c16169040b3c654","335ab9791c80ab80ccbf55e6829ad3c67a6b48426769b9bd7b3d866233ad912b","34bf38fb8bb1e74d1570e4e357bf2c9af3956917bf3f49ee3a5a9bd9e89e174c","351835329ddecfd75c74fd82b207a6f1481394321b3c3613e71dad74654a59ee","38f67149f684713e8271b2f709c125c365cc0ae97c740d0e4a07822f71f3b640","39ddb42041f0ba3c7d87c2d5e74a633a1907f188b57569b2641c77fed674fe0a","3bdb7e7e5d8b7b4dc37fb961272819eeee0da9854657318503be4397567497c4","42d2e9a1a1650d58c21ebcb14eef6da5b248b43c96e1bca816baee4c73978650","42dba17d47c259559dc9a5a110457196ccae97447f2b9e6056fd96e471e09715","43a262b3cc7b2899b166ddf06d37fd4600b2348342514d8646a76c454b4772d0","4462c88079cc51972f1bdcb8a4240ee8757b0bb69df828ade051c95ced540fa0","44adb50a8c3096a079c5fef9dfaae479b2f2804e09106097d480a8c1b0672da1","44b4dce02cbd628e8f88bf7ca36f650db866b16c5a79b3cb6f6b24bcffb1c089","489ef413e51bcbd23a4134c366f2537d99ea81913af43627dcab4ccfd611d1df","49d2a512f63481a42ad30a1b3845fc2929296945519c0998dad4fa361064765a","4d5372c14355d789decb0e100fb05e86f6b854d0187815b60a1b37de41ca245a","4db9e6cc810918143fba3dfe8cc3030847b8297775dee7540ca03fbb0c8788c0","531bfa06d7164dc5cb971e3fe90aefd61c188a5d292350a2cfc12cd8bac760f6","553341c3683a9ccabe10fbb65334a694bab2469fa444570e51d81b7d416414f8","5592b28d4a6f652fce290e1502a6204ad501ec5759438c59209f29bd9e80f972","573b1dee0b00b1936d8e8b4f1f45e47c246d7be09b0573281bdbb0b71035841e","5767fe6251014d97a2f14e1226ae08b11065f78b7f52a390bda3eb87cf63e9d5","588c8e0d458ee5516468d4f0f68711757bd4e291e6456be8e3fde1fa9c6e72c9","59f3d51b41f346c08fb73be2a540ebc2aeffb2220da5c2e5d927b74a5249c907","59fb156e2e6b901524a7b7fe906db455f014deb361096db937db5be952490b36","5c2c78de645d59a57500e0a3ba19d91ff8dc902a6d75c16512d013449a74957c","5da0e429c410ce6220f7206e6ee41f0fc8216000908b3d8eeb651345fb5e7435","5eebfbda3754fc240d1b87806cf57c0f6805eee3cbf8b0c29f8da96017ddbc1f","5f6d93830779e69b1a9e44ceb81fe42ddbc1b453014548b44b348d5e979f98cc","601f57984bead5aa7767885e2d01e9d24582c1c7a2f7e907b70b76bf773726d3","60ae2132f0864e3700db8b6a30ee7e4d7e7479798c5ce14df23a7935016b2eac","67177915a8a163c49f0cfe7f12a065e24046d8b32ee4b6b5071954c12f9f8173","67398f5c224a83debf5455b5caa6976249d35344a3b4f39700cda11569494203","68d1bfff53204d0eeadb35540ddcb43ad2c7aaa9ff647052ab4f2d66f3094e8d","6962015317f58edbed7b8725f344a25fb7d8dfca743715558d916cf1a8b32b24","6ab7e2e0c7749ea166968629f584c2be8687667fdf6861d53368c944e10eda3a","6b11cbd800814e5d86afcd3daf56fed4e8f987007ff4ab835a05e6de470f35ff","6ba15ceea3a22c3a8b3539c1124a4d641409a680db07af35e35d73da877e8da4","6c41c14638745ca2b820153386fd95948d8bf048750328cd397d05241ebec08c","6f3e68f9b4d007249b4585b0760e2b892a7f6b8fd2ef568e93856da20d96ebe4","702a98c7b9a4cccce628ea40ec94f9663c9f3163190c18c0d5011fae44f50a7c","7084504bf52356da59c8ca8e96c6cb4d2d85f10ae4c02fa74b50e26c6b8467a0","737e38e017b1a9308ea2264c8c4e9bba612ffba3fb44de505f3e479ea1d572a4","75b3d2188033c8e2a9f5aed17cd80c71d5599f9af23ed36a9561bdc3a15fec04","76b16f3014b25107d0b88172c2913980948c9bc8c68132ea424c54c00e7858d5","77141d625b4521eeab882b79e217cfe19cf8e74a757729152bf60ee5a70071fc","7b309dc1e54d784f3772631dc4b01f5dc414904d21f77905c9f6d70bf8423d67","7b4a63bc061f7e95461631e58aaf96314591ae0fb0feef90ecc31003824eb66b","7b7a0136f2fc529018f0568a21bcb73996375ed9eb2c627846b28f5b09095a0d","7d00ff77f0f12ab7799ed571bcb438df230135e26796cc4b984908103beae847","801314902f70f8939fef64267687d2bb95c333a62464ee5db76b88aed8b9d360","80757f7f5a5ecd47e64cd5299442038b7922d15d5c303d2a950deac204b7807e","836bea75b79376c547544b06298cd3fb3f5974641b3ceb77eaba687e19e2cec4","86d5cf06b40acdf96215db8a767df3e1fd2c8e4641007e8ee5c6f8bd9b47f3ea","8a4f4d6acdf5d875e2ae14cc17becbb45072c7229a864b3fa1cdc80b45d80597","8ab04f7f610a17d08613fca7d79dde9fb5817904e1055bd6b8eb574e9531ff5b","8b1dd8aa0b6272770d2491d35944fb9b3d3169c72e8275ef2411b801fed1785a","8c7695f70007d17fbdcbcbeb921837b2c5ef3469c27ca65ef3e75e0634e06357","8ccf0173e0006b65019d4b2634f824c69883f8bb6ab3670eff36183df45d437a","8cedf02ad54c94948e69c69dacf8b5f94d6a20b156f112b79b635610b9abccfd","8e0e0aa6ae3df684489ef41c6c65e5c9fb9d72d2aa455b2453a6495ab45aa29b","9059fb2f4ddb94bfe924c3c009e1e1cd8da53513c9ec1a1aa7e20c2376274dd5","911766a8e660a973180d306aa95fe2b9037f37db28cf166e59aaf986ec72608e","95bd4211a0fdb9c028c1b7f694b72ab8222ead20d0f83edd7288ef19105208f8","971e6feb86d955f9aa194e25c596499b5ab5683c68766877b14eacaa86ed6836","993fcab01aa5882308af5b870c0a191884ff4ecdb8cee964ad58e96781763d65","9af2c6bb2897847bf8ebb71ee600c810354bdf8aa78ad8aab864ba89be3aae0a","9b4d84991e2dd181570dd4f5d18e533c57252ec8ddb6642c990386e8cd57cbd7","a05b2c1547f8513ded94425763b6f34cf3019e7f649163d31fd8fec770950fd4","a36f43271195cf031b2a0e3df297a206088a11c3f03cc4ec255721c017825140","a3825df57a7f4d6e3f204d35d1b58f24d0a89dece8c8e8cf277fbad2283eaf0e","a3a6ccc3af9becf7135b58798e5190251c8499171681b3c2c1110dd0cb1ca0f2","a3dbbdbe58586d5917828a058b37e471e15d6a42688397e93888d6ce58025a55","a48a185b6d50ae91a94b571bb43f173102a172cd886649bbe1563c875ca2142a","a4b7d03a4af6e2225902e026adb2e265e07a10a8a062a49aad2f544fd7c900f8","a6de57825868deebdb57a405c7f9085f21a249ea9d36bf1c18e9c709280523dc","a7a9eb9c044a5fc5e27bc9ba533b794543e154c2081266988e2ca07e37380787","a92d2d46d0d65e3ea05b68ab16b32bed760fa2955c9f6b9f91687e429724524c","a9c2cff9357c003de5e6498e0af52ad8f24778fd18ca274fd135a7dbb4464a8a","aa1d22c31d4dc4114888bccbd7110a1f777887ed8dd2dfa006eaaeeac58d2a44","aa313832f108aecbfae05acab011d40ff1d1ec540cd2025851dcc10d92bcd0c3","abbcfbdc79d0536344295d6e0cd6d7ae788a385836c33c7ef7f98f6064ad2ee1","ac3a732c65504a9f4e728cbaf80d4d58f74a3834138a224657eebd03982c1898","ac6eb25fa5be2a1d1418879791cadf43b1a268cb3aa2e505977cb29e4b7035dd","adec207d59a23cfc8afc63b0e45bfdefde9b7ffe74515872f0837025530ab6eb","ae1584bf163b05c014d0d99715f481655949c7762d800997562fc93f3da731b8","b1403965758e40e9d2eb31950f97dc599368edeb98541ede8df2b512ef2fd3bf","b3c086e90eda12260b5bfe8eff16a051882dfd921c02140194c0e0ee9a849466","b4062fe2f07abe03e2e9b88b571c7f2d9c058c78fb157d3d04fa39feda380a02","b416514b63420449c6c56781adafff18f6f28733aeb2fb4bb0c1abeadbd6db6e","b7bfbbc5fad15123960443cb0c118162a62a4b92732a8365eeb77e8df25eca46","b871fea4a33e5e51ff648ca74d16a34f179d3467805cad84238c729282e8acf7","b878eaf74341fbc65c609785b93b38d90f841f2d50bb39496e1f4b1b34b2255d","b9a80691e7d9423ad546a96363a017a4a0725dc854de082d6927da6cd6aa19c2","ba7ef3d90be2bc57c785f55457971ff0812a4d9b9df18ab980229ce648cee31d","ba8669e2e19c21a0045d994c56e811b2d1d51451ab248e76df456427d0d20569","bc260c6b49fe06a331202a2b703cb051aa352d17a8373496dd5ef67ab404a145","bd260517b438daa35921cca54b8c2dcd48b8ca338f7166d91ecd3a3eb14c9d7f","be375723b763ea3e88f9539eebd1f73f8af0b463b7bb88781dc3f589ab36e9ad","c0c4c3b3cd1b400b81316dd67001b92a512569dadd0ed6f783e87e601c8ea54e","c156c12f1256b4a2a6c0558b7094e263876586e4a72333da2997fb97cbb8d15d","c2a5f97fa1daf09015fa78a57b2aed1d33b9c18ffb84bb7f3d0e8d643532b772","c54d091b9d006ed79405b62defa7910a7ab9db6463f46ab1c50064df152aa887","c5a7a5ed8e2b4e72ca8c72025e91e14388ee23c7822c16bd3fe3b11c206ffb84","c5b5f35b88138f27b6aa2395f423d15dbf642258971102de77359ff79eb8d4cb","ca52540a211bac9449b45662ac2a6a00899bf55b5867017ab73b1973ef3a8f6c","cc6f6ad1f5a023bb52f7638f883d4bf20dab6bd3a0b1b9a3c8526fc99aee81d2","cef0df2d68b4f38fd9ce501839e3d4d2a40317d845037baa2b7ffb3ed45918c1","cfd0806446352b03d89be45f1014c0a48728286c5b12fc89d32a3cb31896765d","d03fe289cf120bdb3ae70711da1c8972f650fb8e5c4f91dabf17639a2c7ecb06","d1089a3f2e4f0d043eec44395a5522f107fc649ca561f76013d412c85710c306","d1a68d6cf85c32a15011cd13b374ab8aad619b1b437ffd262c446cc079babedc","d4201c9a33e19e2ba351ec288ec5a43f4b3f2cb133d6a7977f72c529d3e03408","d5991156ebb5beeac70ac0cfc1706990be5752b41bafbe31228053fe18dc3e67","d86adacb713cc4ecf06828aeb2b8e1bb0311144986978c59240ce996214ab69f","dab5fe0369dca967e09653cb0475e09636091ba0a6ee95289de49fe97e505f3d","db0ee162bc04083d6caed8a88a7be44b02d15b2686a2d6dd06a10d024cefb40d","dc453efc8162dbff08e04fdda7a5dcbd986ee0fbee547764ff7ae89afe68806b","dc5e2a39f8e1ce90f88c3f50076ed03188fc60e87b103a0d48e66fe462b7777f","df826a504bad73ab69fcd740f72e6e00488e69db8ec31a55ffb3ed43b0845cba","e05d71cfe0b356b0dddee437f9da2610f85c5dffedc3ab058172ab71624a7d14","e10fb8c50f8e378b43f4f80b41e62b78dc968496196ae8399fa7d203e213a3cd","e5b9be11e940019582c6ac0875f54e7bc92fd15149cecf4e1bf67d4357010cce","e7a64e4c08350ee2f0ecc3af4c2df7388da044de4f7955a941ff965a925b54b8","e84b2c1129b574a485dfa7d8843cf569b3679f234b681f6f8fa0d88d5489b224","e8df3c1953e9c32ae77bbf01dcec48e1052271e0eb6d556da9deda1c50426231","ec46f3be50d9f2f6472669b8c8e38addd54c00bc206c81e873f340c0a11d71f2","eca4fdc50f34ccf5e0b459b0a077ec9033cf25c58e29b3406f24eab6445a6221","edc7488d9f86de7d094c1d02119680b91a15a28cf7a8b09cf9cf194193ae81bc","ee4b82dc8f11c5459a42090c1aafaf645f2c1d247edec1d9b0fae46f4efaa02f","f03f924d1767b748f8fc15bcef798076e746a7917f5fc7b89e2ed022c95faa82","f104ccccf3bc11107b27900670f36de7fdda3a0a7d086d2dc69b4903aa2cbcd5","f18d25a1fabd8f3a62edb164c759b650c13c320f2edc7cab44c01ae88809b285","f2a1ff85c3ac02574d1f55b067c841ea4b0283ed9543f11752fa41723b315ed9","f46a661429090548bfe775c5df5197b0cf6ae5d38a215986b79de385b52d4223","f5d19ba9a4a11db479fd80aea1674eb896f515fd43f34c456b09f49500ecd4b7","f629a172edcac21d929169f2bb1dcf148110151b769bae15e4fc09bd72898fd2","f6d1ca49cea130563f72f266612eb901c9290b3bf36fd4218d5881c5c9d7d35f","f79f17ff115716f428034aa9181d63e67649404559448193fb6c96f35cad3e00","ff0e08dd175e3badf556ea843a972edea4c80f461cfdabbfdb69167ba3845055"]
}

}

address information

https://data.mtgox.com/api/1/generic/bitcoin/addr_details?hash=1f27d1fc284143729944ab89823111d2bb63dc46


Order lag

https://data.mtgox.com/api/1/generic/order/lag

The "lag" value is the age in microseconds of the oldest order pending execution If it's too large it means the engine is busy, and the depth is probably not reliable

Currency information

https://data.mtgox.com/api/1/generic/currency

pass parameter ?currency=<currency_symbol>

https://data.mtgox.com/api/1/generic/currency?currency=EUR

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

Private API

3/25/2013 09:15AM<@MagicalTux> btw for api v1, the "private/" path element is not required anymore since ~5 months ago and is considered deprecated So just remove private/ and should still work/return the same info.

Private info

https://data.mtgox.com/api/1/generic/private/info

returns information about your account, funds, fees, API privileges, withdraw limits . . .

get a bitcoin deposit address

https://data.mtgox.com/api/1/generic/bitcoin/address

get a bitcoin address linked to your account. the returned address can be used to deposit bitcoins in your mtgox account 

result: 
{
 "return": 
 {"addr": "18dGNs5Bd6pPMuSchLHQtb1k996YpUHs3j"},
  "result": "success"
 }
}

optional parameters :

description : a description for the address , a new description will generate a new address

ipn : an URL that will be pinged when this new address receives a transaction, the ping is a POST request with txid, blockid, description . . . as parameters

redeem a private key

https://data.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

redeem a wallet.dat

https://data.mtgox.com/api/1/generic/bitcoin/wallet_add 

allows you to add a wallet.dat file to your account
  • parameters :

"wallet": the file content of a wallet.dat file ( base64 encoded ) "description": optional parameter to add a description linked to this wallet in the account history

  • returns : "amount" ( total number of btcs in this wallet ) + count ( number of bitcoin addresses in this wallet )

Withdraw bitcoins

https://data.mtgox.com/api/1/generic/bitcoin/send_simple

Send bitcoins from your account to a bitcoin address.

Parameters:

Name Value Required Example
address string Yes N/A
amount_int int Yes N/A
fee_int int No N/A
no_instant bool No N/A
green bool No N/A

Answer unknown at the time of writing

Example Error

{u'token': u'unknown_error', u'result': u'error', u'error': u'Parameter amount_int or amount is required'}

idKey

https://data.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 wallet history

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

README! if the above call does not work please use: https://mtgox.com/api/1/generic/wallet/history

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

only the currency parameter is mandatory

valid values for the "type" parameter are : 'in','out','spent','earned','fee','deposit','withdraw' allowing you to filter on one type of transactions

returns a json array with your wallet history

Submit an order

https://data.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 the OID and info about success or error 


[1] => Array
{
    "return": "4c2e69f5-8b35-4171-95a3-9e4088c1586c",
    "result": "success"
}

Cancel an Order

API v2 URL: https://data.mtgox.com/api/2/BTCUSD/money/order/cancel
API v1 URL: https://data.mtgox.com/api/1/BTCUSD/private/order/cancel

Both are the format as shown below, but with API2, all "return" keys are changed to "data"

Parameters
  • oid <the order ID>
Example Response
{
"return": {
          "qid": "09354767-455f-412e-9a0c-efb7bb98c958", 
          "oid": "fda8917a-63d3-4415-b827-758408013690"
          }, 
"result": "success"
}
Example Error
{
"token": "unknown_error", 
"result": "error", 
"error": "Order not found"
}

Your open orders

https://data.mtgox.com/api/1/generic/private/orders

Returns a list of all your currently existing orders with oid and status .

Valid order statuses are: pending, executing, post-pending, open, stop, and invalid.

The order can have 2 amounts, the valid amount and the invalid ( unfunded ) amount. valid amount and invalid amount will be updated when funds are added or when other orders are removed 

 [1] => Array
        (
            [oid] => 66a115f2-9919-487a-9eba-99a0141c9590
            [currency] => USD
            [item] => BTC
            [type] => ask
            [amount] => Array
                (
                    [value] => 1.00000000
                    [value_int] => 100000000
                    [display] => 1.00000000 BTC
                    [display_short] => 1.00 BTC
                    [currency] => BTC
                )

            [valid_amount] => Array
                (
                    [value] => 0.99470000
                    [value_int] => 99470000
                    [display] => 0.99470000 BTC
                    [display_short] => 0.99 BTC
                    [currency] => BTC
                )

            [price] => Array
                (
                    [value] => 10.99489
                    [value_int] => 1099489
                    [display] => $10.99489
                    [display_short] => $10.99
                    [currency] => USD
                )

            [status] => open
            [date] => 1344208333
            [priority] => 1344208333021535
            [actions] => Array
                (
                )

            [invalid_amount] => Array
                (
                    [value] => 0.00530000
                    [value_int] => 530000
                    [display] => 0.00530000 BTC
                    [display_short] => 0.01 BTC
                    [currency] => BTC
                )

        )

Order result

https://data.mtgox.com/api/1/generic/private/order/result (the /private is not needed anymore)

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

Returns JSON. trades is a list. everything is a string. 

{
"return": {
       "order_id": "30f3311c-1d6d-4313-b22d-f45c048fd004", 
       "total_spent": {
              "value_int": "8484299", 
              "currency": "USD", 
              "display_short": "$84.84", 
              "display": "$84.84299", 
              "value": "84.84299"
       }, 
       "trades": [{
              "item": "BTC", 
              "price": {
                     "value_int": "10384000", 
                     "currency": "USD", 
                     "display_short": "$103.84", 
                     "display": "$103.84000", 
                     "value": "103.84000"
              }, 
              "trade_id": "1364879059328495", 
              "spent": {
                     "value_int": "8484299", 
                     "currency": "USD", 
                     "display_short": "$84.84", 
                     "display": "$84.84299", 
                     "value": "84.84299"
              }, 
              "primary": "Y", 
              "currency": "USD", 
              "amount": {
                     "value_int": "81705496", 
                     "currency": "BTC", 
                     "display_short": 
                     "0.82\u00a0BTC", 
                     "display": "0.81705496\u00a0BTC", 
                     "value": "0.81705496"}, 
                     "date": "2013-04-02 05:04:19", 
                     "type": "ask", 
                     "properties": "market"
              }], 
       "total_amount": {
              "value_int": "81705496", 
              "currency": "BTC", 
              "display_short": "0.82\u00a0BTC", 
              "display": "0.81705496\u00a0BTC", 
              "value": "0.81705496"
              }, 
       "avg_cost": {
              "value_int": "10384000", 
              "currency": "USD", 
              "display_short": "$103.84", 
              "display": "$103.84000", 
              "value": "103.84000"}
       }, 
"result": "success"
}

Application API

HOTP key

https://data.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://data.mtgox.com/api/1/generic/private/merchant/order/create

Required Parameters:
  • currency: <currency>
  • 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
<?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);
}

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: 

<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>
<!-- You only need the following tag once on the page, after all the buttons (for example on the last line before closing the <body> tag) -->
<![if !IE]><script type="text/javascript" src="https://payment.mtgox.com/js/button.min.js"></script><![endif]>

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

Examples

genBTC's trader

python: https://github.com/genbtc/trader.python/ also includes Windows binaries (current project, please contact genBTC on freenode to contribute)

Goxcli

best example of all, using nearly all the API methods, works as an intereactive shell and as a shell API so you can build your own app on top of it :

python : https://github.com/Trasp/GoxCLI

bitcoin_dealer (trading script)

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

magento mtgox

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

XChange

XChange (Java) API : https://github.com/timmolter/XChange

MtGox-Java

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

See Also

Retrieved from "https://en.bitcoin.it/w/index.php?title=MtGox/API/HTTP/v1&oldid=38152"