Crypto.bg API (beta)

General principles

Public and private endpoints

The API provides one public endpoint, returning the exchange rates for https://crypto.bg. All other endpoints are private and require authentication. The common pattern of authentication is sending an API key as a header along with the request. Some endpoints require additional submission of hashed checksum, as described below.

Example:

# sending Authentication header from command line curl:
curl -X POST http://my.url.com  -H 'Authorization: Token token="my-api-token-here"'

Note: the header syntax: the header name is Authorization; the header value is Token followed by a variable assignment token="..."

Basic URL, methods

Getting an API key

Getting exchange rates

Public crypto.bg rates

Example:

# Example request:
curl https://crypto.bg/api/v1/public_rates

# Example response
{
    "rates": {
        "bitcoin": {
            "bid": "571.328897",
            "ask": "2008.701740"
        },
        "litecoin": {
            "bid": "5.905970",
            "ask": "6.277923"
        }
    }
}

Private Client rates

Example:

# Request
 curl https://crypto.bg/api/v1/rates -H 'Authorization: Token token="my-api-token"'

# Response
{
    "rates": {
        "bitcoin": {
            "bid": "503.808209",
            "ask": "2008.701740"
        },
        "litecoin": {
            "bid": "5.728791",
            "ask": "6.277923"
        }
    }
}

Getting client information

Example:

# Request
 curl https://crypto.bg/api/v1/client -H 'Authorization: Token token="my-api-token"'

# Response
{
    "client": {
        "id": 3,
        "name": "test",
        "url": "http: //ima.net",
        "euro_rate": "1.95",
        "bitcoin_buy_margin": "3.0",
        "bitcoin_sell_margin": "3.0",
        "litecoin_buy_margin": "3.0",
        "litecoin_sell_margin": "3.0",
        "dogecoin_buy_margin": "3.0",
        "dogecoin_sell_margin": "3.0",
        "description": null,
        "created_at": "2014-09-30T21: 15: 55.542Z",
        "updated_at": "2014-09-30T21: 15: 55.542Z",
        "hedge_buy": false,
        "hedge_sell": false,
        "client_type": "merchant"
    }
}

Creating orders

Posted data structure

The posted JSON object has the following structure: order as a root element, then the data subset containing the order parameters, then the checksum entry and finally the optional merchant_attributes subset.

Example JSON data:

{
    "order": {
        "data": {
            "buy_sell": "buy",
            "blockchain": "bitcoin",
            "sum_levs": "30",
            "payment_method": "epay",
            "email": "ima@nema.net",
            "user_address": "1HRFjhvtpxftxzj6BycEBRFfpWvW1WH777"
        },
        "checksum": "182b9b0320b0e1912d06a88620002e37720e7637",
        "merchant_attributes": {
            "atr1": "val1",
            "attr2": "vall2"
        }
    }
}

Parameters

Mandatory parameters

Checksum generation

To generate the control checksum, follow the steps:

  1. Construct a string consisting of the following parameters, separated by semicolon (no spaces): api_key, email, buy_sell, sum_coins or sum_levs (depending on the order type)
  2. Execute a HMAC sha1 hashing of this string, encoded with your data key
  3. The resulting hash is your control checksum string that you should include in your request

Example string

# Raw string
string = "37891471897dycuhf818f4831:my@email.com:buy:0.18"

# Encoding the string in Ruby:
client_data_key = "4r98cu1f891u4958u"
checksum = OpenSSL::HMAC.hexdigest('sha1', client_data_key, string) #=> "20263128e7931d55d05eb74c25a5fbe35513e0d3"

Constructing the request:

With all elements combined, an order creation request will look similar to this:

curl -X POST https://crypto.bg/api/v1/order
  -H 'Authorization: Token token="my-api-token-here"'
  -d '{"order":{"data": {"buy_sell": "buy", "blockchain": "bitcoin",
  "sum_levs": "30", "payment_method": "epay", "email": "ima@nema.net",
  "user_address": "1HRFjhvtpxftxzj6BycEBRFfpWvW1WH777"}, "checksum":
  "182b9b0320b0e1912d06a88620002e37720e7637", "merchant_attributes":
  {"atr1": "val1", "attr2": "vall2"}}}' -H "Content-Type: application/json"

Simple Merchant Integration Use Case

A typical implementation of our API is for merchants, who want to receive bitcoin payments from their customers. The flow in this case goes like this:textile the customer makes bitcoin payment to us, based on an order the merchant has created programmatically in our system through the API, we process the received bitcoin payment on behalf of the merchant and pay the merchant the due amount depending on the contract arrangements.

The steps to follow in this case are as follows:

Example:

{
    "order": {
        "data": {
            "buy_sell": "sell",
            "sum_levs": "10",
            "email": "ima@nema.net"
        },
        "checksum": "843dfc50445a98c217358de60b7b2dd2f254bfc5",
        "merchant_attributes": {
          "attr1": "val1",
          "attr2": "val2"
        }
    }
}

Returned JSON order object

Upon a successful order creation, a JSON object of the newly created order is returned. Otherwise a JSON error message is returned. The returned attributes are as follows:

Always returned

Returned when type is "buy"

Returned when type is "sell"

Еxample response when creating a sell order

# Response
{
    "order": {
        "id": "1b4256",
        "status": "new",
        "buy_sell": "sell",
        "blockchain": "bitcoin",
        "sum_coins": "0.1019",
        "sum_levs": "55.0",
        "user_address": "",
        "transaction_id": "",
        "payment_method": "epay",
        "merchant_address": "1LCA7GmhdELhrLXRGTM3PhQGbDa8m2erk7"
    },
    "merchant_attributes": {
      "attr1": "val1",
      "attr2": "val2"
    }
}

Getting order details

Example

# Request
curl https://crypto.bg/api/v1/order/1b4859 -H 'Authorization: Token token="my-api-token"'

# Response
{
    "order": {
        "id": "1b4256",
        "status": "finalized",
        "buy_sell": "buy",
        "blockchain": "bitcoin",
        "sum_coins": "0.1019",
        "sum_levs": "55.0",
        "user_address": "1LCA7GmhdELhrLXRGTM3PhQGbDa8m2erk7",
        "transaction_id": "7dba6943461a9ac557bc73a0214817caf2170edf7ec3ed97d7ad86ea74c448cb",
        "payment_method": "atm",
        "merchant": "60000",
        "epay_code": "8285829282"
    },
    "merchant_attributes": {
      "attr1": "val1",
      "attr2": "val2"
    }
}

Orders scoped per client

Example

# Request
curl https://crypto.bg/api/v1/client/orders -H 'Authorization: Token token="my-api-key"'

# Response
{
    "orders": {
        "order": {...}

    }
}

Creating customer numbers

Posted data structure

The posted JSON object has the following structure: customer_data as a root element, then the mandatory fields of the email and bitcoin_address values and an optional field foreign_key to enable associating our number record with a customer record in the remote application

Example JSON data:

{
    "customer_data": {
        "email": "your_email@here.com",
        "bitcoin_address": "your_btc_address_here",
        "foreign_key": "some_foreign_id"
    }
}

Parameters

Constructing the request:

With all elements combined, an customer number generation request will look similar to this:

curl -X POST https://crypto.bg/api/v1/create_customer_number
  -H 'Authorization: Token token="my-api-token-here"'
  -d '{"customer_data": {"email": "my@email.com",
    "bitcoin_address": "1CUyH1sdrM1xeL18YSNpsVGheJFsSJghn2",
    "foreign_key": "some_foreign_id"}}'
  -H "Content-Type: application/json"

A successful request will result in a repsonse containing the generated customer number and the associated email and bitcoin_address fields:

{"customer_number": {"value": "123456789", "bitcoin_address": "1CUyH1sdrM1xeL18YSNpsVGheJFsSJghn2", "email": "i_have@email.com", "foreign_key": "your-foreign-key"}}

Whenever JSON or data errors are detected in the request, an error response will be returned, such as:

{"error": {"message": "Invalid request"}}
{"error": {"message": "Invalid crypto address"}}
{"error": {"message": "Invalid email"}}

Creating customer bitcoin addresses

Posted data structure

The posted JSON object has the following structure: customer_data as a root element, then the mandatory fields of the email and payout_method values and an optional field foreign_key to enable associating our address record with a customer record in the remote application. Each payout method has specific required fields:

Example JSON data:

{
    "customer_data": {
        "email": "your_email@here.com",
        "payout_method": "epay",
        "epay_kin": "123456789",
        "foreign_key": "some_foreign_id"
    }
}

{
    "customer_data": {
        "email": "your_email@here.com",
        "payout_method": "easypay",
        "name": "My Name",
        "egn": "7001052312",
        "foreign_key": "some_optional_foreign_id"
    }
}

Parameters

Constructing the request:

With all elements combined, an customer number generation request will look similar to this:

curl -X POST https://crypto.bg/api/v1/create_customer_bitcoin_address
  -H 'Authorization: Token token="my-api-token-here"'
  -d '{"customer_data": {"email": "ima@nema.net", "payout_method": "easypay",
        "egn": "7506079999", "name": "My name", "foreign_key": "test key",
        "epay_kin": "123456789"}}'
  -H "Content-Type: application/json"

A successful request will result in a repsonse containing the generated customer number and the associated email and bitcoin_address fields:

{"customer_bitcoin_address": {"bitcoin_address": "mgSYHJHqtmPtAhYuJWy5hEFSfzo467o5fT", "payout_method": "easypay", "name": "My name", "email": "ima@nema.net","egn": "7506079999","epay_kin": "123456789", "foreign_key": "test key"}}

Whenever JSON or data errors are detected in the request, an error response will be returned, such as:

{"error": {"message": "Invalid request"}}
{"error": {"message": "Invalid payout method: possible values are: epay, easypay"}}
{"error": {"message": "Epay KIN is required for epay payouts"}}
{"error": {"message": "Name and EGN are required for easypay payouts"}}

Powered by Crypto.bg