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.zerohash.com/time')
import requests

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

Sample Response

{
  "epoch": 1550174574
}

Return the current unix time of the server in seconds.

Index

GET /index

const axios = require('axios')
axios.get('https://api.zerohash.com/index?underlying=BTC&quoted_currency=USD')
import requests
requests.get('https://api.zerohash.com/index?underlying=BTC&quoted_currency=USD')

Sample Response

{
  "timestamp": 1564686909724,
  "index": "BTC/USD",
  "underlying": "BTC",
  "quoted_currency": "USD",
  "value": 1234.5678901234
}

Query for the most recently calculated Zero Hash Index value.

The following query parameters are required:

Parameter Description Type
timestamp When the index was calculated timestamp
index The specific index, which is the unique combination of underlying and quoted_currency string
underlying The asset being valued string
quoted_currency The asset in which the underlying is being valued string
value The index price for the underlying asset, as quoted in the quoted_currency number

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.zerohash.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 where the requestor is the Platform, either party associated with the trade, or the account group where the trade was settled.

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": "BTC/USD",
    "trade_quantity": "4",
    "trade_price": "10000",
    "trade_type": "block",
    "physical_delivery": true,
    "comment": null,
    "last_update": 1565832456717,
    "transaction_timestamp": 1565731066447,
    "settlement_timestamp": 1565731965906,
    "accepted_timestamp": 1565731066768,
    "defaulted_timestamp": null,
    "settled_timestamp": 1565794980952,
    "contract_size": 1,
    "underlying": "BTC",
    "quoted_currency": "USD",
    "trade_reporter": "[email protected]",
    "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,
        "settling": true
      },
      {
        "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,
        "settling": true
      }
    ]
  }
}

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": "BTC/USD",
    "trade_quantity": "1.0",
    "trade_price": "10000.000000",
    "trade_type": "regular",
    "physical_delivery": true,
    "comment": "Some comments about the trade for Zero Hash to store",
    "settlement_timestamp": 1575849302321,
    "transaction_timestamp": 1575849302321,
    "accepted_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,
        "current_obligations_met_timestamp": 1564686909724,
        "obligations_outstanding_timestamp": 1564686909724,
        "client_order_id": null,
        "settling": true
      },
      {
        "participant_code": "S1I5ED",
        "side": "sell",
        "asset": "USD",
        "amount": "4000.0000",
        "liquidity_indicator": null,
        "execution_id": null,
        "order_id": null,
        "current_obligations_met_timestamp": 1564686909724,
        "obligations_outstanding_timestamp": 1564686909724,
        "client_order_id": null,
        "settling": true
      }
    ]
  }
}

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
client_trade_id A unique identifier for the trade, generally produced by the Platform on which the trade was executed
Note: this must be unique, per platform, per 24 hour period
string
trade_reporter A text field to indicate the name or identifier of the person or entity submitting the trade, e.g. an email address string
platform_code The unique identifier to the Platform on which the trade was executed, as provided by Zero Hash string
market_identifier_code (optional) The ISO 10383 market identifier code for the platform string
symbol A free text field to identify the pair being traded, e.g. BTC/USD string
product_type spot or forward string
trade_type The type of trade to be settled
Valid values are regular or block
string
trade_price The price the trade was executed, refer to
Note: if the amount is included per side, then this must equal to the seller's amount divided by the buyer's amount accurate for up to 20 figures
string
trade_quantity (conditional) The quantity purchased
Note: if the amount is included per side, then this should not be included, otherwise it is required
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
transaction_timestamp The unix timestamp the trade was executed on the external platform in milliseconds timestamp
comment (optional) An optional field to use if there is any additional information needed string
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
array
settlement_price_index_id (conditional) The unique identifier of the benchmark settlement price to be used when calculating settlement obligations on trades that are settled at Zero Hash - required for forwards only string
settlement_timestamp (optional) The datetime when final settlement will first be attempted - if not included, the standard platform settlement instructions will be applied number (unix ms timestamp)
expiry_timestamp (optional) The last datetime that the product can be traded, and the datetime that all final prices will be set, i.e. the fixing date - relevant for forwards only
Note: after this point, there is no more ability to exit the trade or change its economics
number (unix ms timestamp)

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 (conditional) The amount of the asset that the party is receiving
Note: if the trade_quantity is included, then this should not be included, otherwise it is required
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
settling This field states which side(s) will be settled 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

Trade Price

A trade_price with any precision is accepted, however note that final settlement amounts are limited to the asset’s currency precision limit. Further, when calculating trade notional and settlement values, Zero Hash utilizes banker's rounding. See here for more details.

Quantity and Amount

There are 2 methods of submitting trade price, quantity and amount information to Zero Hash. Depending on your setup, one may be more appropriate than the other:

  1. Submit trade_price and trade_quantity and we will therefore calculate the amount that each side will receive, e.g. for a BTC/USD trade, you may submit a trade_price of 10,000 and a trade_quantity of 1. We would therefore calculate that the buyer receives 1 BTC and the seller receives $10,000. This model is useful for trading platforms that have more defined instruments.
  2. Submit trade_price and the amount field per side, which means you explicitly state the amount that each side receives, e.g. for a BTC/USD trade, you may submit a trade_price of 10,000 and an amount of 1 for the buy side an amount of 10000 for the sell side. This is useful for platforms that have lots of flexibility in the amounts and assets that are traded. Note: if the amount is included per side, then the trade_price must equal to the seller's amount divided by the buyer's amount, accurate for up to 20 figures.

Physical Delivery

This boolean determines if a product is physically or financially-settled.

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.

Trade State

Settlement State

POST /trades/batch

Sample request

[
  {
    "symbol": "BTC/USD",
    "trade_reporter": "AAAAAA",
    "client_trade_id": "5155f7c9-95cb-4556-ab89-c178943a7111",
    "trade_price": "1",
    "trade_quantity": "0.0001",
    "platform_code": "AAAAAA",
    "parties_anonymous": false,
    "transaction_timestamp": 1602182786660,
    "product_type": "spot",
    "trade_type": "regular",
    "physical_delivery": true,
    "parties": [
      {
        "participant_code": "BBBBBB",
        "asset": "BTC",
        "side": "buy",
        "settling": true
      },
      {
        "participant_code": "CCCCCC",
        "asset": "USD",
        "side": "sell",
        "settling": true
      }
    ]
  },
  {
    "symbol": "BTC/USD",
    "trade_reporter": "DDDDDD",
    "client_trade_id": "5155f7c9-95cb-4556-ab89-c178943a7222",
    "trade_price": "2",
    "trade_quantity": "0.0002",
    "platform_code": "DDDDDD",
    "parties_anonymous": false,
    "transaction_timestamp": 1602182786660,
    "product_type": "spot",
    "trade_type": "regular",
    "physical_delivery": true,
    "parties": [
      {
        "participant_code": "EEEEEE",
        "asset": "BTC",
        "side": "buy",
        "settling": true
      },
      {
        "participant_code": "FFFFFF",
        "asset": "USD",
        "side": "sell",
        "settling": true
      }
    ]
  }
]

Sample Response

{
  "message": [
    {
      "trade_id": "a51d841b-0b1f-441c-96e3-fd164e0b3ff8",
      "client_trade_id": "5155f7c9-95cb-4556-ab89-c178943a7111",
      "trade_state": "accepted",
      "market_identifier_code": null,
      "trade_reporter_code": "AAAAAA",
      "symbol": "BTC/USD",
      "trade_quantity": "0.0001",
      "trade_price": "1",
      "trade_type": "regular",
      "physical_delivery": true,
      "comment": null,
      "last_update": 1602526124763,
      "transaction_timestamp": 1602182786660,
      "accepted_timestamp": 1602526124692,
      "defaulted_timestamp": null,
      "settled_timestamp": null,
      "expiry_timestamp": null,
      "settlement_timestamp": null,
      "settlement_price_index_id": null,
      "contract_size": 1,
      "underlying": "BTC",
      "quoted_currency": "USD",
      "trade_reporter": "AAAAAA",
      "platform_code": "AAAAAA",
      "product_type": "spot",
      "parties_anonymous": false,
      "parties": [
        {
          "participant_code": "BBBBBB",
          "side": "buy",
          "asset": "BTC",
          "amount": "null",
          "liquidity_indicator": null,
          "execution_id": null,
          "order_id": null,
          "obligations_outstanding_timestamp": null,
          "current_obligations_met_timestamp": null,
          "settlement_state": null,
          "client_order_id": null,
          "collateral_percentage": null
        },
        {
          "participant_code": "CCCCCC",
          "side": "sell",
          "asset": "USD",
          "amount": "null",
          "liquidity_indicator": null,
          "execution_id": null,
          "order_id": null,
          "obligations_outstanding_timestamp": null,
          "current_obligations_met_timestamp": null,
          "settlement_state": null,
          "client_order_id": null,
          "collateral_percentage": null
        }
      ],
      "platform_name": null
    },
    {
      "trade_id": "fe47ef4b-43d3-41c6-a7e9-42e414a6b34e",
      "client_trade_id": "5155f7c9-95cb-4556-ab89-c178943a7222",
      "trade_state": "accepted",
      "market_identifier_code": null,
      "trade_reporter_code": "DDDDDD",
      "symbol": "BTC/USD",
      "trade_quantity": "0.0002",
      "trade_price": "2",
      "trade_type": "regular",
      "physical_delivery": true,
      "comment": null,
      "last_update": 1602526124648,
      "transaction_timestamp": 1602182786660,
      "accepted_timestamp": 1602526124637,
      "defaulted_timestamp": null,
      "settled_timestamp": null,
      "expiry_timestamp": null,
      "settlement_timestamp": null,
      "settlement_price_index_id": null,
      "contract_size": 1,
      "underlying": "BTC",
      "quoted_currency": "USD",
      "trade_reporter": "DDDDDD",
      "platform_code": "DDDDDD",
      "product_type": "spot",
      "parties_anonymous": false,
      "parties": [
        {
          "participant_code": "EEEEEE",
          "side": "buy",
          "asset": "BTC",
          "amount": "null",
          "liquidity_indicator": null,
          "execution_id": null,
          "order_id": null,
          "obligations_outstanding_timestamp": null,
          "current_obligations_met_timestamp": null,
          "settlement_state": null,
          "client_order_id": null,
          "collateral_percentage": null
        },
        {
          "participant_code": "FFFFFF",
          "side": "sell",
          "asset": "USD",
          "amount": "null",
          "liquidity_indicator": null,
          "execution_id": null,
          "order_id": null,
          "obligations_outstanding_timestamp": null,
          "current_obligations_met_timestamp": null,
          "settlement_state": null,
          "client_order_id": null,
          "collateral_percentage": null
        }
      ],
      "platform_name": null
    }
  ]
}

Allows a Trade Reporter to post multiple trades to Zero Hash for settlement. All trades submitted together must each independently pass validation for the batch to be accepted. If any trade is rejected, the entire batch will be rejected. This is useful for liquidity providers that wish to capture a spread between two counterparty trades.

The field requirements are the same as POST /trades, so please refer to the section above.

Loans

GET /loans

Sample Response

{
  "message":[
    {...}, // see loan by ID response below
    {...}  // see loan by ID response below
  ],
  "page":1,
  "total_pages":2,
  "page_size":200,
  "count":234
}

This returns all loans received by Zero Hash where the requestor is the Platform or either party associated with the loan.

Optional query parameters include:

GET /loans/:loan_id

Sample Response

{
  "message": {
    "last_update": 1600970538000,
    "loan_id": "1a72a8c1-8c3c-46b3-8cc4-aa520073174a",
    "client_loan_id": "testloan",
    "loan_state": "terminated",
    "platform_code": "188IMJ",
    "platform_name": "Lending Platform Operator",
    "loan_reporter_code": "188IMJ",
    "loan_reporter": "[email protected]",
    "symbol": "USDC/BTC",
    "loan_term": "Daily",
    "spot_rate": "zh_index",
    "lender_participant_code": "188IMJ",
    "lender_participant_name": "Lending Platform Operator",
    "lender_obligations_outstanding_timestamp": 1600970538000,
    "lender_current_obligations_met_timestamp": 1600970538000,
    "lender_settlement_state": "settled",
    "borrower_participant_code": "8VX5KD",
    "borrower_participant_name": "Lending Counterparty",
    "borrower_obligations_outstanding_timestamp": 1600970538000,
    "borrower_current_obligations_met_timestamp": 1600970538000,
    "borrower_settlement_state": "settled",
    "loan_asset": "USDC",
    "loan_quantity": "10000",
    "initial_loan_value_usd": "10022.62",
    "current_loan_value_usd": "10030.63",
    "principal_rate": "1.0030625226112",
    "collateral_asset": "BTC",
    "collateral_quantity": "0",
    "current_collateral_value_usd": "11864.27",
    "collateral_rate": "10378.8174826308",
    "collateral_requirement_percentage": "120",
    "collateral_release_percentage": "140",
    "collateral_top_up_percentage": "110",
    "loan_rate": "10",
    "accrual_method": "Actual/365",
    "accrue_interest_type": "loan_asset",
    "accrual_amount": "2.73972602739726",
    "accrue_interest_asset": "USDC",
    "settle_interest_asset": "USDC",
    "accrual_start_timestamp": 1600970538000,
    "last_interest_calculation_timestamp": 1600970538000,
    "transaction_timestamp": 1600970538000,
    "accepted_timestamp": 1600970538000,
    "maturity_timestamp": 1600970538000,
    "settled_timestamp": 1600970538000,
    "defaulted_timestamp": 1600970538000,
    "repayment_default_timestamp": 1600970538000,
    "principal_swap_default_timestamp": 1600970538000,
    "collateral_default_timestamp": 1600970538000,
    "interest_default_timestamp": 1600970538000
  }
}

A particular loan that has been submitted to Zero Hash for settlement. Note: the loan_id field is the Zero Hash-provided identifier.

Parameter Description Type
last_update When the loan was last updated
Note: this is specific to key loan terms, loan state or settlement states - last_update will not change as we update current_loan_value_usd, principal_rate, current_collateral_value_usd, collateral_rate or accrual_amount as we do this near-continuously
timestamp
loan_id Zero Hash-determined unique identifier for a loan string
client_loan_id Client-determined unique identifier for a loan string
loan_state Current state or status of the loan. See {states-FAQ page} string
platform_code The unique identifier to the Platform on which the trade was executed, as provided by Zero Hash string
platform_name The name of the Platform Operator string
loan_reporter_code Zero Hash participant code of the Platform Operator string
loan_reporter The specific user who reported the loan string
symbol The symbol attributed to the loan string
loan_term Used for reporting purposes only. This categorizes a loan into general term buckets string
spot_rate The index used to value collateral and loan amounts string
lender_participant_code Zero Hash participant code of the lender string
lender_participant_name The name of the lender string
lender_obligations_
outstanding_timestamp
The most recent timestamp at which point the lender was deemed to have obligations outstanding timestamp
lender_current_
obligations_met_timestamp
The most recent timestamp at which point the lender was deemed to have met all current obligations timestamp
lender_settlement_state The settlement state for the lender string
borrower_participant_code Zero Hash participant code of the borrower string
borrower_participant_name The name of the borrower string
borrower_obligations_
outstanding_timestamp
The most recent timestamp at which point the borrower was deemed to have obligations outstanding timestamp
borrower_current_
obligations_met_timestamp
The most recent timestamp at which point the borrower was deemed to have met all current obligations timestamp
borrower_settlement_state The settlement state for the borrower string
loan_asset The asset being lent string
loan_quantity The amount of the asset being lent string
initial_loan_value_usd The initial value of the loan_quantity in USD string
current_loan_value_usd The current value of the loan_quantity in USD string
principal_rate The rate used to determine the current_loan_value_usd string
collateral_asset The asset used to collateralize the loan string
collateral_quantity The amount of collateral currently held for a particular loan string
current_collateral_value_usd The current value of the collateral_quantity in USD string
collateral_rate The rate used to determine the current_collateral_value_usd string
collateral_
requirement_percentage
Percent of collateral that must be posted by the borrower, measured as a percentage against the initial loan value string
collateral_
release_percentage
Ratio of current collateral value to current loan value, above which collateral must be released from lender to borrower string
collateral_
top_up_percentage
Ratio of current collateral value to current loan value, below which collateral must be posted from borrower to lender string
loan_rate The interest rate applied to the loan string
accrual_method The method used to calculate interest: Actual/365 or Actual/360 string
accrue_interest_type Whether the loan accrues interest in USD or the loan_asset string
accrual_amount The amount that has been accrued in the base_currency to date string
accrue_interest_asset The asset that interest is accrued in string
settle_interest_asset The asset that interest will be paid in, regardless to how it is accrued string
accrual_start_timestamp When interest accruals will begin timestamp
last_interest_
calculation_timestamp
The most recent timestamp when the acrual_amount was updated timestamp
transaction_timestamp Date and time that the loan was transacted; determined by the loan submitter timestamp
accepted_timestamp When the loan was accepted by Zero Hash timestamp
maturity_timestamp Date and time that the loan expires/matures timestamp
settled_timestamp When the loan was fully settled and terminated by Zero Hash timestamp
defaulted_timestamp When the loan was considered defaulted by Zero Hash timestamp
repayment_default_
timestamp
The timestamp when the loan's principal and collateral must be returned, or be considered in default timestamp
principal_swap_default_
timestamp
The timestamp when the loan's principal and collateral must be initially swapped, or be considered in default timestamp
collateral_default_
timestamp
The timestamp when the loan's collateral top up/release must be delivered/returned, or be considered in default timestamp
interest_default_
timestamp
The timestamp when the loan's currently due accrued interest amounts must be settled, or be considered in default timestamp

GET /loans/portfolios

Sample Response

{
  "message": [
    {
      "participant_code": "ABC123",
      "loan_portfolio_id": "6ae5c10d-07f5-4384-978b-741882b05a99",
      "name": "Test Portfolio",
      "state": "active",
      "counterparty_participant_code": "XYZ456",
      "collateral_asset": "BTC",
      "collateral_requirement_percentage": "130",
      "collateral_top_up_percentage": "110",
      "collateral_release_percentage": "150",
      "loan_ids": {},
      "created_at": 1600970538000
    }
  ],
  "page": 1,
  "total_pages": 1,
  "page_size": 200,
  "count": 1
}

This returns all loan portfolios being managed by the requesting participant.

Parameter Description Type
participant_code The participant who owns the portfolio string
loan_portfolio_id Zero Hash-determined unique identifier for the portfolio string
name Client-determined name for the portfolio string
state Whether the loan is active or retired string
counterparty_participant_code The counterparty for all loans in the portfolio string
collateral_asset The asset used to collateralize the loans in the portfolio string
collateral_
requirement_percentage
Percent of collateral that must be posted in aggregate across all loans, measured as a percentage against total portfolio loan value string
collateral_
release_percentage
Ratio of current collateral value to current portfolio value, above which collateral must be released from lender to borrower string
collateral_
top_up_percentage
Ratio of current collateral value to current portfolio value, below which collateral must be posted from borrower to lender string
loan_ids{} A list of loans nested under the portfolio array
created_at When the loan portfolio was last updated timestamp

Positions

GET /positions

const getPositions = () => {
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'GET' + '/positions' + '{}'
  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.zerohash.com/positions`, options)
}
accounts = make_seed_request('GET', '/positions', {})

Sample Response

{
  "message": [
    {
      "platform_code": "PLAT01",
      "participant_code": "CUST01",
      "asset": "BTC",
      "position_all_open_trades": "10.02",
      "position_all_accepted_trades_only": "10.02",
      "position_all_active_trades_only": "0"
    },
    {
      "platform_code": "PLAT01",
      "participant_code": "CUST01",
      "asset": "USD",
      "position_all_open_trades": "-100200",
      "position_all_accepted_trades_only": "-100200",
      "position_all_active_trades_only": "0"
    },
    {
      "platform_code": "PLAT02",
      "participant_code": "CUST01",
      "asset": "USDC",
      "position_all_open_trades": "-110000",
      "position_all_accepted_trades_only": "0",
      "position_all_active_trades_only": "-110000"
    },
    {
      "platform_code": "PLAT02",
      "participant_code": "CUST01",
      "asset": "USD",
      "position_all_open_trades": "109670",
      "position_accepted_trades_only": "0",
      "position_active_trades_only": "109670"
    }
  ]
}

Returns an array of all positions maintained at Zero Hash for the participant issuing the query. The response will include positions for all platforms for which the participant is active. Response parameters listed below.

Query parameters include:

Response:

Parameter Description Type
platform_code The code of the platform for the position string
participant_code The code of the participant that holds the position string
asset The asset code for the for the position, e.g. USD string
position_all_open_trades The net position of all open trades in the asset, i.e. trades with a trade_state of accepted or active string
position_accepted_trades_only The net position of all trades in the asset with a trade_state of accepted, i.e. trades where settlement has not yet been attempted string
position_active_trades_only The net position of all trades in the asset with a trade_state of active, i.e. trades where settlement has been attempted but was unsuccessful string

GET /positions/platform/:platform_code

const getPositionsForPlatform = (platformCode: string) => {
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'GET' + '/positions/' + platformCode + '{}'
  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.zerohash.com/positions/platform/' + platformCode,
    options
  )
}
accounts = make_seed_request('GET', '/positions/platform/PLAT01', {})

Sample Response

{
  "message": [
    {
      "platform_code": "PLAT01",
      "participant_code": "CUST01",
      "asset": "BTC",
      "position_all_open_trades": "10.02",
      "position_all_accepted_trades_only": "10.02",
      "position_all_active_trades_only": "0"
    },
    {
      "platform_code": "PLAT01",
      "participant_code": "CUST01",
      "asset": "USD",
      "position_all_open_trades": "-100200",
      "position_all_accepted_trades_only": "-100200",
      "position_all_active_trades_only": "0"
    },
    {
      "platform_code": "PLAT01",
      "participant_code": "CUST02",
      "asset": "USDC",
      "position_all_open_trades": "-110000",
      "position_all_accepted_trades_only": "0",
      "position_all_active_trades_only": "-110000"
    },
    {
      "platform_code": "PLAT01",
      "participant_code": "CUST02",
      "asset": "USD",
      "position_all_open_trades": "109670",
      "position_accepted_trades_only": "0",
      "position_active_trades_only": "109670"
    }
  ]
}

Returns an array of all positions maintained at Zero Hash for the platform issuing the query. The response will include positions for all participants active on the platform. Response parameters listed below.

Query parameters include:

Response:

Parameter Description Type
platform_code The code of the platform for the position string
participant_code The code of the participant that holds the position string
asset The asset code for the for the position, e.g. USD string
position_all_open_trades The net position of all open trades in the asset, i.e. trades with a trade_state of accepted or active string
position_accepted_trades_only The net position of all trades in the asset with a trade_state of accepted, i.e. trades where settlement has not yet been attempted string
position_active_trades_only The net position of all trades in the asset with a trade_state of active, i.e. trades where settlement has been attempted but was unsuccessful string

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.zerohash.com/accounts`, options)
}
accounts = make_seed_request('GET', '/accounts', {})

Sample Response

{
  "message": [
    {
      "asset": "USD",
      "account_owner": "ABCDEF",
      "account_type": "collateral_deficiency",
      "account_group": "XYZ456",
      "account_label": "general",
      "balance": "0.00",
      "account_id": "ce819fe8-b1d7-43bb-961c-e09ede0988d3",
      "last_update": 1554395972174
    }
  ],
  "page": 1,
  "total_pages": 1
}

Query parameters include:

Returns an array of all accounts maintained at Zero Hash and their balances as of the most recent settlement run. 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
account_label The account label associated with the account string
balance The balance in the account string
account_id Unique ID of the specific account string
last_update Timestamp when the account balance was updated 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:

Refer to our FAQ for more information: What types of accounts are supported?

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.

Refer to our FAQ for more information: What is an account group?

Account Label

Account Labels can be thought of as “sub account groups”. Within each account group, you can have many Account Labels. They are used to separate funds at a more granular level. The default value is general.

Refer to our FAQ for more information: What is an Account Label?

Supported account_labels:

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.zerohash.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": "00SCXM",
      "account_label": "general"
    },
    {
      "asset": "BTC",
      "amount": "3",
      "account_group": "00SCXM",
      "account_label": "general"
    }
  ]
}

Your current net delivery obligations (NDO) across all accounts. See here for more information on NDOs: What does NDO mean?

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
account_label The account label associated with the account 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.zerohash.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_owner": "ABC123",
    "account_type": "collateral_deficiency",
    "account_group": "00SCXM",
    "account_label": "general",
    "balance": "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_owner The code of the participant that owns the account 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
account_id Unique ID of the specific account string
last_update Timestamp of last settlement run timestamp
account_label The account label associated with the account string

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:

Run Description
deposit deposit represents a new deposit into the particular account, always increasing the total balance of the account
execution_fee execution_fee represents a run to process fees incurred from trading on a Seed CX liquidity venue
network_fee network_fee represents any and all blockchain network fees applied to an account, always decreasing the total balance of the account
settlement settlement is a group of movements due to margining and settling trades, which may increase or decrease the account balance
transfer transfer represents an internal transfer to or from an account at Zero Hash
withdrawal withdrawal represents an approved and processed withdrawal from a particular account, always decreasing the total balance of the account

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": "951806f4-d3ba-42c4-96fe-8083cd3202cf",
      "deposit_reference_id": null,
      "withdrawal_request_id": null,
      "change": "100"
    },
    {
      "run_id": "500",
      "movement_timestamp": 1554395972174,
      "movement_id": "d8f902be-f8c3-4f9c-ac66-67000510900d",
      "movement_type": "final_settlement",
      "trade_id": "3ad29e08-8b4f-435b-89aa-17b7a298b350",
      "deposit_reference_id": null,
      "withdrawal_request_id": null,
      "change": "-200"
    },
    {
      "run_id": "498",
      "movement_timestamp": 1554395972000,
      "movement_id": "c6af3d80-1aca-4280-b96b-a9b8d7ced46a",
      "movement_type": "deposit",
      "trade_id": null,
      "deposit_reference_id": "ebedc42f-85c3-4468-8894-1cb6f49f7a04",
      "withdrawal_request_id": null,
      "change": "10000"
    },
    {
      "run_id": "497",
      "movement_timestamp": 1554395972000,
      "movement_id": "c6af3d80-1aca-4280-b96b-a9b8d7ced46a",
      "movement_type": "withdrawal",
      "trade_id": null,
      "deposit_reference_id": null,
      "withdrawal_request_id": "100",
      "change": "-50"
    }
  ],
  "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 account update string
movement_type The type of movement string
trade_id The unique identifier of the trade or loan that resulted in the movement, if the movement was due to a trade or loan
If a trade, this is equal to the trade_id field provided via the /trades
string
deposit_reference_id This is an external identifier associated with the deposit, if the movement was due to a deposit
This is equal to the reference_id field provided via the /deposits endpoint
string
withdrawal_request_id The withdrawal request ID, if the movement was due to a withdrawal
This is equal to the id field provided via the /withdrawals/requests endpoint
string
change The change due to the specific movement string

Movement Type

Movement Description
collateralize_loan A movement related to an increase in collateral held for any open loan(s)
deposit A deposit of additional assets into Zero Hash
execution_fee A movement due to incurred execution fees related to your trading activity on a Seed CX liquidity venue
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
initial_margin A movement related to an increase or decrease in collateral held for any open position(s)
interest_payment A payment of interest for a loan
loan_collateral_return A movement related to a decrease in collateral held for any open loan(s)
network_fee A blockchain network fee incurred due to an on-chain movement related to your wallet
principal_swap A transfer of principal and collateral assets to open a loan
repayment A transfer to return principal and collateral for a loan that has terminated
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
withdrawal_confirmed Reversal of the temporary hold due to a withdrawal being processed
withdrawal_pending Temporary hold whilst a withdrawal is being processed

Deposits

GET /deposits

const getDeposits = () => {
  const body = {}
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'GET' + '/deposits' + '{}'
  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.zerohash.com/deposits', options)
}
deposits = make_seed_request('GET', '/deposits', {})

Sample Response

{
  "message": [
    {
      "settle_timestamp": 1590663417000,
      "account_id": "80289ce5-072b-4739-929d-dcc5ccc542f3",
      "movement_id": "21bdbb11-712f-4cb7-a178-4f277c80cde0",
      "participant_code": "ABC123",
      "account_group": "00SCXM",
      "account_label": "general",
      "asset": "BTC",
      "amount": "4.0000",
      "reference_id": "408482348dcb0e0331a9148d50f8c76db08138f63fb1586fcfc45200a91ccc5f",
      "zerohash_bank_name": null,
      "run_id": "12613"
    }
  ],
  "page": 1,
  "total_pages": 1
}

Returns an array of deposits associated with the participant requesting. Currently is limited just to deposits made by the requesting participant.

Query parameters include:

Response:

Parameter Description Type
settle_timestamp The timestamp for when the deposit was credited to the participant - this is also the movement_timestamp timestamp
movement_id A unique ID for the specific account update string
account_id Unique ID of the specific account string
participant_code The participant that was credited with the deposit, e.g. ABCDEF string
account_group The account group associated with the account_id that received the deposit, e.g. 00SCXM for the Seed Digital Commodities Market account group string
account_label The account label associated with the account string
asset The asset code for the request, e.g. BTC string
amount The amount that was deposited into the account number
reference_id This is an external identifier associated with the deposit, which is context-specific depending on the asset type and deposit source - wire, transfer or on-chain transaction ID string
zerohash_bank_name The bank into which the (fiat) deposit was made string
run_id A unique ID for the particular run string

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.zerohash.com/deposits/digital_asset_addresses',
    options
  )
}
depositAddresses = make_seed_request('GET', '/deposits/digital_asset_addresses', {})

Sample Response

{
  "message": [
    {
      "created_at": 1561996924964,
      "address": "2NCgV7BXXafJZ86utcYFs5m3tCpkcpLafeG",
      "participant_code": "ABCDEF",
      "asset": "BTC"
    },
    {
      "created_at": 1561996924964,
      "address": "0xe01ed9e684de649bfec799cd79f6c27335c23cb9",
      "participant_code": "ABCDEF",
      "asset": "ETH"
    }
  ]
}

Returns an array of addresses associated with a participant's digital asset wallet. In order to GET deposit addresses for a participant_code other than yourself, you must have the submits_platform_withdrawals_for relationship against said participant_code. Refer here for more information on relationship types.

Query parameters include:

Response:

Parameter Description Type
created_at The timestamp for when the address was created timestamp
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

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.zerohash.com/deposits/digital_asset_addresses',
    options
  )
}
depositAddress = make_seed_request('POST', '/deposits/digital_asset_addresses', {})

Sample Request

{
  "participant_code": "ABCDEF",
  "asset": "BTC"
}

Sample Response

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

Creates a new digital wallet deposit address for the asset and participant_code provided. In order to request a deposit address for a participant_code other than yourself, you must have the submits_platform_withdrawals_for relationship against said participant_code. Refer here for more information on relationship types.

Parameter Description Type
participant_code The participant code to create an address for string
asset The asset code to make an address in, e.g. BTC string

Response:

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

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.zerohash.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.zerohash.com/withdrawals/requests', options)
}
withdrawalRequests = make_seed_request('GET', '/withdrawals/requests', {})

Sample Response

{
  "message": [
    {
      "id": 78,
      "withdrawal_account_id": 51,
      "participant_code": "ABCDEF",
      "requestor_participant_code": "ABCDEF",
      "requested_amount": "23",
      "settled_amount": "21",
      "status": "APPROVED",
      "asset": "BTC",
      "account_group": "00SCXM",
      "transaction_id": null,
      "requested_timestamp": 1554395972174,
      "gas_price": null,
      "client_withdrawal_request_id": null
    }
  ],
  "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 withdrawal request ID number
client_withdrawal_request_id A unique identifier for the withdrawal, generally produced by the Platform on which the trade was executed
Note: this must be unique, per platform, per 24 hour period
string
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
requestor_participant_code The participant code of the requestor, 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
transaction_id The on-chain transaction id once the withdrawal has been confirmed string or null
status The current status of the withdrawal request string
requested_timestamp The timestamp for when the withdrawal request was requested timestamp
gas_price The transaction fee payable on the Ethereum network
If the asset is not an ERC-20 token, this field will always be null
string or null

GET /withdrawals/requests/:id

const getWithdrawalRequests = () => {
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'GET' + '/withdrawals/requests/78' + '{}'
  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.zerohash.com/withdrawals/requests/78',
    options
  )
}
withdrawalRequests = make_seed_request('GET', '/withdrawals/requests/78', {})

Sample Response

{
  "message": [
    {
      "id": 78,
      "withdrawal_account_id": 51,
      "participant_code": "ABCDEF",
      "requestor_participant_code": "ABCDEF",
      "requested_amount": "23",
      "settled_amount": "21",
      "status": "APPROVED",
      "asset": "BTC",
      "account_group": "00SCXM",
      "transaction_id": null,
      "requested_timestamp": 1554395972174,
      "gas_price": null,
      "client_withdrawal_request_id": null
    }
  ]
}

Returns a specific withdrawal request associated with your participant or platform.

See GET /withdrawals/requests for response field descriptions.

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.zerohash.com/withdrawals/requests`, options)
}
resp = make_seed_request('POST', '/withdrawals/requests', {})

Sample Response

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

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/digital_asset_addresses and GET /withdrawals/fiat_accounts endpoints.

There are 3 ways to submit withdrawal requests:

  1. 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.
  2. The second method allows for submitting a digital asset address instead of the withdrawal_account_id. When POSTing an address, Zero Hash will first scan to see if you already have an existing withdrawal_account_id for that destination, and if not, it will create one automatially and provide you the withdrawal_account_id in response. This is not available as standard. Please contact us if you'd like to learn more about this option.
  3. The third method allows for submitting a fiat withdrawal account{} instead of the withdrawal_account_id. When POSTing an account{}, Zero Hash will first scan to see if you already have an existing withdrawal_account_id for that destination, and if not, it will create one automatially and provide you the withdrawal_account_id in response. This is not available as standard. Please contact us if you'd like to learn more about this option.

Request body:

Parameter Description Type
client_withdrawal_request_id A unique identifier for the withdrawal, generally produced by the Platform on which the trade was executed
Note: this must be unique, per platform, per 24 hour period
string
withdrawal_account_id The whitelisted withdrawal account or address to withdraw funds to
Note: only one of withdrawal_account_id, address or account{} can be submitted per withdrawal, but Zero Hash will always respond with withdrawal_account_id
string
address The digital asset address to withdraw funds to, which may or may not already exist in Zero Hash as an approved withdrawal_account_id
Note: only one of withdrawal_account_id, address or account{} can be submitted per withdrawal, but Zero Hash will always respond with withdrawal_account_id
string
account{} The fiat account to withdraw funds to, which may or may not already exist in Zero Hash as an approved withdrawal_account_id
Note: only one of withdrawal_account_id, address or account{} can be submitted per withdrawal, but Zero Hash will always respond with withdrawal_account_id
object
participant_code The participant code against whom the withdrawal will be made 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 string
asset The asset code for the withdrawal request, e.g. BTC string
destination_tag The destination tag or memo ID associated with the transaction
If the asset is EOS, XLM or XRP and no_destination_tag is false, then this is required
string
no_destination_tag Whether or not the specific withdrawal and destination address requires a destination tag
If the asset is EOS, XLM or XRP, this field is required
Note: Zero Hash requires that no_destination_tag be false for EOS
boolean
gas_price Applicable only for ERC-20 tokens, the transaction fee payable on the Ethereum network - refer to our FAQ on how this works string
input_data Applicable only for smart contract executions on the Ethereum blockchain. This is the ABI encoding of the function and its arguments in RLP format. string

Account field shape:

Parameter Description Type
name The nickname given to the withdrawal account
Note: Zero Hash will append the last 4 digits of the account number to this when saving it
string
limit The limit applied to the account on a per-withdrawal basis number
type The type of account: REAL_TIME_FIAT for 24/7 USD withdrawals, DOMESTIC_FIAT for US wires or INTERNATIONAL_FIAT for international wires string
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

DELETE /withdrawals/requests/:id

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.zerohash.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",
    "requestor_participant_code": "ABCDEF",
    "requested_amount": "20",
    "account_group": "00SCXM",
    "settled_amount": null,
    "status": "REJECTED",
    "asset": "BTC",
    "requested_timestamp": 1561996924964,
    "gas_price": null,
    "client_withdrawal_request_id": null
  }
}

Rejects a pending withdrawal request.

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.zerohash.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": "M9zjMhjaPfwaeyeH2SY6aWyGqdTS9feg8Z",
      "status": "APPROVED",
      "limit": 1000,
      "asset": "LTC",
      "last_update": 1554395972174,
      "submitted_address": "33nb3pKcSZ69rUNNvZYkksisWvrzCmi3Jt",
      "participant_code": "ABCDEF"
    }
  ],
  "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 limit applied to the account on a per-withdrawal basis number
last_update Timestamp for when the withdrawal address last update timestamp
submitted_address This is the original value for an address submitted by you, that was converted into a newer format supported by Zero Hash - this will be null if no conversion is necessary string
participant_code The participant the request belongs to, e.g. ABCDEF string

GET /withdrawals/digital_asset_addresses/:id

const getWithdrawalAddresses = () => {
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'GET' + '/withdrawals/digital_asset_addresses/:id' + '{}'
  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.zerohash.com/withdrawals/digital_asset_addresses/:id',
    options
  )
}
withdrawalAddresses = make_seed_request('GET', '/withdrawals/digital_asset_addresses/:id', {})

Sample Response

{
  "message": {
    "withdrawal_account_id": 123,
    "name": "Fund ABC Wallet",
    "address": "M9zjMhjaPfwaeyeH2SY6aWyGqdTS9feg8Z",
    "status": "APPROVED",
    "limit": 1000,
    "asset": "LTC",
    "last_update": 1554395972174,
    "submitted_address": "33nb3pKcSZ69rUNNvZYkksisWvrzCmi3Jt",
    "participant_code": "ABCDEF"
  }
}

Returns a specific crypto withdrawal account associated with your participant or platform.

See GET /withdrawals/digital_asset_addresses for response field descriptions.

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.zerohash.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,
      "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,
      "last_update": 1571175076187,
      "participant_code": "ABCDEF"
    },
    { ... }
  ],
  "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
type The type of account: REAL_TIME_FIAT for 24/7 USD withdrawals, DOMESTIC_FIAT for US wires or INTERNATIONAL_FIAT for international wires string
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
last_update Timestamp for when the withdrawal address last update timestamp
submitted_address This is the original value for an address submitted by you, that was converted into a newer format supported by Zero Hash - this will be null if no conversion is necessary string
participant_code The participant the request belongs to, e.g. ABCDEF string

GET /withdrawals/fiat_accounts/:id

const getFiatWithdrawalAccounts = () => {
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'GET' + '/withdrawals/fiat_accounts/:id' + '{}'
  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.zerohash.com/withdrawals/fiat_accounts/:id',
    options
  )
}
zeroHashAccounts = make_seed_request('GET', '/withdrawals/fiat_accounts/:id', {})

Sample Response

{
  "message": {
    "withdrawal_account_id": 286,
    "name": "Primary (1234)",
    "status": "PENDING_CREATION",
    "asset": "USD",
    "limit": 750000,
    "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,
    "last_update": 1571175076187,
    "participant_code": "ABCDEF"
  }
}

Returns a specific fiat withdrawal account associated with your participant or platform.

See GET /withdrawals/fiat_accounts for response field descriptions.

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

Withdrawal Account Status

Status Description
PENDING_CREATION Account is awaiting approval
APPROVED The account is approved for use
REJECTED The account was rejected for use
DELETED The account was deleted, removing it from view in the portal
PENDING_CHANGE DEPRECATED The address is awaiting a change approval for either unlocking or changing the limit

Transfers

GET /transfers

const getTransfers = () => {
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'GET' + '/transfers' + '{}'
  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.zerohash.com/transfers', options)
}
resp = make_seed_request('GET', '/transfers', {})

Sample Response

{
  "message": [
    {
      "id": 39,
      "created_at": "2020-09-01T20:53:31.653Z",
      "updated_at": "2020-09-01T20:53:31.653Z",
      "status": "settled",
      "from_participant_code": "ABC123",
      "from_account_group": "UNALLOCATED",
      "from_account_label": "general",
      "to_participant_code": "DEMO01",
      "to_account_group": null,
      "to_account_label": "general",
      "asset": "BTC",
      "amount": "20.00",
      "movement_id": "1902a0eb-a925-4d08-bcad-ea8ed4696a24",
      "admin_transfer": true
    },
    {
      "id": 38,
      "created_at": "2020-09-01T20:53:31.406Z",
      "updated_at": "2020-09-01T20:53:31.406Z",
      "status": "approved",
      "from_participant_code": "ABC123",
      "from_account_group": "UNALLOCATED",
      "from_account_label": "general",
      "to_participant_code": "ABC123",
      "to_account_group": "XYZ456",
      "to_account_label": "general",
      "asset": "USD",
      "amount": "100.00",
      "movement_id": null,
      "admin_transfer": false
    }
  ],
  "page": 1,
  "total_pages": 1
}

Returns an array of all transfers requests made to or from your participant, or to or from your platform's account group.

Response:

Parameter Description Type
id The transfer request ID number
created_at The timestamp when the transfer request was requested timestamp
updated_at The timestamp when the transfer request was last updated timestamp
status The current status of the transfer request string
from_participant_code The source participant for the transfer to, e.g. ABCDEF string
from_account_group The source account group for the transfer, e.g. ABCDEF
Note: this may be null if the requesting participant is not authorized to see the source account group
string
from_account_label The source account label for the transfer, e.g. general string
to_participant_code The destination participant for the transfer, e.g. ABCDEF string
to_account_group The destination account group for the transfer, e.g. ABCDEF
Note: this may be null if the requesting participant is not authorized to see the destination account group
string
to_account_label The destination account label for the transfer, e.g. general string
asset The asset code for the request, e.g. USD string
amount The amount or quantity transferred, e.g. 100 string
movement_id A unique ID for the specific account update
Note: this will be null until the transfer updates to settled
string

Transfer Request Status

Status Description
PENDING The request has been created and is pending approval from users
APPROVED The request is approved but not settled
CANCELED The request is canceled and in a terminal state
REJECTED The request is rejected and in a terminal state
SETTLED The request was settled and is in a terminal state

GET /transfers/:id

const getTransfers = () => {
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'GET' + '/transfers/39' + '{}'
  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.zerohash.com/transfers/39', options)
}
resp = make_seed_request('GET', '/withdrawals/requests/39', {})

Sample Response

{
  "message": [
    {
      "id": 39,
      "created_at": "2020-09-01T20:53:31.653Z",
      "updated_at": "2020-09-01T20:53:31.653Z",
      "status": "settled",
      "from_participant_code": "ABC123",
      "from_account_group": "UNALLOCATED",
      "to_participant_code": "DEMO01",
      "to_account_group": null,
      "asset": "BTC",
      "amount": "20.00",
      "movement_id": "1902a0eb-a925-4d08-bcad-ea8ed4696a24",
      "admin_transfer": true
    }
  ]
}

Returns single transfer made to or from your participant, or to or from your platform's account group.

See GET /transfers for response field descriptions.

POST /transfers

const postTransfers = () => {
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'POST' + '/transfers' + '{}'
  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.zerohash.com/transfers', options)
}
resp = make_seed_request('POST', '/transfers', {})

Creates new transfer request. Note: you can only submit transfers between your own accounts. To submit transfers on behalf of others, you need the submits_platform_transfers_for relationship (see here for more information). Transfer requests created through the API go directly into an APPROVED state.

Request body:

Parameter Description Type
from_participant_code The source participant for the transfer to, e.g. ABCDEF string
from_account_group The source account group for the transfer, e.g. ABCDEF string
from_account_label The source account label for the transfer, e.g. general string
to_participant_code The destination participant for the transfer, e.g. ABCDEF string
to_account_group The destination account group for the transfer, e.g. ABCDEF string
to_account_label The destination account label for the transfer, e.g. general string
asset The asset code for the request, e.g. USD string
amount The amount or quantity transferred, e.g. 100 string

Sample Response

{
  "message": [
    {
      "id": 39,
      "created_at": "2020-09-01T20:53:31.653Z",
      "updated_at": "2020-09-01T20:53:31.653Z",
      "status": "settled",
      "from_participant_code": "ABC123",
      "from_account_group": "UNALLOCATED",
      "from_account_label": "general",
      "to_participant_code": "DEMO01",
      "to_account_group": "UNALLOCATED",
      "to_account_label": "general",
      "asset": "BTC",
      "amount": "20.00",
      "movement_id": "1902a0eb-a925-4d08-bcad-ea8ed4696a24",
      "admin_transfer": true
    }
  ]
}

See GET /transfers for response field descriptions.

Participants

GET /participants

const getParticipants = () => {
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'GET' + '/participants' + '{}'
  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.zerohash.com/participants', options)
}
resp = make_seed_request('GET', '/participants', {})

Sample Response

{
  "message": [
    {
      "participant_code": "123XYZ",
      "participant_name": "Trading Firm LLC",
      "relationship_types": [
        "customer_of_platform"
      ],
      "credit_limit": "50000",
      "email": "[email protected]"
    },
    {
      "participant_code": "ABC456",
      "participant_name": "Lots of Capital LLC",
      "relationship_types": [
        "customer_of_platform"
      ],
      "credit_limit": null,
      "email": null
    }
  ],
  "page": 1,
  "total_pages": 1,
  "page_size": 50,
  "count": 2
}

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

Query parameters include:

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
You can find all relationship types and more information on what each time means here
string[]
credit_limit Client-determined credit limit. used purely for reporting purposes at this time string
email Email associated with the participant. If the participant is institutional, this field will be null string

GET /participants/:email

const getParticipants = () => {
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'GET' + '/participants/{email}' + '{}'
  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.zerohash.com/participants/{email}', options)
}
resp = make_seed_request('GET', '/participants/{email}', {})

Sample Response

{
  "message": {
    "participant_code": "123XYZ",
    "email": "[email protected]"
  }
}

Returns a participant to which you are associated by an email. As an alternative to using the email query parameter described above within the GET /participants endpoint, this is a lighter-weight and dedicated endpoint to filter participants by email.

Query parameters include:

Response parameters listed below

Parameter Description Type
participant_code Unique participant code string
email Email associated with the participant string

POST /participants/customers/new

const postParticipantCustomer = () => {
  const body = {
    first_name: "John",
    last_name: "Smith",
    address_one: "1 Main St.",
    address_two: "Suite 1000",
    country: "United States",
    signed_timestamp: "1603378501286",
    email: "[email protected]",
    metadata: {},
    state: "IL",
    city: "Chicago",
    date_of_birth: "1985-09-02",
    id_number_type: "ssn",
    id_number: "123456789",
    zip: "12345"
  }
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'POST' + '/participants/customers/new' + 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.zerohash.com/participants/customers/new`,
    options
  )
}
resp = make_seed_request('POST', '/participants/customers/new', {})

Sample Request

{
  "first_name": "John",
  "last_name": "Smith",
  "email": "[email protected]",
  "address_one": "1 Main St.",
  "address_two": "Suite 1000",
  "city": "Chicago",
  "state": "IL",
  "zip": "12345",
  "country": "United States",
  "date_of_birth": "1985-09-02",
  "id_number_type": "ssn",
  "id_number": "123456789",
  "signed_timestamp": 1603378501286,
  "metadata": {}
}

Sample Response

{
  "message": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "[email protected]",
    "address_one": "1 Main St.",
    "address_two": "Suite 1000",
    "country": "United States",
    "state": "IL",
    "city": "Chicago",
    "zip": "12345",
    "date_of_birth": "1985-09-02",
    "id_number_type": "ssn",
    "id_number": "123456789",
    "non_us_other_type": null,
    "id_issuing_authority": null,
    "signed_timestamp": 1603378501286,
    "risk_rating": null,
    "metadata": {},
    "platform_code": "ABC123",
    "participant_code": "XYZ456"
  }
}

Submits a customer to your platform.

Request body:

Parameter Description Type
first_name The first name of the customer, required string
last_name The last name of the customer, required string
email Customer email address, required
Note: Zero Hash will validate that the email is a correctly formatted email, and that the value is unique per-platform
string
address_one First line for the customer's address, required
Note: PO Box addresses are not accepted
string
address_two First line for the customer's address, if applicable, optional string
city The city customer resides in, required string
state The state the customer resides in, required if country is "United States"
Note: must be one of the supported states
string
zip Zip code of the customer in the format <5digits> or <5digits>-<4digits>, e.g. 77777 or 77777-7777, required if country is "United States" string
country The country the customer resides in, required
Note: must be one of the supported countries
string
date_of_birth Date of birth of the customer in the format YYYY-MM-DD, required string
id_number_type The type of ID document provided, required
Note: must be one of the supported ID types
string
id_number The ID number for the customer, required string
non_us_other_type This is required if you select non_us_other for the id_number_type - a freeform string to describe the ID type string
id_issuing_authority The issuing authority for the ID, if available, optional string
risk_rating The risk-rating associated with the customer, conditionally required for certain platforms string
signed_timestamp The time when the Zero Hash Services Agreement was signed timestamp
metadata Can be used to submit any additional unstructed metadata object

Additional fields in response:

Parameter Description Type
platform_code The unique identifier for the Platform onto which the customer has been created string
participant_code The Zero Hash identifier for the new customer
Note: this value is key to enable you to submit trades and check account balances for this customer
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.

ID Types

Valid options are:

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.zerohash.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

Liquidity

GET /liquidity/rfq

const getQuote = () => {
  const body = '{}'
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'GET' + '/liquidity/rfq' + 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.get(`https://api.zerohash.com/liquidity/rfq`, options)
}
accounts = make_seed_request('GET', '/liquidity/rfq', {})

Sample Response

{
  "request_id": "ce819fe8-b1d7-43bb-961c-e09ede0988d3",
  "participant_code": "CUST01",
  "underlying": "BTC",
  "quoted_currency": "USD",
  "side": "BUY",
  "quantity": "1",
  "price": "11430.90",
  "quote_id": "5cd07738b861c31e3bd61467BTC1Buy1568311644602",
  "expire_ts": 1568311649602,
}

Returns a quote to buy or sell a certain asset, in return for another asset. See one-pager here for more details.

Query parameters include:

Response:

Parameter Description Type
request_id The identifier of the RFQ string
participant_code The identifier of the participant making the quote request string
underlying The asset code for the underlying currency, e.g. BTC string
quoted_currency The asset code for the quoted currency, e.g. USD string
side The participant side of the quote - buy or sell string
quantity The amount of the quoted currency string
price The amount of the underlying currency string
quote_id The identifier for the quote
Note: this is required to execute the quote
string
expire_ts Timestamp when the quote will expire timestamp

POST /liquidity/execute

const executeQuote = (id: string) => {
  const body = '{ "quote_id":' + id + '}'
  const timestamp = Math.round(Date.now() / 1000)
  const payload = timestamp + 'GET' + '/liquidity/execute' + 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.zerohash.com/liquidity/execute`, options)
}
accounts = make_seed_request('POST', '/liquidity/execute', {"quote_id": id})

Sample Response

{
  "request_id": "14f8ebb8-7530-4aa4-bef9-9d73d56313f3",
  "quote": {
    "request_id": "ce819fe8-b1d7-43bb-961c-e09ede0988d3",
    "participant_code": "CUST01",
    "underlying_currency": "BTC",
    "quoted_currency": "USD",
    "side": "BUY",
    "quantity": "1",
    "price": "11430.90",
    "quote_id": "5cd07738b861c31e3bd61467BTC1Buy1568311644602",
    "expire_ts": 1568311649602
  },
  "trade_id": "ba97133e-ab15-4c86-86c1-86671b8420bc",
  "status": "Completed"
}

Executes the quote identified by quote_id. The completed trade is submitted to settlement via the 00SCXM platform.

Body parameters include:

Response:

Parameter Description Type
request_id The identifier of the RFQ string
quote The quote object that was executed quote
trade_id The unique identifier assigned to the trade, which is the same trade_id as found in a GET /trades request
Note: the quote_id will be saved as the client_trade_id
string
status The status of the trade, e.g. Completed string

Private Socket Feed

Balances

Connecting

Initial Subscription

const WebSocket = require('ws')
const crypto = require('crypto')

const KEY = '...'
const SECRET = '...'
const PASSPHRASE = '...'

const sendWebsocketMessage = (client, type, body, secret, key, phrase) => {
  const TIMESTAMP = String(Math.round(Date.now() / 1000))
  const payload = TIMESTAMP + 'POST' + 'undefined' + JSON.stringify(body)
  const decodedSecret = Buffer.from(secret, 'base64')
  const hmac = crypto.createHmac('sha256', decodedSecret)
  const signedPayload = hmac.update(payload).digest('base64')

  client.send(JSON.stringify({
    messageType: type,
    body: body,
    KEY: key,
    PASSPHRASE: phrase,
    TIMESTAMP,
    SIGNED: signedPayload
  }))
}

const ws = new WebSocket(`wss://ws.zerohash.com`)

ws.on('open', () => {
  sendWebsocketMessage(ws, 'subscribe', { filter: {} }, SECRET, KEY, PASSPHRASE)
})

ws.on('message', (data) => {
  console.log(data)
})

ws.on('error', (data) => {
  console.error(data)
})

setInterval(() => {
  sendWebsocketMessage(ws, 'ping', {}, SECRET, KEY, PASSPHRASE)
}, 10000)
# Even after removing type annotations, the below code works with Python 3.4+ only.
# For ease of use, Python 3.6+ is recommended if using websockets.

import asyncio
import hashlib
import hmac
import json
from base64 import b64decode, b64encode
from datetime import datetime
from logging import getLogger

import websockets

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 = 'ws.zerohash.com'
WS_URL = 'wss://' + URL_BASE
API_PUBLIC_KEY = '...'
API_PRIVATE_KEY = '...'
PASSPHRASE = '...'


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())


async def connect_private():
    """Connect to the private websocket endpoint that requires authentication."""
    async with websockets.connect(WS_URL) as conn:
        t = str(int(datetime.now().timestamp()))
        sig = sign(API_PRIVATE_KEY, 'POST', 'undefined', json.dumps({}), t)
        # NB: there is no messageType and payload for an auth message
        await conn.send(
            json.dumps({
                'body': {},
                'KEY': API_PUBLIC_KEY,
                'PASSPHRASE': PASSPHRASE,
                'TIMESTAMP': t,
                'SIGNED': sig.decode('utf-8')
            })
        )
        while True:
            message_handler(await conn.recv())


def message_handler(msg: str):
    """Print the parts of the message. Simple example of message handling.

    :param msg: Message string to process
    """
    try:
        msg = json.loads(msg)
    except json.JSONDecodeError:
        logger.error('Error loading JSON message from server: {}'.format(msg))
        return
    if 'message' in msg:
        logger.info(msg['message'])
        return
    logger.info('Received {} message'.format(msg['messageType']))
    logger.info('Payload: {}'.format(msg['payload']))


# Run the event loop
loop = asyncio.get_event_loop()
loop.run_until_complete(connect_private())

Our private websocket feed URL is wss://ws.zerohash.com

Once connected, you will need to subscribe to your balance updates.

Parameter Description Type
body{} An object used to restrict what is returned in the subscription object
messageType Subscription message type - subscribe string
key Your public key string
passphrase Your passphrase string
timestamp Time in seconds since Unix Epoch string
signed your hmac signature string

Subscription Filters

Optional filters you can include within the body to restrict what the WebSocket will emit updates about:

Parameter Description Type
filter{} A filter object used to specify account characteristics object
skipInitialBalance A boolean to determine whether the WebSocket should send you a snapshot of all account balances that match your filter boolean

The filter{} object can include:

Parameter Description Type
account_owner The code for the specific participant you want updates for string
account_group The group that you want updates for string
account_type The type that you want updates for - available, collateral, payable, receivable or collateral_deficiency string
asset The asset code you would like updates for string

Subscription Response

Subscription Response

{
  "messageType": "subscribed",
  "body": "0000-0000"
}

Upon successfully subscribing you will receive a subscription confirmation message with subscription ID.

Maintaining Subscription

Ping Message

{
  "messageType": "ping"
}

Once the connection is established, you will need to sed a ping request every 20 seconds to maintain the subscription, or the connection will be closed.

Initial Balance

Sample Response

{
  "messageType": "initial-balance",
  "body": {
    "account_id": "12345",
    "account_owner": "ABC123",
    "account_group": "XYZ456",
    "account_type": "available",
    "balance": "1.0",
    "asset": "BTC",
    "last_update": "2020-05-28T13:14:15.929Z"
  }
}

An initial-balance message includes a snapshot of all current account balances that meet your subscription criteria. Results will be paginated.

Parameter Description Type
account_id Unique ID of the specific account string
account_owner The code of the participant that owns the account string
account_group The group that the account is a part of string
account_type available, collateral, payable, receivable or collateral_deficiency string
balance The balance in the account string
asset The asset code for the specific account, e.g. USD string
last_update Timestamp when the account balance was updated timestamp

Balance Update

Sample Response

{
  "messageType": "balance-updated",
  "body": {
    "account_id": "12345",
    "participant_code": "00AABB",
    "account_group": "12345",
    "account_type": "available",
    "new_balance": "1.0",
    "change": "1.0",
    "asset": "BTC",
    "run_timestamp": "2020-05-28T13:14:15.929Z",
    "run_type": "deposit",
    "run_id": "12345",
    "movements": [
      {
        "movement_timestamp": "2020-05-28T13:14:15.929Z",
        "movement_id": "1",
        "movement_type": "deposit",
        "trade_id": "1",
        "deposit_reference_id": "1",
        "withdrawal_request_id": null,
        "transfer_request_id": null,
        "change": "100.00"
      }
    ]
  }
}

After receiving the initial-balance message, you will be sent incremental balance-updated messages, which show any balance changes to accounts that meet your subscription criteria.

Parameter Description Type
account_id Unique ID of the specific account string
participant_code The code of the participant that owns the account string
account_group The group that the account is a part of string
account_type available, collateral, payable, receivable or collateral_deficiency string
new_balance Updated balance value string
change The difference of an old and new balance string
asset The asset code for the specific account, e.g. USD string
run_timestamp Timestamp when the account balance was updated timestamp
run_type The type of run string
run_id A unique ID for the particular run string
movements[] An array of movements related to the specific account update
Refer to the GET /accounts/:account_id/movements section for field definitions
array