marketplace_global_get_offers_ex

General marketplace API which lets read offers related to given wallet

Request

{
    "jsonrpc": "2.0",
    "id": "0",
    "method": "marketplace_global_get_offers_ex",
    "params": {
        "filter": {
            "amount_low_limit": 0,
            "amount_up_limit": 0,
            "bonus": false,
            "category": "",
            "fake": false,
            "keyword": "",
            "limit": 100,
            "location_city": "",
            "location_country": "",
            "offer_type_mask": 0,
            "offset": 0,
            "order_by": 0,
            "primary": "",
            "rate_low_limit": "0.000000",
            "rate_up_limit": "0.000000",
            "reverse": false,
            "target": "",
            "timestamp_start": 0,
            "timestamp_stop": 0
        }
    }
}

Request parameters

amount_low_limit - filter offers selection by field amount of specified currency at lower boundary.
amount_up_limit - filter offers selection by field amoun of specified currency t at higher boundary.
bonus - boolean; when true, only offers that have a non-empty b (bonus) field are returned. When false (the default), the bonus field is not taken into account at all. Note that this is a presence check, not a text match — use keyword to search inside the bonus text.
category - fiter by category, work's as substring matching, i.e. if categories set to "CLS:MAN:TSH" and filters category fileds set to "MAN" then it fits category condition.
fake - boolean; reserved flag, accepted by the API for compatibility with the GUI wallet but currently not applied by the core when matching offers. Leave it as false.
keyword - This use search by keyword throught the all fields.
limit - Maximum records to return.
location_city - Used to filter by city name or geo-tag
location_country - Filters by country code.
offer_type_mask - unsigned int; bitmask restricting the selection to certain offer types. Bits may be combined with a bitwise OR; 0 disables the filter and returns offers of every type. The bits correspond one-to-one to the ot field of the returned offers:

Constant	Value	Matches offers with `ot`
`OFFER_TYPE_MASK_PRIMARY_TO_TARGET`	0x00000001 (1)	0
`OFFER_TYPE_MASK_TARGET_TO_PRIMARY`	0x00000002 (2)	1
`OFFER_TYPE_MASK_GOODS_TO_PRIMARY`	0x00000004 (4)	2
`OFFER_TYPE_MASK_PRIMARY_TO_GOODS`	0x00000008 (8)	3

For example 5 (1 | 4) returns only offers of type 0 and type 2. An offer whose ot is not one of 0-3 is never returned when the mask is non-zero.

offset - Offeset regarding first item which fit specified filter, count include only items which fit the filter. Userful for enumeration big amount or records, up to whole offers database enumeration.
order_by - chose in how to order offers in selection. At this moment supported following ordering:

"order_by"
0	Order by timestamp (most usable)
1	Order by an amount of Nirmata
2	Order by the amount of specified currency
3	Order by rate, which calculated as the amount currency divided to amount Nirmata
4	Order by payment type(as string)
5	Order by contact field(as string)
6	Order by location: country string concatenated with city string
7	Order by target string, basically title string

primary - string; filter by the offer's p field (the currency paid or received in exchange for the target), matched as a case-insensitive substring. For instance "usd" matches an offer whose p is "USD". Empty string disables this filter.
rate_low_limit - Filter by low limit of the rate between Nirmata and currency amount currency divided to amount Nirmata
rate_up_limit - Filter by high limit of the same rate. Like rate_low_limit, it is passed as a decimal number formatted as a string (for example "1.500000"); "0.000000" disables the limit.
reverse - Reverse order
target - Basically a title for subject of the Offer - could be the name of the goods or currency which supposed to be traded.
timestamp_start - Setup a lower timestamp boundary. Useful if the offers are selecting for given time range.
timestamp_stop - Setup a higher timestamp boundary. Useful if the offers are selecting for given time range.

Response

{
  "id": 0,
  "jsonrpc": "2.0",
  "result": {
    "offers": [
      {
        "ap": "20",
        "at": "1",
        "b": "",
        "cat": "CLS:MAN:TSH",
        "cnt": "Skype: some_skype, discord: some_user#01012",
        "com": "Some nice comments about tshirt",
        "do": "Additional conditions",
        "et": 10,
        "fee": 10000000000,
        "index_in_tx": 0,
        "lci": "",
        "lco": "World Wide",
        "ot": 1,
        "p": "USD",
        "pt": "Credit cards, BTC, NIR, ETH",
        "security": "0000000000000000000000000000000000000000000000000000000000000000",
        "t": "T-shirt with Nirmata logo, made by Crypjunkie",
        "timestamp": 1570219600,
        "tx_hash": "6ba12c5d2c66d31f770bfdc88ae9dc90d007b9b33f946fc7c1d9750f8655331c",
        "tx_original_hash": "0000000000000000000000000000000000000000000000000000000000000000"
      },
      {
        "ap": "20",
        "at": "1",
        "b": "",
        "cat": "CLS:MAN:TSH",
        "cnt": "Skype: some_skype, discord: some_user#01012",
        "com": "Some nice comments about tshirt",
        "do": "Additional conditions",
        "et": 10,
        "fee": 10000000000,
        "index_in_tx": 0,
        "lci": "",
        "lco": "World Wide",
        "ot": 1,
        "p": "USD",
        "pt": "Credit cards, BTC, NIR, ETH",
        "security": "0000000000000000000000000000000000000000000000000000000000000000",
        "t": "T-shirt with Nirmata logo, made by Crypjunkie",
        "timestamp": 1570219840,
        "tx_hash": "2987b671cc337203628a3a1bb7ac811e41f110864d6162d3c2276d2c79f694d6",
        "tx_original_hash": "0000000000000000000000000000000000000000000000000000000000000000"
      }
    ],
    "status": "OK",
    "total_offers": 1284
  }
}

Response information

offers - array of objects; the offers matching the filter, ordered and paginated according to order_by, reverse, offset and limit. Fields of each item are described below.
status - string; call result. OK if the request has been processed successfully, FAILED if the filter could not be applied (for example an unknown order_by value), or BUSY if the core is not ready yet.
total_offers - unsigned int; total number of offers currently held in the node's marketplace database. Note that this is the size of the whole database, not the number of offers that matched the filter, so it cannot be used directly to compute a page count.
ap - the amount of the currency specified for use in this offer
at - the amount of the items to be sold/bought
b - string; the offer's "bonus" — a free-form text field the offer author can use for a promotion, discount or any additional incentive. Empty when the author did not set one. The bonus request filter selects offers where this field is non-empty, and keyword searches inside its text.
cat - category of the goods, could be specified with subcategories by separation CLS:MAN:TSH, which could mean Clothes->Man->Tshirts
cnt - contacts, like skype, discord, telegram, whatever
com - comments regarding this offer
do - additional conditions, if need to specify
et - expiration time, set in days, eg 5 - expire in 5 days after creation
fee - fee paid for this transaction with the offer, it can be default offer, but the higher fee may bring offers to be higher in search results
index_in_tx - unsigned int; zero-based index of this offer among the service attachments of the transaction identified by tx_hash. A single transaction can carry several marketplace entries, so an offer is uniquely identified by the pair (tx_hash, index_in_tx) — that is the pair you pass when updating or cancelling it.
lci - location city, if the also make sense for an offer, could be google geo-autocomplete id, like ChIJD7fiBh9u5kcRYJSMaMOCCwQ
lco - location country, if this makes sense for an offer
ot - offer type, 0 - buy currency for NiR, 1 - buy NiR for currency, 2 - buy goods for NiR, 3 - sell goods for NiR
p - string; the "primary" side of the offer, i.e. the currency that is paid or received in exchange for t. In the example above the T-shirt (t) is priced in USD (p). Filtered by the primary request parameter as a case-insensitive substring.
pt - payment type, Credit cards, Crypto, Paypal, Flexa
security - string; hex-encoded public key that authorises later modifications of this offer. Any transaction that updates or cancels the offer must carry a signature verifiable against this key, which is how the network ensures only the original author can change it. Callers reading offers do not need to do anything with it.
t - description for the goods/service which is selling/seeking
timestamp - unsigned int; UNIX timestamp of the moment the offer was published, taken from the block containing the transaction that created it. It is not stored in the transaction itself. When an offer is updated, the original publication timestamp is preserved rather than being reset.
tx_hash - string; hex-encoded hash of the transaction that currently carries this offer. For an offer that has been updated, this is the hash of the most recent update transaction, not of the transaction that first published it.
tx_original_hash - string; hex-encoded hash of the transaction that originally published the offer, filled in only when the offer has since been updated and therefore now lives in a different transaction. All zeroes when the offer has never been updated (in which case tx_hash is already the original one).

Request​

Request parameters​

Response​

Response information​

Request

Request parameters

Response

Response information