Introduction

Welcome to the Cape Crypto API Documentation. You can use our full API suite to integrate with us.

Create and cancel orders, view your account balance, stream orderbook and account updates over websocket, and perform all other actions you can perform from the apps.

🚀 Looking for trading features that we haven't added yet? We'll add them for you! Reach out to us

Looking for a Hummingbot connector for Cape Crypto? We have one! Reach out to us

Getting started

The API suite consists of public and private endpoints. Private endpoints require your requests to be signed for authentication. In order to sign your requests, you will need to create and API key and secret, and have 2FA enabled:

1. Sign into your account Cape Crypto
2. Head to the Profile page by clicking the profile icon at the top right
3. Enable 2FA
4. Create a new API key
5. Save your new API key and Secret and do not share it with anyone

Use your API key and secret to sign your requests for all private endpoints. (Public endpoints do not require authentication)

• Base url REST: https://trade.capecrypto.com/api/v2/trade
• Base url WSS: wss://trade.capecrypto.com/api/v2/stream

Authentication

Authentication:

// generateHeaders.js

const crypto = require("crypto");
const apiKey = "123456...";
const secret = "ABCDEF...";

module.exports = async () => {
  const timeStamp = new Date().getTime();
  const queryString = `${timeStamp}${apikey}`;
  const signature = crypto
    .createHmac("sha256", secret)
    .update(queryString)
    .digest("hex");

  return {
    "Content-Type": "application/json;charset=utf-8",
    "X-Auth-Apikey": apikey,
    "X-Auth-Nonce": timeStamp,
    "X-Auth-Signature": signature,
  };
};

To securely access the private endpoints, each request requires authentication headers.

Generate a new signature for each new request, and add these headers to the request.

1. X-Auth-Nonce: Current timestamp in milliseconds UTC time.
2. X-Auth-Apikey: Your API key
3. X-Auth-Signature: HMAC-SHA256 encrypted string of the combined timestamp, apikey and secret (see JS example)

Example using Authentication

POST Create order

// generateHeaders.js

const crypto = require("crypto");
const apiKey = "123456...";
const secret = "ABCDEF...";

module.exports = async () => {
  const timeStamp = new Date().getTime();
  const queryString = `${timeStamp}${apikey}`;
  const signature = crypto
    .createHmac("sha256", secret)
    .update(queryString)
    .digest("hex");

  return {
    "Content-Type": "application/json;charset=utf-8",
    "X-Auth-Apikey": apikey,
    "X-Auth-Nonce": timeStamp,
    "X-Auth-Signature": signature,
  };
};

Send the authenticated request:

// createOrder.js
const axios = require("axios");
const generateHeaders = require("./generateHeaders");

createOrder = async () => {
  const baseUrl = "https://trade.capecrypto.com";
  const method = "POST";
  const path = `/api/v2/trade/market/orders`;
  const url = `${baseUrl}${path}`;
  const headers = await generateHeaders();

  const orderData = {
    market: "btczar",
    side: "sell",
    volume: "0.00001",
    ord_type: "limit",
    price: "800000",
    post_only: true,
    custom_order_id: "302b0494-1a06-4089-846c-0c6b13f1b661",
  };

  const axiosConfig = {
    method: method,
    url: url,
    headers: headers,
    data: orderData,
  };

  try {
    const results = await axios(axiosConfig);
    console.log(JSON.stringify(results.data, undefined, 2));
  } catch (err) {
    console.log(err);
  }
};

Create order response:

{
  "id": 173757,
  "uuid": "7e86a4fa-fcae-4953-b9bc-d6f328beea48",
  "side": "sell",
  "ord_type": "limit",
  "price": "800000.0",
  "avg_price": "0.0",
  "state": "pending",
  "market": "btczar",
  "created_at": "2023-12-08T08:46:59+01:00",
  "updated_at": "2023-12-08T08:46:59+01:00",
  "origin_volume": "0.00001",
  "remaining_volume": "0.00001",
  "executed_volume": "0.0",
  "trades_count": 0,
  "custom_order_id": "302b0494-1a06-4089-846c-0c6b13f1b661"
}

https://trade.capecrypto.com/api/v2/trade/market/orders

Create a new order on your account by signing your request and submitting the request

Public request example

GET Get available markets

const axios = require("axios");

getMarkets = async () => {
  const baseUrl = "https://trade.capecrypto.com";
  const method = "GET";
  const path = `/api/v2/trade/public/markets`;
  const url = `${baseUrl}${path}`;

  const axiosConfig = {
    method: method,
    url: url,
  };

  try {
    const results = await axios(axiosConfig);
    console.log(JSON.stringify(results.data, undefined, 2));
  } catch (err) {
    console.log(err);
  }
};

getMarkets();

Markets response:

[
  {
    "id": "btczar",
    "name": "BTC/ZAR",
    "base_unit": "btc",
    "quote_unit": "zar",
    "min_price": "200000.0",
    "max_price": "1200000.0",
    "min_amount": "0.00001",
    "amount_precision": 8,
    "price_precision": 2,
    "state": "enabled"
  },
  {
    "id": "ethzar",
    "name": "ETH/ZAR",
    "base_unit": "eth",
    "quote_unit": "zar",
    "min_price": "10000.0",
    "max_price": "100000.0",
    "min_amount": "0.0001",
    "amount_precision": 8,
    "price_precision": 2,
    "state": "enabled"
  },
  {
    "id": "xrpzar",
    "name": "XRP/ZAR",
    "base_unit": "xrp",
    "quote_unit": "zar",
    "min_price": "1.0",
    "max_price": "100.0",
    "min_amount": "1.0",
    "amount_precision": 6,
    "price_precision": 2,
    "state": "enabled"
  },
  {
    "id": "usdczar",
    "name": "USDC/ZAR",
    "base_unit": "usdc",
    "quote_unit": "zar",
    "min_price": "14.0",
    "max_price": "29.0",
    "min_amount": "0.5",
    "amount_precision": 2,
    "price_precision": 2,
    "state": "enabled"
  }
]

GET https://trade.capecrypto.com/api/v2/trade/public/markets

Returns a list of all available markets

Public

GET Alive

/public/health/alive

Description

Check that the trade engine is running. Occasionally the trade engine will be temporarily taken offline for udpates and general maintenance. Maintenence will usually not take longer than a few minutes.

Responses

GET Ticker

/public/markets/{market}/tickers

Description

Get ticker of specific market.

Parameters

Responses

GET All tickers

/public/markets/tickers

Description

Get ticker of all markets

Responses

GET K Line

/public/markets/{market}/k-line

Description

Get K-Line (OHLC) of specific market.

Parameters

Responses

GET Orderbook

/public/markets/{market}/depth

Description

Get the orderbook for the specified market eg. 'btczar'. Asks and bids are sorted away from the spread, ie asks are sorted low to high, and bids are sorted high to low. Results are returned in tupples of [price, amount] in the base currency eg. 'btc'.

Parameters

Responses

GET Market trades

/public/markets/{market}/trades

Description

Get recent trades for the specified market, results are paginated

Parameters

Responses

GET Markets

/public/markets

Description

Get all available markets.

Parameters

Responses

GET All Currencies

/public/currencies

Description

Get list of currencies

Parameters

Responses

GET Single Currency

/public/currencies/{id}

Description

Get a single currency

Parameters

Responses

Account

POST Create new beneficiary

/account/beneficiaries

Description

Create a new beneficiary

Parameters

Responses

PATCH Activate new neneficiary

/account/beneficiaries/{id}/activate

Description

Activates a new beneficiary with pin emailed during beneficiary creation

Parameters

Responses

DELETE Delete beneficiary

/account/beneficiaries/{id}

Description

Delete beneficiary

Parameters

Responses

GET Beneficiary by id

/account/beneficiaries/{id}

Description

Get beneficiary by id

Parameters

Responses

GET List Beneficiaries

/account/beneficiaries

Description

Get list of user beneficiaries

Parameters

Responses

GET Withdraw quote

/account/withdraws/{currency}

/account/withdraws/{currency}?bolt=ln...

Description

Get the expected fee to withdraw the specified currency. Submit the quote_id with your withdraw request payload to honor that fee during the withdrawal. Quotes are currently valid for 90 seconds, ensure you submit the withdrawal request before the expires_at parameter.

Parameters

Responses

POST New withdrawal

/account/withdraws

Description

Creates new withdrawal to active beneficiary.

Parameters

Responses

GET Withdrawal history

/account/withdraws

Description

Get your withdraw history, paginated.

Parameters

Responses

GET Instant deposit methods

/payments/methods

Description

Gets your available instant FIAT deposit methods, including voucher providers whose vouchers you can use to redeem (deposit). Use the id of the provider when creating the deposit request for the specific method.

Responses

POST Redeem voucher

/payments/vouchers/new

Description

Redeem a voucher code.

Parameters

Responses

GET Deposit address

/account/deposit_address/{currency}

Description

Fetch the deposit address for the specified currency.

Note: If your currency deposit address has not been created yet, the result may return empty while the address is being created. If it is empty, please try again in a few seconds.

Parameters

Responses

GET Deposit history by txid

/account/deposits/{txid}

Description

Get details of a specific blockchain deposit by the txid.

Parameters

Responses

GET Deposit history

/account/deposits

Description

Get your deposit history

Parameters

Responses

GET Balance

/account/balances/{currency}

Description

Get single account balance by currency code eg. 'btc'

Parameters

Responses

GET All balances

/account/balances

Description

Get account balances for all currencies

Parameters

Responses

POST New lightning payment

/account/lightning/pays

Description

Submits a payment request to pay a BTC Lightning BOLT11 invoice (withdraws this balance from your BTC account).

As the payment is requested and validated on the lightning network, please query your withdrawal history to confirm that the payment succeeded.

Parameters

Responses

POST Create a Lightning invoice

/account/lightning/invoices

Description

Create a new lightning invoice to be paid (receive) over the BTC Lightning network.

You can optionally specify a conversion_percent (1 = 100%, 0.1 = 10%) to automatically convert once the invoice is paid. The conversion percent should be such that the conversion amount is greater than or equal to the minimum order amount for the market eg. 'btczar'. For example if receiving BTC 0.00001, and the minimum order amount on 'btczar' is 0.00001, your conversion percent would have to be 1 (100%). Anything less would cause the invoice creation to fail, as the conversion amount would be below the minimum market order amount.

The invoice expires in 1 hour.

Parameters

Responses

Trading

POST Create Order

/market/orders

Description

Submits a Buy/Sell order to the order book. Orders should be confirmed that they have been created either by querying the order ID that is returned in the response, or subscribing to the websockets for order updates.

You can supply your own custom_order_id for tracking purposes for you own system.

For limit orders, you can specify post_only to ensure that orders wont complete if they would have matched. The order request will fail if post_only is true, and the order would have matched.

Parameters

Responses

GET Order by id

/market/orders/{id}

Description

Get single order details.

Parameters

Responses

GET All orders

/market/orders

Description

Get orders, result is paginated.

Parameters

Responses

GET Trades

/market/trades

Description

Fetch your executed trades.

Parameters

Responses

POST Cancel Order

/market/orders/{id}/cancel

Description

Cancel a specific order by Order id.

Parameters

Responses

POST Cancel All Orders

/market/orders/cancel

Description

Cancel all of your open orders.

Parameters

Responses

Websocket

// generateHeaders.js

const crypto = require("crypto");
const apiKey = "123456...";
const secret = "ABCDEF...";

module.exports = async () => {
  const timeStamp = new Date().getTime();
  const queryString = `${timeStamp}${apikey}`;
  const signature = crypto
    .createHmac("sha256", secret)
    .update(queryString)
    .digest("hex");

  return {
    "Content-Type": "application/json;charset=utf-8",
    "X-Auth-Apikey": apikey,
    "X-Auth-Nonce": timeStamp,
    "X-Auth-Signature": signature,
  };
};

The high performance websocket provides near realtime updates on the orderbook, your orders and balances.

The orderbook endpoint does not require authenticaiton, while the private endpoints (orders, trades, and balances) do require authentication.

To connect to the private endpoints on the websocket, send the authentication headers with the connection request, similar to the REST authentication, and subscribe to the streams you are interested in. You can combine multiple subscriptions in one request, and also provide the subscriptions at the same time as connecting - ie. you only need 1x request to get fully connected.

You can also combine the public and private streams into one so that you only need to maintain 1x connection for example ?stream=btczar.ob-inc&stream=order&stream=trade&stream=balance

SUBSCRIBE Orderbook

const WebSocket = require("ws");

async function connectWssPublic() {
  try {
    const baseUrl = `wss://trade.capecrypto.com/api/v2`;
    const streams = "?stream=btczar.ob-inc&stream=ethzar.ob-inc";
    const path = `/stream/public${streams}`;

    ws = new WebSocket(`${baseUrl}${path}`);
  } catch (err) {
    console.log(err);
  }

  ws.on("open", () => {
    console.log("Connected to websocket");
  });

  ws.on("message", function message(data) {
    data = JSON.parse(data);
    console.log(JSON.stringify(data, undefined, 2));

    if (["ob-snap", "ob-inc"].includes(data)) {
      // handle all subscribed markets
      // updateOrderBook(data);
    }
  });
}

connectWssPublic();

?stream={market}.ob-inc

Description

Subscribe to orderbook updates for the specified market. You can subscribe to multiple markets at the same time by adding each market as a param, eg

?stream=btczar.ob-inc&ethzar.ob-inc

Note: if the amount is empty "", the order has been removed from the orderbook

Parameters

Responses

SUBSCRIBE K-Line

const WebSocket = require("ws");

async function connectWssPublic() {
  try {
    const baseUrl = `wss://trade.capecrypto.com/api/v2`;
    const streams = "?stream=btczar.kline-15m";
    const path = `/stream/public${streams}`;

    ws = new WebSocket(`${baseUrl}${path}`);
  } catch (err) {
    console.log(err);
  }

  ws.on("open", () => {
    console.log("Connected to websocket");
  });

  ws.on("message", function message(data) {
    data = JSON.parse(data);
    console.log(JSON.stringify(data, undefined, 2));

    if (["kline-"].includes(data)) {
      // handle all subscribed markets
      // updateOrderBook(data);
    }
  });
}

connectWssPublic();

?stream={market}.kline-{period}

Description

Subscribe to the K-LINE (OHLC) for the specified market to get updates on the OHLC for each period. Similary to the otherendpoints, you can combine streams into a single subscription request.

Parameters

Responses

SUBSCRIBE Private

async function connectWssPrivate() {
  try {
    const baseUrl = `wss://trade.capecrypto.com/api/v2`;
    const headers = await generateHeaders();
    const streams =
      "?stream=btczar.ob-inc&stream=ethzar.ob-inc&stream=order&stream=trade&stream=balance";
    const path = `/stream/private?${streams}`;

    ws = new WebSocket(`${baseUrl}${path}`, { headers });
  } catch (err) {
    console.log(err);
  }

  ws.on("open", () => {
    console.log("Connected to websocket");
  });

  ws.on("message", (data) => {
    data = JSON.parse(data);
    console.log(JSON.stringify(data, undefined, 2));

    if (["ob-snap", "ob-inc"].includes(data)) {
      // handle all subscribed markets
      // updateOrderBook(data);
    }
    if (data["trade"]) {
      // handleOwnTradeUpdate(data);
    }
    if (data["order"]) {
      // handleOwnOrderUpdate(data);
    }

    if (data["balance"]) {
      // handleBalanceUpdate(data);
    }
  });
}

connectWssPrivate();

?stream={subscription}

Combined into 1x: ?stream={order}&stream={trade}&stream={balance}

Description

Subscribe to your account, and receive updates on your placed orders, trades executed, and balance updates.

Parameters

Responses

Models

Ticker

TickerEntry

Orderbook entry

Trade

Order

Market

Currency

Withdraw

Withdraw quote

Beneficiary

Deposit

Account

Instant Deposit Method

Voucher Redemption

Change voucher

Lightning payment

Lightning invoice

Websocket orderbook snapshot

Websocket orderbook increment

{
  "btczar.ob-snap": {
    "asks": [
      ["841039.73", "0.156431"],
      ["845402.1", "0.004389"],
      ["900000.0", "0.00001"]
    ],
    "bids": [
      ["835956.8", "0.047756"],
      ["831012.48", "0.03749"],
      ["829990.51", "0.019462"],
      ["400000.0", "0.0001"]
    ],
    "sequence": 9712
  }
}

States

Errors