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.

Arguments

Parameter* = required	Type	Description
base*	`string`	Ticker of the coin to receive (the coin you are buying)
price*	`number \| RationalValue \| FractionalValue`	Price in `rel` per one unit of `base` (supports decimal numbers, num-rational arrays, or fraction objects)
rel*	`string`	Ticker of the coin you are spending
volume*	`number \| RationalValue \| FractionalValue`	Amount of `base` to purchase; must satisfy each coin's `min_trading_vol` limits
base_confs / rel_confs	`number`	Optional. Override the confirmation requirements for base or rel sides
base_nota / rel_nota	`bool`	Optional. Override whether notarization is required for base or rel sides
match_by	`MatchBy object`	Optional. Restrict matches to specific pubkeys or order UUIDs (ignored after conversion to maker)
min_volume	`number \| RationalValue \| FractionalValue`	Optional. Minimum amount of `base` that must remain if the order converts to maker mode
order_type	`OrderType object`	Optional. Controls maker/taker behaviour (`GoodTillCancelled`, `FillOrKill`, etc.)
save_in_history	`bool`	Optional. Defaults to true. Set false to skip persisting the short order history locally

Response

Parameter* = required	Type	Description
action*	`string`	Always "Buy" for this method
base / rel*	`string`	Tickers of the trade pair
base_amount / rel_amount*	`string`	Decimal string totals representing the matched trade size
uuid*	`string`	UUID of the buy request
base_amount_rat / rel_amount_rat	`RationalValue`	Optional. Rational representation of the matched trade size
base_orderbook_ticker / rel_orderbook_ticker	`string \| null`	Optional. Present when coins are remapped via `orderbook_ticker`
conf_settings	`ConfSettings object`	Optional. Effective confirmation and notarization settings applied to this order
match_by / order_type	`object`	Optional. Echoes the match filters and order type used for this order

Each object inside the result map is a standard OrderDataV1 entry describing the order that was created.

📌 Examples

Command (decimal representation)

POST

buy

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

Command (rational representation in num-rational crate format)

POST

buy

{
  "base": "DOC",
  "method": "buy",
  "price": [
    [
      1,
      [
        66
      ]
    ],
    [
      1,
      [
        25
      ]
    ]
  ],
  "rel": "MARTY",
  "userpass": "RPC_UserP@SSW0RD",
  "volume": [
    [
      1,
      [
        12
      ]
    ],
    [
      1,
      [
        5
      ]
    ]
  ]
}

Command (rational representation as fraction object)

POST

buy

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

Command (with confirmations and notarization settings)

POST

buy

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

Command (set to not save order history)

POST

buy

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

Command (GoodTillCancelled type)

POST

buy

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

Command (FillOrKill type)

POST

buy

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

Command (match by Any)

POST

buy

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

Command (match by Pubkeys)

POST

buy

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

Command (match by Orders)

POST

buy

{
  "base": "BASE",
  "match_by": {
    "data": [
      "d14452bb-e82d-44a0-86b0-10d4cdcb8b24"
    ],
    "type": "Orders"
  },
  "method": "buy",
  "price": [
    [
      1,
      [
        1
      ]
    ],
    [
      1,
      [
        1
      ]
    ]
  ],
  "rel": "REL",
  "userpass": "RPC_UserP@SSW0RD",
  "volume": [
    [
      1,
      [
        1
      ]
    ],
    [
      1,
      [
        1
      ]
    ]
  ]
}

Response (success)

Response (Response (success))

SUCCESS

{
  "result": {
    "action": "Buy",
    "base": "HELLO",
    "base_amount": "1",
    "base_amount_rat": [
      [
        1,
        [
          1
        ]
      ],
      [
        1,
        [
          1
        ]
      ]
    ],
    "base_orderbook_ticker": null,
    "conf_settings": {
      "base_confs": 2,
      "base_nota": true,
      "rel_confs": 5,
      "rel_nota": false
    },
    "dest_pub_key": "0000000000000000000000000000000000000000000000000000000000000000",
    "match_by": {
      "data": [
        "1ab7edc96abaefb358b52c583048eaaeb8ea42609d096d6cddfafa02fa510c6a"
      ],
      "type": "Pubkeys"
    },
    "method": "request",
    "rel": "WORLD",
    "rel_amount": "1",
    "rel_amount_rat": [
      [
        1,
        [
          1
        ]
      ],
      [
        1,
        [
          1
        ]
      ]
    ],
    "rel_orderbook_ticker": null,
    "sender_pubkey": "c213230771ebff769c58ade63e8debac1b75062ead66796c8d793594005f3920",
    "uuid": "288743e2-92a5-471e-92d5-bb828a2303c3"
  }
}

Error (rel balance too low)

Response (Error (rel balance too low))

ERROR

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

Error (amount exceeds available liquidity)

Response (Error (amount exceeds available liquidity))

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"
}

On this page

buy

Response (Response (success))

Response (Error (rel balance too low))

Response (Error (amount exceeds available liquidity))