Sign in

v1

latestOpenAPI 3.1.02026-07-241653251.3 MB
Trades

Submit batch of trades

Submits a batch of trades for settlement that was matched and executed outside of zerohash.

post/trades/batch

Headers

X-SCX-SIGNEDstring required

HMAC-SHA256 signature of the request, base64-encoded. See the Authentication guide for the exact signing formula.

X-SCX-TIMESTAMPstring required
Example:1678901234

Current Unix timestamp in seconds. Must be within 60 seconds of server time or the request is rejected.

Request body

batch_trade_idstring nullable

A unique identifier for a batch of trades. Null when the trade was not submitted as part of a batch.

client_trade_idstring required

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 72 hour period

trade_reporterstring required

A text field to indicate the name or identifier of the person or entity submitting the trade, e.g. an email address

trade_reporter_codestring

A code to identify the person or entity submitting the trade

reporting_partystring nullable

The original reporter of the trade. This field is optional and must be a 6 digit participant code of which you have proper relationships with. Null when not supplied at trade submission.

settlement_schedulestring nullable

Instructs zerohash to settle trades according to a certain schedule. Null when not supplied at trade submission.

platform_codestring required

The unique identifier to the Platform on which the trade was executed, as provided by zerohash.

market_identifier_codestring nullable

The ISO 10383 market identifier code for the platform. Null when not supplied at trade submission.

symbolstring required

A free text field to identify the pair being traded, e.g. BTC/USD

product_type'spot' | 'forward' required

spot or forward

trade_type'regular' | 'block' required

The type of trade to be settled. Valid values are regular or block

trade_pricestring required

The price the trade was executed 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.

trade_quantitystring

The quantity purchased Note: if the amount is included per side, then this should not be included, otherwise it is required

trade_state'accepted' | 'active' | 'terminated'

The current state of the trade;

  • accepted : The trade has been booked by zerohash and pending settlement in the next settlement cycle between the platform and zerohash.
  • active : The trades are eligible for settlement and there are pending payable and receivable obligations.
  • terminated : The trade has been terminated by settlement.
physical_deliveryboolean required

A boolean statement to indicate if the trade is physically delivered. Currently zerohash only supports physically-settled trades, i.e. a value of true

transaction_timestampnumber required

The unix timestamp the trade was executed on the external platform in milliseconds

accepted_timestampnumber

The unix timestamp at which the trade was accepted by zerohash and entered into an accepted status.

defaulted_timestampnumber nullable

The unix timestamp in milliseconds at which the trade was defaulted. Null when the trade has not defaulted.

settled_timestampnumber nullable

The unix timestamp in milliseconds at which the trade entered a settled state. Trades are generally settled instantaneously. Null until the trade is settled.

commentstring nullable

Some comments about the trade for zerohash to store. Null when not supplied at trade submission.

last_updatenumber

The unix timestamp of the last update to the trade object.

parties_anonymousboolean required

A boolean flag to determine if the counterparties are known to each other (false if the platform_code is also a counterparty) to the trade.

settlement_price_index_idstring nullable

The unique identifier of the benchmark settlement price to be used when calculating settlement obligations on trades that are settled at zerohash - required for forwards only. Null for spot trades.

contract_sizenumber

The contract size

underlying'AAVE.ETH' | 'ADA' | 'ALGO' | 'AVAX' | 'BAT.ETH' | 'BCH' | 'BTC' | 'BUSD.ETH' | 'COMP.ETH' | 'DAI.ETH' | 'DOGE' | 'DOT' | 'EGLD' | 'EOS' | 'ETC' | 'ETH' | 'ETH.ARBITRUM' | 'GRT.ETH' | 'GYEN.ETH' | 'HBAR' | 'LINK.ETH' | 'LTC' | 'LUNA' | 'MATIC.ETH' | 'MATIC.POLYGON' | 'MKR.ETH' | 'MOB' | 'SAND.ETH' | 'SOL' | 'UNI.ETH' | 'USDC.ETH' | 'USDC.ALGO' | 'USDC.POLYGON' | 'USDC.SOL' | 'USDC.HBAR' | 'USDC.XLM' | 'USDC.AVAX' | 'USDT.ETH' | 'UST' | 'WBTC.ETH' | 'XEM' | 'XLM' | 'XRP' | 'XTZ' | 'ZUSD.ETH'

the underlying asset

quoted_currency'CAD' | 'EUR' | 'GBP' | 'JPY' | 'MXN' | 'USD'

the quoted asset

settlement_timestampnumber nullable

The unix timestamp in milliseconds when final settlement will first be attempted - if not included, the standard platform settlement instructions will be applied. Null when not supplied at trade submission.

expiry_timestampnumber nullable

The last unix timestamp in milliseconds 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. Null for spot trades.

bank_feestring nullable

An optional field that clients can use to specify the fee taken by the banking partner (supports 2 decimal places). Null when not supplied at trade submission.

spread_notionalstring nullable

The spread_notional is a field that shows the notional cost of the spread applied to the trade. This field is relevant for trades that are executed using the zerohash RFQ system. Returns null when no spread applied.

spread_bpsstring nullable

The spread_bps is a field that shows the spread in basis points that was applied to the trade. This field is relevant for trades that are executed using the zerohash RFQ system. Returns null when no spread applied.

issuer_fee_ratestring nullable

The rate (in basis points) of the issuer fee applied to the trade. Returns null when no issuer fee applied.

issuer_fee_amountstring nullable

The notional amount of the issuer fee applied to the trade, denominated in the quoted_currency. Returns null when no issuer fee applied.

issuer_fee_payor_type'null' | 'CUSTOMER' | 'PARTICIPANT' | 'PLATFORM' nullable

The type of payor that paid the issuer fee. Returns null when no issuer fee applied.

origin'rest_api' | 'sdk' | 'secondary' | 'null' nullable

Specifies the method through which the movement was initiated, indicating whether it originated via our REST API, SDK, or Secondary Portal. Returns null for legacy/externally-reported trades.

session_idstring

A session identifier to group filled orders that were executed in the same trading session on the zerohash CLOB. An empty string is returned when the trade was not executed on the zerohash CLOB.

Example request

[
  {
    "batch_trade_id": "f2f14251-e296-42ac-9bc7-01c9186b9219",
    "client_trade_id": "f2f14251-e296-42ac-9bc7-01c9186b9219",
    "trade_reporter": "user@00SCXM.com",
    "trade_reporter_code": "00SCXM",
    "reporting_party": "SCXM",
    "settlement_schedule": "ABCDEF",
    "platform_code": "PLAT01",
    "market_identifier_code": "SCXM",
    "symbol": "BTC/USD",
    "product_type": "spot",
    "trade_type": "regular",
    "trade_price": "10000",
    "trade_quantity": "1.0",
    "physical_delivery": true,
    "transaction_timestamp": 2554408627334,
    "accepted_timestamp": 2554408627334,
    "defaulted_timestamp": 2554408627334,
    "settled_timestamp": 2554408627334,
    "comment": "OTC trade executed via phone instruction",
    "last_update": 2554408627334,
    "parties_anonymous": true,
    "underlying": "BTC",
    "quoted_currency": "USD",
    "settlement_timestamp": 2554408627334,
    "expiry_timestamp": 2554408627334,
    "bank_fee": "1.00",
    "spread_notional": "2.50",
    "spread_bps": "100",
    "origin": "rest_api",
    "parties": [
      {
        "side": "buy",
        "participant_code": "ABCDEF",
        "asset": "BTC",
        "amount": "0.00001",
        "liquidity_indicator": "removed",
        "client_order_id": "14f8ebb8-7530-4aa4-bef9-9d73d56313f3",
        "order_id": "593dd810-f051-40a9-9f26-d45280efe8f3",
        "obligations_outstanding_timestamp": 2554408627334,
        "current_obligations_met_timestamp": 2554408627334,
        "settlement_state": "settled",
        "execution_id": "593dd810-f051-40a9-9f26-d45280efe8f3",
        "account_label": "general",
        "collateral_percentage": "0.1",
        "account_profile": "nonprefunded",
        "trader": "ABCDEF",
        "manual_order_indicator": "manual"
      }
    ],
    "session_id": "20260504115000",
    "payment_processor": {
      "name": "checkout.out",
      "id": "593dd810-f051-40a9-9f26-d45280efe8f3"
    },
    "fees": [
      {
        "name": "sample",
        "amount": "1.95"
      }
    ]
  }
]

Response

Successfully created batch of trades. Returns the created resource with generated IDs and timestamps.

Example response

{
  "message": [
    {
      "batch_trade_id": null,
      "trade_id": "78260d47-336e-4253-b800-d528894253b2",
      "client_trade_id": "40b402b0-22ad-4d67-ae8c-7964be34ee29",
      "trade_state": "terminated",
      "market_identifier_code": "SCXM",
      "trade_reporter_code": "00SCXM",
      "symbol": "BTC/USD",
      "trade_quantity": "0.00059241",
      "trade_price": "81531.3718539524991138",
      "trade_type": "regular",
      "physical_delivery": true,
      "comment": "",
      "last_update": 1778771702391,
      "transaction_timestamp": 1778771677000,
      "accepted_timestamp": 1778771677972,
      "defaulted_timestamp": null,
      "settled_timestamp": 1778771702360,
      "expiry_timestamp": null,
      "settlement_timestamp": null,
      "settlement_price_index_id": null,
      "contract_size": 1,
      "underlying": "BTC",
      "quoted_currency": "USD",
      "trade_reporter": "00SCXM",
      "platform_code": "00SCXM",
      "product_type": "spot",
      "parties_anonymous": false,
      "bank_fee": null,
      "reporting_party": "00SCXM",
      "settlement_schedule": null,
      "parties": [
        {
          "settling": true,
          "participant_code": "DL1BXT",
          "side": "buy",
          "asset": "BTC",
          "amount": "0.00059241",
          "liquidity_indicator": null,
          "execution_id": "",
          "order_id": "",
          "obligations_outstanding_timestamp": null,
          "current_obligations_met_timestamp": null,
          "settlement_state": "settled",
          "client_order_id": "",
          "collateral_percentage": null,
          "account_label": "general",
          "account_profile": null,
          "trader": null,
          "zrn": null,
          "manual_order_indicator": null
        },
        {
          "settling": true,
          "participant_code": "00SCXM",
          "side": "sell",
          "asset": "USD",
          "amount": "48.3",
          "liquidity_indicator": null,
          "execution_id": "",
          "order_id": "",
          "obligations_outstanding_timestamp": null,
          "current_obligations_met_timestamp": null,
          "settlement_state": "settled",
          "client_order_id": "",
          "collateral_percentage": null,
          "account_label": "inventory",
          "account_profile": null,
          "trader": null,
          "zrn": null,
          "manual_order_indicator": null
        }
      ],
      "session_id": "20260514151438",
      "fees": [
        {
          "name": "LiquidityFee",
          "amount": "1.7"
        }
      ],
      "issuer_fee_rate": "0",
      "issuer_fee_amount": "0",
      "issuer_fee_payor_type": null,
      "payment_processor": null,
      "network_fee_notional": null,
      "network_fee_quantity": null,
      "total_notional": "50.00",
      "asset_cost_notional": "48.30",
      "origin": "rest_api",
      "spread_notional": "0.12075",
      "spread_bps": "25"
    }
  ]
}