HaggleDigital

QuickStart

Create Markets

Create a Market and open it to begin receiving and matching Orders.

Back to Getting Started with the API

Markets

Once a User has Tradeable Items to represent products, goods or assets relevant to their business, a Market can be created.

The User that creates the Market has Owner rights to that Market. The Market can be opened and closed by the Owner to control when trading is allowed. A newly created Market begins in the CLOSE state (closed), so that the Owner has control over when the Market is actually opened.

Link to Markets documentation

Create a Market

The call to create a new Market requires a Name, and the two Tradeable Items that are exchanged in the Market. The Tradeable Items are referred to as A and B for brevity. The A Tradeable Item is the Transactional Tradeable Item, and B is the Settlement Tradeable Item.

For example, consider a Market for Apples in America. Apples would be the Transactional Tradeable Item, and US Dollars would be the Settlement Tradeable Item. Prices are stated as the quantity of Settlement Tradeable Item per unit of the Transactional Tradeable Item. So, prices in the example US Apple Market are the quantity of US Dollars per Apple.

An optional Description can be provided for the Market. This can be used to provide additional information like opening and closing times, local trading rules, and other information traders may need.

The Market can have an optional Expiry date. Once the Expiry has passed, the Market will be closed. After the Expiry, calls to change the state to OPEN will be rejected. Markets with an Expiry date are useful for trading time-limited Tradeable Items such as Futures Contracts, or tickets for events.

The Owner of a Market may wish to add guardrails to the allowed price range. The optional Max Px and Min Px settings set limits on the prices at which Orders can be placed. These limits can be added, removed or changed whilst the Market is in state OPEN and take effect immediately whilst the Market is matching.

The matching algorithm can be set in the optional Algo setting. This can be either FIFO or BIG, and defaults to FIFO. FIFO means First-In-First-Out, and when two Orders have the same price, the Order with the earliest Submitted timestamp is matched first. BIG stands for Biggest, and when two Orders have the same price, the Order with the largest initial transactional quantity is matched first. FIFO is the most common and standard matching algorithm. BIG may be used for a Market where the Owner wishes to prioritise the high-volume traders over the smaller players. The algorithm can be changed whilst the Market is in state OPEN and takes effect immediately whilst the Market is matching.

The optional Dec Places Px setting can be used to control the number of decimal places used in Price data, and defaults to 2. Prices are effectively a ratio of the quantity of Settlement Tradeable Item required per unit of Transactional Tradeable Item. As a ratio, or fraction, there may be a large possible number of decimal places required to display the price for an Order. In most cases, the Tick Size of the Settlement Tradeable Item is a guide to how many decimal places should be used to display useful Price data. For example, in a Market for Apples in America, US Dollars would be the Settlement Tradeable Item. Dollars have a Tick Size of 0.01, so 2 may be an appropriate Dec Places Px value. This setting can be changed whilst the Market is OPEN and takes effect whilst the Market is matching.

The optional Depth setting controls how many price levels are displayed in Price data, and defaults to 5. Price data shows the best bids and offers in a Market. With a depth of 5, the Price data shows the best bids and offers, and the next four 'worse' bids and offers. The minimum value of 1 would show only the best bids and offers. The maximum value permitted is 20, so this would show the best bids and offers and up to 19 additional price levels on each side. This Depth setting can be changed whilst the Market is OPEN and takes immediate effect if the Market is matching.

  • name (mandatory): Short text description.
  • description (optional): Long text description.
  • tradeable_a_pk (mandatory): Primary key for Transactional Tradeable Item.
  • tradeable_b_pk (mandatory): Primary key for Settlement Tradeable Item.
  • expiry (optional): UTC Datetime after which the Market is closed.
  • max_px (optional): Maximum price allowed on an Order.
  • min_px (optional): Minimum price allowed on an Order.
  • algo (optional): Matching Algorithm [FIFO|BIG]; Defaults to FIFO.
  • dec_places_px (optional): Price decimal place precision; Defaults to 2 decimal places.
  • depth (optional): Price levels displayed in Price data; Defaults to 5 levels.
Windows CMD
              
curl -X POST "https://prod.haggledigital.com/v01/markets/create" ^
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ^
  -H "Content-Type: application/json" ^
  -d "{\"name\": \"My New Market\", \"description\" : \"Optional Long Name for the Market\", \"tradeable_a_pk\": \"00000000-0000-0000-0000-000000000002\", \"tradeable_b_pk\": \"00000000-0000-0000-0000-000000000003\", \"expiry\": \"2040-12-31T23:59:59\", \"max_px\": \"1000.0\", \"min_px\": \"10.0\", \"algo\": \"FIFO\", \"dec_places_px\": 2, \"depth\": 5}"
UNIX/MacOS
              
curl -X POST "https://prod.haggledigital.com/v01/markets/create" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My New Market",
  "description" : "Optional Long Name for the Market",
  "tradeable_a_pk": "00000000-0000-0000-0000-000000000002",
  "tradeable_b_pk": "00000000-0000-0000-0000-000000000003",
  "expiry": "2040-12-31T23:59:59",
  "max_px": "1000.0",
  "min_px": "10.0",
  "algo": "FIFO",
  "dec_places_px": 2,
  "depth": 5
}'

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 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 using or editing the Market.

Response
              
{
  "pk":"00000000-0000-0000-0000-000000000001",
  "name": "My New Market",
  "description" : "Optional Long Name for the Market",
  "tradeable_a_pk": "00000000-0000-0000-0000-000000000002",
  "tradeable_b_pk": "00000000-0000-0000-0000-000000000003",
  "expiry": "2040-12-31T23:59:59",
  "max_px": "1000.0",
  "min_px": "10.0",
  "algo": "FIFO",
  "dec_places_px": 2,
  "depth": 5,
  "state": "CLOSE",
  "private": 1,
  "billing_user_pk": "00000000-0000-0000-0000-000000000004"  
}

Note the state value is initially "CLOSE". The Market is created in the CLOSE state, and will need to be opened with another API call.

Changing Market State to OPEN

The returned JSON data packet has the pk ("primary key") element, where the value is the unique system identifier or key for the created Market. To begin accepting and matching Orders, a call must be made to the endpoint that controls Market state.

The call to /v01/markets/change_state requires the unique system identifier (pk) for the Market, and the state to change the Market to.

  • pk (mandatory): Primary key for Market.
  • state (mandatory): Required state; [OPEN|ACCEPT|HALT|CLOSE]
Windows CMD
              
curl -X POST "https://prod.haggledigital.com/v01/markets/change_state" ^
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ^
  -H "Content-Type: application/json" ^
  -d "{\"pk\": \"00000000-0000-0000-0000-000000000001\", \"state\": \"OPEN\"}"
UNIX/MacOS
                        
curl -X POST "https://prod.haggledigital.com/v01/markets/change_state" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "pk": "00000000-0000-0000-0000-000000000001",
  "state": "OPEN"
}'

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 Market object is returned, which should reflect the changed state of the Market.

Response
              
{
  "pk":"00000000-0000-0000-0000-000000000001",
  "name": "My New Market",
  "description" : "Optional Long Name for the Market",
  "tradeable_a_pk": "00000000-0000-0000-0000-000000000002",
  "tradeable_b_pk": "00000000-0000-0000-0000-000000000003",
  "expiry": "2040-12-31T23:59:59",
  "max_px": "1000.0",
  "min_px": "10.0",
  "algo": "FIFO",
  "dec_places_px": 2,
  "depth": 5,
  "state": "OPEN",
  "private": 1,
  "billing_user_pk": "00000000-0000-0000-0000-000000000004"  
}

Viewing Private Markets

The collection of Private Markets that a User has access to can be retrieved by calling the /v01/markets/private endpoint.

Windows CMD
              
curl -X GET "https://prod.haggledigital.com/v01/markets/private" ^
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
UNIX/MacOS
              
curl -X GET "https://prod.haggledigital.com/v01/markets/private" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

The response will be an HTTP 200 OK message on success, or an error indicating a problem with the optional parameters. On success, a list of Market objects is returned.

If a large number of Markets exist, the data can be requested in paginated form. Query parameters can be added to the request to set the values for rowsPerPage and pageNo. The caller should call iteratively with an incrementing pageNo value until an HTTP 204 No Content message is returned, indicating a successful call with no more data to return.

Viewing Public Markets

Public Markets are uncommon, and require a compelling use case. If Public Markets do exist, they can be viewed in a similar way to the Private Markets.

Windows CMD
              
curl -X GET "https://prod.haggledigital.com/v01/markets/public" ^
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
UNIX/MacOS
              
curl -X GET "https://prod.haggledigital.com/v01/markets/public" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

The response will be an HTTP 200 OK message on success, or an error indicating a problem with the optional parameters. On success, a list of Market objects is returned.

If a large number of Markets exist, the data can be requested in paginated form. Query parameters can be added to the request to set the values for rowsPerPage and pageNo. The caller should call iteratively with an incrementing pageNo value until an HTTP 204 No Content message is returned, indicating a successful call with no more data to return.

Submit Orders

When a Market has been created, and the state set to OPEN, the Market will accept Orders. Buy Orders and Sell Orders are compared on Price, and matched if they have overlapping prices.

Continue to Submit Orders.