Skip to content

Latest commit

 

History

History
501 lines (466 loc) · 21.2 KB

index.mdx

File metadata and controls

501 lines (466 loc) · 21.2 KB

export const title = "Komodo DeFi Framework Method: Buy"; export const description = "The buy method issues a buy request and attempts to match an order from the orderbook based on the provided arguments.";

buy

buy base rel price volume (match_by order_type base_confs base_nota rel_confs rel_nota min_volume)

The buy method issues a buy request and attempts to match an order from the orderbook based on the provided arguments.

* Buy and sell methods always create the `taker` order first. A `taker` order must pay a `dexfee` during the swap as it is taking liquidity from the market. The `dexfee` is calculated as "the greater of either `Minimum transaction amount (dust) TAKER COIN` or `0.0001 TAKER COIN` or `1/777th` the size of the desired order". If your `GoodTillCancelled` order is not matched in 30 seconds, the order is automatically converted to a `maker` request and stays on the orderbook until the request is matched or cancelled. To always act as a maker, please use the [setprice](/komodo-defi-framework/api/legacy/setprice/) method. * To prevent a user from making trades in which the transaction fees may end up costing a significant portion of the value of the trade, we have set a lower limit to the value of a trade. See the description of the `volume` and `min_volume` arguments for more info.

Arguments

Structure Type Description
base string The name of the coin the user desires to receive
rel string The name of the coin the user desires to sell
price various The amount in rel the user wants per one unit of the base coin. Can be a numeric string, expressed using standard RationalValue or FractionalValue objects.
volume various The amount of coins the user is willing to receive of the base coin; the following values must be greater than or equal to the min_trading_vol of the corresponding coin:
  • the argument volume
  • the product of the arguments volume and price
. . Can be a numeric string, expressed using standard RationalValue or FractionalValue objects.
min_volume various (optional) The amount of base coin that will be used as min_volume of GoodTillCancelled order after conversion to maker; the following values must be greater than or equal to the min_trading_vol of the corresponding coin:
  • the argument min_volume
  • the product of the arguments min_volume and price
. Can be a numeric string, expressed using standard RationalValue or FractionalValue objects.
match_by object Optional. A standard MatchBy object, to filter to include only matches by pubkey or uuid. Important: This condition is not applied after a GoodTillCancelled order is converted to a maker request.
order_type object Optional. A standard OrderType object.
base_confs number Number of required blockchain confirmations for base coin atomic swap transaction; default to base coin configuration if not set
base_nota boolean Whether dPoW notarization is required for base coin atomic swap transaction; default to base coin configuration if not set
rel_confs number Number of required blockchain confirmations for rel coin atomic swap transaction; default to rel coin configuration if not set
rel_nota boolean Whether dPoW notarization is required for rel coin atomic swap transaction; default to rel coin configuration if not set
save_in_history boolean Defaults to true. If set to false no order history will be saved (though order status will be temporarily stored while in progress). If true, each order's short record history is stored in a local SQLite database table, and when the order is cancelled or fully matched, it's history will be saved as a json file

Response

Structure Type Description
action string The action of the request (Buy)
base string The base currency of request
base_amount string The resulting amount of base currency that is received if the order matches (in decimal representation)
base_amount_rat rational The resulting amount of base currency that is received if the order matches, represented as a standard RationalValue object.
rel string The rel currency of the request
rel_amount string The maximum amount of rel coin that is spent in order to buy the base_amount (according to price, in decimal representation)
rel_amount_rat rational The maximum amount of rel coin that is spent in order to buy the base_amount (according to price, represented as a standard RationalValue object).
method string This field is used for internal P2P interactions; the value is always equal to "request
dest_pub_key string Reserved for future use. dest_pub_key allows the user to choose the P2P node that is eligible to match with the request. This value defaults to a "zero pubkey", which means anyone can be a match
sender_pubkey string The public key of this node
uuid string The request uuid
match_by object A standard MatchBy object, to filter to include only matches by pubkey or uuid.
conf_settings object A standard ConfSettings object.
base_orderbook_ticker string The ticker of the base currency if orderbook_ticker is configured for the base currency in coins file. If not defined, will return a null value.
rel_orderbook_ticker string The ticker of the rel currency if orderbook_ticker is configured for the rel currency in coins file. If not defined, will return a null value.

📌 Examples

Command (decimal representation)

```json { "userpass": "RPC_UserP@SSW0RD", "method": "buy", "base": "DOC", "rel": "MARTY", "price": 1.1, "volume": 2.4 } ```

Command (rational representation in num-rational crate format)

```json { "result": { "base": "DOC", "rel": "MARTY", "base_amount": "2.4", "base_amount_rat": [ [ 1, [ 12 ] ], [ 1, [ 5 ] ] ], "rel_amount": "2.64", "rel_amount_rat": [ [ 1, [ 66 ] ], [ 1, [ 25 ] ] ], "action": "Buy", "uuid": "3d2286d1-1eef-487b-a07a-904f33034792", "method": "request", "sender_pubkey": "d8064eece4fa5c0f8dc0267f68cee9bdd527f9e88f3594a323428718c391ecc2", "dest_pub_key": "0000000000000000000000000000000000000000000000000000000000000000", "match_by": { "type": "Any" }, "conf_settings": { "base_confs": 1, "base_nota": false, "rel_confs": 1, "rel_nota": false }, "order_type": { "type": "GoodTillCancelled" }, "min_volume": "0.0001", "min_volume_fraction": { "numer": "1", "denom": "10000" }, "min_volume_rat": [ [ 1, [ 1 ] ], [ 1, [ 10000 ] ] ], "base_orderbook_ticker": null, "rel_orderbook_ticker": null }, "userpass": "RPC_UserP@SSW0RD" } ```

Command (rational representation as fraction object)

```json { "userpass": "RPC_UserP@SSW0RD", "method": "buy", "base": "HELLO", "rel": "WORLD", "volume": { "numer": "3", "denom": "2" }, "price": { "numer": "2", "denom": "1" } } ```

Command (with confirmations and notarization settings)

```json { "userpass": "RPC_UserP@SSW0RD", "method": "buy", "base": "HELLO", "rel": "WORLD", "volume": { "numer": "3", "denom": "2" }, "price": { "numer": "2", "denom": "1" }, "base_confs": 2, "base_nota": true, "rel_confs": 5, "rel_nota": false } ```

Command (set to not save order history)

```json { "userpass": "RPC_UserP@SSW0RD", "method": "buy", "base": "HELLO", "rel": "WORLD", "volume": { "numer": "3", "denom": "2" }, "price": { "numer": "2", "denom": "1" }, "save_in_history": false } ```

Command (GoodTillCancelled type)

```json { "userpass": "RPC_UserP@SSW0RD", "method": "buy", "base": "BASE", "rel": "REL", "volume": [ [ 1, [ 1 ] ], [ 1, [ 1 ] ] ], "price": [ [ 1, [ 1 ] ], [ 1, [ 1 ] ] ], "order_type": { "type": "GoodTillCancelled" } } ```

Command (FillOrKill type)

```json { "userpass": "RPC_UserP@SSW0RD", "method": "buy", "base": "BASE", "rel": "REL", "volume": [ [ 1, [ 1 ] ], [ 1, [ 1 ] ] ], "price": [ [ 1, [ 1 ] ], [ 1, [ 1 ] ] ], "order_type": { "type": "FillOrKill" } } ```

Command (match by Any)

```json { "userpass": "RPC_UserP@SSW0RD", "method": "buy", "base": "BASE", "rel": "REL", "volume": [ [ 1, [ 1 ] ], [ 1, [ 1 ] ] ], "price": [ [ 1, [ 1 ] ], [ 1, [ 1 ] ] ], "match_by": { "type": "Any" } } ```

Command (match by Pubkeys)

```json { "userpass": "RPC_UserP@SSW0RD", "method": "buy", "base": "BASE", "rel": "REL", "volume": [ [ 1, [ 1 ] ], [ 1, [ 1 ] ] ], "price": [ [ 1, [ 1 ] ], [ 1, [ 1 ] ] ], "match_by": { "type": "Pubkeys", "data": [ "1ab7edc96abaefb358b52c583048eaaeb8ea42609d096d6cddfafa02fa510c6a" ] } } ```

Command (match by Orders)

```json { "userpass": "RPC_UserP@SSW0RD", "method": "buy", "base": "BASE", "rel": "REL", "volume": [ [ 1, [ 1 ] ], [ 1, [ 1 ] ] ], "price": [ [ 1, [ 1 ] ], [ 1, [ 1 ] ] ], "match_by": { "type": "Orders", "data": [ "d14452bb-e82d-44a0-86b0-10d4cdcb8b24" ] } } ``` #### Response (success) 
{
  "result": {
    "action": "Buy",
    "base": "HELLO",
    "base_amount": "1",
    "base_amount_rat": [
      [1, [1]],
      [1, [1]]
    ],
    "dest_pub_key": "0000000000000000000000000000000000000000000000000000000000000000",
    "method": "request",
    "rel": "WORLD",
    "rel_amount": "1",
    "rel_amount_rat": [
      [1, [1]],
      [1, [1]]
    ],
    "sender_pubkey": "c213230771ebff769c58ade63e8debac1b75062ead66796c8d793594005f3920",
    "uuid": "288743e2-92a5-471e-92d5-bb828a2303c3",
    "match_by": {
      "data": [
        "1ab7edc96abaefb358b52c583048eaaeb8ea42609d096d6cddfafa02fa510c6a"
      ],
      "type": "Pubkeys"
    },
    "conf_settings": {
      "base_confs": 2,
      "base_nota": true,
      "rel_confs": 5,
      "rel_nota": false
    },
    "base_orderbook_ticker": null,
    "rel_orderbook_ticker": null
  }
}

Response (error)

{
  "error": "rpc:278] utxo:884] REL balance 12.88892991 is too low, required 21.15"
}

Response (error)

{
  "error": "rpc:275] lp_ordermatch:665] The WORLD amount 40000/3 is larger than available 47.60450107, balance: 47.60450107, locked by swaps: 0.00000000"
}