Seven Seas

Info

Seven Seas Exchange API Documentation

Welcome to the Seven Seas Exchange API documentation. This API allows you to access and interact with various features of the exchange, such as account management, order creation, and market data.

Base URL: https://www.sevenseas.exchange/api/v1

Seven Seas Exchange API Documentation

API Endpoints (Public)

Markets

Get all markets Endpoint: /markets

Method: GET

Response:

[
  {
    "symbol": "BTC-USDT",
    "lastPrice": 28060.12,
    "priceYesterday": 27801.01,
    "high": 28114.12,
    "low": 27445.62,
    "volume": 7441.68334201
  },
  ...
]

Curl Example

curl https://www.sevenseas.exchange/api/v1/markets

JavaScript Example

const ssx_url = "https://www.sevenseas.exchange/api/v1/";

const fetchMarkets = async () => {
  try {
    const response = await fetch(`${ssx_url}/markets`);
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error("Error fetching market data:", error);
  }
};

fetchMarkets();

Python Example

import requests
api_url = 'https://www.sevenseas.exchange/api/v1'

def fetch_markets():
    try:
        response = requests.get(f'{api_url}/markets')
        data = response.json()
        print(data)
    except Exception as error:
        print("Error fetching market data:", error)

fetch_markets()

Market

Get specific market Endpoint: /markets/[base-quote]

Method: GET

e.g /markets/BTC-USDT

Response:

{
  "symbol": "BTC-USDT",
  "lastPrice": 28060.12,
  "priceYesterday": 27801.01,
  "high": 28114.12,
  "low": 27445.62,
  "volume": 7441.68334201
}

Curl Example

curl https://www.sevenseas.exchange/api/v1/markets/BTC-USDT

Trade History

Get trade history for a market Endpoint: /history/[base-quote]

Method: GET

e.g /history/BTC-USDT

Response:

[
  [
    { "price": 28060.12, "quantity": 0.00049098, "side": "sell", "time": 1679447395274 },
    { "price": 28062.2, "quantity": 0.00049316, "side": "sell", "time": 1679440888294 },
    { "price": 28114.12, "quantity": 0.00050398, "side": "sell", "time": 1679402951724 },
    { "price": 27974.79, "quantity": 0.00050458, "side": "sell", "time": 1679402003913 },
    { "price": 27935.11, "quantity": 0.00050212, "side": "sell", "time": 1679398170334 },
    { "price": 27985.94, "quantity": 0.00050253, "side": "sell", "time": 1679396054651 },
    { "price": 27993.02, "quantity": 0.00050471, "side": "sell", "time": 1679395964615 },
    { "price": 27982.61, "quantity": 0.00049394, "side": "sell", "time": 1679395933611 },
    { "price": 27986.32, "quantity": 0.00000177, "side": "sell", "time": 1679395933611 },
    { "price": 27992.97, "quantity": 0.00002121, "side": "sell", "time": 1679395874309 }
    ...
  ]
]

Curl Example

curl https://www.sevenseas.exchange/api/v1/history/BTC-USDT

Order Book

Get order book for a market Endpoint: /orders/[base-quote]

Method: GET

e.g /orders/BTC-USDT

Response:

{
  "asks": {
    "29327.865": 0.00009192,
    "29331.8655": 0.00009676,
    "29344.329": 0.00010833,
    "29373.5295": 0.00009248,
    "29457.75": 0.00010666,
    ...
  },
  "bids": {
    "26532.9395": 0.00010782,
    "26534.735": 0.000196959,
    "26538.3545": 0.0000964,
    "26538.6395": 0.00019399,
    "26548.548": 0.00010714,
    ...
  }
}

Curl Example

curl https://www.sevenseas.exchange/api/v1/orders/BTC-USDT

Private API

In order to access the private endpoints, you will need to generate an API key and secret. You can do this by going to your account and clicking on generate api keys.

Signing Requests

To access private API endpoints, you need to sign requests with your API key and secret. Below is an example signAndFetchRequest function that generates the required headers for authentication and uses fetch. This function will be referenced in the examples that follow.

In the following examples, the signAndFetchRequest function lives in a file called ssxutils.js and is referenced with ssxutils = require("./ssxutils.js");

ssxutils.js

const CryptoJS = require("crypto-js");

const SEVEN_SEAS_API_KEY = process.env.SSX_API_KEY || "your-api-key";
const SEVEN_SEAS_SECRET_KEY = process.env.SSX_API_SECRET || "your-api-secret";

async function signAndFetchRequest(method, uri, body = "") {
  const contentHash = CryptoJS.SHA512(body).toString(CryptoJS.enc.Hex);
  const timestamp = Date.now();
  const preSign = [timestamp, uri, method].join("");
  const signature = CryptoJS.HmacSHA512(preSign, SEVEN_SEAS_SECRET_KEY).toString(CryptoJS.enc.Hex);

  let response;

  if (method === "GET") {
    const preSign = [timestamp, uri, method].join("");
    const signature = CryptoJS.HmacSHA512(preSign, SEVEN_SEAS_SECRET_KEY).toString(CryptoJS.enc.Hex);
    response = await fetch(`${uri}`, {
      method,
      headers: {
        "api-key": SEVEN_SEAS_API_KEY,
        "api-timestamp": timestamp.toString(),
        "api-signature": signature,
      },
    });
  } else if (method === "POST") {
    console.log("body:", body);
    const contentHash = CryptoJS.SHA512(body).toString(CryptoJS.enc.Hex);
    const preSign = [timestamp, uri, method, contentHash].join("");
    const signature = CryptoJS.HmacSHA512(preSign, SEVEN_SEAS_SECRET_KEY).toString(CryptoJS.enc.Hex);
    response = await fetch(`${uri}`, {
      method,
      headers: {
        "api-key": SEVEN_SEAS_API_KEY,
        "api-timestamp": timestamp.toString(),
        "api-signature": signature,
        "api-content-hash": contentHash,
        "Content-Type": "application/json",
      },
      body,
    });
  } else {
    console.error("Unsupported method:", method);
    return;
  }

  if (response.ok) {
    return data;
  } else {
    console.error("Error Code:", response.status);
    console.log(data.error);
  }
}

module.exports = {
  signAndFetchRequest: signAndFetchRequest,
};

API Endpoints (Private)

Fetch Account Balance

Description

Fetch the account balance for a specific currency.

Endpoint

GET /account/balance/[currency]

Parameters currency: The currency ticker (e.g., "BTC").

Response

{
  "holding": 0.0001,
  "locked": 0
}

Example:

/account/balance/btc

const ssxutils = require("./ssxutils.js");

async function fetchAccountBalance(currency) {
  const method = "GET";
  const endpoint = `/account/balance/${currency}`;
  const uri = `${BASE_URL}${endpoint}`;

  const data = await ssxutils.signAndFetchRequest(method, uri);
  console.log(`${currency} balance:`, data);
  return data;
}

(async () => {
  const currency = "BTC";
  const { holding, locked } = await fetchAccountBalance(currency);
  console.log(`${currency} holding: ${holding}`); //e.g. BTC holding: 0.0001
  console.log(`${currency} locked: ${locked}`); //e.g. BTC locked: 0
})();

Fetch Account Balances

Description

Fetch the account balances for all currencies.

Endpoint

GET /account/balances

Returns

balances: {
    XMR: '{"holding":0,"locked":0}',
    BTC: '{"holding":0.0001,"locked":0}',
    LTC: '{"holding":0.03508136,"locked":0}',
    ETH: '{"holding":0.0542,"locked":0}',
    USDT: '{"holding":0,"locked":0}',
    ...
  }

Example:

/account/balances

async function fetchAccountBalances() {
  const method = "GET";
  const endpoint = `/account/balances`;
  const uri = `${BASE_URL}${endpoint}`;

  const data = await ssxutils.signAndFetchRequest(method, uri);
  return data;
}

(async () => {
  const { balances } = await fetchAccountBalances();
  //Example: Get BTC holding and locked amounts
  const { holding: btcHolding, locked: btcLocked } = JSON.parse(balances.BTC);
  console.log(`btcHolding = ${btcHolding}`); // btcHolding = 0.0001
  console.log(`btcLocked = ${btcLocked}`); // btcLocked = 0
})();

Create Order

Create a new order for a specific market.

Endpoint

POST /create_order

Body Parameters

market: The market identifier (e.g., "BTC-ETH").
side: The order side ("buy" or "sell").
price: The price at which the order should be executed.
quantity: The amount of the asset to be traded.

Returns

If the order is not or partially fulfilled: {orderId: "c4e95480-23aa-4ebe-a2e8-07e4e386132", fulfilled: false}

If the order is completely fulfilled: {fulfilled: true}

If the order creation fails: {error: "some error message"}

Example:

async function createOrder(market, side, price, quantity) {
  const method = "POST";
  const endpoint = `/create_order`;
  const uri = `${BASE_URL}${endpoint}`;

  const body = JSON.stringify({
    market,
    side,
    price,
    quantity,
  });

  const data = await ssxutils.signAndFetchRequest(method, uri, body);
  return data;
}

(async () => {
  const market = "ETH-BTC";
  const side = "buy";
  const price = 0.01;
  const quantity = 0.01;

  const order = await createOrder(market, side, price, quantity);
  console.log("Order created:", order); // { fulfilled: false, orderId: 'c4e95480-23aa-4ebe-a2e8-07e4e386132' }
  console.log(order);
})();

Get All Orders

Description

Retrieve all orders.

Endpoint

GET /account/orders

Returns

{
    id: 'c4e95480-23..-4e....-07.....349',
    side: 'buy',
    marketSymbol: 'ETH-BTC',
    price: 0.01,
    quantity: 0.01,
    filled: 0,
    userId: 'auth0|...',
    createdAt: 1679540851559
  },
  ...

Example

async function getAllOrders() {
  const method = "GET";
  const endpoint = `/account/orders`;
  const uri = `${BASE_URL}${endpoint}`;

  const data = await ssxutils.signAndFetchRequest(method, uri);
  return data;
}

(async () => {
  const orders = await getAllOrders();
  console.log("All orders:", orders);
})();

Get All Orders for Market

Description

Retrieve all orders for a specific market.

Endpoint

GET /account/orders/[market]

Parameters

market: The market identifier (e.g., "BTC-ETH").

Returns:

{
    id: 'c4e95480-23..-4e....-07.....349',
    side: 'buy',
    marketSymbol: 'ETH-BTC',
    price: 0.01,
    quantity: 0.01,
    filled: 0,
    userId: 'auth0|...',
    createdAt: 1679540851559
  },
  ...

Exmaple:

async function getAllOrdersForMarket(market) {
  const method = "GET";
  const endpoint = `/account/orders/${market}`;
  const uri = `${BASE_URL}${endpoint}`;

  const data = await ssxutils.signAndFetchRequest(method, uri);
  return data;
}

(async () => {
  const market = "BTC-ETH";
  const orders = await getAllOrdersForMarket(market);
  console.log(`All orders for ${market}:`, orders);
})();

Get Specific Order

Description

Retrieve a specific order by ID.

Endpoint

GET /account/orders/[id]

Parameters

id: The order identifier.

Returns

{
  "id": "c4e95480-23ff-4ebe-a2e8-07e4e5c03349",
  "side": "buy",
  "marketSymbol": "ETH-BTC",
  "price": 0.01,
  "quantity": 0.01,
  "filled": 0,
  "userId": "auth0|640acb7c37574ab8d6da8697",
  "createdAt": 1679540851559
}

Example:

async function getOrderById(id) {
  const method = "GET";
  const endpoint = `/account/order/${id}`;
  const uri = `${BASE_URL}${endpoint}`;

  const data = await ssxutils.signAndFetchRequest(method, uri);
  return data;
}

(async () => {
  const id = "your-order-id";
  const order = await getOrderById(id);
  console.log("Order:", order);
})();

Cancel an Order

Description

Cancel a specific order by ID.

Endpoint

POST /cancel_order

Body Parameters

id: The order identifier. To cancel all orders, set id to ALL.

Returns

{success: boolean, error: string}

Example:

async function cancelOrder(orderId) {
  const method = "POST";
  const endpoint = `/cancel_order`;
  const uri = `${BASE_URL}${endpoint}`;

  const body = JSON.stringify({
    orderId,
  });

  const data = await ssxutils.signAndFetchRequest(method, uri, body);
  return data;
}

(async () => {
  const orderId = "your-order-id";
  const result = await cancelOrder(orderId);
  console.log("Order cancellation result:", result);
})();

Seven Seas Exchange API Documentation

Table of Contents

API Endpoints (Public)

Markets

Curl Example

JavaScript Example

Python Example

Market

Curl Example

Trade History

Curl Example

Order Book

Curl Example

Private API

Signing Requests

ssxutils.js

API Endpoints (Private)

Fetch Account Balance

Fetch Account Balances

Create Order

Get All Orders

Get All Orders for Market

Get Specific Order

Cancel an Order