Oodlebit API v1

Last Updated: January 2nd, 2020

Introduction

Welcome to the Oodlebit API v1 Documentation.

You can use the Oodlebit API to build third-party applications, such as algorithmic crypto trading bots, market monitoring tools, and more.

Authorization

The Oodlebit API server accepts calls without an API key for some endpoints while others require an API key to authenticate the request. You can create, view, and delete your API keys in your Oodlebit account settings.

When creating your API key it's very important that you only set the permissions to your planned level of activity. The following permissions are available:

  • Read - Perform information GET requests, such as market information or account balances. (RISK: 0 of 10)
  • Trade - Create orders and cancel orders. (RISK: 6 of 10)
  • Withdraw - Withdraw account balances to provided addresses. (RISK: 10 of 10)

RISK WARNING

By enabling the Trade or Withdraw permissions for your API key you are putting your assets at risk. If your secret API key is compromised, your assets could be stolen. Oodlebit Inc. will not be liable for any financial loss. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authorization is required when using an API key and is performed by creating and inserting a HMAC signature along with other parameters into the header of the request.

What is HMAC?
In cryptography, an HMAC is a specific type of message authentication code involving a cryptographic hash function and a secret cryptographic key. It simultaneously verifies both the data integrity and the authentication of a message.

How to construct your HMAC signature and send an authorized request:
  • 1. Concatenate the following parameters YourPublicKey RequestMethod RequestURL UnixTimeStamp Nonce without spaces, into a string.
    • YourPublicKey - This is the Public API that was given to you when you created your API Key.
    • RequestMethod - This is the requests method, currently our API only supports GET.
    • RequestURL - This will be the full request URL including the parameters.
    • UnixTimeStamp - This must be a CDT timezone UNIX timestamp generated at the time of the request.
    • Nonce - This can be a UNIX timestamp, GUID, or randomly generated string.
      • If concatenated correctly your string should look something like this:

      afcaaa66-bbc0-426d-b35a-c76778f32e41GEThttps://www.oodlebit.com/api/v1/getbalance?asset=BTC1565890255778195bcfda249c79c82c46462c10b39

  • 2. Generate a HMACSHA256 signature of your concatenated string using your API secret key as the hashing key.
    Javascript Example:
    
    var concatenatedString = "afcaaa66-bbc0-426d-b35a-c76778f32e41GEThttps://www.oodlebit.com/api/v1/getbalance?asset=BTC1565890255778195bcfda249c79c82c46462c10b39";

    var secretAPIKey = "Vo/fyE+LeGsgiFPgE9dXU4qvy5Yvh7+JsaknI6bWA5M=";

    var HMACsig = CryptoJS.HmacSHA256(concatenatedString, secretAPIKey);

    document.write(HMACsig);
    PHP Example:
    
    $concatenatedString = "afcaaa66-bbc0-426d-b35a-c76778f32e41GEThttps://www.oodlebit.com/api/v1/getbalance?asset=BTC1565890255778195bcfda249c79c82c46462c10b39";

    $secretAPIKey = "Vo/fyE+LeGsgiFPgE9dXU4qvy5Yvh7+JsaknI6bWA5M=";

    $HMACsignature = hash_hmac('sha256', $concatenatedString, $secretAPIKey, false);

    echo $HMACsignature;
  • 3. Join your new HMAC signature into the following string, make sure to separate every parameter with :.
    YourPublicKey:HMAC:Nonce:UNIXTimeStamp
  • 4. Send your request with the following header Auth: YourPublicKey:HMAC:Nonce:UNIXTimeStamp
  • 5. If your request is accepted the server will return a 200 OK response and Success: true.

Request Limits

To protect the integrity of our server we restrict the amount of API requests each user can send to 60 per minute, at a minimum of one request per second. Requests sent below the one second threshold will be rejected. If you exceed 60 API requests within the minute, you will be temporarily blocked until the next minute starts.

*You may request an API limit increase by contacting support.

REST API

GET /GetAssets
No Authorization Required
Read Permission

DESCRIPTION
Returns all available coin assets and their information.

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/getassets

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "AssetId": 1,
    "Name": "BTC",
    "Description": "Bitcoin"
    }
    ]
    }

GET /GetAssetPairs
No Authorization Required
Read Permission

DESCRIPTION
Returns all available asset pairs and their information.

REQUEST PARAMETERS
(optional)BaseAssetId:integer
(optional)QuoteAssetId:integer

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/getassetpairs

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "AssetPairId": 2,
    "BaseAssetId": 1,
    "QuoteAssetId": 7,
    "Name": "LTC/BTC",
    "FeePercentage": 0.00250000,
    "PricePrecision": 6,
    "AmountPrecision": 3,
    "TotalPrecision": 8
    }
    ]
    }

GET /GetAssetPairSummary
No Authorization Required
Read Permission

DESCRIPTION
Returns the last 24 hour information of the specified asset pair.

REQUEST PARAMETERS
(required)AssetPair:string
Example ETH-BTC

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/getassetpairsummary?assetpair=ETH-BTC

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "AssetPairId": 1,
    "AssetPair": "ETH/BTC",
    "High": 0.02677100,
    "Low": 0.02110400,
    "Volume": 0.0,
    "LastPrice": 0.02084400,
    "YesterdayPrice": 0.02052100,
    "BID": 0.02084300,
    "ASK": 0.02084900,
    "BuyOrders": 10,
    "SellOrders": 22,
    "PricePrecision": 6,
    "AmountPrecision": 3,
    "TotalPrecision": 8
    }
    ]
    }

GET /GetAssetPairSummaries
No Authorization Required
Read Permission

DESCRIPTION
Returns the last 24 information on all available asset pairs.

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/getassetpairsummaries

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "AssetPairId": 1,
    "AssetPair": "ETH/BTC",
    "High": 0.02677100,
    "Low": 0.02110400,
    "Volume": 0.0,
    "LastPrice": 0.02084400,
    "YesterdayPrice": 0.02052100,
    "BID": 0.02084300,
    "ASK": 0.02084900,
    "BuyOrders": 10,
    "SellOrders": 22,
    "PricePrecision": 6,
    "AmountPrecision": 3,
    "TotalPrecision": 8
    }
    ]
    }

GET /GetTicker
No Authorization Required
Read Permission

DESCRIPTION
Returns the latest ticker information for the specified asset pair.

REQUEST PARAMETERS
(required)AssetPair:string
Example ETH-BTC

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/getticker?assetpair=ETH-BTC

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "AssetPair": "ETH/BTC",
    "LastPrice": 0.02084400,
    "BID": 0.02084300,
    "ASK": 0.02084900
    }
    ]
    }

GET /GetAssetPairHistory
No Authorization Required
Read Permission

DESCRIPTION
Returns the latest trades for the specified asset pair.

REQUEST PARAMETERS
(required)AssetPair:string
Example ETH-BTC

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/getassetpairhistory?assetpair=ETH-BTC

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "ID": 1,
    "TransactionTime": "2019-07-15T11:08:06",
    "Amount": 25.00000000,
    "Price": 0.00867500,
    "Total": 0.21687500,
    "OrderType": "SELL"
    }
    ]
    }

GET /GetOrderBook
No Authorization Required
Read Permission

DESCRIPTION
Returns all open orders in the orderbooks.

REQUEST PARAMETERS
(required)AssetPair:string
Example ETH-BTC
(required)OrderType:string
Buy, sell or both

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/getorderbook?assetpair=ETH-BTC&ordertype=both

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "AssetPairId": 1,
    "OrderBookId": 1,
    "Price": 0.02084900,
    "Amount": 0.04040000,
    "IsBuyOrder": "SELL"
    }
    ]
    }

GET /CreateOrder
Authorization Required
Trade Permission

DESCRIPTION

Opens a new order in the specified asset pair. Returns UUID of the order when successful. Status: P = Open Order C = Cancelled Order F = Executed Order

You can choose to send either Amount or Total but you can not send both. Its highly recommended that you send Total when placing a Buy order, and to send Amount when placing a Sell order.

By sending Amount for a Buy order you are not guaranteed the Amount as the order will be fullfilled using a calculated Total. The Total is calculated with the following equation (Amount * (ReceivedPrice or LastPrice)). By specifying a Total in your request you are guaranteed to receive the Total minus any fees once your order fully executes.

By sending Total for a Sell order you are not guaranteed the Total as the order will be fullfilled using a calculated Amount. The Amount is calculated with the following equation (Total / (ReceivedPrice or LastPrice)). By specifying a Amount in your request you are guaranteed to receive the Amount minus any fees once your order fully executes.

Make sure Price, Amount, and Total values do not exceed the allowed decimal precision. For example, If the max allowed precision for Price is 3, a Price of x.xxxx would fail, while x.xxx would be accepted. You can retrieve these values by calling any of the GetAssetPair APIs.

REQUEST PARAMETERS
(required)AssetPair:string
Example ETH-BTC
(required)OrderPosition:string
Buy or sell
(required)OrderType:string
L = Limit M = Market R = Stop Limit S = Stop Loss
(required)Price:decimal
The price of your order.
(optional)StopPrice:decimal
Order opens when StopPrice is met - only required when ordertype = R
(optional)Amount:decimal
Amount to order.
(optional)Total:decimal
Total to order.

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/createorder?assetpair=ETH-BTC&orderposition=buy&ordertype=L&price=0.018&total=0.05

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "UUID": "1c79c61f-8547-49d6-9450-1e27456119fa"
    }
    ]
    }

GET /CancelOrder
Authorization Required
Trade Permission

DESCRIPTION
Cancels the open order of the specified UUID.

REQUEST PARAMETERS
(required)UUID:string
The UUID of the open order.

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/cancelorder?UUID=1c79c61f-8547-49d6-9450-1e27456119fa

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "UUID": "f57a42e1-9862-467d-89fd-7c48dc2f7dba"
    }
    ]

GET /GetOpenOrders
Authorization Required
Read Permission

DESCRIPTION
Returns all open orders and their information for the specified asset pair.

REQUEST PARAMETERS
(required)AssetPair:string
Example ETH-BTC

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/getopenorders?assetpair=LTC-BTC

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "UUID": "bfac5de1-2ec1-46df-95e3-fbccb3106fd9",
    "Amount": 10.00000000,
    "AssetPair": "LTC/BTC",
    "Filled": 0.0,
    "OrderDate": "2019-07-15T12:12:13",
    "Price": 0.00865000,
    "Side": "Sell",
    "Total": 0.08650000,
    "OrderRequestId": 5328,
    "Status": "P",
    "Stop": 0.00000000,
    "OrderType": "L",
    "BaseDecimals": 6
    }
    ]
    }

GET /GetOrder
Authorization Required
Read Permission

DESCRIPTION
Returns information on a specified open order based on its UUID.

REQUEST PARAMETERS
(required)UUID:string
The UUID of the open order.

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/getorder?UUID=bfac5de1-2ec1-46df-95e3-fbccb3106fd9

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "UUID": "bfac5de1-2ec1-46df-95e3-fbccb3106fd9",
    "Amount": 10.00000000,
    "AssetPair": "LTC/BTC",
    "Filled": 0.0,
    "OrderDate": "2019-07-15T12:12:13",
    "Price": 0.00865000,
    "Side": "Sell",
    "Total": 0.08650000,
    "OrderRequestId": 5328,
    "Status": "P",
    "Stop": 0.00000000,
    "OrderType": "L",
    "BaseDecimals": 6
    }
    ]
    }

GET /GetOrderHistory
Authorization Required
Read Permission

DESCRIPTION
Returns order history for the user on a specified asset pair.

REQUEST PARAMETERS
(required)AssetPair:string
Example ETH-BTC

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/getorderhistory?assetpair=ETH-BTC

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "UUID": "bfac5de1-2ec1-46df-95e3-fbccb3106fd9",
    "Amount": 10.00000000,
    "AssetPair": "LTC/BTC",
    "Filled": 0.0,
    "OrderDate": "2019-07-15T12:12:13",
    "Price": 0.00865000,
    "Side": "Sell",
    "Total": 0.08650000,
    "OrderRequestId": 5328,
    "Status": "P",
    "Stop": 0.00000000,
    "OrderType": "L",
    "BaseDecimals": 6
    }
    ]
    }

GET /GetBalances
Authorization Required
Read Permission

DESCRIPTION
Returns all wallet balances greater than zero for the user.

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/getbalances

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "AssetId": 1,
    "AssetName": "BTC",
    "Balance": 100000.54320621,
    "AvailableBalance": 99999.02715421,
    "PendingWithdrawal": 0.00000000
    }
    ]
    }

GET /GetBalance
Authorization Required
Read Permission

DESCRIPTION
Returns wallet balance information for the specified asset.

REQUEST PARAMETERS
(required)Asset:string
Example BTC

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/getbalance?asset=BTC

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "AssetId": 1,
    "AssetName": "BTC",
    "Balance": 100000.54320621,
    "AvailableBalance": 99999.02715421,
    "PendingWithdrawal": 0.00000000
    }
    ]
    }

GET /DepositAddress
Authorization Required
Read Permission

DESCRIPTION
Returns deposit wallet address for specified asset.

REQUEST PARAMETERS
(required)Asset:string
Example BTC

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/depositaddress?asset=BTC

RESPONSE EXAMPLE (200 OK):

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "DepositAddress": 1F1tAaz5x1HUXrCNLbtMDqcw6o5GNn4xqX
    }
    ]
    }

GET /Withdraw
Authorization Required
Withdraw Permission

DESCRIPTION
User can withdraw assets from their specified asset wallet.

RISK WARNING

By enabling the Withdraw permissions for your API key you are putting your assets at risk. If your secret API key is compromised, your assets could be stolen. Oodlebit Inc. will not be liable for any financial loss. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

REQUEST PARAMETERS
(required)Asset:string
The asset wallet to withdraw from. Example BTC
(required)Address:string
The address that will receive the withdrawn amount.
(required)Amount:decimal
The amount to withdraw from the asset wallet.
(required)TakeFeeAmount:bool
Take the withdrawal fee from the amount True or False.

EXAMPLE REQUEST URL:

https://www.oodlebit.com/api/v1/withdraw?asset=BTC&address=1Bpvb85nX4wGXiRDiKAHXENtNtzDE9WWyP&amount=0.037&takefeeamount=true

RESPONSE EXAMPLE (200 OK):
WithdrawAsset = asset.Name, WithdrawAmount = WithdrawalAmount, TakeFeeFromAmount = TakeFeeAmount, WithdrawToAddress = WithdrawalAddress 

    {
    "Success": true,
    "Message": "",
    "Result": [
    {
    "WithdrawAsset": BTC,
    "WithdrawAmount": 0.037,
    "TakeFeeFromAmount": true,
    "WithdrawToAddress": 1F1tAaz5x1HUXrCNLbtMDqcw6o5GNn4xqX
    }
    ]
    }

Example Code

Here you will find working code examples in multiple languages to help you get started with the Oodlebit API.

PHP

GETORDERBOOK EXAMPLE

    <?php
    //Set timezone to CDT
    date_default_timezone_set('America/Chicago');

    //Create new DateTime object
    $date = new DateTime();

    $secretAPIKey = "ENTERYOURSECRETKEY";
    $publicAPIKey = "ENTERYOURPUBLICKEY";
    $requestMethod = "GET";
    $requestURL = "https://www.oodlebit.com/api/v1/getorderbook?assetpair=ETH-BTC&ordertype=both";
    $UnixTimeStamp = $date->getTimestamp();
    $Nonce = $date->getTimestamp();

    //Join all of the values
    $concatenatedString = $publicAPIKey.$requestMethod.$requestURL.$UnixTimeStamp.$Nonce;

    //Get the HMAC signature for the concatenated string
    $HMACsignature = hash_hmac('sha256', $concatenatedString, $secretAPIKey, false);

    //Create Auth header signature
    $authSig = $publicAPIKey.":".$HMACsignature.":".$Nonce.":".$UnixTimeStamp;


    $curl = curl_init();

    //Set Request Method
    curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "GET");

    //Set Request URL
    curl_setopt($curl, CURLOPT_URL, $requestURL);

    //Add Auth Header with HMAC signature and other parameters
    curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'Auth: '.$authSig,
    'Content-Type: application/json',
    ));

    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);

    //Execute Request
    $result = curl_exec($curl);

    //Display Request Result
    echo $result;

    if(!$result){die("Connection Failure");}
    curl_close($curl);
    ?>

C#

GETORDERBOOK EXAMPLE

    public static string getHMACSha256(String data, String key)
    {
    using (HMACSHA256 hmac = new HMACSHA256(Encoding.ASCII.GetBytes(key)))
    {
    return BitConverter.ToString(hmac.ComputeHash(Encoding.ASCII.GetBytes(data))).Replace("-", "").ToLower();
    }
    }

    public static void GetOrderBook()
    {
    //URL
    const string URL = "https://www.oodlebit.com";
    //Params
    string urlParameters = "/api/v1/getorderbook?assetpair=ETH-BTC&ordertype=both";

    HttpClient client = new HttpClient();

    client.BaseAddress = new Uri(URL);
    string PublicKey = "YOURPUBLICKEY";
    var SecretKey = "YOURSECRETKEY";
    string RequestMethod = "GET";
    Int32 unixTimestamp = (Int32)(DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1))).TotalSeconds;
    Int32 Nonce = (Int32)(DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1))).TotalSeconds;

    var concatenatedString = PublicKey + RequestMethod + URL + urlParameters + unixTimestamp.ToString() + Nonce.ToString();

    var HMACsig = getHMACSha256(concatenatedString, SecretKey);

    client.DefaultRequestHeaders.TryAddWithoutValidation("Auth", PublicKey + ":" + HMACsig + ":" + Nonce.ToString() + ":" + unixTimestamp.ToString());
    client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

    HttpResponseMessage response = client.GetAsync(urlParameters).Result;
    if (response.IsSuccessStatusCode)
    {//success
    // Parse the response body.
    string result = await response.Content.ReadAsStringAsync();
    dynamic json = JsonConvert.DeserializeObject(result);
    if ((bool)json.Success)
    {
    Console.WriteLine(json.Result);
    } else
    {
    Console.WriteLine(response.StatusCode.ToString() + " " + json.Message + " " + json.Success);
    }
    }
    else //fail
    {
    Console.WriteLine("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
    }
}

Trigger Email