View on GitHub

bitme.github.io

BitMe info docs

REST API

This API is RESTful-based meaning that HTTP methods and response codes are used to convey meaning. All response bodies are returned in JSON.

For code examples/libraries check out our GitHub.

Authentication

For API calls that require authentication the following applies.

Each request must contain a request parameter called nonce in addition to the specific parameters for each API call. Every API request sent for the lifetime of an API key must include an ever-incrementing nonce value. A simple solution is to simply use the Unix epoch for this.

Each request must also contain two HTTP request headers:

  • Rest-Key - your API key
  • Rest-Sign - a SHA-512 HMAC of the request parameters (including nonce) using your API secret

Errors

The API will attempt to respond with the most appropriate HTTP response code whenever possible. When the API call completes successfully, the API will always return HTTP response code 200 OK. When responding with a non-200 HTTP response code, the API will return a single error object. This error object will contain an API code (do not confuse this with the HTTP response code) and message that will give you a hint as to what went wrong. The error object will also (repetitively) contain the HTTP response code as http_code.

When checking for a specific error condition, you should use the HTTP response code, or more specifically the API code, as the messages are subject to change at any time.

{
  "error": {
    "code": 1101,
    "http_code": 401,
    "message": "Invalid API key"
  }
}

HTTP Response Codes

  • 200 OK - Success
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Authentication for the request failed
  • 403 Forbidden - Request understood, but was rejected for some reason
  • 404 Not Found - The API call does not exist
  • 420 Enhance Your Calm - Your request rate is too high, you are being rate limited
  • 500 Internal Server Error - Something went wrong, you should contact BitMe
  • 503 Service Temporarily Unavailable - The service is unavailable, it may be down for maintenance or other issues

Error codes

The API-specific error codes are 4-digits, starting with 1000. These may be used to gain more details about why a request failed than the HTTP response code by itself. Each group of 100 codes (1000-1099) represent a category of errors.

Every API call may return a code in the 1000 (generic errors), 1100 (authentication errors), and 1700 (rate limiting) range. Additional possible codes specific to each API call are documented below under each call's section.

The first code in each category (ending in 00), coinciding with a HTTP response code of 500, is a generic catch-all for the category. If you see this, then something has gone wrong and you should contact us.

code http_code message
1000 500 Unknown error
1001 404 The requested resource was not found
1002 400 Invalid request parameter value
1003 503 API is temporarily unavailable
1100 500 Unknown authentication error
1101 401 Invalid API key
1102 401 Invalid nonce
1103 401 Invalid signing hash
1105 403 Invalid username and/or password
1106 403 Login successful, Two-factor authentication required
1200 500 Unknown transaction error
1201 403 Insufficient available account balance
1202 403 Cannot exceed deposit limit
1203 403 Cannot exceed withdrawal limit
1400 500 Unknown order error
1401 403 Cannot have more than 100 open orders
1402 403 Cannot create an order that will execute against own order
1500 500 Unknown error relating to a user
1501 403 Invalid user
1504 403 The given email address is already in use
1505 403 Cannot use same user
1506 403 User must agree to terms of use
1700 500 Unknown rate limiting error
1701 420 You are being rate limited, lower your request rate

GET /rest/verify-credentials

Verifies credentials (Rest-Key and Rest-Sign headers and nonce parameter). If just getting started with the API in your development environment, getting this to return HTTP response code 200 OK would be a good first goal to have.

  • Requires Auth? Yes

Request Parameters

None specific to this request

Error Codes

None specific to this request (see Error codes section above)

Response Body

Returns an empty JSON object on success

{}

GET /rest/accounts

Gets user's account balances.

  • Requires Auth? Yes

Request Parameters

None specific to this request

Error Codes

None specific to this request (see Error codes section above)

Response Body

Returns an array of account objects on success.

{
  "accounts": [
    {
      "currency_cd": "BTC",
      "currency_name": "Bitcoin",
      "balance": "40.39990000000000000000",
      "available": "0.39990000000000000000"
    },
    {
      "currency_cd": "USD",
      "currency_name": "US Dollar",
      "balance": "101.40052440000000000000",
      "available": "100.40052440000000000000"
    }
  ]
}

GET /rest/bitcoin-address

Gets the latest Bitcoin address associated with user's account. New addresses are automatically created 24 hours after the first time an address is used to make a deposit, old addresses will remain functional.

Note that if the deposit amount exceeds any of the user's current account limits then the excess amount will be delayed in becoming available.

  • Requires Auth? Yes

Request Parameters

None specific to this request.

Error Codes

None specific to this request (see Error codes section above)

Response Body

Returns an address object on success

  • address - latest Bitcoin address associated with user's account
{
  "address": {
    "address": "mocJjuVHSzZLx9o1nUmH5xGEE74rVxJDnN"
  }
}

Orders

POST /rest/order/create

Creates an order based on the given parameters.

Upon response, the order may be completely executed (and automatically closed), partially executed and remain open, or not executed at all and remain open.

  • Requires Auth? Yes
Request Parameters
  • currency_pair - currency pair of the order you are placing (BTCUSD)
  • order_type_cd - character code of the order type to place (BID or ASK)
  • quantity - quantity of the order at the given rate, numeric value accepting precision up to 8 digits, minimum 0.1
  • rate - rate at which you would like to place your order, numeric value accepting precision up to 3 digits
Error Codes
  • 1201
  • 1401
  • 1402
Response Body

Returns an order object on success

  • uuid - UUID of the order
  • order_type_cd - character code of the order type (BID or ASK)
  • currency_pair - currency pair of the order (BTCUSD)
  • rate - rate of the order
  • quantity - quantity of the order at a specific rate
  • executed - quantity of the order that has been executed, the maximum this value will ever be is equal to quantity
  • created - when the order was created in ISO 8601 format
  • closed - when the order was closed in ISO 8601 format, will be null if order is still open
  • executions - array of any executions that have occurred on the order
    • uuid - UUID of the order execution
    • executed - quantity of the order that was executed
    • rate - rate at which the execution occurred
    • created - when the execution occurred in ISO 8601 format
{ 
  "order": {
    "uuid": "74eb9e44-cbbf-4265-aec5-e39e5bd2e128",
    "order_type_cd": "BID",
    "currency_pair": "BTCUSD",
    "rate": "5.12300000000000000000",
    "quantity": "2.00000000000000000000",
    "executed": "1.00000000000000000000",
    "created": "2012-06-17T11:30:52.607Z",
    "closed": null,
    "executions": [{
      "uuid": "9c48ff1f-a064-49e1-9c4d-ff39091332b8",
      "executed": "1.00000000000000000000",
      "rate": "5.12345676000000000000",
      "created": "2012-06-17T11:30:52.607Z"
    }]
  }
}

POST /rest/order/cancel

Cancels an order that was previously created and is still open, this includes orders that were never or only partially executed.

  • Requires Auth? Yes
Request Parameters
  • uuid - UUID of order you would like to cancel
Error Codes

None specific to this request (see Error codes section above)

Response Body

Returns an order object on success (same as /rest/order/create)

{
  "order": {
    "uuid": "b96d7abf-7b7e-434d-b8ab-9dd81b79564a",
    "order_type_cd": "BID",
    "currency_pair": "BTCUSD",
    "rate": "2.00000000000000000000",
    "quantity": "10.00000000000000000000",
    "executed": "0.00000000000000000000",
    "created": "2012-06-15T05:18:55.464Z",
    "closed": "2012-06-15T05:20:55.488Z",
    "executions": []
  }
}

POST /rest/bitcoin-withdraw

Withdraws bitcoins of the given amount to a given bitcoin address. Note that the user will be charged a 0.0005 BTC fee for each withdrawal. This fee may be subtracted from the given amount if the user does not have enough available balance to cover the fee.

  • Requires Auth? Yes
Request Parameters
  • amount - The amount of bitcoins to withdraw, numeric value accepting precision up to 8 digits, minimum 0.01
  • address - The bitcoin address to send the bitcoins to
Error Codes
  • 1201
Response Body

Returns a transaction object on success

  • id - id of the transaction
  • transaction_type_cd - type of the transaction (will always be 'DEBIT' for this call)
  • transaction_category_cd - category of the transaction (will always be 'BITCOIN' for this call)
  • currency_cd - three character code of the currency the transaction is in (will always be 'BTC' for this call)
  • amount - amount of bitcoins (note this may differ from the given amount)
  • transaction_status_cd - status of the transaction (will always be 'PENDING' for this call)
  • created - when the transaction was created in ISO 8601 format
  • cleared - when the transaction was cleared in ISO 8601 format
{
  "transaction": {
    "id": 26,
    "transaction_type_cd": "DEBIT",
    "transaction_category_cd": "BITCOIN",
    "currency_cd": "BTC",
    "amount": "50.00000000000000000000",
    "transaction_status_cd": "PENDING",
    "created": "2013-09-04T09:22:24.745Z",
    "cleared": null
  }
}

GET /rest/transaction/:id

Gets the transaction object for the given transaction

  • Requires Auth? Yes
Request Parameters
  • :id - ID of the transaction to retrieve
Error Codes

None specific to this request (see Error codes section above)

Response Body

Returns a transaction object on success

  • id
  • transaction_type_cd
  • transaction_category_cd
  • currency_cd
  • amount
  • transaction_status_cd
  • created
  • cleared
{
  "transaction": {
    "id": 26,
    "transaction_type_cd": "DEBIT",
    "transaction_category_cd": "BITCOIN",
    "currency_cd": "BTC",
    "amount": "30.00000000000000000000",
    "transaction_status_cd": "PENDING",
    "created": "2013-09-04T20:32:05.946Z",
    "cleared": null
  }
}

GET /rest/transactions/:currency_cd

Get an array of transactions for the given currency

  • Requires Auth? Yes
Request Parameters
  • :currency_cd
  • limit
  • orderBy - "DESC" or "ASC"
  • page
Error Codes

None specific to this request (see Error codes section above)

Response Body

Returns an array of transaction objects on success (same as GET /rest/transaction/:id)

GET /rest/order/:uuid

Gets the order object for the given order

  • Requires Auth? Yes
Request Parameters
  • :uuid - UUID of the order to retrieve
Error Codes

None specific to this request (see Error codes section above)

Response Body

Returns an order object on success (same as /rest/order/create)

{
  "order": {
    "uuid": "f3724c4b-e2ae-4817-896f-2fa02238519b",
    "order_type_cd": "BID",
    "currency_pair": "BTCUSD",
    "rate": "2.00000000000000000000",
    "quantity": "10.00000000000000000000",
    "executed": "0.00000000000000000000",
    "created": "2012-06-15T10:35:01.843Z",
    "closed": null,
    "executions": []
  }
}

GET /rest/orders/open

Gets user's open orders.

  • Requires Auth? Yes
Request Parameters

None specific to this request.

Error Codes

None specific to this request (see Error codes section above)

Response Body

Returns an orders array on success.

{
  "orders": [
    {
      "uuid": "20ade3fd-6161-4edc-89aa-90b5e82b30e5",
      "order_type_cd": "BID",
      "currency_pair": "BTCUSD",
      "rate": "0.50000000000000000000",
      "quantity": "2.00000000000000000000",
      "executed": "0.00000000000000000000",
      "created": "2012-06-18T07:42:47.595Z",
      "executions": []
    },
    {
      "uuid": "a3b34de8-f4d1-4e77-918f-12cd8f194b28",
      "order_type_cd": "ASK",
      "currency_pair": "BTCUSD",
      "rate": "1.00000000000000000000",
      "quantity": "40.00000000000000000000",
      "executed": "5.00000000000000000000",
      "created": "2012-06-17T19:43:14.278Z",
      "executions": [
        {
          "uuid": "56984d87-455f-4192-af69-7d824945721c",
          "executed": "2.00000000000000000000",
          "rate": "1.00000000000000000000",
          "created": "2012-06-18T05:14:25.012Z"
        },
        {
          "uuid": "1ed5bc71-9f0a-4b49-a04b-a03719168689",
          "executed": "1.00000000000000000000",
          "rate": "1.00000000000000000000",
          "created": "2012-06-18T03:44:22.299Z"
        },
        {
          "uuid": "80feb0c3-3012-4759-b831-4a47e3ed6c70",
          "executed": "1.00000000000000000000",
          "rate": "1.00000000000000000000",
          "created": "2012-06-17T19:46:23.500Z"
        },
        {
          "uuid": "bb5af512-2e77-477a-a874-a3544c0cef98",
          "executed": "1.00000000000000000000",
          "rate": "1.00000000000000000000",
          "created": "2012-06-17T19:43:14.278Z"
        }
      ]
    }
  ]
}

GET /rest/orderbook/:currency_pair

Gets the current full orderbook for the given currency pair.

  • Requires Auth? No
Request Parameters
  • currency_pair - currency pair of the orderbook to get (BTCUSD)
Error Codes

None specific to this request (see Error codes section above)

Response Body

Returns an orderbook object on success.

{
  "orderbook": {
    "bids": [
      {
        "order_type_cd": "BID",
        "currency_pair": "BTCUSD",
        "rate": "0.50000000000000000000",
        "quantity": "2.00000000000000000000"
      }
    ],
    "asks": [
      {
        "order_type_cd": "ASK",
        "currency_pair": "BTCUSD",
        "rate": "1.00000000000000000000",
        "quantity": "35.00000000000000000000"
      }
    ]
  }
}

GET /rest/compat/orderbook/:currency_pair

Gets a Bitcoin Charts-compatible orderbook for the given currency pair.

  • Requires Auth? No
Request Parameters
  • currency_pair - currency pair of the orderbook to get (BTCUSD)
Error Codes

None specific to this request (see Error codes section above)

Response Body

Returns an object with an array of asks and array of bids on success. Each bid/ask is an array, with the first value being the rate (price) and the second value the quantity (amount).

As an example, for the currency_pair BTCUSD, the first value would be the rate (1 BTC = ? USD), and the second value would be the quantity (? BTC).

{
  "asks": [
    [
      "6.449",
      "67.23"
    ],
    [
      "6.45",
      "0.09"
    ],
    [
      "6.454",
      "0.12"
    ]
  ],
  "bids": [
    [
      "5.788",
      "2.66318"
    ],
    [
      "5.79",
      "48.95943817"
    ],
    [
      "5.790",
      "0.12309412"
    ],
    [
      "5.791",
      "0.020261"
    ]
  ]
}

GET /rest/compat/trades/:currency_pair

Gets a Bitcoin Charts-compatible array of trades for the given currency pair.

Returns trade executions in last 24 hours by default, use since for more control.

  • Requires Auth? No
Request Parameters
  • currency_pair - currency pair of the orderbook to get (BTCUSD)
  • since - (optional) return trades with a higher tid than the given one
Error Codes

None specific to this request (see Error codes section above)

Response Body

Returns an array of trade objects on success.

  • date - UNIX epoch of when trade execution occurred
  • price - AKA rate, the price of 1 unit of the base currency in the counter currency
  • amount - AKA quantity, the amount of the counter currency in the execution
  • tid - a ever-incrementing unique integer for each execution
[
  {
    "tid": 1,
    "amount": "1.00000000000000000000",
    "price": "1.00000000000000000000",
    "date": 1340541530
  },
  {
    "tid": 2,
    "amount": "1.00000000000000000000",
    "price": "1.00000000000000000000",
    "date": 1340541530
  },
  {
    "tid": 3,
    "amount": "1.00000000000000000000",
    "price": "1.00000000000000000000",
    "date": 1340541530
  },
  {
    "tid": 4,
    "amount": "0.98100000000000000000",
    "price": "1.00000000000000000000",
    "date": 1340541530
  },
  {
    "tid": 5,
    "amount": "1.00000000000000000000",
    "price": "1.00000000000000000000",
    "date": 1340541632
  }
]