NAV Navbar
javascript python

Web API

Overview

# Please note that many of the Python examples presented use type
# annotations introduced in Python 3.6. They are easy to remove
# manually if you are using an older version of Python. You could
# also use the strip-hints library to remove the type hints from
# the code. Examples have been tested with CPython 3.6+ only.

The information below should be used to help you consume our Web API.

URLs

Public Endpoints

Public endpoints do not require authentication. This information is fundamental to the exchange and publicly available.

Time

GET /time

const axios = require('axios')

axios.get('https://api.seedcx.com/time')
import requests

requests.get('https://api.seedcx.com/time')

Sample Response

  {
    "epoch": 1550174574
  }

Return the current unix time of the server in seconds.

Authentication

const crypto = require('crypto')
const request = require('request-promise')


const makeRequest = (
    apiKey,
    apiSecret,
    passphrase,
    host,
    route,
    method,
    body
  ) => {
    // CREATE SIGNATURE
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + method + route + JSON.stringify(body)
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    // Don't forget to base 64 encode your digest
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': apiKey,
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': passphrase
    }

    const derivedMethod = {
      POST: 'post',
      PUT: 'put',
      GET: 'get'
    }[method]

    const options =  {
      headers,
      body,
      json: true
    }

    return request[derivedMethod](`https://${host}${route}`, options)
  }
import hashlib
import hmac
import json
from base64 import b64decode, b64encode
from datetime import datetime
from typing import Any, Dict, Optional
from urllib.parse import urljoin

import requests
from logging import getLogger

logger = getLogger(__name__)

# NB: THESE CREDENTIALS SHOULD NOT BE STORED IN PLAINTEXT
# Keys here are kept in plaintext for the purposes of demonstration
# We encourage you to encrypt your keys and decrypt them only when being used
URL_BASE = 'api.seedcx.com'
HTTP_BASE = 'https://' + URL_BASE
API_PUBLIC_KEY = 'usjHuLksaeBXWSsa8uU7ES'
API_PRIVATE_KEY = '2mC4ZvVd4goRkuJm+rjr9byUiaUW1b6tVN4xy9QXNSE='
PASSPHRASE = 'testingisgreat'


def sign(api_key: str, method: str, route: str, json_body: str, timestamp: str) -> bytes:
    """Given a key and data, create and sign a payload.

    :param api_key: Key to sign the message with
    :param method: HTTP method
    :param route: Relative route. EX. /fills
    :param json_body: JSON as a string. Usually created via json.dumps(dict)
    :param timestamp: Unix Epoch time as a string
    :return: Base64 encoded digest
    """
    msg = bytes(timestamp + method + route + json_body, encoding='utf-8')
    hm = hmac.new(key=b64decode(api_key), msg=msg, digestmod=hashlib.sha256)
    return b64encode(hm.digest())


def headers() -> Dict[str, Any]:
    """Create a header template for use in HTTP requests."""
    return {
        'X-SCX-API-KEY': API_PUBLIC_KEY,
        'X-SCX-SIGNED': '',  # Put here to make sure we alway send something
        # The datetime.timestamp function is available only in Python 3.3+
        'X-SCX-TIMESTAMP': str(int(datetime.now().timestamp())),  # Unix Epoch
        'X-SCX-PASSPHRASE': PASSPHRASE
    }


def make_seed_request(
    method: str, url: str, body: Optional[Dict[str, str]] = None
) -> requests.Response:
    """Create and send an HTTP request with a signature to the Zero Hash API.

    :param method: HTTP method
    :param url: Relative route. EX. /fills
    :param body: Dictionary for serializing into the JSON body of the request. For GET requests,
                 this can be omitted or set to an empty dict. Nothing will be sent, but it is
                 required for the signature.
    :return: requests.Response object
    """
    if body is None:
        body = {}
    h = headers()
    json_body = json.dumps(body, separators=(',', ':'))
    h['X-SCX-SIGNED'] = sign(API_PRIVATE_KEY, method, url, json_body, h['X-SCX-TIMESTAMP'])
    args = {'method': method, 'url': urljoin(HTTP_BASE, url)}
    logger.info('Making {} request to {}'.format(method, urljoin(URL_BASE, url)))
    if body:
        args['data'] = json_body
        h['Content-Type'] = 'application/json'
        logger.debug(json_body)
    args['headers'] = h

    # Since we don't know if it's a GET or POST, use the generic request function and create an
    # args dict so that we can conditionally pass data/JSON
    return requests.request(**args)

Example Headers

{
  "X-SCX-API-KEY": "h2yFu1uijCDEqkbdop4GAF",
  "X-SCX-SIGNED": "PFMlg+bMFVjjAiGPLR/zJCStmiiOIeyz5NIOZEmpfH0=",
  "X-SCX-TIMESTAMP": 1550175822,
  "X-SCX-PASSPHRASE": "passphrase"
}

Zero Hash Uses HMAC SHA-256 verification to ensure the authenticity of every API request.

To Authenticate with us, you will need to set the following headers:

Header Description
X-SCX-API-KEY Your public key
X-SCX-SIGNED Signature for your request
X-SCX-TIMESTAMP Unix timestamp
X-SCX-PASSPHRASE Your passphrase

To sign your request:

  1. Concatenate timestamp + method + route + request body

    Example: 1549468233POST/orders{"client_order_id":"abcdefg","instrument_code":"COSP:BTC/USD","market_code":"SCXM","order_type":"limit","price":"3780","quantity":"10","side":"buy"}

  2. Generate an HMAC digest using your private key (using HMAC SHA-256).

    Example: Private Key = 2mC4ZvVd4goRkuJm+rjr9byUiaUW1b6tVN4xy9QXNSE=

  3. Encode the HMAC digest in Base64.

    Using the above private key should produce a base64 encoded digest of: +p94Yo3z33zvTmoA+BFtzQIW+qJz1X8IZcnuudpX6A8=

Private Endpoints

# The below Python examples make use of the functions defined above.

Trades

GET /trades

Sample Response

{
   "message":[
      {...}, // see trade by ID response below
      {...}  // see trade by ID response below
   ],
   "page":1,
   "total_pages":32
}

This returns an array of all trades received by Zero Hash for settlement from trading on SCXM, SCXS or any another platform supported by Zero Hash. Your intraday fills from trading on SCXM and SCXS may not be included until Zero Hash receives the trades for settlement.

Optional query parameters include:

GET /trades/:trade_id

A particular trade that has been submitted to Zero Hash for settlement. Note: the trade_id field is the Zero Hash-provided identifier returned as a response to the trade submission endpoints.

Sample Response

{
  "message": {
    "trade_id": "9411a2d9-8964-47d0-8971-a52db2f65748",
    "client_trade_id": "fjfd9wekdwoc0sdkcs09w",
    "trade_state": "terminated",
    "market_identifier_code": "SCXM",
    "trade_reporter_code": "00SCXM",
    "symbol": "COSP:BTC/USD",
    "trade_quantity": "4",
    "trade_price": "10000",
    "trade_type": "block",
    "physical_delivery": true,
    "comment": null,
    "last_update": 1565832456717,
    "transaction_timestamp": 1565731066447,
    "start_settle_on": 1565731965906,
    "accepted_timestamp": 1565731066768,
    "defaulted_timestamp": null,
    "settled_timestamp": 1565794980952,
    "contract_size": 1,
    "underlying": "BTC",
    "quoted_currency": "USD",
    "trade_reporter": "00SCXM",
    "platform_code": "00SCXM",
    "product_type": "spot",
    "parties_anonymous": false,
    "parties": [
      {
        "participant_code": "0M2CKW",
        "side": "buy",
        "asset": "BTC",
        "amount": "4",
        "liquidity_indicator": null,
        "execution_id": "ex_id1",
        "order_id": "foo",
        "desk_code": null,
        "trading_account_code": null,
        "obligations_outstanding_timestamp": null,
        "current_obligations_met_timestamp": null,
        "settlement_state": "settled",
        "client_order_id": null
      },
      {
        "participant_code": "1J32WQ",
        "side": "sell",
        "asset": "USD",
        "amount": "40000",
        "liquidity_indicator": null,
        "execution_id": "ex_id2",
        "order_id": "foo",
        "desk_code": null,
        "trading_account_code": null,
        "obligations_outstanding_timestamp": null,
        "current_obligations_met_timestamp": null,
        "settlement_state": "settled",
        "client_order_id": null
      }
    ]
  }
}

POST /trades

Sample Response

{
   "message":{
      "trade_id":"92616fce-31d3-465a-af01-0fb5d2dc4d40",
      "client_trade_id":"f2f14251-e296-42ac-9bc7-01c9186b9219",
      "trade_state":"terminated",
      "market_identifier_code":"TEST",
      "trade_reporter_code":"SGC7CQ",
      "symbol":"COSP:BTC/USD",
      "trade_quantity":"1.0",
      "trade_price":"10000.000000",
      "trade_type":"regular",
      "physical_delivery":true,
      "settlement_state":null,
      "comment":"Some comments about the trade for ZeroHash to store",
      "start_settle_on":1575849302321,
      "transaction_timestamp":1575849302321,
      "accepted_timestamp":1564686909724,
      "current_obligations_met_timestamp":1564686909724,
      "obligations_outstanding_timestamp":1564686909724,
      "settled_timestamp":null,
      "defaulted_timestamp":null,
      "contract_size":1,
      "underlying":"BTC",
      "quoted_currency":"USD",
      "trade_reporter":"{ a name or email }",
      "platform_code":"00TEST",
      "product_type":"spot",
      "parties_anonymous":true,
      "last_update":1564686909724,
      "parties":[
         {
            "participant_code":"PKOHXY",
            "side":"buy",
            "asset":"BTC",
            "amount":"1.0",
            "liquidity_indicator":null,
            "execution_id":null,
            "order_id":null,
            "client_order_id":null
         },
         {
            "participant_code":"S1I5ED",
            "side":"sell",
            "asset":"USD",
            "amount":"4000.0000",
            "liquidity_indicator":null,
            "execution_id":null,
            "order_id":null,
            "client_order_id":null
         }
      ]
   }
}

Allows a Trade Reporter to post executed spot trades to Zero Hash for settlement. The following fields are part of the submission.

Parameter Description Type
market_identifier_code The market identifier code, which must be zero for this post request string
symbol A free text field to identify the pair being traded string
trade_price The price the trade was executed
If asset and amount are included, this must equal to the seller's amount divided by the buyer's amount
string
trade_type The type of trade to be settled
Valid values are regular or block
string
product_type Currently only spot is supported string
expiry_date The last date that the product can be traded, or the date upon which the contract expires string
settlement_date The date upon which settlement will be attempted string
client_trade_id A unique identifier for the trade, generally produced by the Platform on which the trade was executed
Note: Zero Hash cannot guarantee the uniqueness of this field
string
platform_code The unique identifier to the Platform on which the trade was executed, as provided by Zero Hash string
trade_reporter A text field to indicate the name or idenifier of the person or entity submitting the trade string
physical_delivery A boolean statement to indicate if the trade is physically delivered
Currently Zero Hash only supports physically-settled trades, i.e. a value of true
boolean
comment (optional) An optional field to use if there is any additional information needed string
transaction_timestamp The unix timestamp the trade was executed on the external platform in milliseconds timestamp
parties_anonymous A boolean flag to determine if the counterparties are known to each other
Must be false if the platform_code is also a counterparty to the trade
boolean
parties The counterparties of the trade
Currently Zero Hash only supports 2 parties per trade
parties[]

Parameters for a specific party to a trade.

Parameter Description Type
side The side of the party, buy or sell string
participant_code The participant code as assigned by Zero Hash
Note: this will be Anonymous for counterparties to the trade if the parties_anonymous boolean was flagged as true by the Trade Reporter
string
asset The asset that is being received by the party string
amount The amount of the asset that the party is receiving string
liquidity_indicator (optional) This an optional field that can be sent to mark whether the party added or removed liquidity upon execution, used for reporting purposes only string
client_order_id (optional) This is an optional field that may have been sent by your clients and can be sent as part of the request, used for reporting purposes only string
order_id (optional) This is an optional field that can be used to identify orders within your system, used for reporting purposes only string
execution_id (optional) This an optional field that can be used to identify the ID of the execution for orders, used for reporting purposes only string

As a response, all information provided in the trade submission will be returned, plus the following additional fields:

Parameter Description Type
trade_id A unique ID from Zero Hash string
trade_state accepted, active, settled or defaulted string
accepted_timestamp The timestamp when the trade was first accepted into Zero Hash with a trade_state of accepted timestamp
current_obligations_met_timestamp The most recent timestamp when the trade reached the settlement_state of current_obligations_met. Will be null if this has not occured yet timestamp
obligations_outstanding_timestamp The most recent timestamp when the trade reached the settlement_state of obligations_outstanding. Will be null if this has not occured yet timestamp
settlement_state null, obligations_oustanding, current_obligations_met, counterparty_defaulted, settled or defaulted string
settled_timestamp The timestamp when the trade fully settled all obligations, thereby reaching the terminal settlement_state of settled. Will be null if this has not occured yet timestamp
defaulted_timestamp The timestamp when the trade defaulted due to obligations not being met on time, thereby reaching the terminal settlement_state of defaulted. Will be null if this has not occured yet timestamp
last_update The timestamp that indicates the last time the trade was updated timestamp
start_settle_on The timestamp when Zero Hash will first attempt to fully settle the trade timestamp

Trade State

Settlement State

Parties Anonymous

The parties_anonymous field is used to protect counterparty information. In the event that a Trade Reporter wishes to keep the counterparty details anonymous, this flag can be set to true. This is relevant for brokers and other types of agency execution providers.

Accounts

GET /accounts

const getAccounts = () => {
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'GET' + '/accounts' + '{}'
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      body,
      json: true
    }
    return request.get(`https://api.seedcx.com/accounts`, options)
  }
accounts = make_seed_request('GET', '/accounts', {})

Sample Response

{
   "message":[
      {
         "asset":"USD",
         "account_owner": "ABCDEF",
         "account_type":"collateral_deficiency",
         "account_group":"seed",
         "balance":"0.00",
         "usd_adjusted":"0.00",
         "account_id":"ce819fe8-b1d7-43bb-961c-e09ede0988d3",
         "last_update":1554395972174
      }
   ]
}

Returns an array of all accounts maintained at Zero Hash and their balances as of the most recent settlement run. See this page to predict trade and settlement obligations that will affect those account balances. Response parameters listed below.

Parameter Description Type
asset The asset code for the specific account, e.g. USD string
account_owner The code of the participant that owns the account string
account_type available, collateral, payable, receivable or collateral_deficiency string
account_group The group that the account is a part of string
balance The balance in the account string
usd_adjusted The adjusted, USD-value of holdings in this account string
account_id Unique ID of the specific account string
last_update Timestamp of last settlement run timestamp

Assets

Refer to our FAQ page to see which assets we support and their corresponding asset codes.

Account Type

Account types refer to their utilization. Zero Hash maintains 5 account types:

Account Group

Account groups are utilized as part of the Zero Hash settlement infrastructure, to determine for which purpose the funds in the account have been allocated. Generally, an account group refers to a platform. For example, the group of accounts used in trading on the Seed Digital Commodities Market platform will have an account_group value of 00SCXM, which is the platform code for Seed Digital Commodities Market. A participant may be provided multiple account groups into which they can allocate funds for settling trades executed across many platforms.

USD Adjusted

Please refer to our FAQ page for more information on the usd_adjusted field. In short, the usd_adjusted value of an account is the value of the account's holdings, converted to USD and haircut according to Zero Hash's haircut levels.

GET /accounts/net_delivery_obligations

const getNDO = () => {
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'GET' + '/accounts/net_delivery_obligations' + '{}'
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      body,
      json: true
    }
    return request.get(`https://api.seedcx.com/accounts/net_delivery_obligations`, options)
  }
account = make_seed_request('GET', '/accounts/net_delivery_obligations', {})

Sample Response

{
   "message":[
      {
         "asset": "USD",
         "amount": "10532.15",
         "account_group": "seed"
      },
      {
         "asset": "BTC",
         "amount": "3",
         "account_group": "seed"
      }
   ]
}

Your current net delivery obligations across all accounts. Response parameters listed below.

Parameter Description Type
asset The asset code for the specific account, e.g. USD string
amount The amount owed string
account_group The sub account determination used for allocating towards settlements string

GET /accounts/:account_id

const getAccount = () => {
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'GET' + '/accounts/e5e18303-a352-4c28-8dab-3779e66a659b' + '{}'
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      body,
      json: true
    }
    return request.get(`https://api.seedcx.com/accounts/e5e18303-a352-4c28-8dab-3779e66a659b`, options)
  }
account = make_seed_request('GET', '/accounts/e5e18303-a352-4c28-8dab-3779e66a659b', {})

Sample Response

{
   "message":[
      {
         "asset":"USD",
         "account_type":"collateral_deficiency",
         "account_group":"seed",
         "balance":"0.00",
         "usd_adjusted":"0.00",
         "account_id":"ce819fe8-b1d7-43bb-961c-e09ede0988d3",
         "last_update":1554395972174
      }
   ]
}

Information about a specific account. Response parameters listed below.

Parameter Description Type
asset The asset code for the specific account, e.g. USD string
account_type available, collateral, payable, receivable or collateral_deficiency string
account_group The sub account determination used for allocating towards settlements string
balance The balance in the account string
usd_adjusted The adjusted, USD-value of holdings in this account string
account_id Unique ID of the specific account string
last_update Timestamp of last settlement run timestamp

GET /accounts/:account_id/run_history

Sample Response

{
   "message":[
      {
         "run_timestamp":1549577062214,
         "run_type":"settlement",
         "run_id":"500",
         "change":"2000",
         "new_balance":"146645"
      },
      {
         "run_timestamp":1520134020000,
         "run_type":"deposit",
         "run_id":"480",
         "change":"100000",
         "new_balance":"144645"
      },
      {
         "run_timestamp":1510101010000,
         "run_type":"withdrawal",
         "run_id":"375",
         "change":"-20000",
         "new_balance":"44645"
      }
   ],
   "page":1,
   "total_pages":32
}

Returns the history of grouped settlements, deposits, withdrawals and other changes that have been applied to an account to lead up to its current balance.

Parameter Description Type
run_timestamp The time that the particular run was executed timestamp
run_type The type of run string
run_id A unique ID for the particular run string
change The net change to the account due to all movements within the particular run string
new_balance The new account balance post-run string

Run Type

A run is a group of movements that pertain to the same type of change to an account. They are split into the following buckets:

GET /accounts/:account_id/movements

Sample Response

{
   "message":[
      {
         "run_id":"500",
         "movement_timestamp":1554395972174,
         "movement_id":"ab938734-0aa6-4378-baa1-2cc56aeee757",
         "movement_type":"final_settlement",
         "trade_id":"332300000000228562",
         "change":"100"
      },
      {
         "run_id":"500",
         "movement_timestamp":1554395972174,
         "movement_id":"d8f902be-f8c3-4f9c-ac66-67000510900d",
         "movement_type":"final_settlement",
         "trade_id":"332300000000228563",
         "change":"-200"
      }
   ],
   "page":1,
   "total_pages":40

Returns the history of each itemized movement that has been applied to an account to lead up to its current balance.

Parameter Description Type
run_id A unique ID for the particular run string
movement_timestamp The timestamp of the specific movement timestamp
movement_id A unique ID for the specific movement string
movement_type The type of movement string
trade_id The ID of the trade that resulted in the movement string
change The change due to the specific movement string

Movement Type

Movement Description
deposit A deposit of additional assets into Zero Hash
final_settlement A movement due to the full delivery and final settlement of a trade
final_settlement_default A movement due to a financially-settled trade whose final settlement obligation could not be fully settled due to a default
final_settlement_default_fallback A movement due to the financial settlement for the portion of a physically-settled trade's final settlement obligation that was not fully delivered due to a default
final_settlement_default_partial A movement due to the partial physical delivery of a physically-settled trade whose final settlement obligation could not be fully delivered due to a default
final_settlement_previous A movement due to the full delivery and final settlement of a previously submitted trade whose obligations were outstanding
initial_margin A movement related to an increase or decrease in collateral held for any open position(s)
network_fee A blockchain network fee incurred due to an on-chain movement related to your wallet
transfer An internal transfer to or from an account at Zero Hash
variation_margin A payment made or collected due to changes in the market value of the position since the trade was executed or since the previous time the position was marked to market
variation_margin_previous A payment made or collected to settle a previously outstanding variation margin obligation
withdrawal A processed withdrawal from Zero Hash

Deposits

GET /deposits/digital_asset_addresses

const getDepositAddresses = () => {
    const body = {}
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'GET' + '/deposits/digital_asset_addresses' + '{}'
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      body,
      json: true
    }
    return request.get('https://api.seedcx.com/deposits/digital_asset_addresses', options)
  }
depositAddresses = make_seed_request('GET', '/deposits/digital_asset_addresses', {})

Sample Response

{
   "message":[
      {
         "address":"2NCgV7BXXafJZ86utcYFs5m3tCpkcpLafeG",
         "participant_code":"ABCDEF",
         "asset":"BTC",
         "created_timestamp":1561996924964,
      }
   ],
   "page":1,
   "total_pages":1
}

Returns an array of addresses associated with a participant's digital asset wallet.

Query parameters include:

Response:

Parameter Description Type
address The digital wallet address string
asset The asset code for the request, e.g. BTC string
participant_code The participant the request belongs to, e.g. ABCDEF string
created_timestamp The timestamp for when the address was created timestamp

DEPRECATED GET /deposits/addresses

const getDepositAddresses = () => {
    const body = {}
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'GET' + '/deposits/addresses' + '{}'
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      body,
      json: true
    }
    return request.get('https://api.seedcx.com/deposits/addresses', options)
  }
depositAddresses = make_seed_request('GET', '/deposits/addresses', {})

Sample Response

{
   "message":[
      {
         "address":"2NCgV7BXXafJZ86utcYFs5m3tCpkcpLafeG",
         "participant_code":"ABCDEF",
         "asset":"BTC",
         "created_timestamp":1561996924964,
      }
   ],
   "page":1,
   "total_pages":1
}

Returns an array of digital wallet deposit addresses.

Query parameters include:

Response:

Parameter Description Type
address The digital wallet address string
asset The asset code for the request, e.g. BTC string
participant_code The participant the request belongs to, e.g. ABCDEF string
created_timestamp The timestamp for when the address was created timestamp

POST /deposits/digital_asset_addresses

const postDepositAddress = () => {
    const body = { participant_code: 'ABCDEF', asset: 'BTC' }
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'POST' + '/deposits/digital_asset_addresses' + JSON.stringify(body)
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      body,
      json: true
    }
    return request.post('https://api.seedcx.com/deposits/digital_asset_addresses', options)
  }
depositAddress = make_seed_request('POST', '/deposits/digital_asset_addresses', {})

Sample Response

{
   "message":{
      "address":"2NCgV7BXXafJZ86utcYFs5m3tCpkcpLafeG",
      "participant_code":"ABCDEF",
      "asset":"BTC",
      "created_timestamp":1561996924964,
   },
}

Creates a new digital wallet deposit address for the asset provided. Currently, the creation of new digital addresses on demand is only supported for BTC, BCH, and LTC.

Parameter Description Type
participant_code The participant code the account belongs to string
asset The asset code for the withdrawal request, e.g. BTC string

Response:

Parameter Description Type
address The digital wallet address string
asset The asset code for the request, e.g. BTC string
participant_code The participant the request belongs to, e.g. ABCDEF string
created_timestamp The timestamp for when the address was created timestamp

DEPRECATED POST /deposits/addresses

const postDepositAddress = () => {
    const body = { participant_code: 'ABCDEF', asset: 'BTC' }
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'POST' + '/deposits/addresses' + JSON.stringify(body)
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      body,
      json: true
    }
    return request.post('https://api.seedcx.com/deposits/addresses', options)
  }
depositAddress = make_seed_request('POST', '/deposits/addresses', {})

Sample Response

{
   "message":{
      "address":"2NCgV7BXXafJZ86utcYFs5m3tCpkcpLafeG",
      "participant_code":"ABCDEF",
      "asset":"BTC",
      "created_timestamp":1561996924964,
   },
}

Creates a new digital wallet deposit address for the asset provided. Currently, the creation of new digital addresses on demand is only supported for BTC, BCH, and LTC.

Parameter Description Type
participant_code The participant code the account belongs to string
asset The asset code for the withdrawal request, e.g. BTC string

Response:

Parameter Description Type
address The digital wallet address string
asset The asset code for the request, e.g. BTC string
participant_code The participant the request belongs to, e.g. ABCDEF string
created_timestamp The timestamp for when the address was created timestamp

GET /deposits/fiat_accounts

const getFiatDepositAccounts = () => {
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'GET' + '/deposits/fiat_accounts' + '{}'
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      body,
      json: true
    }
    return request.get('https://api.seedcx.com/deposits/fiat_accounts', options)
  }
zeroHashAccounts = make_seed_request('GET', '/deposits/fiat_accounts', {})

Sample Response

{
   "message":{
      "USD": [
         {
            "type":"united_states_wire",
            "shortName":"BMO Harris",
            "bankName":"BMO Harris Bank N.A.",
            "bankPhysicalAddress":"123 Nowhere St.",
            "accountNumber":"123-123-4",
            "routingNumber":"07102343",
            "recipientName":"Zero Hash LLC",
            "recipientPhysicalAddress":"123 Nowhere St.",
            "reference":"Your Participant Code"
         },
         { ... }
      ],
      "EUR": [...]
   },
}

Retrieves a list of all fiat deposit accounts available to you per fiat currency. The account details are keyed by currency code. Note: your participant code is provided as the reference field for each bank account. You must include this with any deposit to ensure that funds can be allocated correctly to your participant.

Withdrawals

GET /withdrawals/requests

const getWithdrawalRequests = () => {
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'GET' + '/withdrawals/requests' + '{}'
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      body,
      json: true
    }
    return request.get('https://api.seedcx.com/withdrawals/requests', options)
  }
withdrawalAddresses = make_seed_request('GET', '/withdrawals/requests', {})

Sample Response

{
   "message":[
      {
         "id": 78,
         "withdrawal_account_id": 51,
         "participant_code": "ABCDEF",
         "requested_amount": "23",
         "settled_amount": "21",
         "status": "APPROVED",
         "asset": "BTC",
         "account_group": "00SCXM",
         "requested_timestamp":1554395972174
      }
   ],
   "page":1,
   "total_pages":1
}

Returns an array of all withdrawal requests created by users as part of your participant.

Query parameters include:

Response:

Parameter Description Type
id The ID of the Withdrawal Request number
withdrawal_account_id The ID of the withdrawal account the address belongs to number
asset The asset code for the request, e.g. BTC string
participant_code The participant the request belongs to, e.g. ABCDEF string
account_group The account group the request was made against, e.g. 00SCXM for the Seed Digital Commodities Market account group string
requested_amount The initially requested amount, e.g. 100.10 string
settled_amount The settled amount. This can be less than or equal to the requested_amount, e.g. 99 string or null
status The current status of the withdrawal request string
requested_timestamp The timestamp for when the withdrawal request was requested timestamp

POST /withdrawals/requests

const postWithdrawalRequest = () => {
   const body = {
      withdrawal_account_id: 123,
      participant_code: "ABCDEF",
      amount: "20",
      asset: "BTC",
      account_group: "00SCXM"
   }
   const timestamp = Math.round(Date.now() / 1000)
   const payload = timestamp + 'POST' + '/withdrawals/requests' + JSON.stringify(body)
   const decodedSecret = Buffer.from(apiSecret, 'base64')
   const hmac = crypto.createHmac('sha256', decodedSecret)
   const signedPayload = hmac.update(payload).digest('base64')

   // SET HEADERS
   const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
   }
   const options =  {
      headers,
      body,
      json: true
   }
   return request.post(`https://api.seedcx.com/withdrawals/requests`, options)

resp = make_seed_request('POST', '/withdrawals/requests', {})

Sample Response

{
  "message": {
    "id": 117,
    "withdrawal_account_id": 146,
    "participant_code":"ABCDEF",
    "account_group": "00SCXM",
    "requested_amount":"20",
    "settled_amount": null,
    "status":"APPROVED",
    "asset":"BTC",
    "requested_timestamp": 1561996924964
  }
}

Creates new withdrawal requests to be settled. Withdrawal requests created through the API go directly into an Approved state. To retrieve withdrawal account IDs use the GET /withdrawals/addresses endpoint.

There are 2 ways to submit withdrawal requests:

The first, standard method uses a withdrawal_account_id to choose the location to withdrawal to, which can be for a fiat currency or a digital asset. The account must be in an Approved state before submitting withdrawal requests to it.

Parameter Description Type
withdrawal_account_id The whitelisted withdrawal account or address to withdraw funds to string
participant_code The participant code the account belongs to string
account_group The account group to withdraw against, e.g. 00SCXM for the Seed Digital Commodities Market account group string
amount The amount to withdraw in whole amounts string
asset The asset code for the withdrawal request, e.g. BTC string

The second method allows for submitting a digital asset address instead of the withdrawal_account_id. This is not generally available. Please contact us if you'd like to learn more about this option.

Parameter Description Type
address The digital asset address to withdraw funds to string
participant_code The participant code the account belongs to string
account_group The account group to withdraw against, e.g. 00SCXM for the Seed Digital Commodities Market account group string
amount The amount to withdraw in whole amounts string
asset The asset code for the withdrawal request, e.g. BTC string

DELETE /withdrawals/requests

const deleteWithdrawalRequest = () => {
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'DELETE' + '/withdrawals/requests' + '{}'
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      json: true
    }
    const withdrawalRequestId = 1
    return request.delete(`https://api.seedcx.com/withdrawals/requests/${withdrawalRequestId}`, options)
  }
resp = make_seed_request('DELETE', '/withdrawals/requests/1', {})

Sample Response

{
  "message": {
    "id": 1,
    "withdrawal_account_id": 146,
    "participant_code":"ABCDEF",
    "requested_amount":"20",
    "account_group":"00SCXM",
    "settled_amount": null,
    "status":"REJECTED",
    "asset":"BTC",
    "requested_timestamp": 1561996924964
  }
}

Rejects a pending withdrawal request.

Withdrawal Request Status

Status Description
PENDING The request has been created and is pending approval from users
APPROVED The request is approved but not settled
REJECTED The request is rejected and in a terminal state
SETTLED The request was settled and sent for confirmation onchain if a digital asset

GET /withdrawals/digital_asset_addresses

const getWithdrawalAddresses = () => {
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'GET' + '/withdrawals/digital_asset_addresses' + '{}'
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      json: true
    }
    return request.get(`https://api.seedcx.com/withdrawals/digital_asset_addresses?participant_code=YOUR_PARTICIPANT_CODE`, options)
  }
withdrawalAddresses = make_seed_request('GET', '/withdrawals/digital_asset_addresses?participant_code=YOUR_PARTICIPANT_CODE', {})

Sample Response

{
   "message":[
      {
         "withdrawal_account_id": 123,
         "name":"Fund ABC Wallet",
         "address":"0xEXAMPLEB5771D523402234FF0d7596d2C62411dE",
         "status":"APPROVED",
         "limit":1000,
         "locked":false,
         "asset":"ETH",
         "created_timestamp":1554395972174
      }
   ],
   "page":1,
   "total_pages":1
}

Returns an array of all withdrawal addresses created by users as part of your participant.

Query parameters include:

Response:

Parameter Description Type
withdrawal_account_id The ID of the withdrawal account the address belongs to number
name The nickname the address was given when it was created string
address The blockchain address string
status The approval status of the address string
asset The asset code for the specific account, e.g. BTC string
limit The balance in the account number
locked Indicates that the address is locked and cannot be used boolean
created_timestamp Timestamp for when the withdrawal address was created timestamp

DEPRECATED GET /withdrawals/addresses

const getWithdrawalAddresses = () => {
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'GET' + '/withdrawals/addresses' + '{}'
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      json: true
    }
    return request.get(`https://api.seedcx.com/withdrawals/addresses?participant_code=YOUR_PARTICIPANT_CODE`, options)
  }
withdrawalAddresses = make_seed_request('GET', '/withdrawals/addresses?participant_code=YOUR_PARTICIPANT_CODE', {})

Sample Response

{
   "message":[
      {
         "withdrawal_account_id": 123,
         "name":"Fund ABC Wallet",
         "status":"APPROVED",
         "limit":1000,
         "locked":false,
         "asset":"ETH",
         "address":"0xEXAMPLEB5771D523402234FF0d7596d2C62411dE",
         "created_timestamp":1554395972174
      }
   ],
   "page":1,
   "total_pages":1
}

Returns an array of all withdrawal addresses created by users as part of your participant.

Query parameters include:

Response:

Parameter Description Type
withdrawal_account_id The ID of the withdrawal account number
name The nickname given to the withdrawal account string
status The approval status of the withdrawal account string
asset The asset code for the specific withdrawal account, e.g. BTC string
limit The limit applied to the account on a per-withdrawal basis number
locked Indicates that the withdrawal account is locked and cannot be used boolean
address The blockchain address string
created_timestamp Timestamp for when the withdrawal address was created timestamp

Withdrawal Account Status

Status Description
PENDING_CREATION Address is awaiting approval
APPROVED The address is approved for use
REJECTED The address was rejected for use
LOCKED The address has been temporarily locked from use
PENDING_CHANGE The address is awaiting a change approval for either unlocking or changing the limit

GET /withdrawals/fiat_accounts

const getFiatWithdrawalAccounts = () => {
    const timestamp = Math.round(Date.now() / 1000)
    const payload = timestamp + 'GET' + '/withdrawals/fiat_accounts' + '{}'
    const decodedSecret = Buffer.from(apiSecret, 'base64')
    const hmac = crypto.createHmac('sha256', decodedSecret)
    const signedPayload = hmac.update(payload).digest('base64')

    // SET HEADERS
    const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
    }
    const options =  {
      headers,
      body,
      json: true
    }
    return request.get('https://api.seedcx.com/withdrawals/fiat_accounts', options)
  }
zeroHashAccounts = make_seed_request('GET', '/withdrawals/fiat_accounts', {})

Sample Response

{
   "message": [
      { 
         "withdrawal_account_id": 286,
         "name": "Primary (1234)",
         "status": "PENDING_CREATION",
         "asset": "USD",
         "limit": 750000,
         "locked": false,
         "type": "DOMESTIC_FIAT",
         "beneficiary_name": "John Doe",
         "account_number": "1231234",
         "bank_name": "BMO Harris",
         "routing_number": "07102343",
         "swift_code": null,
         "recipient_instructions": null,
         "intermediary_bank_name": null,
         "intermediary_bank_code_type": null,
         "intermediary_bank_code": null,
         "intermediary_bank_account_number": null,
         "correspondent_bank_name": null,
         "correspondent_bank_code_type": null,
         "correspondent_bank_code": null,
         "correspondent_bank_account_number": null,
         "created_timestamp": 1571175076187 
      },
      { ... }
   ],
   "page": 1,
   "total_pages": 1
}

Retrieves a list of all whitelisted fiat withdrawal accounts.

Parameter Description Type
withdrawal_account_id The ID of the withdrawal account number
name The nickname given to the withdrawal account string
status The approval status of the withdrawal account string
asset The asset code for the specific withdrawal account, e.g. USD string
limit The limit applied to the account on a per-withdrawal basis number
locked Indicates that the withdrawal account is locked and cannot be used boolean
type The type of account: DOMESTIC_FIAT for US wires or INTERNATIONAL_FIAT for international wires boolean
beneficiary_name The owner of the account at the withdrawal destination string
account_number The unique IBAN or account number for the final withdrawal destination string
bank_name The name of the destination financial institution string
routing_number For US wires, the ABA routing number identifies the destination financial institution string
swift_code SWIFT code, if applicable string
recipient_instructions Any additional instructions on the account string
intermediary_
bank_name
Intermediary bank name, if applicable string
intermediary_
bank_code_type
Intermediary bank identifier code type, if applicable
Options include SWIFT
string
intermediary_
bank_code
Intermediary bank identifier that corresponds to intermediary_bank_code_type, if applicable string
intermediary_
bank_account_number
Intermediary bank IBAN or account number, if applicable string
correspondent_
bank_name
Correspondent bank name, if applicable string
correspondent_
bank_code_type
Correspondent bank identifier code type, if applicable
Options include SWIFT
string
correspondent_
bank_code
Correspondent bank identifier that corresponds to correspondent_bank_code_type, if applicable string
correspondent_
bank_account_number
Correspondent bank IBAN or account number, if applicable string
created_timestamp Timestamp for when the withdrawal address was created timestamp

Participants

GET /participants

Returns a list of all participants to which you are associated.

Sample Response

{
   "message": [
      {
         "participant_code":"123XYZ",
         "participant_name":"Trading Firm LLC",
         "relationship_types":[
            "customer_of_platform"
         ]
      },
      {
         "participant_code":"ABC456",
         "participant_name":"Lots of Capital LLC",
         "relationship_types":[
            "customer_of_platform"
         ]
      }
   ]
}

Response parameters listed below

Parameter Description Type
participant_code Unique participant code string
participant_name Name of participant string
relationship_types An array of the types of relationships you have with the participant string[]

Query parameters include:

POST /participants/customers

const postParticipantCustomer = () => {
   const body = {
   name: 'customer_1',
   email: 'foo@bar.com',
   state: 'IL',
   signed_timestamp: '1569014063570',
   country: 'United States',
   ssn: '123456789',
   metadata: {}
}
   const timestamp = Math.round(Date.now() / 1000)
   const payload = timestamp + 'POST' + '/participants/customers' + JSON.stringify(body)
   const decodedSecret = Buffer.from(apiSecret, 'base64')
   const hmac = crypto.createHmac('sha256', decodedSecret)
   const signedPayload = hmac.update(payload).digest('base64')

   // SET HEADERS
   const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase'
   }
   const options =  {
      headers,
      body,
      json: true
   }
   return request.post(`https://api.seedcx.com/participants/customers`, options)

resp = make_seed_request('POST', '/participants/customers', {})

Sample Request

{
   "name": "customer_1",
   "email": "foo@bar.com",
   "state": "IL",
   "signed_timestamp": "1569014063570",
   "country": "United States",
   "ssn": "123456789",
   "metadata": {}
}

Sample Response

{
  "message": {
    "name": "John Doe",
    "registration_code":"ABCDEF",
    "email":"foo@bar.com",
    "ssn":"123456789"
  }
}

Submits a customer to your platform.

Request body:

Parameter Description Type
name The first and last name of the customer string
email The participant code the account belongs to string, email
state The state the customer resides in. Required only if country is "United States" string, must be in a supported state
signed_timestamp The amount to withdraw in whole amounts string, milliseconds timestamp
country The country the customers resides in string, must in a must be in a supported country
ssn A standard Social Security Number string, length 9
metadata Can be used to submit any additional unstructed metadata Object

POST /participants/documents

const postParticipantDocument = (filepath) => {
   const document = fs.readFileSync(filepath).toString('base64')

   const body = {
      document,
      mime: 'pdf',
      file_name: 'supporting_document.pdf',
      participant_code: 'ABC123'
   }

   const timestamp = Math.round(Date.now() / 1000)
   const payload = timestamp + 'POST' + '/participants/documents' + JSON.stringify({})
   const decodedSecret = Buffer.from(apiSecret, 'base64')
   const hmac = crypto.createHmac('sha256', decodedSecret)
   const signedPayload = hmac.update(payload).digest('base64')

   const fileHash = crypto
      .createHash('sha256')
      .update(body.document)
      .digest('base64')

   // SET HEADERS
   const headers = {
      'X-SCX-API-KEY': 'public_key',
      'X-SCX-SIGNED': signedPayload,
      'X-SCX-TIMESTAMP': timestamp,
      'X-SCX-PASSPHRASE': 'passphrase',
      'X-SCX-FILE-HASH': fileHash
   }
   const options =  {
      headers,
      body,
      json: true
   }
   return request.post(`https://api.seedcx.com/participants/documents`, options)

with open(filepath, 'rb') as document:
   resp = make_seed_request('POST', '/participants/documents', {
        'document': base64.b64encode(document.read()),
        'mime': 'pdf',
        'file_name': 'supporting_document.pdf',
        'participant_code': 'ABC123'
    })

Sample Request

{
   "document": "aGVsbG8gd29ybGQ=",
   "mime": "pdf",
   "file_name": "supporting_document.pdf",
   "participant_code": "ABC123"
}

Sample Response

{
  "message": {
    "state": "Success",
    "file_name": "supporting_document.pdf",
    "created_at": 1572899177383
  }
}

Submits a document on behalf of you or a customer if you operate a platform on Zero Hash. In order to Authenticate you will need to do the following:

Request body:

Parameter Description Type
document base 64 encoded file that you wish to upload (10mb limit) binary
mime The MIME type of the file you are uploading string
file_name The name of the document that you are uploading string
participant_code Your participant code, or the participant_code of the customer on behalf of whom you are uploading the document string

Supported Regions

Zero Hash operates in a wide range of supported regions. For more information, please contact us to learn more. Please refer to our disclosures page for more information on regional regulation. Specifically, you can see a list of disclosures pertaining to certain states in which Zero Hash has licensing here.