latest contributor to this doc

Last Edit: @smk762 ,

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 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.

StructureTypeDescription
basestringThe name of the coin the user desires to receive
relstringThe name of the coin the user desires to sell
pricevariesThe price in rel the user is willing to pay per one unit of the base coin. Can be a numeric string, expressed using standard RationalValue or FractionalValue objects.
volumevariesThe 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_volumevaries (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_byobjectOptional. 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_typeobjectOptional. A standard OrderType object.
base_confsnumberNumber of required blockchain confirmations for base coin atomic swap transaction; default to base coin configuration if not set
base_notabooleanWhether dPoW notarization is required for base coin atomic swap transaction; default to base coin configuration if not set
rel_confsnumberNumber of required blockchain confirmations for rel coin atomic swap transaction; default to rel coin configuration if not set
rel_notabooleanWhether dPoW notarization is required for rel coin atomic swap transaction; default to rel coin configuration if not set
save_in_historybooleanDefaults 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

StructureTypeDescription
actionstringThe action of the request (Buy)
basestringThe base currency of request
base_amountstringThe resulting amount of base currency that is received if the order matches (in decimal representation)
base_amount_ratrationalThe resulting amount of base currency that is received if the order matches, represented as a standard RationalValue object.
relstringThe rel currency of the request
rel_amountstringThe maximum amount of rel coin that is spent in order to buy the base_amount (according to price, in decimal representation)
rel_amount_ratrationalThe maximum amount of rel coin that is spent in order to buy the base_amount (according to price, represented as a standard RationalValue object).
methodstringThis field is used for internal P2P interactions; the value is always equal to "request
dest_pub_keystringReserved 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_pubkeystringThe public key of this node
uuidstringThe request uuid
match_byobjectA standard MatchBy object, to filter to include only matches by pubkey or uuid.
conf_settingsobjectA standard ConfSettings object.
base_orderbook_tickerstringThe 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_tickerstringThe 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.

POST
buy
{
  "userpass": "testpsw",
  "method": "buy",
  "base": "HELLO",
  "rel": "WORLD",
  "volume": "1",
  "price": "1"
}

POST
buy
{
  "userpass": "testpsw",
  "method": "buy",
  "base": "HELLO",
  "rel": "WORLD",
  "volume": [
    [
      1,
      [
        1
      ]
    ],
    [
      1,
      [
        1
      ]
    ]
  ],
  "price": [
    [
      1,
      [
        1
      ]
    ],
    [
      1,
      [
        1
      ]
    ]
  ]
}

POST
buy
{
  "userpass": "testpsw",
  "method": "buy",
  "base": "HELLO",
  "rel": "WORLD",
  "volume": {
    "numer": "3",
    "denom": "2"
  },
  "price": {
    "numer": "2",
    "denom": "1"
  }
}

POST
buy
{
  "userpass": "testpsw",
  "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
}

POST
buy
{
  "userpass": "testpsw",
  "method": "buy",
  "base": "HELLO",
  "rel": "WORLD",
  "volume": {
    "numer": "3",
    "denom": "2"
  },
  "price": {
    "numer": "2",
    "denom": "1"
  },
  "save_in_history": false
}

POST
buy
{
  "userpass": "testpsw",
  "method": "buy",
  "base": "BASE",
  "rel": "REL",
  "volume": [
    [
      1,
      [
        1
      ]
    ],
    [
      1,
      [
        1
      ]
    ]
  ],
  "price": [
    [
      1,
      [
        1
      ]
    ],
    [
      1,
      [
        1
      ]
    ]
  ],
  "order_type": {
    "type": "GoodTillCancelled"
  }
}

POST
buy
{
  "userpass": "testpsw",
  "method": "buy",
  "base": "BASE",
  "rel": "REL",
  "volume": [
    [
      1,
      [
        1
      ]
    ],
    [
      1,
      [
        1
      ]
    ]
  ],
  "price": [
    [
      1,
      [
        1
      ]
    ],
    [
      1,
      [
        1
      ]
    ]
  ],
  "order_type": {
    "type": "FillOrKill"
  }
}

POST
buy
{
  "userpass": "testpsw",
  "method": "buy",
  "base": "BASE",
  "rel": "REL",
  "volume": [
    [
      1,
      [
        1
      ]
    ],
    [
      1,
      [
        1
      ]
    ]
  ],
  "price": [
    [
      1,
      [
        1
      ]
    ],
    [
      1,
      [
        1
      ]
    ]
  ],
  "match_by": {
    "type": "Any"
  }
}

POST
buy
{
  "userpass": "testpsw",
  "method": "buy",
  "base": "BASE",
  "rel": "REL",
  "volume": [
    [
      1,
      [
        1
      ]
    ],
    [
      1,
      [
        1
      ]
    ]
  ],
  "price": [
    [
      1,
      [
        1
      ]
    ],
    [
      1,
      [
        1
      ]
    ]
  ],
  "match_by": {
    "type": "Pubkeys",
    "data": [
      "1ab7edc96abaefb358b52c583048eaaeb8ea42609d096d6cddfafa02fa510c6a"
    ]
  }
}

POST
buy
{
  "userpass": "testpsw",
  "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"
    ]
  }
}