Place Action

Orders are sent to the exchange using the contract’s place action. Below are the details of the place action as defined in the ABI.

{

“name”: “place”,

“base”: “”,

“fields”: [ {“name”:”account”, “type”:”name”},

{“name”:”clId”, “type”:”uint64"},

{“name”:”scope”, “type”:”name”},

{“name”:”price”, “type”:”uint64"},

{“name”:”qty”, “type”:”uint64"},

{“name”:”flags”, “type”:”uint8"}

]

}

Let’s take a closer look at each of these fields.

Account: This is the account that is placing the order. The transaction must be signed using the private key for this account, and the user must have sufficient funds available within their exchange wallet.

Clid: This is the client order id, a unique id that the client assigns to each order request. This id allows the user to identify the order after the exchange contract process it.

Scope: Order scope is the amalgamation of the trading pair and order side. Scope follows the pattern: X.Y.Z. All values are lower case and X is the trading pair base currency, Y is the trading pair quote currency, and Z is the order side (either ‘b’ for bid or ‘a’ for ask). For example, setting scope to eox.eos.b would place a buy order for the eox.eos trading pair.

Price: This is an integer representation of the limit price for the order. eosfinex orders support 4 digits of price precision to the right of the decimal point. The integer representation is obtained by simply multiplying the floating point price by 10000. For example, the integer representation of the limit price 4.1250 is 41250 (4.1250 * 10000).

Qty: This is an integer representation of the order size. Like prices, eosfinex orders support 4 digits of size precision to the right of the decimal point. To convert from decimal to integer representation, again simply multiply by 10000. For example, the integer representation of the order size 100.05 is 1000500 (100.05 * 10000).

Flags: The flags field is used to specify order options. Each bit in the 8-bit field represents a different option and can be enabled by setting that bit to true. This allows enabling multiple options on the same order.

Here is a list of each option and its corresponding bit:

00000001 Post Only: The order will receive a price reflecting the maker rebate. 00000010 Immediate or Cancel: Any size that does not fill immediately will be canceled. 00000100 Market: Ignore limit price and trade at the best available price. 00001000 Self Trade Prevention: Do not trade with an order having the same account. 01000000 Release on Trade: Transfer new funds out of the exchange after a trade. 10000000 Sweep Collateral: Transfer collateral balance out of exchange when canceled.

For example, if flags = 11000010, this will be an Immediate or Cancel order that will transfer the full collateral balance, as well as any funds acquired due to a trade, out of the exchange upon order completion.

Let’s attempt to make this more clear through an example. We will assume the user has the following exchange balances.

cleos get currency balance [exchange_account] [user_account]

20.00000000 EOS

5.00000000 EOX

Let’s also assume that the user wants to buy 3.0000 EOX using EOS, and that the user wants to pay no more than 1.5 EOS for each EOX. In that case, the user would send the following command.

cleos push action exchange_account place ‘[user_account 1 eox.eos.b 15000 30000 0]’

Let’s assume that the order did not fill after it was placed, and it is resting in the order book waiting to be filled. If we query the user’s exchange wallet balances we see that some EOS has been reserved as collateral to support the order that was just placed.

cleos get currency balance [exchange_account] [user_account]

15.50000000 EOS

5.00000000 EOX

Next, we can query the orders table to see the order we just placed.