HaggleDigital

QuickStart

Submit Orders

Submit Orders and confirm they are working in the Market.

Back to Getting Started with the API

Orders

With a Market created and opened, trading on the Market can begin. Orders can be accepted into the Market and matched on price to trade and create Fills.

A User can query the system to view the current state of Orders that they have submitted. Orders from other Users cannot be viewed, but will be visible anonymously in Price data, which is covered later.

Link to Orders documentation

Submit an Order

The call to submit a new Order requires some mandatory parameters and several optional parameters.

The Order requires a Market key to define which Market the Order is for. The Order also requires a Buy-Sell indicator [B|S], and a quantity value for the amount of Transactional Tradeable Item. Also, an Order Type is required [LIMIT|MARKET|STOPLIMIT|STOPMARKET], and also mandatory is a TimeInForce parameter [GTC|GTD|DAY]. Please refer to the Orders documentation for a full explanation of Order parameters and behaviour.

A LIMIT or STOPLIMIT Order will normally require a Limit Price, supplied in the limit_px field. Similarly, if the Order is a STOPMARKET or STOPLIMIT Order, a Stop Price is required, that is used to determine when the Order should trigger into the Market.

The TimeInForce field, time_in_force, should be set to either GTC, GTD, or DAY. A GTC Order is Good Til Cancel, and will remain working in the Market until the submitting User cancels it, even if the Market closes and opens again later. A GTD Order is Good Til Date, and is automatically canceled by the system once the expiry datetime passes. A DAY Order is good for the Day, in that it works until the current Market open session closes.

The User can submit the Order with their own optional Client Order ID in the cl_ord_id field. If the Order is generated from an external system, that system may have sales reference codes, and this field can be used to tag the Order with the external system ID.

The OnBehalfOf field can be used to store the identity of the originator of the Order. When using the system for routing Orders, one HaggleDigital User can submit multiple Orders that were submitted on behalf of users of another system.

If the Order has TimeInForce set as GTD (Good Til Date), the expiry field should be set to contain a UTC datetime. The GTD Order will be canceled once the expiry datetime passes.

An Order can be released into the Market at a future time by putting a UTC datetime in the effective field. The system receives the Order and holds it back from the Market until the effective time passes.

A Settlement Quantity can be supplied in the settl_qty field, and this can be used as an alternative to Limit Price. Prices are ratios, and may have many decimal places, so Users may supply a Transactional Quantity and a Settlement Quantity, with the price being the implied ratio. For example, a User may want to buy three items for one dollar; they might supply a limit price of 0.333 recurring, but it may be more convenient, and accurate, to omit a Limit Price and supply a Settlement Quantity of 1 dollar. Either use a Limit Price or a Settlement Quantity, Orders with both will be rejected.

This system supports Average Limit Orders. These Orders apply a Limit Price to the whole Order, on average, rather than each partial fill. The average_limit_flag boolean field can be used to apply this behaviour to the submitted Order.

If additional information has to be tagged to the Order, a free-text field called spare is provided.

  • mkt_pk (mandatory): Primary key for the Market.
  • buy_sell (mandatory): Buy or Sell indicator; [B|S]
  • trans_qty (mandatory): Quantity of Transactional Tradeable Item.
  • ord_type (mandatory): Order Type indicator; [LIMIT|MARKET|STOPLIMIT|STOPMARKET]
  • time_in_force (mandatory): Time in Force indicator; [GTC|GTD|DAY]
  • limit_px (optional): Limit Price.
  • stop_px (optional): Stop Price.
  • cl_ord_id (optional): Client Order ID.
  • on_behalf_of (optional): On Behalf Of.
  • expiry (optional): UTC Datetime after which the Order is canceled.
  • effective (optional): UTC Datetime after which the Order is released into the Market.
  • settl_qty (optional): Amount of Settlement Tradeable Item; Optionally replaces Limit Price.
  • average_limit_flag (optional): Flag indicator [True|False]; Defaults to False.
  • spare (optional): Free text field for additional data.
Windows CMD
              
curl -X POST "https://prod.haggledigital.com/v01/orders/create" ^
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ^
  -H "Content-Type: application/json" ^
  -d "{\"mkt_pk\": \"00000000-0000-0000-0000-000000000001\", \"buy_sell\": \"B\", \"trans_qty\": \"10\", \"time_in_force\": \"GTC\", \"ord_type\": \"LIMIT\", \"limit_px\": \"1.99\"}"
UNIX/MacOS
              
curl -X POST "https://prod.haggledigital.com/v01/orders/create" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "mkt_pk": "00000000-0000-0000-0000-000000000001",
  "buy_sell": "B",
  "trans_qty": "10",  
  "time_in_force": "GTC",  
  "ord_type": "LIMIT",  
  "limit_px": "1.99"
}'

Response

The response will be an HTTP 200 OK message on success, or an error indicating a problem with the supplied data.

In the case of a successful response, a copy of the created Order object is returned, which will include a "pk" field. The value in the "pk" field is the unique identifier key that will be required whenever querying or canceling the Order.

Response
              
{
  "pk": "00000000-0000-0000-0000-000000000010",
  "mkt_pk": "00000000-0000-0000-0000-000000000001",
  "buy_sell": "B",
  "ord_type": "LIMIT",
  "ord_status": "NEW",
  "time_in_force": "GTC",
  "limit_px": "1.99",
  "current_limit_px": "1.99",
  "stop_px": null,
  "avg_px": null,
  "trans_qty": "10",
  "settl_qty": "19.90",
  "trans_open_qty": "-10",
  "settl_open_qty": "19.90",
  "trans_last_qty": null,
  "settl_last_qty": null,
  "trans_fill_qty": null,
  "settl_fill_qty": null,
  "average_limit_flag": false,
  "effective": "",
  "expiry": "",
  "stop_trigger_exec_id": "",
  "spare": "",
  "user_pk": "00000000-0000-0000-0000-000000000020",
  "submitted": "2026-10-16T15:30:00",
  "cl_ord_id": "",
  "on_behalf_of": ""
}

The pk field returned is the Primary Key for the Order, the unique system identifier for the Order that should be used whenever making calls pertaining to this Order.

The current_limit_px is the limit price that the system uses for matching. This value may differ slightly from the limit_px value.

The fields ending "qty" represent quantities of Tradeable Items. These may hold negative values, due to how the system tracks the Order as it fills. For example, a Buy Order starts with a negative value in trans_open_qty and increases, as it trades, towards zero when it completes. Conversely, for a Buy Order, the settl_open_qty starts positive, and decreases to exhaustion at zero. In the example of buying Apples, the Order "wants" Apples and is short 10 of them, and has 19.90 US Dollars to spend. For a Sell Order, the reverse is true, the Order has positive trans_open_qty (Apples to sell) and wants US Dollars, so starts with a negative settl_open_qty and approaches zero as it trades.

Viewing Orders

The GET /v01/orders/multiple endpoint can be used to view Orders submitted by the current User. Supplying the Market key as the mkt_pk query parameter returns Orders submitted by that User for the selected Market, with the most recently submitted Orders returned first. Additional query parameters are available to filter by submission time or Order status, and to control pagination. These are described in the full API documentation.

Note that the GET /v01/orders/single endpoint will take an Order Primary Key as a path parameter (e.g. GET /v01/orders/single/{order_pk}). The combination of these two endpoints allows either targeted querying of specific Orders one-by-one, or broad queries across the User's Orders. These notes only show the multiple endpoint for brevity.

A User can only view Orders that they have submitted. Price data reveals only the transactional quantities and prices for other Orders in the Market, and Price data is anonymous.

Windows CMD
              
curl -X GET "https://prod.haggledigital.com/v01/orders/multiple?mkt_pk=00000000-0000-0000-0000-000000000001" ^
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
UNIX/MacOS
                        
curl -X GET "https://prod.haggledigital.com/v01/orders/multiple?mkt_pk=00000000-0000-0000-0000-000000000001" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

The response will be an HTTP 200 OK or HTTP 204 No Content message on success, or an error indicating a problem with the supplied query parameters.

In the case of a successful response, a list of Order objects is returned. If no Orders are present, an HTTP 204 No Content message is returned.

View Prices

When a Market has Orders working in it, Price data is available. Price data shows the best Buy and Sell Orders working in the Market, to guide Users on current trading activity.

Continue to View Prices.