Marketplace API

Order models#

Order status#

StatusDescription
activeIndicates that the order is currently valid and can be traded
inactiveIndicates that the order is temporarily inactive and may become active again in the future
cancelledIndicates that the order has been cancelled and cannot be traded
soldIndicates that the order has been traded and cannot be traded again

OKX order model#

The response to creating an order or query order:

ParameterTypeDescription
orderIdStringOrder ID
createTimeLongCreation time of the order, timestamp in seconds
updateTimeLongTime when order status is updated, timestamp in seconds
listingTimeLongOrder listing time, timestamp in seconds
expirationTimeLongExpiry time of the order, end time, timestamp in seconds
statusStringOrder status, including active, cancelled, sold, inactive, see “Order Status Enumeration”
orderHashStringThe Order hash
protocolDataStringOrder parameters (json), structure varies for each market
protocolAddressStringOrder transaction contract address
chainStringChain name refer to Supported blockchains for details
makerStringAddress of the person who initiated the order
orderTypeStringOffer indicates offer; BuyNow indicates listings
priceStringPrice per NFT for the order
currencyAddressStringAddress of the token used in the order
collectionAddressStringNFT contract address
tokenIdStringNFT token ID
amountStringQuantity of NFTs for the order
availableAmountStringQuantity of NFTs that can be use for this order

Order parameters model#

The order parameters details for creating an order:

ParameterTypeDescription
offererStringThe wallet address initiating the order
offerArrayThe offerer of the order supplies all offered items list, an array of Offer Item Model
considerationArrayThe consideration contains an array of items that must be received in order to fulfill the order, An array of Consideration Item Model
startTimetimestampThe startTime indicates the block timestamp at which the order becomes active
endTimetimestampThe endTime indicates the block timestamp at which the order expires
orderTypenumberThe orderType designates one of four types for the order depending on two distinct preferences: OrderType
zoneString
zoneHashStringA fixed value:0x0000000000000000000000000000000000000000000000000000000000000000
saltStringThe salt represents an arbitrary source of entropy for the order
conduitKeyStringA fixed value: 0x066003C1493A346357Af15158cD985b4A6e29D3F888888888888888888888888
totalOriginalConsiderationItemsnumberThe amount of consideration size
counternumberThe counter indicates a value that must match the current counter for the given offerer

Offer item model#

The offerer of the order supplies all the offered items listed. When listing order, the offer array must have exactly one item, and it must be an ERC-721 or ERC-1155 token. When offering order, the offer array must have exactly one item, which must be a currency.

ParameterTypeDescription
itemTypenumberThe itemType designates the type of item, with valid types being Ether (or other native token for the given chain), ERC20, ERC721, ERC1155, ERC721 with "criteria" (explained below), and ERC1155 with criteria.
tokenStringThe token designates the account of the item's token contract (with the null address used for Ether or other native tokens).
identifierOrCriteriaStringThe identifierOrCriteria represents either the ERC721 or ERC1155 token identifier or, in the case of a criteria-based item type, a merkle root composed of the valid set of token identifiers for the item. This value will be ignored for Ether and ERC20 item types, and can optionally be zero for criteria-based item types to allow for any identifier.
startAmountnumberThe startAmount represents the amount of the item in question that will be required, should the order be fulfilled at the moment the order becomes active.
endAmountnumberThe endAmount represents the amount of the item in question that will be required, should the order be fulfilled at the moment the order expires. If this value differs from the item's startAmount, the realized amount is calculated linearly based on the time elapsed since the order became active.

Consideration item model#

The consideration contains an array of items that must be received in order to fulfill the order. The consideration array must have exactly two or three items. The items are (in order): the asset (when offer is NFT, listing is the offerer fee), the optional OKX fee, and an optional collection fee.

ParameterTypeDescription
itemTypenumberThe itemType designates the type of item, with valid types being Ether (or other native token for the given chain), ERC20, ERC721, ERC1155, ERC721 with "criteria" (explained below), and ERC1155 with criteria.
tokenStringThe token designates the account of the item's token contract (with the null address used for Ether or other native tokens).
identifierOrCriteriaStringThe identifierOrCriteria represents either the ERC721 or ERC1155 token identifier or, in the case of a criteria-based item type, a merkle root composed of the valid set of token identifiers for the item. This value will be ignored for Ether and ERC20 item types, and can optionally be zero for criteria-based item types to allow for any identifier.
startAmountnumberThe startAmount represents the amount of the item in question that will be required, should the order be fulfilled at the moment the order becomes active.
endAmountnumberThe endAmount represents the amount of the item in question that will be required, should the order be fulfilled at the moment the order expires. If this value differs from the item's startAmount, the realized amount is calculated linearly based on the time elapsed since the order became active.
recipientStringRecipient that will receive each item.

Enums#

OrderType#

enum OrderType {
  FULL_OPEN,
  PARTIAL_OPEN,
  FULL_RESTRICTED,
  PARTIAL_RESTRICTED
}

ItemType#

enum ItemType {
  NATIVE,
  ERC20,
  ERC721,
  ERC1155,
  ERC721_WITH_CRITERIA,
  ERC1155_WITH_CRITERIA
}

Buy item model#

ParameterTypeDescription
orderIdStringorder ID to fill
takeCountIntegerQuantity of tokens to buy