SatoExchange Private Account API

(Last Updated: 1 Dec 2019)

INTRODUCTION

This API reference includes technical documentation needed to query private account data and trigger actions on your account like trading activities and wallet activities like deposit and withdrawal will also be supported shortly with full backwards compatibility.

SUMMARY

The account API endpoints are POST request endpoints and are intended to allow access to private account data, trading and wallet activities. Endpoints receives and return results strictly in the JSON-RPC 2.0 standards receiving and returning data in JSON format with a content type header of application/json.

To place trade orders you might need to know the market information to add as parameters from the market api section v1 or v3.

STANDARDS AND CONVENTIONS

1. API authentication is required on all requests to all endpoints by your API key.
2. Member can create, revoke, delete and generate new API keys anytime they want or for security reasons from their account page https://www.satoexchange.com/account/ Note: Always ensure maximum security for your API keys as they give access to your account.
3. Members specify the access levels and activities that can be performed on their accounts by their API keys.
4. Endpoints are available always and we may implement rate-limiting later if abuse is discovered.
5. Data available in JSON format
6. Versioning required to avoid breaking changes and this version is v2 (/api/v2)
   
7. Content encoding: gzip supported for optimized data transfer.
8. No region-blocked API endpoints.

TOOLS

Instead of writing complex boilerplate codes to send authenticated requests to the API server, our team and volunteers will constantly release libraries and API kits for different languages to access the API endpoints with JSON-RPC standards and with authentications seamlessly.

Both the request structures and the use of the available libraries will be contained on this page. However we may not cover fully all the documentation for all tools especially library's written by third parties, but we will try as much as we can to keep a link to every tool documentation on this page.

ENDPOINT

All requests are JSON RPC standard requests to https://www.satoexchange.com/api/v2

AUTHENTICATION

Every request must be authenticated and there are 3 parameters required for authentication:

    The account username

    The request timestamp

    And the auth token (we will see how to generate this shortly)

Example JSON-RPC request:

{"jsonrpc": "2.0", "method": "balances", "params": {"username":"user_username","timestamp":1575378667,"auth":"YOUR_AUTH_TOKEN_HERE"}, "id": 1}

Example if you need to get your account deposit address for BTC:

{"jsonrpc": "2.0", "method": "deposit", "params": {"username":"user_username","timestamp":1575378667,"auth":"YOUR_AUTH_TOKEN_HERE","coin":"BTC"}, "id": 1}

Note: The parameter coin was added in the same scope as other auth parameters and value BTC was supplied as the value.

This is the convention all api parameters follow except few other parameters that are expected to be an object have key-value pairs of its own.

Example of such parameters are filters in queries that return list like orders or trade histories.

The filter parameter may look like:

{"jsonrpc": "2.0", "method": "account_trade_history", "params": {"username":"user_username","timestamp":1575378667,"auth":"YOUR_AUTH_TOKEN_HERE","filter":{"market_id":24}}, "id": 1}

Note that the filter parameter has a key market_id which specifies the market for which trade history should be returned.

AUTH TOKEN:

The auth token is part of the 3 parameters required for authentication which have to be supplied in all requests.  The auth token is generated from your API key.

Auth token is the sha256 hash of your  username + Api key + request method + timestamp

A simple JavaScript example will look like:

const auth = sha256(username + apiKey + method + timestamp.toString()); //using the js-sha256 package

Where method is the request method (example account_trade_history).

API Methods and Parameters

Going forward, we will keep off the JSON-RPC boiler plates and just provide details on the method and parameters need to complete requests to each available method endpoint available assuming that you are familiar with the JSON-RPC 2.0 standards.

We will be doing this providing information about the methods and parameters and additionally with the SatoExchange JSONRPC JavaScript Client API (github.com/satoexchange/satoexchange-rpc-api-client)

SatoExchange JSONRPC JavaScript Client API

SatoExchange JavaScript client is easily initialized:

Initializing the SatoClient Library:

Require the npm satoexchange-rpc-api-client package to your workload:

$> npm i satoexchange-rpc-api-client

Use the library:

var SatoClient = require("satoexchange-rpc-api-client").SatoClient;
var satoClient = new SatoClient('username','API_KEY');
satoClient.account_orders({})
.then(function (response) {
    console.log(response.data);
})
.catch(function (error) {
    console.log(error);
});

Account Orders

Method: account_orders

Params:

JavaScript

satoClient.account_orders({ market: "SATX/BTC" })
    .then(function(response) {
        console.log(response.data);
    })
    .catch(function(error) {
        console.log(error);
    });

Sample Result

{
    jsonrpc: "2.0",
    id: 1,
    result: {
        orders: [
            {
                id: "576189",
                created_date: "2019-11-10 09:22:47",
                price: "0.00000008",
                amount: "97653.00000000",
                total: "0.00781224",
                fee: "0.00001562",
                net_total: "0.00782786",
                type: "buy",
                slug: "SATX/BTC"
            },
            ...
        ]
    }
}

satoClient.account_trade_history({
    filter: {
      market_id: 1,
      type: "sell"
    },
    limit: 5,
    sort_dir: "ASC"
  })
  .then(function(response) {
    console.log(response.data);
  })
  .catch(function(error) {
    console.log(error);
  });

{
  jsonrpc: "2.0",
  id: 1,
  result: {
    trades: [
      {
        id: "64",
        market_id: "1",
        type: "sell",
        buyer_id: "1",
        seller_id: "7778",
        buy_order_id: "111",
        sell_order_id: "709",
        created_date: "1531723034",
        chart_hour: "2018-07-16 06:00",
        amount: "0.00100000",
        total: "0.00010000",
        price: "0.10000000",
        fee: "0.00000040",
        active: "0",
        slug: "BCH/BTC",
        base_coin: "BTC",
        alt_coin: "BCH",
        base_name: "Bitcoin",
        alt_name: "Bitcoin Cash",
        actual_type: "Buy",
        net_total: "0.00010040"
      },
      ...
    ],
    limit: 5,
    page: 1,
    pages_count: 1,
    order_by: "created_date",
    sort_dir: "ASC",
    filter: { market_id: 1, type: "sell" }
  }
}

Account Balances

Method: balances

Params:

JavaScript Example 1

satoClient.balances({
    include_zero_balances: false
  })
  .then(function(response) {
    console.log(response.data);
  })
  .catch(function(error) {
    console.log(error);
  }); 

Example 2

satoClient.balances({
    coin: "BTC"
  })
  .then(function(response) {
    console.log(response.data);
  })
  .catch(function(error) {
    console.log(error);
  });

Example 1 result

{
  jsonrpc: "2.0",
  id: 1,
  result: [
    {
      user_id: "1",
      coin_id: "94",
      amount: "975963.42794293",
      name: "Helenex",
      symbol: "HELX",
      id: "94",
      last_price: "0.00000146",
      buy_order_held: 0,
      sell_order_held: 0,
      order_held: "0.00000000",
      available: "975963.42794293",
      btc_value: 1.4249066047966779
    },
    ...
  ]
}

Example 2 result

{
  jsonrpc: "2.0",
  id: 1,
  result: {
    id: "1180",
    user_id: "1",
    coin_id: "1",
    amount: "0.016648288371310743",
    buy_order_held: "0.010881680000000001",
    sell_order_held: 0,
    stop_loss_held: 0,
    available: 0.005766608371310742,
    stop_loss_available: 0.016648288371310743
  }
}

Deposit

This endpoint returns the deposit address for a particular coin and the coin parameter is mandatory.

Method: deposit

Params:

JavaScript

satoClient.deposit({
    coin: "XRP"
  })
  .then(function(response) {
    console.log(response.data);
  })
  .catch(function(error) {
    console.log(error);
  });

Sample Result

{
  jsonrpc: "2.0",
  id: 1,
  result: {
    wallet: {
      id: "9",
      coin_id: "9",
      address: "rw2ciyaNshpHe7bCHo4bRWq6pqqynnWKQg:::ucl:::2434000991",
      symbol: "XRP"
    }
  }
}

In the case of XRP and some other wallet address that needs memo/payment id, they may be attached to the address with delimeters.

satoClient.get_currencies({})
  .then(function(response) {
    console.log(response.data);
  })
  .catch(function(error) {
    console.log(error);
  });

{
  jsonrpc: "2.0",
  id: 1,
  result: {
    currencies: [
      {
        id: "1",
        name: "Bitcoin",
        symbol: "BTC",
        is_erc20: false,
        token_address: ""
      },
      ...
    ],
    order_by: "id",
    sort_dir: "ASC"
  }
}

satoClient.get_market_history({ market_id: 1, limit: 10 })
  .then(function(response) {
    console.log(response.data);
  })
  .catch(function(error) {
    console.log(error);
  });

{
  jsonrpc: "2.0",
  id: 1,
  result: {
    market: {
      id: "1",
      slug: "BCH/BTC",
      last_price: "0.28899794",
      high: "0",
      low: "0",
      ask: "0.04500000",
      bid: "0.01600000",
      growth: "0",
      volume: "0.00000000",
      date_listed: "2018-05-31 14:55:51"
    },
    history: [
      {
        created_date: "2019-05-16 05:51:20",
        type: "buy",
        price: "0.28899794",
        amount: "0.00014455",
        total: "0.00004177"
      },
      ...
    ],
    limit: 2,
    page: 1,
    pages_count: 146
  }
}

satoClient.get_market_orders({ market_id: 1})
  .then(function(response) {
    console.log(response.data);
  })
  .catch(function(error) {
    console.log(error);
  });

{
  jsonrpc: "2.0",
  id: 1,
  result: {
    market: {
      id: "1",
      slug: "BCH/BTC",
      last_price: "0.28899794",
      high: "0",
      low: "0",
      ask: "0.04500000",
      bid: "0.01600000",
      growth: "0",
      volume: "0.00000000",
      date_listed: "2018-05-31 14:55:51"
    },
    buy_orders: [
      { price: "0.01600000", amount: "0.01015525", total: "0.00016248" },
      { price: "0.01050001", amount: "0.03969425", total: "0.00041679" }
    ],
    sell_orders: [
      { price: "0.16999000", amount: "0.00718092", total: "0.00122068" },
      { price: "0.26999000", amount: "0.01000000", total: "0.00269990" },
      { price: "0.27654321", amount: "0.00192879", total: "0.00053339" }
    ],
    limit: 100,
    page: 1,
    pages_count: 1
  }
}

satoClient.get_markets({ action: "search", search_q: "XRP" })
  .then(function(response) {
    console.log(response.data);
  })
  .catch(function(error) {
    console.log(error);
  });

{
  jsonrpc: "2.0",
  id: 1,
  result: {
    search_q: "XRP",
    markets: [
      {
        id: "4",
        slug: "XRP/BTC",
        last_price: "0.00003797",
        date_listed: "2018-05-31 14:55:52"
      },
      {
        id: "31",
        slug: "XRP/ETH",
        last_price: "0.00689999",
        date_listed: "2018-05-31 14:55:53"
      },
      {
        id: "86",
        slug: "XRP/DOGE",
        last_price: "150.00000000",
        date_listed: "2018-05-31 14:55:58"
      },
      {
        id: "116",
        slug: "XRP/SATX",
        last_price: "75.00000000",
        date_listed: "2018-09-11 05:43:05"
      }
    ],
    order_by: "id",
    sort_dir: "ASC"
  }
}

satoClient.order({
    action: "buy",
    market: "DASH/BTC",
    price: 0.001,
    amount: 0.1
  })
  .then(function(response) {
    console.log(response.data);
  })
  .catch(function(error) {
    console.log(error);
  });

{
  jsonrpc: "2.0",
  id: 1,
  result: {
    new_order: {
      type: "buy",
      user_id: "1",
      market_id: "2",
      stake_coin_id: "1",
      created_date: "2019-12-08 20:16:30",
      initial_amount: 0.1,
      amount: 0.1,
      price: 0.001,
      total: "0.00010000",
      fee: "0.00000020",
      net_total: "0.00010020",
      status: "open",
      id: 588150,
      display_type: "Buy",
      class: "success"
    }
  }
}

satoClient.order({
    action: "get_order",
    order_id: 112211,
  })
  .then(function(response) {
    console.log(response.data);
  })
  .catch(function(error) {
    console.log(error);
  });

{
    jsonrpc: "2.0"
    id: 1
    result: {
        order_data: {
            id: "1987310"
            type: "sell"
            market_id: "403"
            initial_amount: "8333.33333333"
            price: "0.06000000"
            total: "-0.3499999998000476"
            status: "completed"
            market: "SATX/USDT"
            remaining_amount: "0.00000000"
        }
    }
}

SatoExchange Market Data API (CMC spec)

(Last Updated: 7 Oct 2019)

INTRODUCTION

This API reference includes technical documentation needed to to query market and assets data on SatoExchange and it fully adhere to the Coin Market Cap (CMC) standards seen on https://docs.google.com/document/d/1S4urpzUnO2t7DmS_1dc4EL4tgnnbTObPYXvDeBnukCg/mobilebasic.

SUMMARY

The public GET request endpoints are intended to allow access to market data. Endpoints return results in JSON format. Referenced in the /assets and /ticker endpoints is a Unified Cryptoasset ID (UCID). Please view this page for more information on the UCID.

STANDARDS AND CONVENTIONS

1. No API authentication required on market endpoints.
2. Full market queries available every 60 seconds.
3. Data available in JSON format
4. Versioning required to avoid breaking changes and this version is v3 (api/v3/asset, api/v3/asset, etc.)
5. Content encoding: gzip supported for optimized data transfer.
6. No region blocked API endpoints.

ENDPOINT OVERVIEW

All requests have root api link https://www.satoexchange.com/api/v3/

ENDPOINT 1

ASSETS   https://www.satoexchange.com/api/v3/assets

The assets endpoint is to provide a detailed summary for each currency available on the exchange.

{  

   "BTC":{  

      "name":"Bitcoin",

      "unified_cryptoasset_id" :"1",

      "can_withdraw":"true",

      "can_deposit":"true",

      "min_withdraw":"0.01",

      "max_withdraw ":"100"

      "name":"bitcoin",

      "maker_fee":"0.01",

      "taker_fee":"0.01",

   },

   "ETH":{  

      "name":"Ethereum",

      "unified_cryptoasset_id":"1027",

      "can_withdraw":"false",

      "can_deposit":"false",

      "min_withdraw":"10.00",

      "max_withdraw ":"0.00"

      "maker_fee":"0.01",

      "taker_fee":"0.01",

   }

}

Assets response descriptions.

ENDPOINT 2

TICKER   https://www.satoexchange.com/api/v3/ticker

The ticker endpoint is to provide a 24-hour pricing and volume summary for each market pair available on the exchange.

{  

   "BTC_USDT":{  

      "base_id":"1",

      "quote_id":"825",

      "last_price":"10000",

      "quote_volume":"20000",

      "base_volume":"2",

      "isFrozen":"0"

   },

   "LTC_BTC":{  

      "base_id":"2",

      "quote_id":"1",

      "last_price":"0.00699900",

      "base_volume":"20028,526",

      "quote_volume":"279594",

      "isFrozen":"0"

   }

}

Ticker response descriptions.

ENDPOINT 3

ORDERBOOK   https://www.satoexchange.com/api/v3/orderbook/market_pair

The order book endpoint is to provide a complete level 2 order book (arranged by best asks/bids) with full depth returned for a given market pair.

Parameters:

{  

   "timestamp":"1566359163",

   "bids":[  

      [  

         "12462000",

         "0.04548320"

      ],

      [  

         "12457000",

         "3.00000000"

      ]

   ],

   "asks":[  

      [  

         "12506000",

         "2.73042000"

      ],

      [  

         "12508000",

         "0.33660000"

      ]

   ]

}

Order book response descriptions.

ENDPOINT 4

TRADES   https://www.satoexchange.com/api/v3/trades/market_pair

The trades endpoint is to return data on all recently completed trades for a given market pair.

Parameters:

[  

   {        

      "tradeID":3523643,

      "price":"0.01",

      "base_volume":"569000",

      "quote_volume":"0.01000000",

      "trade_timestamp":"1566360780",

      "type":"sell"

   }

]

Trades response descriptions.