Cryptolocator API Documentation

With the Cryptolocator API you can query our public trade data and advertisements, manage your Cryptolocator account by updating advertisements, automate trading and more.

Making requests to the API

Most API requests need to be encoded with application/x-www-form-urlencoded and sent as HTTP GET or POST requests to the appropriate API endpoint. When uploading files multipart/form-data encoding is also supported

Responses

Return values are UTF-8 encoded JSON with the following metadata structure, which corresponds to an API request with the message return value:

{
"data": {
"message": String
}
}

If the API request ended in an unrecoverable error, there is no data top level field. This helps against accidentally using an error message as legitimate data, creating confusing situations. Errors will also return with an appropriate HTTP error code. If the API is requested with invalid data a 400 Bad Request response is returned, but other HTTP error codes can be returned as well.

Instead there is an error field that contains an object with the fields code and message. The error object can contain more fields if specified on the error documentation. The code field is meant to be read by the application, the message field is meant to be human readable. An example error return object:

{
"error": {
"code": Required, Integer
"message": Required, String
}
}

You can find a full list of error codes and their meanings at the end of this page.

Authentication

To authenticate with our API you will need to register a Cryptolocator account. After registering, visit your Apps Dashboard to create the necessary authentication token to enable public API for your Cryptolocator account.

Request headers format is:

{
"X-Access-Token": String
}

API reference

A list of all API endpoints, both public and authenticated

Authentication required Endpoint HTTP method Function
true public/v1/me GET Self info
true public/v1/order_book GET Order book
false public/v1/orders GET Ads list
true public/v1/ads GET Self ads list
true public/v1/ads/:id GET Ad info
true public/v1/ads/:id PATCH Update the ad
true public/v1/ads/:ad_id/trades POST Create a trade
true public/v1/trades GET Own trades
true public/v1/trades/search POST Search by own trades
true public/v1/trades/:trade_id GET Trade info
true public/v1/trades/:trade_id/confirm POST Confirm the payment
true public/v1/trades/:trade_id/complete POST Complete the trade and send ETH to buyer
true public/v1/trades/:trade_id/cancel POST Cancel the trade
true public/v1/trades/:trade_id/prolong POST Add extra time for escrow
true public/v1/trades/:trade_id/feedbacks POST Leave a feedback
true public/v1/trades/:trade_id/messages GET Get list of messages
true public/v1/trades/:trade_id/messages POST Create a message

GET public/v1/me

Description

Self info

Responses

200

Success

{
"data": {
"user": {
"id": Integer
"user_name": String
"balance": [
{
"currency": String, One of: ETH, BTC, USDT
"value": Float
}
]
}
}
}

GET public/v1/order_book

Description

Order book

Params

{
"crypto_currency_code": Required, String
"currency_code": Required, String
}

Responses

200

Success

{
"data": {
"asks": [
{
"price": Float
"max": Float
}
]
"bids": [
{
"price": Float
"max": Float
}
]
}
}

GET public/v1/orders

Description

Returns advertisements. If there are a lot of ads, the response will be paginated. You can filter the response using the optional arguments. For an authenticated request, the offers available for your account will be returned

Params

{
"currency_code": String
"country_code": String
"is_active": Integer, 1 - true, 0 - false
"type": String, One of: Ad::Buy, Ad::Sell
"page": Integer
"limit": Integer
}

Responses

200

Success

{
"data": {
"ads": [
{
"id": Integer
"type": String, One of: Ad::Buy, Ad::Sell
"price": Float
"working_now": Boolean
"location": String, Accurate place name
"user": {
"id": Integer
"user_name": String
"online": Boolean
"response_time": Integer, Seconds
"current_sign_in_at": DateTime
}
"payment_method": {
"code": String
"name": String
}
"country_code": String
"currency_code": String
"crypto_currency_code": String
"payment_method_code": String
"first_time_limit": Float
"profit_in_percent": Float
"for_sms_verified_people": Boolean
"for_identified_people": Boolean
"amount_min": Integer
"amount_max": Integer
"limit_min": Integer
"limit_max": Integer
"require_feedback_score": Integer
"require_trade_volume": Integer
"for_trusted_people": Boolean
"total_pages": Integer
"total_count": Integer
}
]
}
}

GET public/v1/ads

Description

Self ads list

Responses

200

Success

{
"data": {
"ads": [
{
"id": Integer
"type": String, One of: Ad::Buy, Ad::Sell
"price": Float
"working_now": Boolean
"location": String, Accurate place name
"user": {
"id": Integer
"user_name": String
"online": Boolean
"response_time": Integer, Seconds
"current_sign_in_at": DateTime
}
"payment_method": {
"code": String
"name": String
}
"country_code": String
"currency_code": String
"crypto_currency_code": String
"payment_method_code": String
"first_time_limit": Float
"profit_in_percent": Float
"for_sms_verified_people": Boolean
"for_identified_people": Boolean
"amount_min": Integer
"amount_max": Integer
"limit_min": Integer
"limit_max": Integer
"require_feedback_score": Integer
"require_trade_volume": Integer
"for_trusted_people": Boolean
"total_pages": Integer
"total_count": Integer
}
]
}
}

GET public/v1/ads/:id

Description

Ad info

Responses

200

Success

{
"data": {
"ad": {
"id": Integer
"type": String, One of: Ad::Buy, Ad::Sell
"price": Float
"working_now": Boolean
"location": String, Accurate place name
"user": {
"id": Integer
"user_name": String
"online": Boolean
"response_time": Integer, Seconds
"current_sign_in_at": DateTime
}
"payment_method": {
"code": String
"name": String
}
"country_code": String
"currency_code": String
"crypto_currency_code": String
"payment_method_code": String
"first_time_limit": Float
"profit_in_percent": Float
"for_sms_verified_people": Boolean
"for_identified_people": Boolean
"amount_min": Integer
"amount_max": Integer
"limit_min": Integer
"limit_max": Integer
"require_feedback_score": Integer
"require_trade_volume": Integer
"for_trusted_people": Boolean
"total_pages": Integer
"total_count": Integer
}
}
}

400

Ad is not exists. Ad can't be accessed by current user due to ad inactivity or relationship between users

{
"error": {
"code": Integer, 2
"message": String, Resource not found
}
}

PATCH public/v1/ads/:id

Description

Update the ad

Params

{
"ad": {
"equation": String
"profit_in_percent": Integer
"amount_max": Integer
"amount_min": Integer
}
}

Responses

200

Success

400

Error

{
"error": {
"code": Integer, 31
"message": String, Too many active ads. Limit was reached
}
}

400

Error

{
"error": {
"code": Integer, 5
"message": String, The API was called with invalid parameters
}
}

POST public/v1/ads/:ad_id/trades

Description

Create a trade

Params

{
"trade": {
"message": String
"amount": Float
}
}

Responses

200

Success

{
"data": {
"trade": {
"id": Integer
}
}
}

400

Error

{
"error": {
"code": Integer, 5
"message": String, The API was called with invalid parameters
}
}

400

Error

{
"error": {
"code": Integer, 8
"message": String, Unclassified error. See message and payload
}
}

400

Error

{
"error": {
"code": Integer, 26
"message": String, Limit of opened trades was exceeded
}
}

400

Error

{
"error": {
"code": Integer, 27
"message": String, For SMS verified users only
}
}

400

Error

{
"error": {
"code": Integer, 28
"message": String, Identified people only
}
}

400

Error

{
"error": {
"code": Integer, 29
"message": String, Trader is not available now
}
}

GET public/v1/trades

Description

Own trades

Params

{
"opened": boolean
}

Responses

200

Success

{
"data": {
"trades": [
{
"id": Integer
"amount": Float
"price": Float
"fee": Float
"created_at": DateTime
"completed_at": DateTime
"cancelled_at": DateTime
"paid_confirmed_at": DateTime
"escrow_expired_at": DateTime
"escrow_prolongable": Boolean
"cost": Float
"feedback_allowed": Boolean
"status": String
"ad": {
"id": Integer
"type": String, One of: Ad::Buy, Ad::Sell
"price": Float
"working_now": Boolean
"location": String, Accurate place name
"user": {
"id": Integer
"user_name": String
"online": Boolean
"response_time": Integer, Seconds
"current_sign_in_at": DateTime
}
"payment_method": {
"code": String
"name": String
}
"country_code": String
"currency_code": String
"crypto_currency_code": String
"payment_method_code": String
"first_time_limit": Float
"profit_in_percent": Float
"for_sms_verified_people": Boolean
"for_identified_people": Boolean
"amount_min": Integer
"amount_max": Integer
"limit_min": Integer
"limit_max": Integer
"require_feedback_score": Integer
"require_trade_volume": Integer
"for_trusted_people": Boolean
"total_pages": Integer
"total_count": Integer
}
"contractor": {
"id": Integer
"user_name": String
"online": Boolean
"response_time": Integer, Seconds
"current_sign_in_at": DateTime
}
}
]
}
}

POST public/v1/trades/search

Description

Search by own trades

Params

{
"created_at_from": Date
"created_at_to": Date
"status": String, One of: completed, cancelled, opened, paid_confirmed, new
"type": String, One of: Ad::Buy, Ad::Sell
"by_payment_method": String
"currency_code": String
"crypto_currency_code": String
"partner_id": Integer
}

Responses

200

Success

{
"data": {
"trades": [
{
"id": Integer
"amount": Float
"price": Float
"fee": Float
"created_at": DateTime
"completed_at": DateTime
"cancelled_at": DateTime
"paid_confirmed_at": DateTime
"escrow_expired_at": DateTime
"escrow_prolongable": Boolean
"cost": Float
"feedback_allowed": Boolean
"status": String
"ad": {
"id": Integer
"type": String, One of: Ad::Buy, Ad::Sell
"price": Float
"working_now": Boolean
"location": String, Accurate place name
"user": {
"id": Integer
"user_name": String
"online": Boolean
"response_time": Integer, Seconds
"current_sign_in_at": DateTime
}
"payment_method": {
"code": String
"name": String
}
"country_code": String
"currency_code": String
"crypto_currency_code": String
"payment_method_code": String
"first_time_limit": Float
"profit_in_percent": Float
"for_sms_verified_people": Boolean
"for_identified_people": Boolean
"amount_min": Integer
"amount_max": Integer
"limit_min": Integer
"limit_max": Integer
"require_feedback_score": Integer
"require_trade_volume": Integer
"for_trusted_people": Boolean
"total_pages": Integer
"total_count": Integer
}
"contractor": {
"id": Integer
"user_name": String
"online": Boolean
"response_time": Integer, Seconds
"current_sign_in_at": DateTime
}
}
]
}
}

GET public/v1/trades/:trade_id

Description

Trade info

Responses

200

Success

{
"data": {
"trade": {
"id": Integer
"amount": Float
"price": Float
"fee": Float
"created_at": DateTime
"completed_at": DateTime
"cancelled_at": DateTime
"paid_confirmed_at": DateTime
"escrow_expired_at": DateTime
"escrow_prolongable": Boolean
"cost": Float
"feedback_allowed": Boolean
"status": String
"ad": {
"id": Integer
"type": String, One of: Ad::Buy, Ad::Sell
"price": Float
"working_now": Boolean
"location": String, Accurate place name
"user": {
"id": Integer
"user_name": String
"online": Boolean
"response_time": Integer, Seconds
"current_sign_in_at": DateTime
}
"payment_method": {
"code": String
"name": String
}
"country_code": String
"currency_code": String
"crypto_currency_code": String
"payment_method_code": String
"first_time_limit": Float
"profit_in_percent": Float
"for_sms_verified_people": Boolean
"for_identified_people": Boolean
"amount_min": Integer
"amount_max": Integer
"limit_min": Integer
"limit_max": Integer
"require_feedback_score": Integer
"require_trade_volume": Integer
"for_trusted_people": Boolean
"total_pages": Integer
"total_count": Integer
}
"contractor": {
"id": Integer
"user_name": String
"online": Boolean
"response_time": Integer, Seconds
"current_sign_in_at": DateTime
}
}
}
}

POST public/v1/trades/:trade_id/confirm

Description

Confirm the payment

Responses

200

Success

400

Error

{
"error": {
"code": Integer, 23
"message": String, Can't be paid. Trade is in cancelled, completed or paid status
}
}

POST public/v1/trades/:trade_id/complete

Description

Complete the trade and send ETH to buyer

Responses

200

Success

400

Error

{
"error": {
"code": Integer, 20
"message": String, Trade is not paid yet
}
}

POST public/v1/trades/:trade_id/cancel

Description

Cancel the trade

Responses

200

Success

400

Error

{
"error": {
"code": Integer, 21
"message": String, Trade already completed or cancelled
}
}

POST public/v1/trades/:trade_id/prolong

Description

Add extra time for escrow

Responses

200

Success

400

Error

{
"error": {
"code": Integer, 24
"message": String, Escrow not expired yet
}
}

400

Error

{
"error": {
"code": Integer, 25
"message": String, Already prolonged
}
}

POST public/v1/trades/:trade_id/feedbacks

Description

Leave a feedback

Params

{
"body": String
"grade": Required, String, One of: negative, neutral, positive
}

Responses

200

Success

400

Error

{
"error": {
"code": Integer, 5
"message": String, The API was called with invalid parameters
}
}

400

Error

{
"error": {
"code": Integer, 22
"message": String, You can't leave feedback for this trade. Possible reasons: Trade is not finished yet, cancelled unexpectedly, or allowed time for the feedback was expired.
}
}

GET public/v1/trades/:trade_id/messages

Description

Get list of messages

Responses

200

Success

{
"data": {
"messages": [
{
"id": Integer
"date": DateTime
"attachment": String, Path to file
"body": String
"user": {
"id": Integer
"user_name": String
"online": Boolean
"response_time": Integer, Seconds
"current_sign_in_at": DateTime
}
}
]
}
}

POST public/v1/trades/:trade_id/messages

Description

Create a message

Params

{
"message": {
"body": Required, String
"attachment": File, jpg, jpeg, gif, png, csv, pdf
}
}

Responses

200

Success

400

Error

{
"error": {
"code": Integer, 5
"message": String, The API was called with invalid parameters
}
}

API error codes

Code Message
1 Authentication token invalid or was not sent
2 Resource not found
3 General server error. We log all errors, so if you cause an unexpected server error we'll fix it
4 Requested action cannot be done to this resource
5 The API was called with invalid parameters
6 Account was blocked by admin
7 Resource forbidden. The token owner cannot access this resource
8 Unclassified error. See message and payload
20 Trade is not paid yet
21 Trade already completed or cancelled
22 You can't leave feedback for this trade. Possible reasons: Trade is not finished yet, cancelled unexpectedly, or allowed time for the feedback was expired.
23 Can't be paid. Trade is in cancelled, completed or paid status
24 Escrow not expired yet
25 Already prolonged
26 Limit of opened trades was exceeded
27 For SMS verified users only
28 Identified people only
29 Trader is not available now
30 You can't generate a new address: accounts with a non-zero balance exist
31 Too many active ads. Limit was reached
32 Exchange rate was changed
33 Exchange daily limit was exceeded
34 Exchange internal error
35 2FA code is invalid
36 Password is invalid
61 Personal data required
281 The seller has limited the sale
282 Trade volume limit reached. KYC required.
291 Partner blocked you