Skip to content

Trading against Bitcoin on the Omni distributed exchange

Jump to bottom
Adam edited this page Apr 24, 2020 · 8 revisions

This guide provides some basic instructions on how to interact with the Bitcoin markets on the distributed exchange of the Omni Layer protocol using Omni Core.

Prerequisites: A fully synchronized Omni Core Client v0.8+, an address holding bitcoins and some basic knowledge of using the command line interface of Omni Core. For selling tokens, you also need the tokens you wish to post for sale on the address holding the bitcoins.

Table of contents:

Selling: Posting a new sell offer

In order to create a new sell offer you need to use the command omni_senddexsell, which can be used to place, update or cancel a sell offer on the distributed exchange. Any token can be traded against Bitcoin and the distributed exchange is not limited to trading of Omni or Test Omni.

For example this command:

$ omnicore-cli "omni_senddexsell" "123sellerswalletaddress45689abc" 1 "10" "0.75" 25 "0.00005" 1

Will create a new sell offer:

  • From the address 123sellerswalletaddress45689abc
  • For token ID #1 (Omni tokens)
  • Selling "10" token ID #1 (Omni tokens)
  • Requesting a total of "0.75" bitcoins for all
  • Allowing a payment window of 25 blocks. This is the length of time a buyer has to send payment after sending their "accept transaction".
  • Requires the buyers payment transaction to have a minimum miner fee of "0.00005" BTC
  • Action 1 = Create new offer

Note: An Address can only have one active sell offer at a time, regardless of the token ID being sold. Attempts to post additional sales from the same address will be invalid.

Selling: Updating an existing sell offer

Just like posting a new sale, the same command is also be used to update an existing sell order with new information. Say you decide you want to change an offer, e.g. the number of coins you are offering for sale, or change the asking price.

Simply replace the action = 1 with action = 2 and send the new transaction with the new details.

For example this command:

$ omnicore-cli "omni_senddexsell" "123sellerswalletaddress45689abc" 1 "5" "0.5" 25 "0.00005" 2

Will update our previous sell offer:

  • From the address 123sellerswalletaddress45689abc
  • For token ID #1 (Omni tokens)
  • Selling "5" token ID #1 (Omni tokens) - Updated Parameter
  • Requesting a total of "0.5" bitcoins for all - Updated Parameter
  • Allowing a payment window of 25 blocks
  • Requires the buyers payment transaction to have a minimum miner fee of "0.00005" BTC
  • Action 2 = Update offer

Note that while the portion of an offer which has been accepted can't be changed, sending an update message still has an effect, in that it affects any coins which have not been accepted, and it affects accepted coins, if the buyer fails to send payment.

Selling: Canceling your existing sell offer

Just like posting a new sale, the same command is also be used to cancel an existing sell order.

To cancel an offer, simply replace the action = 1 with action = 3 and use the same token ID to explicitly specify the offer to cancel. The fields amount for sale, amount of bitcoins desired, payment window and minimum miner fee are irrelevant and can be set to 0.

For example this command:

$ omnicore-cli "omni_senddexsell" "123sellerswalletaddress45689abc" 1 "0" "0" 25 "0.00005" 3

Will cancel our previous sell offer:

  • From the address 123sellerswalletaddress45689abc
  • For token ID #1 (Omni tokens)
  • Selling "0" token ID #1 (Omni tokens) - irrelevant for this action type
  • Requesting a total of "0" bitcoins for all - irrelevant for this action type
  • Allowing a payment window of 25 blocks - irrelevant for this action type
  • Requires the buyers payment transaction to have a minimum miner fee of "0.00005" BTC irrelevant for this action type
  • Action 3 = Cancel offer

Buying: Viewing available offers

You can view the complete list of available offers using the omni_getactivedexsells command.

For example:

$ omnicore-cli "omni_getactivedexsells"
[
  {
    "txid" : "OriginalSaleTransactionID",
    "propertyid" : 1,                  
    "seller" : "123sellerswalletaddress45689abc",
    "amountavailable" : "2",  
    "bitcoindesired" : "0.5",
    "unitprice" : "0.1" ,    
    "timelimit" : 25,
    "minimumfee" : "0.00005",    
    "amountaccepted" : "3.0",
    "accepts": [
    ]
  },
 ...,
 {
    "txid": "6a99305e39fb2874498a5503de7d191ff447472b19cad0be0e1ee3a8d0a57cb4",
    "propertyid": 2,
    "seller": "1rM1oMEFMfhPBo4kRaf2CMXf9XQCHyYWi",
    "amountavailable": "33.59857941",
    "bitcoindesired": "0.33937959",
    "unitprice": "0.01010101",
    "timelimit": 10,
    "minimumfee": "0.00010000",
    "amountaccepted": "0.00000000",
    "accepts": [
    ]
  }
]

In this output you can see the list of all current open offers and their available amounts and prices.

If there is a specific sellers address you wish to view, the command can filter the outputs using the sellers address.

Example:

omnicore-cli "omni_getactivedexsells" "123sellerswalletaddress45689abc"
[
  {
    "txid" : "OriginalSaleTransactionID",
    "propertyid" : 1,                  
    "seller" : "123sellerswalletaddress45689abc",
    "amountavailable" : "2",  
    "bitcoindesired" : "0.5",
    "unitprice" : "0.1" ,    
    "timelimit" : 25,
    "minimumfee" : "0.00005",    
    "amountaccepted" : "3.0",
    "accepts": [
    ]
  }

Buying: Accepting an offer

After viewing the list of available sell offers in the previous command if you wish to proceed with purchasing you must first send an accept transaction to the sellers address using the command omni_senddexaccept.

Purpose: The accept transaction, when confirmed on the blockchain, is validated to determine if the seller still has the amount of tokens you wish to purchase available.

If the seller does, then those tokens are reserved for the buyer for a period equal to the "timelimit" as specified by the sell offer. This time limit refers to the number of blocks in which the final payment must be received for the reserved funds to be released and transferred to the buyer.

For example this command:

$ omnicore-cli "omni_senddexaccept" "123buyerswalletaddress45689abc1" "123sellerswalletaddress45689abc" 1 "3.0"

Will:

  • Reserve for purchase for the address 123buyerswalletaddress45689abc1
  • From the seller "123sellerswalletaddress45689abc"
  • For token ID #1 (Omni Tokens)
  • "3.0" the amount of tokens to reserve

If the accept transaction is confirmed valid and the funds are reserved they will be visible in the accepts data element in the output from the omni_getactivedexsells "123sellerswalletaddress45689abc".

Example:

$ omnicore-cli "omni_getactivedexsells" "123sellerswalletaddress45689abc"
[                                  // (array of JSON objects)
  {
    "txid" : "OriginalSaleTransactionID",
    "propertyid" : 1,                  
    "seller" : "123sellerswalletaddress45689abc",
    "amountavailable" : "2",  
    "bitcoindesired" : "0.5",
    "unitprice" : "0.1" ,    
    "timelimit" : 25,
    "minimumfee" : "0.00005",    
    "amountaccepted" : "3.0",
    "accepts": [                    
      {
        "buyer" : "123buyerswalletaddress45689abc1",               // (string) the Bitcoin address of the buyer
        "block" : 123456,                  // (number) the index of the block that contains the "accept" order
        "blocksleft" : 20,                 // (number) the number of blocks left to pay
        "amount" : "3.0"            // (string) the amount of tokens accepted and reserved
        "amounttopay" : "0.3"       // (string) the amount in bitcoins needed finalize the trade
      }
    ]
  }

Note: If after your transaction confirms you do not see an entry in the accepts field for your address then it means your accept transaction was not valid. Most likely this happened because the seller no longer had enough tokens remaining for sale that were unreserved. You can view the exact details using omni_gettransaction <your original accept transaction id/hash>

Buying: Paying for an offer

Note: It is highly recommend that a buyer only attempt to send the payment when there is a large number of blocks remaining for the payment to be accepted.

  • Due to the volatile nature of the Bitcoin blockchain, if a payment transaction gets delayed and doesn't confirm until after the reserved funds "timelimit" has expired, the payment is lost and the funds remain with the seller. THERE IS NO UNDO in this situation.

Please proceed with caution!

Once your accept transaction has been confirmed and you see the amount of tokens you wish to buy are reserved for you, you can complete the purchase by using the omni_senddexpay command.

IMPORTANT Final payment MUST BE SENT USING THE omni_senddexpay command as sending payment from any other non Omni Layer supporting wallet or interface could result in a complete loss of funds.

For example:

$ omnicore-cli "omni_senddexsell" "123buyerswalletaddress45689abc1" "123sellerswalletaddress45689abc" 1 "0.3"

Will send a payment of "0.3" bitcoins, for the token #1 that the seller "123sellerswalletaddress45689abc" currently has reserved for the buyer "123buyerswalletaddress45689abc1"

Once the transaction confirms before the time limit expires the reserved funds will be released to the buyer and the sale is complete.

If the payment is not received (= confirmed on the blockchain) before the time limit expires, then the reserved funds are released back to the seller and available for someone else to purchase.

Clone this wiki locally