QuickStart
Create Fills
Submit overlapping Buy and Sell Orders to trade and create Fills.
Back to Getting Started with the API
Trading to Create Fills
When a Market is open, it can receive Buy and Sell Orders. A Market in OPEN state continually assesses the working Orders and attempts to match Buy Orders to Sell Orders.
Orders on opposite sides of the Market can be matched if:
- One Order is a MARKET Order and the Order on the opposite side is a LIMIT Order.
- Both Orders are LIMIT Orders and the price of the Buy Order is equal to or greater than the price of the Sell Order.
If these conditions are met, the Order with the smaller available quantity of the Transactional Tradeable Item determines how much can be transferred. The price then determines how much Settlement Tradeable Item is transferred in exchange. Amounts of both Tradeable Items are constrained to their respective tick sizes, ensuring that all transferred quantities are valid Tradeable Item amounts. A matched transfer between the two Orders is called an execution, or trade.
For every execution, two Fill records are created, one for each Order involved. Each Fill record documents the state of the Order at the time of execution, quantities exchanged, running totals, settlement state and counterparty details.
The Owner of a Market can then download the Fill records, settle the agreed trades externally, and update the Fills to record their Settlement State. The raison d'etre of a Market is to create these agreements.
Link to Settlement documentationSubmit Orders to Trade
The call to submit Orders has been covered previously in Submit Orders. To view the current Market price data, refer to View Prices.
Submit a Buy Order
Using the example Market for Apples in US Dollars, the call below places a Buy Order for 5 Apples at a price of 2.00 US Dollars per Apple.
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\": \"5\", \"time_in_force\": \"GTC\", \"ord_type\": \"LIMIT\", \"limit_px\": \"2.00\"}"
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": "5",
"time_in_force": "GTC",
"ord_type": "LIMIT",
"limit_px": "2.00"
}'
The call should return an HTTP 200 OK message on success. At this point, the Order can be viewed using GET /v01/orders/multiple with the Market key supplied as the mkt_pk query parameter. The current Market Price data can also be viewed using POST /v01/prices/multiple.
Note that the example above uses a LIMIT type Order with a limit price of 2.00 US Dollars per Apple. To trade against this Order, a Sell Order must be submitted. This can be either a Sell MARKET Order, or a Sell LIMIT Order with a price of 2.00 US Dollars or less.
Submit a Sell Order
Below is the example call to place a Sell Order for 10 Apples at a price of 2.00 US Dollars per Apple. This Order uses the same price as the working Buy Order so that the two Orders overlap and an execution can occur.
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\": \"S\", \"trans_qty\": \"10\", \"time_in_force\": \"GTC\", \"ord_type\": \"LIMIT\", \"limit_px\": \"2.00\"}"
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": "S",
"trans_qty": "10",
"time_in_force": "GTC",
"ord_type": "LIMIT",
"limit_px": "2.00"
}'
The call should return an HTTP 200 OK message on success. Within a few seconds, the Market should review the working Orders, match the Buy and Sell Orders, execute the trade, and create the associated Fills.
The GET /v01/orders/multiple endpoint can now be called again for the Market to see the updated state of the two Orders. If the Orders were submitted as above, an execution should have occurred.
The Buy Order will be in FILLED state, and will be removed from the working Orders. All 5 Apples have been bought at a price of 2.00 US Dollars per Apple.
The Sell Order will be in PARTIAL_FILL state, and will have sold 5 of its original 10 Apples. The remaining Sell Order for 5 Apples will continue to be visible in the Market Price data. The Sell Order had a TimeInForce setting of GTC so it will continue to work in the Market until it is canceled. If further Buy LIMIT Orders are submitted at 2.00 or higher, or Buy MARKET Orders are submitted, the Sell Order will execute again, until all 10 Apples have been sold. An Order can execute multiple times, so a single Order may have multiple Fills associated with it.
A call can be made to view the current Market Price data, with the relevant Market key in a payload list, to "POST /v01/prices/multiple". The Market Price data should show only the Sell LIMIT Order working 5 Apples at 2.00 US Dollars per Apple.
Now that an execution has occurred, Fill records will have been created and can be downloaded.
View Fills
The GET /v01/fills/multiple endpoint requires a Market key and supports optional query parameters to filter the returned executions. A separate endpoint is available to retrieve Fills for a single Order.
An optional list of Order keys can be supplied to return only executions involving those Orders.
The settlement_state parameter can be used to return executions with particular Settlement States: [NEW|PENDING|SETTLED|BUSTED|ERROR]. This allows a Market Owner, for example, to request only NEW executions requiring settlement processing.
Optional parameters can limit the time span by Order submission time or Fill creation time.
Pagination is supported through the rowsPerPage and pageNo query parameters.
- mkt_pk (mandatory): Primary key for the Market.
- order_pk (optional): List of Order keys.
- settlement_state (optional): Filter by state; [NEW|PENDING|SETTLED|BUSTED|ERROR]
- order_submitted_start (optional): Filter by Order submission time, start.
- order_submitted_end (optional): Filter by Order submission time, end.
- fill_created_start (optional): Filter by Fill created time, start.
- fill_created_end (optional): Filter by Fill created time, end.
- rowsPerPage (optional): Fill records to return on one page; Defaults to 100
- pageNo (optional): Page number, zero indexed; Defaults to 0
curl -X GET "https://prod.haggledigital.com/v01/fills/multiple?mkt_pk=00000000-0000-0000-0000-000000000001" ^
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
curl -X GET "https://prod.haggledigital.com/v01/fills/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 execution objects containing paired Fills is returned. Each returned object represents one execution and contains the Buy-side Fill, the Sell-side Fill, and data common to both sibling Fills. If no Fills are present, an HTTP 204 No Content message is returned.
[
{
"exec_id": "00000000-0000-0000-0000-000000000100",
"created": "2026-10-26T13:30:00",
"mkt_pk": "00000000-0000-0000-0000-000000000001",
"tradeable_a_pk": "00000000-0000-0000-0000-000000000002",
"tradeable_b_pk": "00000000-0000-0000-0000-000000000003",
"exec_px": "2.00",
"buy_fill_pk": "00000000-0000-0000-0000-000000000021",
"buy_user_pk": "00000000-0000-0000-0000-000000000020",
"buy_cl_ord_id": "",
"buy_on_behalf_of": "",
"buy_order_pk": "00000000-0000-0000-0000-000000000011",
"buy_buy_sell": "B",
"buy_order_submitted": "2026-10-26T13:29:00",
"buy_ord_type": "LIMIT",
"buy_limit_px": "2.00",
"buy_trans_qty": "5",
"buy_settl_qty": "10.00",
"buy_trans_last_qty": "5",
"buy_settl_last_qty": "10.00",
"buy_trans_fill_qty": "5",
"buy_settl_fill_qty": "10.00",
"buy_average_limit_flag": false,
"buy_counterparty_clordid": "",
"buy_counterparty_order_pk": "00000000-0000-0000-0000-000000000012",
"buy_settlement_state": "NEW",
"sell_fill_pk": "00000000-0000-0000-0000-000000000022",
"sell_user_pk": "00000000-0000-0000-0000-000000000020",
"sell_cl_ord_id": "",
"sell_on_behalf_of": "",
"sell_order_pk": "00000000-0000-0000-0000-000000000012",
"sell_buy_sell": "S",
"sell_order_submitted": "2026-10-26T13:29:30",
"sell_ord_type": "LIMIT",
"sell_limit_px": "2.00",
"sell_trans_qty": "10",
"sell_settl_qty": "20.00",
"sell_trans_last_qty": "5",
"sell_settl_last_qty": "10.00",
"sell_trans_fill_qty": "5",
"sell_settl_fill_qty": "10.00",
"sell_average_limit_flag": false,
"sell_counterparty_clordid": "",
"sell_counterparty_order_pk": "00000000-0000-0000-0000-000000000011",
"sell_settlement_state": "NEW"
}
]
The exec_id and exec_px are data pertaining to the execution that occurred between the two Orders. Every execution is assigned a unique exec_id.
Fields relating to the Buy Order are prefixed with "buy_". The Buy Order has an original Transactional Quantity (buy_trans_qty) of 5 Apples and a Limit Price (buy_limit_px) of 2.00, giving an original Settlement Quantity (buy_settl_qty) of 10.00. The fields buy_trans_last_qty and buy_settl_last_qty show the quantities transferred in this execution. The fields buy_trans_fill_qty and buy_settl_fill_qty show the cumulative quantities filled up to and including this execution.
The data for the Buy Order includes the submitting User key (buy_user_pk) and the submitted Order key (buy_order_pk), so that the Owner of the Market can relate this execution to the Order and the User owning that Order. The buy_cl_ord_id and buy_on_behalf_of fields can carry references supplied when the Order was submitted, allowing the execution to be traced back to an originating external system.
Fields relating to the Sell Order are prefixed with "sell_" and mirror the corresponding Buy-side fields.
Each side includes a field linking its Fill to the counterparty Order. The buy_counterparty_order_pk has the Order key for the Sell Order that the Buy Order executed with. Similarly, the sell_counterparty_order_pk has the Order key for the Buy Order that the Sell Order executed with.
Both Fills also include a Settlement State, exposed as buy_settlement_state and sell_settlement_state. The PUT /v01/fills/update endpoint can be used to change the Settlement State for an execution. This allows the Market Owner to process NEW executions, mark them as settlement progresses, and later query only those still requiring attention.
Full API Documentation
This QuickStart covers the calls required to set up a User, create Tradeable Items, create a Market, place Orders, view Price data, and download resultant Fills.
The full API provides calls to:
- Share Tradeables with other Users.
- Allow other Users to access your Markets.
- Place complex Order types tailored to specific Trading Strategies.
- Track the Settlement of Fills.
- Download Historic Price data for Charting.
- Review Invoices for Usage Costs.
The API is intended to allow Users to integrate modern electronic exchange behaviour into existing business workflows with minimal development effort and cost. An electronic Market can therefore become a 'plug-in' element within an existing workflow, leaving the core business function unchanged while prices are negotiated in real time.
Your first Market is free, so you can experiment with Haggle in the Production environment, build a real integration, and explore the API without incurring any usage charges.