API

The API allows developers to access the functionality of Metaexchange without needing to use the website.

All API requests return data in JSON format.


API errors

When an API call fails, an error will be returned. The structure of an error is:

{
"error":<error code>,
"message":<error message>,
}

Error codes:

  1. None
  2. GeneralException
  3. MissingParameter
  4. UnknownMarket
  5. InvalidAddress
  6. InvalidAccount
  7. OrderNotFound
  8. UnknownCurrency
  9. NetworkAlert
  10. InvalidParameter
  11. Unsupported
  12. OrderException
  13. BadCaptcha


Rate limiting

Our API has rate limits, which when exceeded result in an HTTP status of 403 being returned for the request. Each API call has a separate maximum rate limit; the lowest maximum rate across all end points is 1 request per second.


Times/dates

We always use unix timestamps for any date/time information returned from our API.


API summary V1

Submit your receiving address and get back deposit details
/api/1/submitAddress

Get the status of your order by TXID
/api/1/getOrderStatus

Get a list of your last transactions
/api/1/getMyLastTransactions

Get a list of all supported markets
/api/1/getAllMarkets

Get details of a particular market
/api/1/getMarket

Get a list of the last transactions
/api/1/getLastTransactions


API summary V2

Version 2 of our API offers extended functionality for our limit order capable markets.

Calculate how much you would receive for a given buy/sell order after fees
/api/2/getQuote

Submit your order details and receive a deposit address to use when placing the order. This is the same endpoint as the V1 api; it has extra optional parameters to handle limit orders.
/api/1/submitAddress

Gets a list of your last transactions, using the receiving address as the primary index
/api/2/getMyLastTransactions

Gets a list of your open orders, including both limit and pending market orders
/api/2/getMyOpenOrders

Gets the public orderbook for the given market
/api/2/getOrderbook

Returns an array of resulting output transactions, given a single input transaction. The array is neccessary because in a limit order market, one single input transaction can result in multiple output transactions as several orders get lifted off the book in one go.
/api/2/getOrderStatus

Migrating from V1

There is one major difference between the behaviour of limit order markets and regular markets and that is the way refunds are handled.

In regular markets, a full refund is issued if the deposited amount is greater than the maximum type for the order (see ask_max, bid_max, as specified in the result from /api/1/getMarket ).

In limit order markets, however an order will be partially filled and then only the amount which is over the maximum is returned as a refund.

If you have existing code which relies on the old behavior, the thing to do is to check the result of /api/1/getMarket , look for the has_orderbook field, this indicates which behaviour the given market will exhibit.


API detail

The main function. This will take your supplied receiving address and provide you with a deposit address and a memo (depending on the market).

HTTP Method: POST

Required parameters:

Optional parameters:

Example:

POST https://metaexchange.info/api/1/submitAddress HTTP/1.1
Connection: close
Accept: application/json
Content-Type: application/x-www-form-urlencoded
symbol_pair=bitBTC_BTC&receiving_address=monsterer&order_type=buy

Results:

{"deposit_address":"mrveCRH4nRZDpS7fxgAiLTX7GKvJ1cARY9","receiving_address":null,"memo":null,"refund_address":null}

Possible order types:

  1. none
  2. buy
  3. sell
  4. buyLimit
  5. sellLimit

Get the status of a particular order when you know the blockchain transaction id. This will return results for unconfirmed or confirmed transactions.

HTTP Method: POST

Required parameters:

Example:

POST https://metaexchange.info/api/1/getOrderStatus HTTP/1.1
Connection: close
Accept: application/json
Content-Type: application/x-www-form-urlencoded
txid=ed7364fd1b8ba4cc3428470072300fb88097c3a343c75b6e604c68799a0148cb

Results:

{"received_txid":"70827daa9f08211491297a5ded2c3f8d7a2b654f1e6f3d4e2ff3ad7e14966a85","sent_txid":"231500b3ecba3bf2ba3db650f5e7565478382c5b","order_type":"sell","symbol_pair":"bitBTC_BTC","amount":"0.1","price":"0","fee":"0","miners_fee":"0","status":"completed","notes":null,"date":1485255789,"deposit_address":"1-n2HPFvf376vxQV1mo"}

Possible order statuses:

  1. none
  2. processing
  3. completed
  4. refunded
  5. pending
  6. placed
  7. partialFill
  8. failure

refunded will be listed for orders which have expired, or have been returned due to failure.

pending indicates the order is unconfirmed.

placed indicates the order is live in the market.

partialFill indicates the order was partially filled and is still open.

completed indicates the order has been completely filled.

failure indicates there has been a permenant failure processing the order.

processing is an internal status which should never be visible. Orders stuck in this status might need to be followed up with a support request.

Get details about a particular market, such as bid/ask price and transaction limits.

HTTP Method: POST

Required parameters:

Example:

POST https://metaexchange.info/api/1/getMarket HTTP/1.1
Connection: close
Accept: application/json
Content-Type: application/x-www-form-urlencoded
symbol_pair=bitBTC_BTC

Results:

{"symbol_pair":"bitBTC_BTC","ask":"1.006","bid":"0.994","ask_max":"1","bid_max":"0.8","ask_fee_percent":"0","bid_fee_percent":"0","up":false,"has_orderbook":false,"buy_disabled":false,"sell_disabled":false,"btc_volume_24h":"0","quote_volume_24h":"0","last_price":"0","asset_name":null,"realised_spread_percent":"0","price_delta":"0","flipped":false,"buy_quantity":"0.994","sell_quantity":"1.006","notes":null,"is_asset":false,"asset_type":"none"}

The values displayed in metaexchange for 1 BTC conversion quantity appear in the fields (1 BTC ->) buy_quantity and sell_quantity (-> 1 BTC).

Get a list of all available markets along with the best prices and transaction limits.

HTTP Method: GET

Example:

https://metaexchange.info/api/1/getAllMarkets

Results:

[{"symbol_pair":"bitBTC_BTC","ask":"1.006","bid":"0.994","ask_max":"1","bid_max":"0.8","ask_fee_percent":"0","bid_fee_percent":"0","up":false,"has_orderbook":false,"buy_disabled":false,"sell_disabled":false,"btc_volume_24h":"0","quote_volume_24h":"0","last_price":"0","asset_name":null,"realised_spread_percent":"0","price_delta":"0","flipped":false,"buy_quantity":"0.994","sell_quantity":"1.006","notes":null,"is_asset":false,"asset_type":"none"}]

Get the most recent transactions, sorted in descending order. This will only show transactions with status completed or partialFill.

HTTP Method: POST

Required parameters:

Optional parameters:

Example:

POST https://metaexchange.info/api/1/getLastTransactions HTTP/1.1
Connection: close
Accept: application/json
Content-Type: application/x-www-form-urlencoded
symbol_pair=bitBTC_BTC

Results:

[{"received_txid":"70827daa9f08211491297a5ded2c3f8d7a2b654f1e6f3d4e2ff3ad7e14966a85","sent_txid":"231500b3ecba3bf2ba3db650f5e7565478382c5b","order_type":"sell","symbol_pair":"bitBTC_BTC","amount":"0.1","price":"0","fee":"0","miners_fee":"0","status":"completed","notes":null,"date":1485255789,"deposit_address":"1-n2HPFvf376vxQV1mo"},{"received_txid":"70bc0017c21e29738a93b9f4ce21d36814898bf7bcdfc6feba5227e9ab3495d5","sent_txid":"4217b7b0dcb940e5732c977473c8d893f52370c4","order_type":"buy","symbol_pair":"bitBTC_BTC","amount":"0.0001","price":"0","fee":"0","miners_fee":"0","status":"completed","notes":null,"date":1485255789,"deposit_address":"mpwPhGCtbe8AeoFq3FWq6ToKbeapL7zM8b"}]

Get your most recent transactions, sorted in descending order. Use this when you know the deposit address to which you sent funds, or the transaction memo. This shows transactions with any status.

HTTP Method: POST

Required parameters:

Optional parameters:

Example:

POST https://metaexchange.info/api/1/getMyLastTransactions HTTP/1.1
Connection: close
Accept: application/json
Content-Type: application/x-www-form-urlencoded
memo=1-mqjz4GnADMucWuR4v

Results:

[{"received_txid":"ab265b51259a651c68b4a82b8bce5c501325d323","sent_txid":"f94f79e29110107c917ba41fa02fcfc2ccb5e4cc","order_type":"sell","symbol_pair":"bitBTC_BTC","amount":"0.7","price":"0","fee":"0","miners_fee":"0","status":"refunded","notes":"Over 0.2 BTC!","date":1485255789,"deposit_address":"1-n2HPFvf376vxQV1mo"},{"received_txid":"18159b00b90374cb467a7744a031d84663e92136","sent_txid":"ed7364fd1b8ba4cc3428470072300fb88097c3a343c75b6e604c68799a0148cb","order_type":"sell","symbol_pair":"bitBTC_BTC","amount":"0.07","price":"0","fee":"0","miners_fee":"0","status":"completed","notes":null,"date":1485255789,"deposit_address":"1-n2HPFvf376vxQV1mo"}]

API V2 detail

Calcate what you would receive for a given order in the specified market after all fees have been deducted.

HTTP Method: POST

Required parameters:

Example:

POST https://metaexchange.info/api/2/getQuote HTTP/1.1
Connection: close
Accept: application/json
Content-Type: application/x-www-form-urlencoded
symbol_pair=bitBTC_BTC&order_type=buy&deposit_amount=1

Results:

{"result":"0.99","remaining":"0"}

If the result from the quote contains a non-zero remaining field, this indicates that the order was larger than the maximum amount. In fact, it indicates the amount which would be refunded.

Get your most recent transactions, sorted in descending order. Use this when you know the receiving address which will receive the funds. This shows transactions with any status.

HTTP Method: POST

Required parameters:

Example:

POST https://metaexchange.info/api/2/getMyLastTransactions HTTP/1.1
Connection: close
Accept: application/json
Content-Type: application/x-www-form-urlencoded
symbol_pair=bitBTC_BTC&receiving_address=monsterer,16KLJg9B1Nfky5HL72tsbtV7gyoWNTENor&limit=20

Results:

[{"received_txid":"ab265b51259a651c68b4a82b8bce5c501325d323","sent_txid":"f94f79e29110107c917ba41fa02fcfc2ccb5e4cc","order_type":"sell","symbol_pair":"bitBTC_BTC","amount":"0.7","price":"0","fee":"0","miners_fee":"0","status":"refunded","notes":"Over 0.2 BTC!","date":1485255789,"deposit_address":"1-n2HPFvf376vxQV1mo"},{"received_txid":"18159b00b90374cb467a7744a031d84663e92136","sent_txid":"ed7364fd1b8ba4cc3428470072300fb88097c3a343c75b6e604c68799a0148cb","order_type":"sell","symbol_pair":"bitBTC_BTC","amount":"0.07","price":"0","fee":"0","miners_fee":"0","status":"completed","notes":null,"date":1485255789,"deposit_address":"1-n2HPFvf376vxQV1mo"}]

Get your open orders. This will show both resting limit orders and pending market orders. See below for possible order statuses.

HTTP Method: POST

Required parameters:

Example:

POST https://metaexchange.info/api/2/getMyOpenOrders HTTP/1.1
Connection: close
Accept: application/json
Content-Type: application/x-www-form-urlencoded
symbol_pair=bitBTC_BTC&receiving_address=monsterer,16KLJg9B1Nfky5HL72tsbtV7gyoWNTENor

Results:

[{"symbol_pair":"bitBTC_BTC","type":"buyLimit","total_balance":"1","remaining_balance":"0.97","price":"0.00001","expires":1485259389,"date":-62135596800,"txid":"634c0c68431d4e4f22cc1f734a14554d336a665e93a340ee32af4ac0a3937348","receiving_address":"monsterer","deposit_address":"mtaSAyRk1vZcbdSHEjzjrkYdGhF2pqr6ya","refund_address":"mnevVYSFSy3xFTbe98BWzQoAsdVW572oiL","status":"partialFill","relative_percent":0}]

Possible order statuses:

  1. none
  2. processing
  3. completed
  4. refunded
  5. pending
  6. placed
  7. partialFill
  8. failure

refunded will be listed for orders which have expired, or have been returned due to failure.

pending indicates the order is unconfirmed.

placed indicates the order is live in the market.

partialFill indicates the order was partially filled and is still open.

completed indicates the order has been completely filled.

failure indicates there has been a permenant failure processing the order.

processing is an internal status which should never be visible. Orders stuck in this status might need to be followed up with a support request.

Get the orderbook for the given market. Amounts are in base units, prices are in quote units.

HTTP Method: POST

Required parameters:

Example:

POST https://metaexchange.info/api/2/getOrderbook HTTP/1.1
Connection: close
Accept: application/json
Content-Type: application/x-www-form-urlencoded
symbol_pair=bitBTC_BTC&limit=20

Results:

{"bids":[{"price":"0.000035","amount":"0.1"},{"price":"0.00003","amount":"0.9"},{"price":"0.00002","amount":"1.4"},{"price":"0.000025","amount":"0.2"}],"asks":[{"price":"0.00004","amount":"1"},{"price":"0.00005","amount":"0.2"},{"price":"0.00006","amount":"1.9"},{"price":"0.00007","amount":"0.3"}]}

Get a list of output transactions for a given input transaction when you know the blockchain transaction id. The only difference between this version and the V1 version is that this returns an array of results, rather than just a single result to reflect the fact that one input transaction can result in multiple output transactions in a limit order market.

HTTP Method: POST

Required parameters:

Example:

POST https://metaexchange.info/api/2/getOrderStatus HTTP/1.1
Connection: close
Accept: application/json
Content-Type: application/x-www-form-urlencoded
txid=ed7364fd1b8ba4cc3428470072300fb88097c3a343c75b6e604c68799a0148cb

Results:

[{"received_txid":"70827daa9f08211491297a5ded2c3f8d7a2b654f1e6f3d4e2ff3ad7e14966a85","sent_txid":"231500b3ecba3bf2ba3db650f5e7565478382c5b","order_type":"sell","symbol_pair":"bitBTC_BTC","amount":"0.1","price":"0","fee":"0","miners_fee":"0","status":"completed","notes":null,"date":1485255789,"deposit_address":"1-n2HPFvf376vxQV1mo"}]

Possible order statuses:

  1. none
  2. processing
  3. completed
  4. refunded
  5. pending
  6. placed
  7. partialFill
  8. failure

refunded will be listed for orders which have expired, or have been returned due to failure.

pending indicates the order is unconfirmed.

placed indicates the order is live in the market.

partialFill indicates the order was partially filled and is still open.

completed indicates the order has been completely filled.

failure indicates there has been a permenant failure processing the order.

processing is an internal status which should never be visible. Orders stuck in this status might need to be followed up with a support request.