How the API works

API Endpoint

All your API requests should be made to the following API endpoint:

Supported Request Methods

GET Use GET to retrieve a resource or a set of resources (such as a list of all your Hoppers, your current orders, or a list of your latest transactions). This method is safe and idempotent.

POST Use POST to create a resource. For example: place a new buy/sell order, create a new trading bot.

PATCH Use PATCH to update a resource. For example: start or stop your Hopper, or update your personal details. With this method you only need to provide the fields you wish to modify in the request body.

DELETE Use DELETE when you want to delete a resource.

Request Parameters

There are four types of parameters that we use in our API: path, query string, header and request body parameters. Request body parameters are data posted in the JSON request body for POST and PATCH requests. Header parameters are obviously parameters which need to be posted in the header. More info about the Header, Path and Query string parameters can be found underneath.

Header Parameters

Every request to our API needs to be authenticated by posting the following values in the header:

  • access_token - Your access token received with the Oauth2 authentication

Path Parameters

These are parameters that are supplied in the URI of the endpoint. For example the GET Hopper endpoint:{hopper_id}

In order to retrieve a Hopper by its unique ID, you need to replace its ID value in the {hopper_id} placeholder. For example to retrieve a Hopper with ID 37, you would request the following URL:

Some endpoints require multiple parameters. For example if you wish to return a specific order from the previous Hopper, you need to call the following URL:{hopperId}/order/{orderId}

And by replacing the parameters with the Hopper and Order ID you will get:

For a detailed list of parameters required in each API endpoint, please refer to our API reference guide.

Query String Parameters

We use these type of parameters in GET requests for filtering and/or pagination of data. These parameters are not specified in the path, but as a set of values separated by the ‘&’ character in the URL string.

For example to retrieve a Hopper’s Bitcoin buy orders, you could call the Hopper Order endpoint like this:

By looking at our API reference you can see that, in this case, the order_type parameter can either take the values ‘buy’ or ‘sell’, and the coin parameter could be any lower case crypto currency coin code.

Response Format

All responses are in the form of a JSON object. Thus, the MIME type you find in all of our responses will be application/json. Please refer to our API reference documentation for the specific JSON response format in the body of each request and response.

HTTP Response Codes

We use the response status codes defined by the RFC 2616 and RFC 6585 standards.

200 - OK Successful request. Client gets back the result of the request in the body and the headers of the response.

201 – Created The request has been accepted and a new resource was created.

202 – Accepted The request has been accepted for processing, but the processing has not been completed.

204 – No Content The server successfully processed the request but no content is returned.

304 – Not Modified The resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match. There is no need to re-transmit the resource since the client still has a previously-downloaded copy.

HTTP Error Codes

400 – Bad Request The server cannot or will not process the request due to an apparent client error. The message body will return the error information.

400 – Bad Request The server cannot or will not process the request due to an apparent client error. The message body will return the error information.

401 – Unauthorized The request requires user authentication and has been refused due to invalid or missing API credentials.

403 – Forbidden The server understood the request, but is refusing to fulfill it because you are not allowed to access it or your credentials have been revoked to access it.

404 – Not found The requested resource could not be found. This error can be due to a temporary or permanent condition.

405 – Method Not Allowed The used request method is not supported by the requested API endpoint.

405 – Method Not Allowed The used request method is not supported by the requested API endpoint.

429 – Too Many Request The user has exceeded the API requests rate limit. Check the returned Retry-After header to know how many seconds you need to wait to make a new request. Please consult our rate limit section to find out what our current request limits are.

500 – Internal Server Error An error happened in our server that prevents it from answering your request. Our developers will have their free coffee taken away for a week as a first warning...

503 – Service Unavailable Our servers could be experiencing a problem, and will not be able to fulfill your request.

Error messages

Whenever the API returns an error code, it will attach a JSON object with the description of the error in its body. An error message would look something like this:

    "status": 400,
    "error": 1,
    "message": "Missing required request parameters: [access_token]"

Rate Limits

Our API has a request rate limit to provide an equal share of our bandwidth resources to all of our users. Our current rate limits are 2 request per second per user, except when it comes to placing buy orders. In that case, the maximum amount of buy orders that can be placed is one order each 8 seconds.

If you exceed the amount of available request per second, you will get a 429 error response code. Please check the Retry-After header attached to the response, which contains the amount of seconds you have to wait until you can perform another request.